tiny.smg.command.usages

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

1const std = @import("std");2const pretty_json = @import("pretty").json;34const smg = @import("../root.zig");5const exports = smg.exports;6const graph_mod = smg.graph;7const model = smg.model;8const options = smg.cli.options;9const output = smg.cli.output;10const resolve = smg.cli.resolve;11const session = smg.command.session;12const table = smg.cli.table;13const validation = smg.cli.validation;14const view = smg.view;1516pub const Row = struct {17    node: []const u8,18    rel: []const u8,19    file: ?[]const u8,20    line: ?i64,21    end_line: ?i64,22};2324pub fn run(allocator: std.mem.Allocator, _: std.mem.Allocator, args: []const []const u8, limits: smg.Limits, boundary: session.PhaseBoundary) !u8 {25    if (try validation.rejectMissingOptionValues(allocator, args, &.{ "--rel", "--format", "--limit" })) return 2;26    if (try validation.rejectUnexpectedOptionsPlain(allocator, "usages", "[OPTIONS] NAME", args, &.{ "--rel", "--format", "--limit" })) return 2;27    if (try validation.rejectInvalidChoiceOption(allocator, "usages", "[OPTIONS] NAME", args, "--format", &.{ "text", "json" })) return 2;28    if (try validation.rejectInvalidIntegerOption(allocator, "usages", "[OPTIONS] NAME", args, "--limit")) return 2;29    const pos = try options.positional(allocator, args);30    if (pos.len == 0) {31        try output.writeClickUsageError(allocator, "usages", "[OPTIONS] NAME", "Missing argument 'NAME'.");32        return 2;33    }34    if (pos.len > 1) {35        try output.writeClickUsageError(allocator, "usages", "[OPTIONS] NAME", try validation.unexpectedArgumentMessage(allocator, pos[1..]));36        return 2;37    }38    const root = try smg.storage.requireRoot(allocator);39    try session.noteGraphAge(allocator, root);40    var opened = try smg.storage.store.openRead(allocator, root, limits.storage);41    defer opened.close();42    const name = try resolve.storedNode(allocator, root, &opened.reader, pos[0], limits.suggestions);43    const rel = options.flagValue(args, "--rel");44    const node_context = try smg.storage.context.loadFromReader(allocator, &opened.reader, name, true);45    var source_names: std.ArrayList([]const u8) = .empty;46    for (node_context.incoming) |edge| {47        if (rel == null and !exports.isCoupling(edge.rel)) continue;48        try source_names.append(allocator, edge.source);49    }50    const source_nodes = try smg.storage.context.loadNodesFromReader(allocator, &opened.reader, source_names.items);51    boundary.seal();52    defer boundary.beginTeardown();53    const usage_rows = try storedRows(allocator, source_nodes, node_context.incoming, rel);54    const limit = options.signedLimitValue(args);55    const displayed = options.slicedLen(usage_rows.len, limit);56    if (std.mem.eql(u8, options.flagValue(args, "--format") orelse "", "json")) return try writeJson(allocator, name, usage_rows[0..displayed], usage_rows.len, limit);57    if (usage_rows.len == 0) return try output.writeOutFmt(allocator, "{s}: no usages found\n", .{name});58    var out: std.Io.Writer.Allocating = .init(allocator);59    try out.writer.print("Usages of {s} ({d}):\n\n", .{ name, usage_rows.len });60    try writeTable(allocator, &out.writer, usage_rows[0..displayed], usage_rows.len);61    return try output.writeOut(out.written());62}6364fn storedRows(allocator: std.mem.Allocator, source_nodes: []const model.Node, edges: []const model.Edge, rel: ?[]const u8) ![]const Row {65    var out: std.ArrayList(Row) = .empty;66    for (edges) |edge| {67        if (rel == null and !exports.isCoupling(edge.rel)) continue;68        const source_node = storedNode(source_nodes, edge.source);69        try out.append(allocator, .{70            .node = edge.source,71            .rel = edge.rel,72            .file = if (source_node) |node| node.file else null,73            .line = if (source_node) |node| node.line else null,74            .end_line = if (source_node) |node| node.end_line else null,75        });76    }77    std.mem.sort(Row, out.items, {}, rowLess);78    return try out.toOwnedSlice(allocator);79}8081fn storedNode(nodes: []const model.Node, name: []const u8) ?model.Node {82    for (nodes) |node| {83        if (std.mem.eql(u8, node.name, name)) return node;84    }85    return null;86}8788pub fn rows(allocator: std.mem.Allocator, graph: graph_mod.Graph, edges: []const model.Edge, rel: ?[]const u8) ![]const Row {89    var out: std.ArrayList(Row) = .empty;90    for (edges) |edge| {91        if (rel == null and !exports.isCoupling(edge.rel)) continue;92        const source_node = graph_mod.getNode(&graph, edge.source);93        try out.append(allocator, .{94            .node = edge.source,95            .rel = edge.rel,96            .file = if (source_node) |node| node.file else null,97            .line = if (source_node) |node| node.line else null,98            .end_line = if (source_node) |node| node.end_line else null,99        });100    }101    std.mem.sort(Row, out.items, {}, rowLess);102    return try out.toOwnedSlice(allocator);103}104105pub fn writeJson(allocator: std.mem.Allocator, target: []const u8, usage_rows: []const Row, total: usize, limit: i64) !u8 {106    var out: std.Io.Writer.Allocating = .init(allocator);107    var writer = pretty_json.Writer.init(&out.writer, .minified);108    try writer.beginObject();109    try writer.objectField("target");110    try writer.write(target);111    try writer.objectField("usages");112    try writer.beginArray();113    for (usage_rows) |row| {114        try writer.beginObject();115        try writer.objectField("node");116        try writer.write(row.node);117        try writer.objectField("rel");118        try writer.write(row.rel);119        if (row.file) |file| {120            try writer.objectField("file");121            try writer.write(file);122        }123        if (row.line) |line| {124            try writer.objectField("line");125            try writer.write(line);126        }127        if (row.end_line) |line| {128            try writer.objectField("end_line");129            try writer.write(line);130        }131        try writer.endObject();132    }133    try writer.endArray();134    try writer.objectField("count");135    try writer.write(total);136    try writer.objectField("displayed");137    try writer.write(usage_rows.len);138    try writer.objectField("truncated");139    try writer.write(usage_rows.len < total);140    try writer.objectField("limit");141    try writer.write(limit);142    try writer.endObject();143    try out.writer.writeByte('\n');144    return try output.writeOut(out.written());145}146147pub fn writeTable(allocator: std.mem.Allocator, writer: *std.Io.Writer, usage_rows: []const Row, total: usize) !void {148    const columns = [_]table.Column{149        .{ .header = "rel", .max_width = 16 },150        .{ .header = "node", .max_width = 48 },151        .{ .header = "file", .max_width = 56 },152    };153    var scratch_state = std.heap.ArenaAllocator.init(allocator);154    defer scratch_state.deinit();155    const scratch = scratch_state.allocator();156    var table_rows: std.ArrayList([]const []const u8) = .empty;157    for (usage_rows) |row| {158        try table.appendRow(scratch, &table_rows, &.{159            row.rel,160            row.node,161            try location(scratch, row),162        });163    }164    try table.writeJsonOption(allocator, writer, &columns, table_rows.items, total, "--format json");165}166167fn rowLess(_: void, a: Row, b: Row) bool {168    const file_order = std.mem.order(u8, a.file orelse "", b.file orelse "");169    if (file_order != .eq) return file_order == .lt;170    const line_a = a.line orelse 0;171    const line_b = b.line orelse 0;172    if (line_a != line_b) return line_a < line_b;173    const rel_order = std.mem.order(u8, a.rel, b.rel);174    if (rel_order != .eq) return rel_order == .lt;175    return std.mem.lessThan(u8, a.node, b.node);176}177178fn location(allocator: std.mem.Allocator, row: Row) ![]const u8 {179    const file = row.file orelse return "";180    if (row.line) |line| {181        if (row.end_line) |end_line| {182            if (end_line != line) return try std.fmt.allocPrint(allocator, "{s}:{d}-{d}", .{ file, line, end_line });183        }184        return try std.fmt.allocPrint(allocator, "{s}:{d}", .{ file, line });185    }186    return file;187}188189test "usage rows filter coupling edges and render compact locations" {190    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);191    defer arena.deinit();192    const allocator = arena.allocator();193    var graph = graph_mod.init(allocator);194    try graph_mod.addNode(&graph, .{ .name = "target", .type = model.NodeType.function, .file = "src/app.py", .line = 1 });195    try graph_mod.addNode(&graph, .{ .name = "owner", .type = model.NodeType.module, .file = "src/app.py" });196    try graph_mod.addNode(&graph, .{ .name = "caller_a", .type = model.NodeType.function, .file = "src/app.py", .line = 20 });197    try graph_mod.addNode(&graph, .{ .name = "caller_b", .type = model.NodeType.function, .file = "src/app.py", .line = 10 });198    try graph_mod.addEdge(&graph, .{ .source = "owner", .rel = model.RelType.contains, .target = "target" });199    try graph_mod.addEdge(&graph, .{ .source = "caller_a", .rel = model.RelType.calls, .target = "target" });200    try graph_mod.addEdge(&graph, .{ .source = "caller_b", .rel = model.RelType.imports, .target = "target" });201    const incoming = try view.incoming(graph, allocator, "target", null);202    const usage_rows = try rows(allocator, graph, incoming, null);203    try std.testing.expectEqual(@as(usize, 2), usage_rows.len);204    try std.testing.expectEqualStrings("caller_b", usage_rows[0].node);205    try std.testing.expectEqualStrings("caller_a", usage_rows[1].node);206    var out: std.Io.Writer.Allocating = .init(allocator);207    try out.writer.writeAll("Usages of target (2):\n\n");208    try writeTable(allocator, &out.writer, usage_rows, usage_rows.len);209    try std.testing.expectEqualStrings(210        \\Usages of target (2):211        \\212        \\rel      node      file213        \\-------  --------  -------------214        \\imports  caller_b  src/app.py:10215        \\calls    caller_a  src/app.py:20216        \\217    , out.written());218    var truncated: std.Io.Writer.Allocating = .init(allocator);219    try writeTable(allocator, &truncated.writer, usage_rows[0..1], usage_rows.len);220    try std.testing.expectEqualStrings(221        "rel      node      file\n" ++222            "-------  --------  -------------\n" ++223            "imports  caller_b  src/app.py:10\n" ++224            "(showing 1 of 2 \xE2\x80\x94 use --limit 0 for all, --format json for exact records)\n",225        truncated.written(),226    );227}