tiny.smg.scan.python

1const std = @import("std");23const smg = @import("../root.zig");4const graph_mod = smg.graph;5const lines_mod = smg.lines;6const model = smg.model;7const scan_root = smg.scan;8const text = smg.text;910const core = scan_root.core;11const metrics = scan_root.scan_metrics;1213const CallTarget = core.CallTarget;14const SourceLines = lines_mod.SourceLines;15const Stats = core.Stats;1617const identByte = metrics.identByte;18const indentation = metrics.indentation;19const pythonCommentLine = metrics.pythonCommentLine;20const skipQuoted = metrics.skipQuoted;21const textFunctionMetadata = metrics.textFunctionMetadata;22const textSpanMetadata = metrics.textSpanMetadata;2324const Alias = struct {25    local: []const u8,26    target: []const u8,27};2829const PythonLine = struct {30    raw: []const u8,31    trimmed: []const u8,32    indent: usize,33    number: i64,34};3536const PythonBodyContext = struct {37    allocator: std.mem.Allocator,38    scratch: std.mem.Allocator,39    graph: *graph_mod.Graph,40    parent: []const u8,41    path: []const u8,42    source: []const u8,43    source_lines: SourceLines,44    lines: []const PythonLine,45    parent_indent: usize,46    in_class: bool,47    aliases: []const Alias,48    stats: *Stats,49};5051const PythonBodyLineAction = enum {52    scan,53    skip,54    stop,55};5657const PythonBodyFrame = struct {58    parent: []const u8,59    start: usize,60    action_start: usize,61    end: usize,62    parent_indent: usize,63    in_class: bool,64};6566const PythonBodyScan = struct {67    block_end: ?usize = null,68    child: ?PythonBodyFrame = null,69};7071const PythonClassContext = struct {72    allocator: std.mem.Allocator,73    scratch: std.mem.Allocator,74    graph: *graph_mod.Graph,75    parent: []const u8,76    path: []const u8,77    source: []const u8,78    source_lines: SourceLines,79    lines: []const PythonLine,80    aliases: []const Alias,81    stats: *Stats,82};8384const PythonClassRecord = struct {85    qualified: []const u8,86    index: usize,87    block_end: usize,88    line: PythonLine,89    end_line: i64,90    decorators: []const []const u8,91};9293pub fn scan(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, module: []const u8, path: []const u8, source: []const u8, source_lines: SourceLines, stats: *Stats) !void {94    try scanLines(allocator, scratch, graph, module, path, source, source_lines, stats);95}9697fn scanLines(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, module: []const u8, path: []const u8, source: []const u8, source_lines: SourceLines, stats: *Stats) !void {98    var lines: std.ArrayList(PythonLine) = .empty;99    var split = std.mem.splitScalar(u8, source, '\n');100    var line_no: i64 = 0;101    while (split.next()) |raw_line| {102        line_no += 1;103        const trimmed = text.trim(raw_line);104        try lines.append(scratch, .{ .raw = raw_line, .trimmed = trimmed, .indent = indentation(raw_line), .number = line_no });105    }106    var aliases: std.ArrayList(Alias) = .empty;107    try extractImportsText(allocator, scratch, graph, module, lines.items, stats, &aliases);108    try walkTextBody(allocator, scratch, graph, module, path, source, source_lines, lines.items, 0, lines.items.len, 0, false, aliases.items, stats);109    try extractDynamicImportsText(allocator, graph, module, lines.items, stats);110}111112fn extractImportsText(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, module: []const u8, lines: []const PythonLine, stats: *Stats, aliases: *std.ArrayList(Alias)) !void {113    var index = lines.len;114    while (index > 0) {115        index -= 1;116        const line = lines[index];117        if (line.trimmed.len == 0 or pythonCommentLine(line.trimmed)) continue;118        const metadata = if (line.indent == 0) &.{} else try core.boolMetadata(allocator, "deferred");119        if (std.mem.startsWith(u8, line.trimmed, "import ")) {120            try extractImportText(allocator, scratch, graph, module, line.trimmed["import ".len..], metadata, stats, aliases);121        } else if (std.mem.startsWith(u8, line.trimmed, "from ")) {122            try extractFromImportText(allocator, scratch, graph, module, line.trimmed["from ".len..], metadata, stats, aliases);123        }124    }125}126127fn extractImportText(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, module: []const u8, raw: []const u8, metadata: []const model.Pair, stats: *Stats, aliases: *std.ArrayList(Alias)) !void {128    var imports: std.ArrayList([]const u8) = .empty;129    var split = std.mem.splitScalar(u8, raw, ',');130    while (split.next()) |part| {131        const item = text.trim(part);132        if (item.len != 0) try imports.append(scratch, item);133    }134    var index = imports.items.len;135    while (index > 0) {136        index -= 1;137        const item = imports.items[index];138        const as_index = std.mem.indexOf(u8, item, " as ");139        const target_raw = text.trim(if (as_index) |pos| item[0..pos] else item);140        if (!dottedName(target_raw)) continue;141        const target = try allocator.dupe(u8, target_raw);142        try core.addImportEdge(allocator, graph, module, target, metadata, stats);143        const local = if (as_index) |pos| text.trim(item[pos + " as ".len ..]) else firstDottedPart(target);144        if (local.len != 0 and identifier(local)) try aliases.append(scratch, .{ .local = local, .target = target });145    }146}147148fn extractFromImportText(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, module: []const u8, raw: []const u8, metadata: []const model.Pair, stats: *Stats, aliases: *std.ArrayList(Alias)) !void {149    const import_index = std.mem.indexOf(u8, raw, " import ") orelse return;150    const raw_module = text.trim(raw[0..import_index]);151    if (raw_module.len == 0) return;152    const target = try resolveImportTarget(allocator, scratch, module, raw_module);153    try core.addImportEdge(allocator, graph, module, target, metadata, stats);154    const imports_raw = text.trim(raw[import_index + " import ".len ..]);155    var imports: std.ArrayList([]const u8) = .empty;156    var split = std.mem.splitScalar(u8, imports_raw, ',');157    while (split.next()) |part| {158        const item = text.trim(part);159        if (item.len != 0) try imports.append(scratch, item);160    }161    var index = imports.items.len;162    while (index > 0) {163        index -= 1;164        const item = imports.items[index];165        if (std.mem.eql(u8, item, "*")) continue;166        const as_index = std.mem.indexOf(u8, item, " as ");167        const imported_raw = text.trim(if (as_index) |pos| item[0..pos] else item);168        if (!dottedName(imported_raw)) continue;169        const local = if (as_index) |pos| text.trim(item[pos + " as ".len ..]) else firstDottedPart(imported_raw);170        if (local.len == 0 or !identifier(local)) continue;171        try aliases.append(scratch, .{172            .local = local,173            .target = try std.fmt.allocPrint(allocator, "{s}.{s}", .{ target, imported_raw }),174        });175    }176}177178fn walkTextBody(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, parent: []const u8, path: []const u8, source: []const u8, source_lines: SourceLines, lines: []const PythonLine, start: usize, end: usize, parent_indent: usize, in_class: bool, aliases: []const Alias, stats: *Stats) anyerror!void {179    const context: PythonBodyContext = .{ .allocator = allocator, .scratch = scratch, .graph = graph, .parent = parent, .path = path, .source = source, .source_lines = source_lines, .lines = lines, .parent_indent = parent_indent, .in_class = in_class, .aliases = aliases, .stats = stats };180    try walkTextBodyContext(context, start, end);181}182183fn walkTextBodyContext(context: PythonBodyContext, start: usize, end: usize) anyerror!void {184    var frames: std.ArrayList(PythonBodyFrame) = .empty;185    try frames.append(context.scratch, .{ .parent = context.parent, .start = start, .action_start = start, .end = end, .parent_indent = context.parent_indent, .in_class = context.in_class });186    while (frames.pop()) |frame| {187        var frame_context = context;188        frame_context.parent = frame.parent;189        frame_context.parent_indent = frame.parent_indent;190        frame_context.in_class = frame.in_class;191        var index = frame.start;192        while (index < frame.end) : (index += 1) {193            const line = context.lines[index];194            switch (bodyLineAction(frame_context, frame.action_start, line)) {195                .skip => continue,196                .stop => break,197                .scan => {},198            }199            const result = try scanBodyLine(frame_context, index, frame.end);200            if (result.child) |child| {201                if (result.block_end) |block_end| {202                    if (block_end + 1 < frame.end) try frames.append(context.scratch, .{ .parent = frame.parent, .start = block_end + 1, .action_start = frame.action_start, .end = frame.end, .parent_indent = frame.parent_indent, .in_class = frame.in_class });203                }204                try frames.append(context.scratch, child);205                break;206            }207            if (result.block_end) |block_end| index = block_end;208        }209    }210}211212fn bodyLineAction(context: PythonBodyContext, start: usize, line: PythonLine) PythonBodyLineAction {213    if (line.trimmed.len == 0 or pythonCommentLine(line.trimmed)) return .skip;214    if (line.indent < context.parent_indent) return .stop;215    if (start != 0 and line.indent <= context.parent_indent) return .stop;216    if (line.indent != context.parent_indent and start == 0) return .skip;217    if (start != 0 and line.indent != context.parent_indent + 4 and line.indent <= context.parent_indent) return .skip;218    return .scan;219}220221fn scanBodyLine(context: PythonBodyContext, index: usize, end: usize) anyerror!PythonBodyScan {222    const line = context.lines[index];223    var decorators: std.ArrayList([]const u8) = .empty;224    var definition_index = index;225    if (std.mem.startsWith(u8, line.trimmed, "@")) {226        definition_index = try collectDecorators(context.allocator, context.scratch, context.lines, index, end, &decorators);227        if (definition_index == index) return .{};228    }229    if (try scanClassDefinition(context, definition_index, decorators.items)) |result| return result;230    if (try scanFunctionDefinition(context, definition_index, decorators.items)) |block_end| return .{ .block_end = block_end };231    if (decorators.items.len == 0) try extractAssignmentText(context.allocator, context.graph, context.parent, context.path, context.source, line, context.stats);232    return .{};233}234235fn scanClassDefinition(context: PythonBodyContext, definition_index: usize, decorators: []const []const u8) anyerror!?PythonBodyScan {236    const definition_line = context.lines[definition_index];237    const name = className(definition_line.trimmed) orelse return null;238    const block_end = blockEnd(context.lines, definition_index);239    const child = try extractClassText(context.allocator, context.scratch, context.graph, context.parent, context.path, context.source, context.source_lines, context.lines, definition_index, block_end, name, decorators, context.aliases, context.stats);240    return .{ .block_end = block_end, .child = child };241}242243fn scanFunctionDefinition(context: PythonBodyContext, definition_index: usize, decorators: []const []const u8) anyerror!?usize {244    const definition_line = context.lines[definition_index];245    const name = functionName(definition_line.trimmed) orelse return null;246    const block_end = blockEnd(context.lines, definition_index);247    try extractFunctionText(context.allocator, context.scratch, context.graph, context.parent, context.path, context.source_lines, context.lines, definition_index, block_end, name, context.in_class, decorators, context.aliases, context.stats);248    return block_end;249}250251fn collectDecorators(allocator: std.mem.Allocator, scratch: std.mem.Allocator, lines: []const PythonLine, start: usize, end: usize, decorators: *std.ArrayList([]const u8)) !usize {252    const indent = lines[start].indent;253    var index = start;254    while (index < end) : (index += 1) {255        const line = lines[index];256        if (line.trimmed.len == 0) continue;257        if (line.indent != indent or !std.mem.startsWith(u8, line.trimmed, "@")) break;258        if (decoratorNameText(line.trimmed)) |name| try decorators.append(scratch, try allocator.dupe(u8, name));259    }260    return index;261}262263fn extractClassText(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, parent: []const u8, path: []const u8, source: []const u8, source_lines: SourceLines, lines: []const PythonLine, index: usize, block_end: usize, name: []const u8, decorators: []const []const u8, aliases: []const Alias, stats: *Stats) !?PythonBodyFrame {264    const context: PythonClassContext = .{ .allocator = allocator, .scratch = scratch, .graph = graph, .parent = parent, .path = path, .source = source, .source_lines = source_lines, .lines = lines, .aliases = aliases, .stats = stats };265    const class_record = try classRecord(context, index, block_end, name, decorators);266    try addClassNode(context, class_record);267    try addClassRelations(context, class_record);268    return classBodyFrame(class_record);269}270271fn classRecord(context: PythonClassContext, index: usize, block_end: usize, name: []const u8, decorators: []const []const u8) !PythonClassRecord {272    return .{273        .qualified = try std.fmt.allocPrint(context.allocator, "{s}.{s}", .{ context.parent, name }),274        .index = index,275        .block_end = block_end,276        .line = context.lines[index],277        .end_line = context.lines[block_end].number,278        .decorators = decorators,279    };280}281282fn addClassNode(context: PythonClassContext, class_record: PythonClassRecord) !void {283    try graph_mod.addNode(context.graph, .{284        .name = class_record.qualified,285        .type = model.NodeType.class,286        .file = context.path,287        .line = class_record.line.number,288        .end_line = class_record.end_line,289        .docstring = try docstring(context.allocator, context.scratch, context.lines, class_record.index, class_record.block_end),290        .metadata = try textSpanMetadata(context.allocator, context.source_lines, class_record.line.number, class_record.end_line, null),291    });292}293294fn addClassRelations(context: PythonClassContext, class_record: PythonClassRecord) !void {295    try core.addScanEdge(context.graph, context.stats, .{ .source = context.parent, .rel = model.RelType.contains, .target = class_record.qualified, .metadata = try model.sourcePair(context.allocator, "scan") });296    context.stats.nodes_added += 1;297    try core.countType(context.stats, context.allocator, model.NodeType.class);298    try extractSuperText(context.allocator, context.scratch, context.graph, context.parent, class_record.qualified, class_record.line.trimmed, context.aliases, context.stats);299    try recordDecoratorSkipsText(context.stats, class_record.decorators, class_record.qualified);300}301302fn classBodyFrame(class_record: PythonClassRecord) ?PythonBodyFrame {303    if (class_record.block_end <= class_record.index) return null;304    return .{ .parent = class_record.qualified, .start = class_record.index + 1, .action_start = class_record.index + 1, .end = class_record.block_end + 1, .parent_indent = class_record.line.indent, .in_class = true };305}306307fn extractFunctionText(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, parent: []const u8, path: []const u8, source_lines: SourceLines, lines: []const PythonLine, index: usize, block_end: usize, name: []const u8, in_class: bool, decorators: []const []const u8, aliases: []const Alias, stats: *Stats) !void {308    const line = lines[index];309    const qualified = try std.fmt.allocPrint(allocator, "{s}.{s}", .{ parent, name });310    const node_type = if (in_class) model.NodeType.method else model.NodeType.function;311    try graph_mod.addNode(graph, .{312        .name = qualified,313        .type = node_type,314        .file = path,315        .line = line.number,316        .end_line = lines[block_end].number,317        .docstring = try docstring(allocator, scratch, lines, index, block_end),318        .metadata = try textFunctionMetadata(allocator, stats.metricInputAllocator(allocator), source_lines, line.number, lines[block_end].number, .python),319    });320    try core.addScanEdge(graph, stats, .{ .source = parent, .rel = model.RelType.contains, .target = qualified, .metadata = try model.sourcePair(allocator, "scan") });321    stats.nodes_added += 1;322    try core.countType(stats, allocator, node_type);323    try recordDecoratorSkipsText(stats, decorators, qualified);324    try extractCallsText(allocator, scratch, graph, qualified, if (in_class) parent else null, lines, index + 1, block_end + 1, aliases, stats);325}326327fn extractAssignmentText(allocator: std.mem.Allocator, graph: *graph_mod.Graph, parent: []const u8, path: []const u8, source: []const u8, line: PythonLine, stats: *Stats) !void {328    _ = source;329    const eq = std.mem.indexOfScalar(u8, line.trimmed, '=') orelse return;330    const name = text.trim(line.trimmed[0..eq]);331    if (!identifier(name) or !core.isUpper(name)) return;332    const qualified = try std.fmt.allocPrint(allocator, "{s}.{s}", .{ parent, name });333    try graph_mod.addNode(graph, .{334        .name = qualified,335        .type = model.NodeType.constant,336        .file = path,337        .line = line.number,338        .end_line = line.number,339        .metadata = try model.sourcePair(allocator, "scan"),340    });341    try core.addScanEdge(graph, stats, .{ .source = parent, .rel = model.RelType.contains, .target = qualified, .metadata = try model.sourcePair(allocator, "scan") });342    stats.nodes_added += 1;343    try core.countType(stats, allocator, model.NodeType.constant);344}345346fn extractSuperText(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, parent: []const u8, qualified: []const u8, line: []const u8, aliases: []const Alias, stats: *Stats) !void {347    const open = std.mem.indexOfScalar(u8, line, '(') orelse return;348    const close = std.mem.lastIndexOfScalar(u8, line, ')') orelse return;349    if (close <= open + 1) return;350    var split = std.mem.splitScalar(u8, line[open + 1 .. close], ',');351    while (split.next()) |raw_item| {352        const item = text.trim(raw_item);353        if (!dottedName(item)) continue;354        const target = aliasTarget(aliases, item) orelse item;355        if (try resolveLocalType(scratch, graph.*, parent, target)) |resolved| {356            try core.addScanEdge(graph, stats, .{ .source = qualified, .rel = model.RelType.inherits, .target = resolved, .metadata = try model.sourcePair(allocator, "scan") });357        } else {358            try stats.deferred.append(.{ .source = qualified, .rel = model.RelType.inherits, .target = try allocator.dupe(u8, target) });359        }360    }361}362363fn extractCallsText(allocator: std.mem.Allocator, scratch: std.mem.Allocator, graph: *graph_mod.Graph, caller: []const u8, class_name: ?[]const u8, lines: []const PythonLine, start: usize, end: usize, aliases: []const Alias, stats: *Stats) !void {364    var calls: std.ArrayList(CallTarget) = .empty;365    var index = start;366    while (index < end) : (index += 1) {367        const line = lines[index];368        if (line.trimmed.len == 0 or pythonCommentLine(line.trimmed)) continue;369        try collectCallsInLine(allocator, scratch, line.trimmed, class_name, aliases, &calls);370    }371    var call_index = calls.items.len;372    while (call_index > 0) {373        call_index -= 1;374        try core.addCallEdge(allocator, graph, caller, calls.items[call_index], stats);375    }376}377378fn collectCallsInLine(allocator: std.mem.Allocator, scratch: std.mem.Allocator, line: []const u8, class_name: ?[]const u8, aliases: []const Alias, calls: *std.ArrayList(CallTarget)) !void {379    var index: usize = 0;380    while (index < line.len) : (index += 1) {381        const byte = line[index];382        if (byte == '"' or byte == '\'') {383            index = skipQuoted(line, index);384            if (index >= line.len) break;385            continue;386        }387        if (byte == '#') break;388        if (byte != '(') continue;389        const raw = targetBeforeParen(line, index) orelse continue;390        if (try callTargetFromText(allocator, raw, class_name, aliases)) |target| try calls.append(scratch, target);391    }392}393394fn callTargetFromText(allocator: std.mem.Allocator, raw: []const u8, class_name: ?[]const u8, aliases: []const Alias) !?CallTarget {395    if (std.mem.eql(u8, raw, "def") or std.mem.eql(u8, raw, "class") or builtin(raw)) return null;396    const first_dot = std.mem.indexOfScalar(u8, raw, '.');397    if (first_dot == null) {398        if (aliasTarget(aliases, raw)) |target| return .{ .name = target, .resolved = false };399        return .{ .name = try allocator.dupe(u8, raw), .resolved = false };400    }401    const root = raw[0..first_dot.?];402    const suffix = raw[first_dot.? + 1 ..];403    if ((std.mem.eql(u8, root, "self") or std.mem.eql(u8, root, "cls")) and class_name != null) {404        return .{ .name = try std.fmt.allocPrint(allocator, "{s}.{s}", .{ class_name.?, suffix }), .resolved = true };405    }406    if (aliasTarget(aliases, root)) |target_prefix| {407        return .{ .name = try std.fmt.allocPrint(allocator, "{s}.{s}", .{ target_prefix, suffix }), .resolved = false };408    }409    return .{ .name = try allocator.dupe(u8, raw), .resolved = false };410}411412fn extractDynamicImportsText(allocator: std.mem.Allocator, graph: *graph_mod.Graph, module: []const u8, lines: []const PythonLine, stats: *Stats) !void {413    for (lines) |line| {414        if (line.trimmed.len == 0 or pythonCommentLine(line.trimmed)) continue;415        var index: usize = 0;416        while (index < line.trimmed.len) : (index += 1) {417            const byte = line.trimmed[index];418            if (byte == '"' or byte == '\'') {419                index = skipQuoted(line.trimmed, index);420                if (index >= line.trimmed.len) break;421                continue;422            }423            if (byte == '#') break;424            if (byte != '(') continue;425            const raw = targetBeforeParen(line.trimmed, index) orelse continue;426            if (!std.mem.eql(u8, raw, "importlib.import_module") and !std.mem.eql(u8, raw, "__import__")) continue;427            const target = firstTextStringArgument(line.trimmed[index + 1 ..]) orelse continue;428            if (!std.mem.startsWith(u8, target, ".")) try core.addImportEdge(allocator, graph, module, try allocator.dupe(u8, target), try core.boolMetadata(allocator, "dynamic"), stats);429        }430    }431}432433fn blockEnd(lines: []const PythonLine, start: usize) usize {434    const base_indent = lines[start].indent;435    var last = start;436    var index = start + 1;437    while (index < lines.len) : (index += 1) {438        const line = lines[index];439        if (line.trimmed.len == 0 or pythonCommentLine(line.trimmed)) continue;440        if (line.indent <= base_indent) break;441        last = index;442    }443    return last;444}445446fn className(line: []const u8) ?[]const u8 {447    if (!std.mem.startsWith(u8, line, "class ")) return null;448    const rest = text.trim(line["class ".len..]);449    return core.leadingIdentifier(rest);450}451452fn functionName(line: []const u8) ?[]const u8 {453    const rest = if (std.mem.startsWith(u8, line, "def "))454        line["def ".len..]455    else if (std.mem.startsWith(u8, line, "async def "))456        line["async def ".len..]457    else458        return null;459    return core.leadingIdentifier(text.trim(rest));460}461462fn decoratorNameText(line: []const u8) ?[]const u8 {463    if (!std.mem.startsWith(u8, line, "@")) return null;464    const rest = line[1..];465    var end: usize = 0;466    while (end < rest.len and (identByte(rest[end]) or rest[end] == '.')) end += 1;467    if (end == 0) return null;468    return rest[0..end];469}470471fn recordDecoratorSkipsText(stats: *Stats, decorators: []const []const u8, target: []const u8) !void {472    for (decorators) |decorator| {473        try stats.deferred.append(.{ .source = decorator, .rel = model.RelType.decorates, .target = target });474    }475}476477fn targetBeforeParen(line: []const u8, paren: usize) ?[]const u8 {478    if (paren == 0) return null;479    var end = paren;480    while (end > 0 and std.ascii.isWhitespace(line[end - 1])) end -= 1;481    var start = end;482    while (start > 0 and (identByte(line[start - 1]) or line[start - 1] == '.')) start -= 1;483    if (start == end) return null;484    const raw = line[start..end];485    if (raw[0] == '.' or raw[raw.len - 1] == '.' or std.mem.indexOf(u8, raw, "..") != null) return null;486    return raw;487}488489fn firstTextStringArgument(raw: []const u8) ?[]const u8 {490    var rest = text.trim(raw);491    if (rest.len == 0) return null;492    if (rest[0] != '"' and rest[0] != '\'') return null;493    const quote = rest[0];494    rest = rest[1..];495    var end: usize = 0;496    while (end < rest.len) : (end += 1) {497        if (rest[end] == '\\') {498            if (end + 1 < rest.len) end += 1;499            continue;500        }501        if (rest[end] == quote) return rest[0..end];502    }503    return null;504}505506fn docstring(allocator: std.mem.Allocator, scratch: std.mem.Allocator, lines: []const PythonLine, definition_index: usize, block_end: usize) !?[]const u8 {507    if (definition_index >= block_end) return null;508    const def_indent = lines[definition_index].indent;509    var index = definition_index + 1;510    while (index <= block_end) : (index += 1) {511        const line = lines[index];512        if (line.trimmed.len == 0 or pythonCommentLine(line.trimmed)) continue;513        if (line.indent <= def_indent) return null;514        return try docstringFromLine(allocator, scratch, lines, index, block_end);515    }516    return null;517}518519fn docstringFromLine(allocator: std.mem.Allocator, scratch: std.mem.Allocator, lines: []const PythonLine, start: usize, block_end: usize) !?[]const u8 {520    const first = lines[start].trimmed;521    const quote = if (std.mem.startsWith(u8, first, "\"\"\""))522        "\"\"\""523    else if (std.mem.startsWith(u8, first, "'''"))524        "'''"525    else if (first.len >= 2 and (first[0] == '"' or first[0] == '\''))526        first[0..1]527    else528        return null;529    var content = first[quote.len..];530    if (std.mem.indexOf(u8, content, quote)) |end| {531        const doc = text.trim(content[0..end]);532        return if (doc.len == 0) null else try allocator.dupe(u8, doc);533    }534    var out: std.Io.Writer.Allocating = .init(scratch);535    errdefer out.deinit();536    if (content.len != 0) try out.writer.writeAll(content);537    var index = start + 1;538    while (index <= block_end) : (index += 1) {539        const line = text.trim(lines[index].raw);540        if (std.mem.indexOf(u8, line, quote)) |end| {541            if (out.written().len != 0) try out.writer.writeByte('\n');542            try out.writer.writeAll(line[0..end]);543            break;544        }545        if (out.written().len != 0) try out.writer.writeByte('\n');546        try out.writer.writeAll(line);547    }548    const raw_doc = try out.toOwnedSlice();549    const doc = text.trim(raw_doc);550    return if (doc.len == 0) null else try allocator.dupe(u8, doc);551}552553fn dottedName(value: []const u8) bool {554    if (value.len == 0) return false;555    var split = std.mem.splitScalar(u8, value, '.');556    while (split.next()) |part| {557        if (!identifier(part)) return false;558    }559    return true;560}561562fn identifier(value: []const u8) bool {563    if (value.len == 0 or (!std.ascii.isAlphabetic(value[0]) and value[0] != '_')) return false;564    for (value[1..]) |byte| if (!identByte(byte)) return false;565    return true;566}567568fn aliasTarget(aliases: []const Alias, local: []const u8) ?[]const u8 {569    for (aliases) |alias| {570        if (std.mem.eql(u8, alias.local, local)) return alias.target;571    }572    return null;573}574575fn resolveLocalType(scratch: std.mem.Allocator, graph: graph_mod.Graph, parent: []const u8, raw: []const u8) !?[]const u8 {576    if (graph_mod.getNode(&graph, raw)) |node| return node.name;577    const local = try std.fmt.allocPrint(scratch, "{s}.{s}", .{ parent, raw });578    if (graph_mod.getNode(&graph, local)) |node| return node.name;579    return null;580}581582fn firstDottedPart(value: []const u8) []const u8 {583    const end = std.mem.indexOfScalar(u8, value, '.') orelse value.len;584    return value[0..end];585}586587fn resolveImportTarget(allocator: std.mem.Allocator, scratch: std.mem.Allocator, module: []const u8, raw: []const u8) ![]const u8 {588    if (!std.mem.startsWith(u8, raw, ".")) return try allocator.dupe(u8, raw);589    var dots: usize = 0;590    while (dots < raw.len and raw[dots] == '.') dots += 1;591    var parts: std.ArrayList([]const u8) = .empty;592    var split = std.mem.splitScalar(u8, module, '.');593    while (split.next()) |part| try parts.append(scratch, part);594    const keep = if (dots > parts.items.len) 0 else parts.items.len - dots;595    const base = if (keep == 0) "" else try core.joinDotted(allocator, parts.items[0..keep]);596    const suffix = raw[dots..];597    if (base.len == 0) return try allocator.dupe(u8, suffix);598    if (suffix.len == 0) return base;599    return try std.fmt.allocPrint(allocator, "{s}.{s}", .{ base, suffix });600}601602fn builtin(name: []const u8) bool {603    const builtins = [_][]const u8{ "print", "len", "range", "enumerate", "zip", "map", "filter", "isinstance", "issubclass", "hasattr", "getattr", "setattr", "delattr", "type", "id", "hash", "repr", "str", "int", "float", "bool", "bytes", "callable", "chr", "list", "dict", "dir", "set", "tuple", "frozenset", "sorted", "reversed", "min", "max", "sum", "abs", "round", "open", "ord", "iter", "next", "any", "all", "__import__", "cls", "super", "property", "staticmethod", "classmethod", "ValueError", "TypeError", "KeyError", "AttributeError", "RuntimeError", "Exception", "NotImplementedError", "StopIteration", "AssertionError", "OSError", "IOError", "FileNotFoundError", "ImportError" };604    for (builtins) |item| if (std.mem.eql(u8, name, item)) return true;605    return false;606}

1pub const python = @import("python.zig");