tiny.smg.exports

1const std = @import("std");2const graph_mod = @import("graph.zig");3const api = @import("api.zig");4const view = @import("view.zig");5const model = @import("model.zig");6const pretty = @import("pretty");7const json = pretty.json;89pub fn toJson(allocator: std.mem.Allocator, graph: graph_mod.Graph, indent: bool) ![]const u8 {10    var out: std.Io.Writer.Allocating = .init(allocator);11    errdefer out.deinit();12    const nodes = try view.allNodes(graph, allocator, null);13    const edges = try view.allEdges(graph, allocator);14    var writer = json.Writer.init(&out.writer, if (indent) .indent_2 else .minified);15    try writer.beginObject();16    try writer.objectField("nodes");17    try writer.beginArray();18    for (nodes) |node| try writeNodeDataObject(allocator, &writer, node);19    try writer.endArray();20    try writer.objectField("edges");21    try writer.beginArray();22    for (edges) |edge| try writeEdgeDataObject(allocator, &writer, edge);23    try writer.endArray();24    try writer.endObject();25    try out.writer.writeByte('\n');26    return try out.toOwnedSlice();27}2829pub fn nodeJson(allocator: std.mem.Allocator, node: model.Node, incoming: []const model.Edge, outgoing: []const model.Edge) ![]const u8 {30    var out: std.Io.Writer.Allocating = .init(allocator);31    errdefer out.deinit();32    var writer = json.Writer.init(&out.writer, .minified);33    try writer.beginObject();34    try writeNodeDataFields(allocator, node, &writer);35    try writer.objectField("incoming");36    try writer.beginArray();37    for (incoming) |edge| {38        try writer.beginObject();39        try writer.objectField("source");40        try writer.write(edge.source);41        try writer.objectField("rel");42        try writer.write(edge.rel);43        try writer.endObject();44    }45    try writer.endArray();46    try writer.objectField("outgoing");47    try writer.beginArray();48    for (outgoing) |edge| {49        try writer.beginObject();50        try writer.objectField("target");51        try writer.write(edge.target);52        try writer.objectField("rel");53        try writer.write(edge.rel);54        try writer.endObject();55    }56    try writer.endArray();57    try writer.endObject();58    try out.writer.writeByte('\n');59    return try out.toOwnedSlice();60}6162fn writeNodeDataObject(allocator: std.mem.Allocator, writer: *json.Writer, node: model.Node) !void {63    try writer.beginObject();64    try writeNodeDataFields(allocator, node, writer);65    try writer.endObject();66}6768fn writeNodeDataFields(allocator: std.mem.Allocator, node: model.Node, writer: *json.Writer) !void {69    try writer.objectField("name");70    try writer.write(node.name);71    try writer.objectField("type");72    try writer.write(node.type);73    if (node.file) |file| {74        try writer.objectField("file");75        try writer.write(file);76    }77    if (node.line) |line| {78        try writer.objectField("line");79        try writer.write(line);80    }81    if (node.end_line) |line| {82        try writer.objectField("end_line");83        try writer.write(line);84    }85    if (node.docstring) |doc| {86        try writer.objectField("docstring");87        try writer.write(doc);88    }89    if (node.metadata.len != 0) try writeMetadata(allocator, writer, node.metadata);90}9192fn writeEdgeDataObject(allocator: std.mem.Allocator, writer: *json.Writer, edge: model.Edge) !void {93    try writer.beginObject();94    try writer.objectField("source");95    try writer.write(edge.source);96    try writer.objectField("rel");97    try writer.write(edge.rel);98    try writer.objectField("target");99    try writer.write(edge.target);100    if (edge.metadata.len != 0) try writeMetadata(allocator, writer, edge.metadata);101    try writer.endObject();102}103104fn writeMetadata(allocator: std.mem.Allocator, writer: *json.Writer, metadata: []const model.Pair) !void {105    try writer.objectField("metadata");106    try writer.beginObject();107    for (metadata) |pair| {108        try writer.objectField(pair.key);109        if (pair.json) {110            var parsed = std.json.parseFromSlice(std.json.Value, allocator, pair.value, .{}) catch {111                try writer.raw(pair.value);112                continue;113            };114            defer parsed.deinit();115            try writer.write(parsed.value);116        } else {117            try writer.write(pair.value);118        }119    }120    try writer.endObject();121}122123pub fn toText(allocator: std.mem.Allocator, graph: graph_mod.Graph) ![]const u8 {124    var out: std.Io.Writer.Allocating = .init(allocator);125    errdefer out.deinit();126    const nodes = try view.allNodes(graph, allocator, null);127    if (nodes.len == 0) return try allocator.dupe(u8, "Empty graph.");128    const edges = try view.allEdges(graph, allocator);129    try out.writer.print("Nodes ({d}):\n", .{nodes.len});130    for (nodes) |node| {131        try out.writer.print("  [{s}] {s}", .{ node.type, node.name });132        if (node.file) |file| {133            try out.writer.print("\n    @ {s}", .{file});134            if (node.line) |line| try out.writer.print(":{d}", .{line});135        }136        if (node.docstring) |doc| try out.writer.print("\n    # {s}", .{doc});137        try out.writer.writeByte('\n');138    }139    if (edges.len != 0) {140        try out.writer.print("\nEdges ({d}):\n", .{edges.len});141        for (edges) |edge| try out.writer.print("  {s} --{s}--> {s}\n", .{ edge.source, edge.rel, edge.target });142    }143    return try out.toOwnedSlice();144}145146pub fn toMermaid(allocator: std.mem.Allocator, graph: graph_mod.Graph) ![]const u8 {147    var out: std.Io.Writer.Allocating = .init(allocator);148    errdefer out.deinit();149    const nodes = try view.allNodes(graph, allocator, null);150    const edges = try view.allEdges(graph, allocator);151    try out.writer.writeAll("graph TD\n");152    for (nodes) |node| {153        try out.writer.print("    {s}[\"{s} ({s})\"]\n", .{ try ident(allocator, node.name), node.name, node.type });154    }155    for (edges) |edge| {156        try out.writer.print("    {s} -->|{s}| {s}\n", .{ try ident(allocator, edge.source), edge.rel, try ident(allocator, edge.target) });157    }158    return try out.toOwnedSlice();159}160161pub fn toDot(allocator: std.mem.Allocator, graph: graph_mod.Graph) ![]const u8 {162    var out: std.Io.Writer.Allocating = .init(allocator);163    errdefer out.deinit();164    const nodes = try view.allNodes(graph, allocator, null);165    const edges = try view.allEdges(graph, allocator);166    try out.writer.writeAll("digraph smg {\n    rankdir=LR;\n");167    for (nodes) |node| {168        try out.writer.print("    {s} [label=\"{s}\\n({s})\"];\n", .{ try ident(allocator, node.name), node.name, node.type });169    }170    for (edges) |edge| {171        try out.writer.print("    {s} -> {s} [label=\"{s}\"];\n", .{ try ident(allocator, edge.source), try ident(allocator, edge.target), edge.rel });172    }173    try out.writer.writeAll("}\n");174    return try out.toOwnedSlice();175}176177pub fn toDsm(allocator: std.mem.Allocator, graph: graph_mod.Graph, level: []const u8) ![]const u8 {178    const nodes = try view.allNodes(graph, allocator, null);179    const edges = try view.allEdges(graph, allocator);180    var names: std.ArrayList([]const u8) = .empty;181    for (nodes) |node| {182        if (std.mem.eql(u8, level, "all") or std.mem.eql(u8, node.type, model.NodeType.module) or std.mem.eql(u8, node.type, model.NodeType.package) or (std.mem.eql(u8, level, "class") and std.mem.eql(u8, node.type, model.NodeType.class))) {183            try names.append(allocator, node.name);184        }185    }186    if (names.items.len == 0) return try allocator.dupe(u8, "");187    var map = std.StringHashMap([]const u8).init(allocator);188    for (nodes) |node| {189        if (containsName(names.items, node.name)) {190            try map.put(node.name, node.name);191            continue;192        }193        if (std.mem.eql(u8, level, "all")) continue;194        if (try containingOwner(allocator, graph, node.name, names.items)) |owner_name| try map.put(node.name, owner_name);195    }196    var out: std.Io.Writer.Allocating = .init(allocator);197    errdefer out.deinit();198    try out.writer.writeAll("");199    for (names.items) |name| {200        try out.writer.writeByte(',');201        try out.writer.writeAll(name);202    }203    try out.writer.writeByte('\n');204    for (names.items) |row| {205        try out.writer.writeAll(row);206        for (names.items) |col| {207            var count: usize = 0;208            for (edges) |edge| {209                if (!isCoupling(edge.rel)) continue;210                const source = map.get(edge.source) orelse continue;211                const target = map.get(edge.target) orelse continue;212                if (!std.mem.eql(u8, source, target) and std.mem.eql(u8, source, row) and std.mem.eql(u8, target, col)) count += 1;213            }214            try out.writer.print(",{d}", .{count});215        }216        try out.writer.writeByte('\n');217    }218    return try out.toOwnedSlice();219}220221pub fn isCoupling(rel: []const u8) bool {222    return std.mem.eql(u8, rel, model.RelType.calls) or223        std.mem.eql(u8, rel, model.RelType.imports) or224        std.mem.eql(u8, rel, model.RelType.inherits) or225        std.mem.eql(u8, rel, model.RelType.implements) or226        std.mem.eql(u8, rel, model.RelType.depends_on);227}228229pub const coupling_relations: []const []const u8 = relations: {230    const names = @typeInfo(model.RelType).@"struct".decl_names;231    var selected: [names.len][]const u8 = undefined;232    var count: usize = 0;233    for (names) |name| {234        const relation: []const u8 = @field(model.RelType, name);235        if (!isCoupling(relation)) continue;236        selected[count] = relation;237        count += 1;238    }239    const bound = selected[0..count].*;240    break :relations &bound;241};242243pub fn isNamespaceHandleImport(rel: []const u8, source: []const u8, target: []const u8) bool {244    if (!std.mem.eql(u8, rel, model.RelType.imports)) return false;245    if (std.mem.eql(u8, source, target)) return false;246    if (!std.mem.endsWith(u8, target, ".root")) return false;247    const namespace = target[0 .. target.len - ".root".len];248    if (source.len <= namespace.len + 1) return false;249    if (!std.mem.startsWith(u8, source, namespace)) return false;250    return source[namespace.len] == '.';251}252253/// Returns whether an edge belongs in architecture coupling metrics.254///255/// Raw graph queries and exports retain namespace-handle and test edges.256pub fn isArchitectureCoupling(graph: graph_mod.Graph, edge: model.Edge) bool {257    if (!isCoupling(edge.rel)) return false;258    if (isNamespaceHandleImport(edge.rel, edge.source, edge.target)) return false;259    if (graph_mod.getNode(&graph, edge.source)) |node| {260        if (api.isTestDeclaration(node)) return false;261    }262    if (graph_mod.getNode(&graph, edge.target)) |node| {263        if (api.isTestDeclaration(node)) return false;264    }265    return true;266}267268test "coupling relation table matches the coupling predicate" {269    const names = @typeInfo(model.RelType).@"struct".decl_names;270    var coupling: usize = 0;271    inline for (names) |name| {272        const relation: []const u8 = @field(model.RelType, name);273        var listed = false;274        for (coupling_relations) |candidate| {275            if (std.mem.eql(u8, candidate, relation)) listed = true;276        }277        try std.testing.expectEqual(isCoupling(relation), listed);278        if (listed) coupling += 1;279    }280    try std.testing.expectEqual(coupling, coupling_relations.len);281}282283test "namespace handle imports cover ancestor handles but not cross-package roots" {284    try std.testing.expect(isNamespaceHandleImport("imports", "lib.agent.src.facet", "lib.agent.src.root"));285    try std.testing.expect(isNamespaceHandleImport("imports", "lib.agent.src.facets.lisp", "lib.agent.src.root"));286    try std.testing.expect(!isNamespaceHandleImport("imports", "lib.lang.src.runtime.bindings", "lib.preserves.src.root"));287    try std.testing.expect(!isNamespaceHandleImport("imports", "lib.agent.src.root", "lib.agent.src.facet"));288    try std.testing.expect(!isNamespaceHandleImport("calls", "lib.agent.src.facet.step", "lib.agent.src.root.Event"));289    try std.testing.expect(!isNamespaceHandleImport("imports", "lib.agent.src.root", "lib.agent.src.root"));290}291292test "architecture coupling excludes namespace handles and test declarations" {293    var graph = graph_mod.init(std.testing.allocator);294    defer graph_mod.deinit(&graph);295    const test_metadata = [_]model.Pair{.{ .key = api.test_key, .value = "true" }};296    try graph_mod.addNode(&graph, .{ .name = "pkg.root", .type = model.NodeType.module });297    try graph_mod.addNode(&graph, .{ .name = "pkg.worker", .type = model.NodeType.function });298    try graph_mod.addNode(&graph, .{ .name = "pkg.test_worker", .type = model.NodeType.function, .metadata = &test_metadata });299300    const handle: model.Edge = .{ .source = "pkg.worker", .rel = model.RelType.imports, .target = "pkg.root" };301    const production: model.Edge = .{ .source = "pkg.root", .rel = model.RelType.calls, .target = "pkg.worker" };302    const test_call: model.Edge = .{ .source = "pkg.test_worker", .rel = model.RelType.calls, .target = "pkg.worker" };303    try std.testing.expect(isCoupling(handle.rel));304    try std.testing.expect(isCoupling(test_call.rel));305    try std.testing.expect(!isArchitectureCoupling(graph, handle));306    try std.testing.expect(isArchitectureCoupling(graph, production));307    try std.testing.expect(!isArchitectureCoupling(graph, test_call));308}309310fn ident(allocator: std.mem.Allocator, value: []const u8) ![]const u8 {311    const out = try allocator.dupe(u8, value);312    for (out) |*byte| {313        if (!std.ascii.isAlphanumeric(byte.*)) byte.* = '_';314    }315    return out;316}317318fn csvCell(writer: *std.Io.Writer, value: []const u8) !void {319    if (std.mem.indexOfAny(u8, value, ",\"\n") == null) {320        try writer.writeAll(value);321        return;322    }323    try writer.writeByte('"');324    for (value) |byte| {325        if (byte == '"') try writer.writeByte('"');326        try writer.writeByte(byte);327    }328    try writer.writeByte('"');329}330331fn cmpString(_: void, a: []const u8, b: []const u8) bool {332    return std.mem.lessThan(u8, a, b);333}334335fn containsName(names: []const []const u8, name: []const u8) bool {336    for (names) |item| if (std.mem.eql(u8, item, name)) return true;337    return false;338}339340fn containingOwner(allocator: std.mem.Allocator, graph: graph_mod.Graph, name: []const u8, names: []const []const u8) !?[]const u8 {341    var current = name;342    while (true) {343        const incoming = try view.incoming(graph, allocator, current, model.RelType.contains);344        if (incoming.len == 0) return null;345        current = incoming[0].source;346        if (containsName(names, current)) return current;347    }348}349350fn sampleGraph(allocator: std.mem.Allocator) !graph_mod.Graph {351    var graph = graph_mod.init(allocator);352    try graph_mod.addNode(&graph, .{ .name = "app", .type = model.NodeType.module });353    try graph_mod.addNode(&graph, .{ .name = "app.main", .type = model.NodeType.function, .file = "app.py", .line = 1 });354    try graph_mod.addEdge(&graph, .{ .source = "app", .target = "app.main", .rel = model.RelType.contains });355    return graph;356}357358test "json export omits storage kind" {359    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);360    defer arena.deinit();361    const allocator = arena.allocator();362    const graph = try sampleGraph(allocator);363    const rendered_json = try toJson(allocator, graph, false);364    try std.testing.expect(std.mem.indexOf(u8, rendered_json, "\"kind\"") == null);365    try std.testing.expect(std.mem.indexOf(u8, rendered_json, "\"nodes\"") != null);366    try std.testing.expect(std.mem.indexOf(u8, rendered_json, "\"edges\"") != null);367    const pretty_json = try toJson(allocator, graph, true);368    try std.testing.expectEqualStrings(369        \\{370        \\  "nodes": [371        \\    {372        \\      "name": "app",373        \\      "type": "module"374        \\    },375        \\    {376        \\      "name": "app.main",377        \\      "type": "function",378        \\      "file": "app.py",379        \\      "line": 1380        \\    }381        \\  ],382        \\  "edges": [383        \\    {384        \\      "source": "app",385        \\      "rel": "contains",386        \\      "target": "app.main"387        \\    }388        \\  ]389        \\}390        \\391    , pretty_json);392}393394test "indented json export renders nested metadata through pretty json" {395    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);396    defer arena.deinit();397    const allocator = arena.allocator();398    const metadata = [_]model.Pair{399        .{ .key = "metrics", .value = "{\"fan_in\":1,\"tags\":[\"alpha\",2]}", .json = true },400        .{ .key = "source", .value = "manual" },401    };402    var graph = graph_mod.init(allocator);403    try graph_mod.addNode(&graph, .{ .name = "app", .type = model.NodeType.module, .metadata = &metadata });404405    const pretty_json = try toJson(allocator, graph, true);406    try std.testing.expect(std.mem.indexOf(u8, pretty_json,407        \\      "metadata": {408        \\        "metrics": {409        \\          "fan_in": 1,410        \\          "tags": [411        \\            "alpha",412        \\            2413        \\          ]414        \\        },415        \\        "source": "manual"416        \\      }417    ) != null);418}419420test "text mermaid dot and dsm match python contract markers" {421    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);422    defer arena.deinit();423    const allocator = arena.allocator();424    const empty = graph_mod.init(allocator);425    try std.testing.expectEqualStrings("Empty graph.", try toText(allocator, empty));426    var graph = try sampleGraph(allocator);427    const text_out = try toText(allocator, graph);428    try std.testing.expect(std.mem.indexOf(u8, text_out, "Nodes (2):") != null);429    try std.testing.expect(std.mem.indexOf(u8, text_out, "[module] app") != null);430    const mermaid = try toMermaid(allocator, graph);431    try std.testing.expect(std.mem.startsWith(u8, mermaid, "graph TD"));432    try std.testing.expect(std.mem.indexOf(u8, mermaid, "-->|contains|") != null);433    const dot = try toDot(allocator, graph);434    try std.testing.expect(std.mem.startsWith(u8, dot, "digraph smg {"));435    try std.testing.expect(std.mem.indexOf(u8, dot, "label=\"contains\"") != null);436    try graph_mod.addNode(&graph, .{ .name = "lib", .type = model.NodeType.module });437    try graph_mod.addNode(&graph, .{ .name = "lib.f", .type = model.NodeType.function });438    try graph_mod.addEdge(&graph, .{ .source = "lib", .target = "lib.f", .rel = model.RelType.contains });439    try graph_mod.addEdge(&graph, .{ .source = "app.main", .target = "lib.f", .rel = model.RelType.calls });440    const dsm = try toDsm(allocator, graph, "module");441    try std.testing.expect(std.mem.startsWith(u8, dsm, ",app,lib"));442    try std.testing.expect(std.mem.indexOf(u8, dsm, "app,0,1") != null);443}

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