tiny.smg.api

1//! Render-neutral public-surface facts derived from a scanned graph.23const std = @import("std");4const graph_mod = @import("graph.zig");5const limits_mod = @import("limits/root.zig");6const model = @import("model.zig");78const testing_limits = @import("root.zig").default_limits.api;910pub const visibility_key = "visibility";11pub const test_key = "test";12pub const signature_key = "signature";13pub const alias_target_key = "alias_target";14pub const direct_alias_target_key = "zig_direct_alias_target";15pub const declared_type_key = "zig_declared_type";16pub const declared_type_state_key = "zig_declared_type_state";17pub const container_kind_key = "zig_container_kind";18pub const member_identifier_key = "zig_member_identifier";19pub const member_order_key = "zig_member_order";20pub const source_spelling_key = "zig_source_spelling";21pub const member_type_key = "zig_member_type";22pub const member_expression_key = "zig_member_expression";23pub const member_gap_key = "zig_member_gap";24pub const source_start_byte_key = "source_start_byte";25pub const source_end_byte_key = "source_end_byte";26pub const source_hash_key = "source_sha256";27pub const source_digest_bytes = std.crypto.hash.sha2.Sha256.digest_length;28pub const source_digest_hex_bytes = source_digest_bytes * 2;2930pub const Error = graph_mod.Error || error{31    AliasCycle,32    DeclaredTypeUnavailable,33    InvalidPublicPath,34    InvalidSourceDigest,35    InvalidSourceSpan,36    InvalidPublicMember,37    NotPublicDeclaration,38    PublicPathDepthExceeded,39    PublicPathNotFound,40    SourceDigestUnavailable,41    SourceDigestMismatch,42    SourceFileUnavailable,43    SourceSpanUnavailable,44};4546/// A Zig container category preserved independently from graph node roles.47pub const ContainerKind = enum {48    @"struct",49    @"enum",50    error_set,51    @"union",52    @"opaque",53};5455/// A source-level member category that is part of a public Zig type surface.56pub const MemberKind = enum {57    field,58    enum_tag,59    error_member,60};6162/// Why a source member is preserved but not projected as a PublicMember.63pub const MemberGapKind = enum {64    unsupported_container_member,65    unsupported_member_syntax,66};6768/// An exact half-open byte range in a source file.69pub const SourceSpan = struct {70    start_byte: u32,71    end_byte: u32,72};7374/// Validated source location and digest for one declaration.75pub const DeclarationSource = struct {76    file: []const u8,77    span: SourceSpan,78    digest: [source_digest_bytes]u8,79};8081/// A public binding and the definition reached through its alias chain.82pub const PublicDeclaration = struct {83    exported: model.Node,84    canonical: model.Node,8586    /// Returns source-owned export docs or docs on the exact canonical declaration.87    pub fn documentation(self: PublicDeclaration) ?[]const u8 {88        if (self.exported.docstring) |docstring| return docstring;89        if (sameSourceFile(self.exported, self.canonical)) {90            if (moduleNode(self.canonical)) return null;91        }92        return self.canonical.docstring;93    }9495    /// Returns the exact source span of the exported binding.96    pub fn bindingSourceSpan(self: PublicDeclaration) Error!SourceSpan {97        return declarationSourceSpan(self.exported);98    }99100    /// Returns the exact source span of the canonical definition.101    pub fn canonicalSourceSpan(self: PublicDeclaration) Error!SourceSpan {102        return declarationSourceSpan(self.canonical);103    }104105    /// Returns validated source evidence for the exported binding.106    pub fn bindingSource(self: PublicDeclaration) Error!DeclarationSource {107        return declarationSource(self.exported);108    }109110    /// Returns validated source evidence for the canonical definition.111    pub fn canonicalSource(self: PublicDeclaration) Error!DeclarationSource {112        return declarationSource(self.canonical);113    }114};115116/// Returns a validated exact source span stored on one declaration node.117pub fn declarationSourceSpan(node: model.Node) Error!SourceSpan {118    const start_raw = model.pairValue(node.metadata, source_start_byte_key);119    const end_raw = model.pairValue(node.metadata, source_end_byte_key);120    if (start_raw == null and end_raw == null) return error.SourceSpanUnavailable;121    if (start_raw == null or end_raw == null) return error.InvalidSourceSpan;122    const start = std.fmt.parseInt(u32, start_raw.?, 10) catch123        return error.InvalidSourceSpan;124    const end = std.fmt.parseInt(u32, end_raw.?, 10) catch125        return error.InvalidSourceSpan;126    if (start >= end) return error.InvalidSourceSpan;127    return .{ .start_byte = start, .end_byte = end };128}129130/// Returns validated file, span, and digest evidence for one declaration node.131pub fn declarationSource(node: model.Node) Error!DeclarationSource {132    const file = node.file orelse return error.SourceFileUnavailable;133    if (file.len == 0) return error.SourceFileUnavailable;134    const encoded = model.pairValue(node.metadata, source_hash_key) orelse135        return error.SourceDigestUnavailable;136    if (encoded.len != source_digest_hex_bytes) {137        return error.InvalidSourceDigest;138    }139    for (encoded) |byte| {140        if (!std.ascii.isHex(byte) or std.ascii.isUpper(byte)) {141            return error.InvalidSourceDigest;142        }143    }144    var digest: [source_digest_bytes]u8 = undefined;145    _ = std.fmt.hexToBytes(&digest, encoded) catch146        return error.InvalidSourceDigest;147    return .{148        .file = file,149        .span = try declarationSourceSpan(node),150        .digest = digest,151    };152}153154/// Returns the SHA-256 digest for exact source bytes.155pub fn sourceDigest(source: []const u8) [source_digest_bytes]u8 {156    var digest: [source_digest_bytes]u8 = undefined;157    std.crypto.hash.sha2.Sha256.hash(source, &digest, .{});158    return digest;159}160161/// Returns the exact declaration bytes after validating their stored span and digest.162pub fn verifiedSource(163    evidence: DeclarationSource,164    contents: []const u8,165) Error![]const u8 {166    if (evidence.span.start_byte >= evidence.span.end_byte or167        evidence.span.end_byte > contents.len)168    {169        return error.InvalidSourceSpan;170    }171    const exact = contents[evidence.span.start_byte..evidence.span.end_byte];172    const digest = sourceDigest(exact);173    if (!std.mem.eql(u8, &digest, &evidence.digest)) {174        return error.SourceDigestMismatch;175    }176    return exact;177}178179/// A member admitted through a public export and owned by its canonical type.180///181/// The record and its strings borrow from the unchanged graph. Only the slice182/// returned by publicMembers is allocated.183pub const PublicMember = struct {184    owner: PublicDeclaration,185    node: model.Node,186    kind: MemberKind,187    /// The zero-based ordinal among source members owned by the canonical type.188    order: u32,189190    /// Returns the exact identifier token, or null for a positional field.191    pub fn identifier(self: PublicMember) ?[]const u8 {192        return memberIdentifier(self.node);193    }194195    /// Returns the exact source spelling of the member, excluding its docs.196    pub fn sourceSpelling(self: PublicMember) []const u8 {197        return model.pairValue(self.node.metadata, source_spelling_key) orelse198            unreachable;199    }200201    /// Returns the exact field type expression when the source has one.202    pub fn typeExpression(self: PublicMember) ?[]const u8 {203        return model.pairValue(self.node.metadata, member_type_key);204    }205206    /// Returns an exact field default or enum assigned-value expression.207    ///208    /// The explicit member kind determines how a renderer labels the value.209    pub fn valueExpression(self: PublicMember) ?[]const u8 {210        return model.pairValue(self.node.metadata, member_expression_key);211    }212213    /// Returns source-owned documentation attached to this member.214    pub fn documentation(self: PublicMember) ?[]const u8 {215        return self.node.docstring;216    }217218    /// Returns the exact half-open source byte range of sourceSpelling.219    pub fn sourceSpan(self: PublicMember) SourceSpan {220        return memberSourceSpan(self.node) orelse unreachable;221    }222};223224/// A source member deliberately outside the supported public projection.225///226/// The record and its strings borrow from the unchanged graph. Only the slice227/// returned by publicMemberGaps is allocated.228pub const PublicMemberGap = struct {229    owner: PublicDeclaration,230    node: model.Node,231    kind: MemberGapKind,232    /// The zero-based ordinal among source members owned by the canonical type.233    order: u32,234235    /// Returns an exact identifier token when the source member has one.236    pub fn identifier(self: PublicMemberGap) ?[]const u8 {237        return memberIdentifier(self.node);238    }239240    /// Returns the exact source spelling of the unsupported member.241    pub fn sourceSpelling(self: PublicMemberGap) []const u8 {242        return model.pairValue(self.node.metadata, source_spelling_key) orelse243            unreachable;244    }245246    /// Returns source-owned documentation attached to this member.247    pub fn documentation(self: PublicMemberGap) ?[]const u8 {248        return self.node.docstring;249    }250251    /// Returns the exact half-open source byte range of sourceSpelling.252    pub fn sourceSpan(self: PublicMemberGap) SourceSpan {253        return memberSourceSpan(self.node) orelse unreachable;254    }255};256257/// Returns the borrowed name of the scanned module or package that owns a source file.258pub fn ownerForFile(graph: graph_mod.Graph, file: []const u8) Error![]const u8 {259    var owner: ?[]const u8 = null;260    for (graph.nodes.items) |node| {261        if (!moduleNode(node)) continue;262        if (!std.mem.eql(u8, node.file orelse continue, file)) continue;263        if (owner != null) return error.AmbiguousName;264        owner = node.name;265    }266    return owner orelse error.NodeNotFound;267}268269/// Returns public children in stable exported-name order.270///271/// The slice owns only its records. Node strings borrow from the unchanged graph.272pub fn publicDeclarations(273    allocator: std.mem.Allocator,274    graph: graph_mod.Graph,275    owner: []const u8,276    limits: limits_mod.Api,277) (std.mem.Allocator.Error || Error)![]PublicDeclaration {278    if (graph_mod.getNode(&graph, owner) == null) return error.NodeNotFound;279    var count: usize = 0;280    for (graph_mod.outgoingEdges(&graph, owner)) |edge_index| {281        const edge = graph.edges.items[edge_index];282        if (!std.mem.eql(u8, edge.rel, model.RelType.contains)) continue;283        const node = graph_mod.getNode(&graph, edge.target) orelse continue;284        if (isPublic(node)) count += 1;285    }286    const declarations = try allocator.alloc(PublicDeclaration, count);287    errdefer allocator.free(declarations);288    var index: usize = 0;289    for (graph_mod.outgoingEdges(&graph, owner)) |edge_index| {290        const edge = graph.edges.items[edge_index];291        if (!std.mem.eql(u8, edge.rel, model.RelType.contains)) continue;292        const node = graph_mod.getNode(&graph, edge.target) orelse continue;293        if (!isPublic(node)) continue;294        declarations[index] = .{295            .exported = node,296            .canonical = try canonicalDeclaration(graph, node, limits),297        };298        index += 1;299    }300    std.debug.assert(index == declarations.len);301    std.mem.sort(PublicDeclaration, declarations, {}, declarationLessThan);302    return declarations;303}304305/// Releases the record slice returned by publicDeclarations.306pub fn freePublicDeclarations(307    allocator: std.mem.Allocator,308    declarations: []PublicDeclaration,309) void {310    allocator.free(declarations);311}312313/// Resolves one exact dotted path through the public surface of an owner.314///315/// The returned nodes borrow from the unchanged graph. A quoted Zig identifier316/// may contain dots and is treated as one path component.317pub fn resolvePublicPath(318    allocator: std.mem.Allocator,319    graph: graph_mod.Graph,320    owner: []const u8,321    path: []const u8,322    limits: limits_mod.Api,323) (std.mem.Allocator.Error || Error)!PublicDeclaration {324    if (path.len == 0 or path[0] == '.' or path[path.len - 1] == '.') {325        return error.InvalidPublicPath;326    }327    var current_owner = owner;328    var remaining = path;329    for (0..limits.public_path_depth) |_| {330        const component_end = try publicPathComponentEnd(remaining);331        const component = remaining[0..component_end];332        if (component.len == 0) return error.InvalidPublicPath;333334        const declarations = try publicDeclarations(allocator, graph, current_owner, limits);335        defer freePublicDeclarations(allocator, declarations);336        var found: ?PublicDeclaration = null;337        for (declarations) |declaration| {338            const name = directPublicName(current_owner, declaration.exported.name) orelse339                continue;340            if (!std.mem.eql(u8, name, component)) continue;341            if (found != null) return error.AmbiguousName;342            found = declaration;343        }344        const declaration = found orelse return error.PublicPathNotFound;345        if (component_end == remaining.len) return declaration;346        current_owner = declaration.canonical.name;347        remaining = remaining[component_end + 1 ..];348    }349    return error.PublicPathDepthExceeded;350}351352fn directPublicName(owner: []const u8, name: []const u8) ?[]const u8 {353    if (!std.mem.startsWith(u8, name, owner)) return null;354    if (name.len <= owner.len or name[owner.len] != '.') return null;355    const suffix = name[owner.len + 1 ..];356    if (suffix.len == 0) return null;357    return suffix;358}359360fn publicPathComponentEnd(path: []const u8) Error!usize {361    if (std.mem.startsWith(u8, path, "@\"")) {362        var index: usize = 2;363        var escaped = false;364        while (index < path.len) : (index += 1) {365            const byte = path[index];366            if (escaped) {367                escaped = false;368                continue;369            }370            if (byte == '\\') {371                escaped = true;372                continue;373            }374            if (byte != '"') continue;375            if (index + 1 == path.len or path[index + 1] == '.') return index + 1;376            return error.InvalidPublicPath;377        }378        return error.InvalidPublicPath;379    }380    return std.mem.indexOfScalar(u8, path, '.') orelse path.len;381}382383/// Returns canonical members admitted through one public Zig declaration.384///385/// The slice owns only its records. Nodes and strings borrow from the unchanged386/// graph. Opaque and non-container declarations return an empty slice.387pub fn publicMembers(388    allocator: std.mem.Allocator,389    graph: graph_mod.Graph,390    declaration: PublicDeclaration,391) (std.mem.Allocator.Error || Error)![]PublicMember {392    if (!isPublic(declaration.exported)) return error.NotPublicDeclaration;393    const owner = graph_mod.getNode(&graph, declaration.canonical.name) orelse394        return error.NodeNotFound;395    const expected = supportedMemberKind(containerKind(owner) orelse return &.{}) orelse396        return &.{};397    return try projectPublicMembers(allocator, graph, declaration, owner, expected);398}399400fn projectPublicMembers(401    allocator: std.mem.Allocator,402    graph: graph_mod.Graph,403    declaration: PublicDeclaration,404    owner: model.Node,405    expected: MemberKind,406) (std.mem.Allocator.Error || Error)![]PublicMember {407    var count: usize = 0;408    for (graph_mod.outgoingEdges(&graph, owner.name)) |edge_index| {409        const edge = graph.edges.items[edge_index];410        if (!std.mem.eql(u8, edge.rel, model.RelType.contains)) continue;411        const node = graph_mod.getNode(&graph, edge.target) orelse continue;412        const kind = nodeMemberKind(node) orelse continue;413        if (kind != expected) return error.InvalidPublicMember;414        count += 1;415    }416    if (count == 0) return &.{};417    const members = try allocator.alloc(PublicMember, count);418    errdefer allocator.free(members);419    var index: usize = 0;420    for (graph_mod.outgoingEdges(&graph, owner.name)) |edge_index| {421        const edge = graph.edges.items[edge_index];422        if (!std.mem.eql(u8, edge.rel, model.RelType.contains)) continue;423        const node = graph_mod.getNode(&graph, edge.target) orelse continue;424        const kind = nodeMemberKind(node) orelse continue;425        std.debug.assert(kind == expected);426        members[index] = try publicMember(declaration, node, kind);427        index += 1;428    }429    std.debug.assert(index == members.len);430    std.mem.sort(PublicMember, members, {}, memberLessThan);431    return members;432}433434/// Releases the record slice returned by publicMembers.435pub fn freePublicMembers(436    allocator: std.mem.Allocator,437    members: []PublicMember,438) void {439    if (members.len != 0) allocator.free(members);440}441442/// Returns explicit source members omitted from the supported projection.443///444/// The slice owns only its records. Nodes and strings borrow from the unchanged445/// graph. A container with no unsupported source members returns an empty slice.446pub fn publicMemberGaps(447    allocator: std.mem.Allocator,448    graph: graph_mod.Graph,449    declaration: PublicDeclaration,450) (std.mem.Allocator.Error || Error)![]PublicMemberGap {451    if (!isPublic(declaration.exported)) return error.NotPublicDeclaration;452    const owner = graph_mod.getNode(&graph, declaration.canonical.name) orelse453        return error.NodeNotFound;454    if (containerKind(owner) == null) return &.{};455    var count: usize = 0;456    for (graph_mod.outgoingEdges(&graph, owner.name)) |edge_index| {457        const edge = graph.edges.items[edge_index];458        if (!std.mem.eql(u8, edge.rel, model.RelType.contains)) continue;459        const node = graph_mod.getNode(&graph, edge.target) orelse continue;460        if (!std.mem.eql(u8, node.type, model.NodeType.member_gap)) continue;461        count += 1;462    }463    if (count == 0) return &.{};464    const gaps = try allocator.alloc(PublicMemberGap, count);465    errdefer allocator.free(gaps);466    var index: usize = 0;467    for (graph_mod.outgoingEdges(&graph, owner.name)) |edge_index| {468        const edge = graph.edges.items[edge_index];469        if (!std.mem.eql(u8, edge.rel, model.RelType.contains)) continue;470        const node = graph_mod.getNode(&graph, edge.target) orelse continue;471        if (!std.mem.eql(u8, node.type, model.NodeType.member_gap)) continue;472        gaps[index] = try publicMemberGap(declaration, node);473        index += 1;474    }475    std.debug.assert(index == gaps.len);476    std.mem.sort(PublicMemberGap, gaps, {}, memberGapLessThan);477    return gaps;478}479480/// Releases the record slice returned by publicMemberGaps.481pub fn freePublicMemberGaps(482    allocator: std.mem.Allocator,483    gaps: []PublicMemberGap,484) void {485    if (gaps.len != 0) allocator.free(gaps);486}487488pub fn visibility(node: model.Node) ?[]const u8 {489    return model.pairValue(node.metadata, visibility_key);490}491492pub fn isPublic(node: model.Node) bool {493    return std.mem.eql(u8, visibility(node) orelse return false, "public");494}495496/// Returns whether the scanner marked a declaration as test-only.497pub fn isTestDeclaration(node: model.Node) bool {498    return std.mem.eql(u8, model.pairValue(node.metadata, test_key) orelse return false, "true");499}500501pub fn signature(node: model.Node) ?[]const u8 {502    return model.pairValue(node.metadata, signature_key);503}504505pub fn aliasTarget(node: model.Node) ?[]const u8 {506    return model.pairValue(node.metadata, alias_target_key);507}508509/// Returns a source expression proved to be a direct declaration alias.510pub fn directAliasTarget(node: model.Node) ?[]const u8 {511    return model.pairValue(node.metadata, direct_alias_target_key);512}513514/// Returns the exact source-spelled Zig type annotation, or null when omitted.515///516/// The returned slice borrows node metadata from the unchanged graph.517/// DeclaredTypeUnavailable means the scanner could not prove either state or518/// encountered contradictory metadata. This fact makes no semantic type-519/// equality claim.520pub fn explicitDeclaredType(node: model.Node) Error!?[]const u8 {521    const state = model.pairValue(node.metadata, declared_type_state_key) orelse522        return error.DeclaredTypeUnavailable;523    const value = model.pairValue(node.metadata, declared_type_key);524    if (std.mem.eql(u8, state, "omitted")) {525        if (value != null) return error.DeclaredTypeUnavailable;526        return null;527    }528    if (!std.mem.eql(u8, state, "explicit")) {529        return error.DeclaredTypeUnavailable;530    }531    const raw = value orelse532        return error.DeclaredTypeUnavailable;533    if (raw.len == 0) return error.DeclaredTypeUnavailable;534    return raw;535}536537test "explicit declared type distinguishes omitted and unavailable states" {538    const Expectation = union(enum) {539        unavailable,540        omitted,541        explicit: []const u8,542    };543    const cases = [_]struct {544        name: []const u8,545        metadata: []const model.Pair,546        expectation: Expectation,547    }{548        .{ .name = "missing state", .metadata = &.{}, .expectation = .unavailable },549        .{ .name = "unknown state", .metadata = &.{.{ .key = declared_type_state_key, .value = "unknown" }}, .expectation = .unavailable },550        .{ .name = "explicit missing value", .metadata = &.{.{ .key = declared_type_state_key, .value = "explicit" }}, .expectation = .unavailable },551        .{ .name = "explicit empty value", .metadata = &.{ .{ .key = declared_type_state_key, .value = "explicit" }, .{ .key = declared_type_key, .value = "" } }, .expectation = .unavailable },552        .{ .name = "omitted with value", .metadata = &.{ .{ .key = declared_type_state_key, .value = "omitted" }, .{ .key = declared_type_key, .value = "u8" } }, .expectation = .unavailable },553        .{ .name = "omitted", .metadata = &.{.{ .key = declared_type_state_key, .value = "omitted" }}, .expectation = .omitted },554        .{ .name = "explicit", .metadata = &.{ .{ .key = declared_type_state_key, .value = "explicit" }, .{ .key = declared_type_key, .value = "?*const u8" } }, .expectation = .{ .explicit = "?*const u8" } },555    };556    for (cases) |case| {557        const node: model.Node = .{ .name = case.name, .type = model.NodeType.constant, .metadata = case.metadata };558        switch (case.expectation) {559            .unavailable => try std.testing.expectError(error.DeclaredTypeUnavailable, explicitDeclaredType(node)),560            .omitted => try std.testing.expect((try explicitDeclaredType(node)) == null),561            .explicit => |expected| {562                const actual = (try explicitDeclaredType(node)).?;563                try std.testing.expectEqualStrings(expected, actual);564                try std.testing.expect(actual.ptr == model.pairValue(node.metadata, declared_type_key).?.ptr);565            },566        }567    }568}569570/// Returns the explicit Zig container category stored by the scanner.571pub fn containerKind(node: model.Node) ?ContainerKind {572    const raw = model.pairValue(node.metadata, container_kind_key) orelse return null;573    return std.meta.stringToEnum(ContainerKind, raw);574}575576fn publicMember(577    owner: PublicDeclaration,578    node: model.Node,579    kind: MemberKind,580) Error!PublicMember {581    if (kind != .field and memberIdentifier(node) == null) {582        return error.InvalidPublicMember;583    }584    if (model.pairValue(node.metadata, source_spelling_key) == null) {585        return error.InvalidPublicMember;586    }587    const order = memberOrder(node) orelse return error.InvalidPublicMember;588    _ = memberSourceSpan(node) orelse return error.InvalidPublicMember;589    if (node.file == null or node.line == null or node.end_line == null) {590        return error.InvalidPublicMember;591    }592    return .{ .owner = owner, .node = node, .kind = kind, .order = order };593}594595fn publicMemberGap(596    owner: PublicDeclaration,597    node: model.Node,598) Error!PublicMemberGap {599    const raw = model.pairValue(node.metadata, member_gap_key) orelse600        return error.InvalidPublicMember;601    const kind = std.meta.stringToEnum(MemberGapKind, raw) orelse602        return error.InvalidPublicMember;603    if (model.pairValue(node.metadata, source_spelling_key) == null) {604        return error.InvalidPublicMember;605    }606    const order = memberOrder(node) orelse return error.InvalidPublicMember;607    _ = memberSourceSpan(node) orelse return error.InvalidPublicMember;608    if (node.file == null or node.line == null or node.end_line == null) {609        return error.InvalidPublicMember;610    }611    return .{ .owner = owner, .node = node, .kind = kind, .order = order };612}613614fn memberIdentifier(node: model.Node) ?[]const u8 {615    return model.pairValue(node.metadata, member_identifier_key);616}617618fn memberOrder(node: model.Node) ?u32 {619    const raw = model.pairValue(node.metadata, member_order_key) orelse return null;620    return std.fmt.parseInt(u32, raw, 10) catch null;621}622623fn memberSourceSpan(node: model.Node) ?SourceSpan {624    const start_raw = model.pairValue(node.metadata, source_start_byte_key) orelse625        return null;626    const end_raw = model.pairValue(node.metadata, source_end_byte_key) orelse627        return null;628    const start = std.fmt.parseInt(u32, start_raw, 10) catch return null;629    const end = std.fmt.parseInt(u32, end_raw, 10) catch return null;630    if (start > end) return null;631    return .{ .start_byte = start, .end_byte = end };632}633634fn supportedMemberKind(kind: ContainerKind) ?MemberKind {635    return switch (kind) {636        .@"struct", .@"union" => .field,637        .@"enum" => .enum_tag,638        .error_set => .error_member,639        .@"opaque" => null,640    };641}642643fn nodeMemberKind(node: model.Node) ?MemberKind {644    if (std.mem.eql(u8, node.type, model.NodeType.field)) return .field;645    if (std.mem.eql(u8, node.type, model.NodeType.enum_tag)) return .enum_tag;646    if (std.mem.eql(u8, node.type, model.NodeType.error_member)) {647        return .error_member;648    }649    return null;650}651652fn canonicalDeclaration(graph: graph_mod.Graph, declaration: model.Node, limits: limits_mod.Api) Error!model.Node {653    return canonicalDeclarationDepth(graph, declaration, 0, limits);654}655656fn canonicalDeclarationDepth(657    graph: graph_mod.Graph,658    declaration: model.Node,659    depth: usize,660    limits: limits_mod.Api,661) Error!model.Node {662    if (depth == limits.alias_resolution_depth) return error.AliasCycle;663    var current = declaration;664    for (0..graph.nodes.items.len + 1) |_| {665        const owner = declarationOwner(graph, current.name) orelse return current;666        const next = try resolveAliasTarget(graph, owner, current, depth, limits) orelse return current;667        if (std.mem.eql(u8, next.name, current.name)) return current;668        if (std.mem.eql(u8, next.name, declaration.name)) {669            if (current.file != null and declaration.file != null and670                !std.mem.eql(u8, current.file.?, declaration.file.?)) return current;671            return error.AliasCycle;672        }673        current = next;674    }675    return error.AliasCycle;676}677678fn resolveAliasTarget(679    graph: graph_mod.Graph,680    owner: []const u8,681    declaration: model.Node,682    depth: usize,683    limits: limits_mod.Api,684) Error!?model.Node {685    const raw = directAliasTarget(declaration) orelse return null;686    if (graph_mod.getNode(&graph, raw)) |node| return node;687    const dot = std.mem.indexOfScalar(u8, raw, '.') orelse {688        const child = childNamed(graph, owner, raw);689        if (child) |node| {690            if (!std.mem.eql(u8, node.name, declaration.name)) return node;691        }692        if (!importBinding(declaration)) return child;693        return localPackageRoot(graph, owner, raw) orelse child;694    };695    const binding = childNamed(graph, owner, raw[0..dot]) orelse return null;696    if (std.mem.eql(u8, binding.name, declaration.name)) return declaration;697    const base = try canonicalDeclarationDepth(graph, binding, depth + 1, limits);698    return joinedNode(graph, base.name, raw[dot..]);699}700701fn importBinding(node: model.Node) bool {702    return std.mem.indexOf(u8, signature(node) orelse return false, "@import(") != null;703}704705fn localPackageRoot(706    graph: graph_mod.Graph,707    owner: []const u8,708    raw: []const u8,709) ?model.Node {710    if (std.mem.indexOfScalar(u8, raw, '.') != null) return null;711    var end = std.mem.lastIndexOfScalar(u8, owner, '.') orelse return null;712    while (true) {713        const prefix = owner[0..end];714        const candidate = joinedChildNode(graph, prefix, raw);715        if (candidate) |node| {716            if (moduleNode(node)) {717                if (std.mem.eql(u8, node.type, model.NodeType.package)) {718                    return childNamed(graph, node.name, "root") orelse node;719                }720                return node;721            }722        }723        end = std.mem.lastIndexOfScalar(u8, prefix, '.') orelse break;724    }725    return null;726}727728fn joinedChildNode(729    graph: graph_mod.Graph,730    prefix: []const u8,731    leaf: []const u8,732) ?model.Node {733    return dottedJoinedNode(graph, prefix, leaf);734}735736fn dottedJoinedNode(737    graph: graph_mod.Graph,738    prefix: []const u8,739    leaf: []const u8,740) ?model.Node {741    if (leaf.len != 0) {742        var iterator = graph_mod.suffixIterator(&graph, leaf);743        while (iterator.nextNode()) |node| {744            if (node.name.len != prefix.len + 1 + leaf.len) continue;745            if (!std.mem.startsWith(u8, node.name, prefix)) continue;746            if (node.name[prefix.len] != '.') continue;747            if (std.mem.eql(u8, node.name[prefix.len + 1 ..], leaf)) return node.*;748        }749        return null;750    }751    for (graph.nodes.items) |node| {752        if (node.name.len != prefix.len + 1 + leaf.len) continue;753        if (!std.mem.startsWith(u8, node.name, prefix)) continue;754        if (node.name[prefix.len] != '.') continue;755        if (std.mem.eql(u8, node.name[prefix.len + 1 ..], leaf)) return node;756    }757    return null;758}759760fn declarationOwner(graph: graph_mod.Graph, name: []const u8) ?[]const u8 {761    var owner: ?[]const u8 = null;762    for (graph_mod.incomingEdges(&graph, name)) |edge_index| {763        const edge = graph.edges.items[edge_index];764        if (!std.mem.eql(u8, edge.rel, model.RelType.contains)) continue;765        if (owner != null) return null;766        owner = edge.source;767    }768    return owner;769}770771fn childNamed(772    graph: graph_mod.Graph,773    owner: []const u8,774    leaf: []const u8,775) ?model.Node {776    for (graph_mod.outgoingEdges(&graph, owner)) |edge_index| {777        const edge = graph.edges.items[edge_index];778        if (!std.mem.eql(u8, edge.rel, model.RelType.contains)) continue;779        const node = graph_mod.getNode(&graph, edge.target) orelse continue;780        const split = std.mem.lastIndexOfScalar(u8, node.name, '.') orelse 0;781        const start = split + @intFromBool(split != 0);782        if (std.mem.eql(u8, node.name[start..], leaf)) return node;783    }784    return null;785}786787fn joinedNode(788    graph: graph_mod.Graph,789    prefix: []const u8,790    suffix: []const u8,791) ?model.Node {792    if (suffix.len != 0 and suffix[0] == '.') {793        return dottedJoinedNode(graph, prefix, suffix[1..]);794    }795    for (graph.nodes.items) |node| {796        if (node.name.len != prefix.len + suffix.len) continue;797        if (!std.mem.startsWith(u8, node.name, prefix)) continue;798        if (std.mem.eql(u8, node.name[prefix.len..], suffix)) return node;799    }800    return null;801}802803fn expectExactJoinedNodes(graph: graph_mod.Graph) !void {804    try std.testing.expectEqualStrings(805        "pkg.foo.Value",806        joinedChildNode(graph, "pkg.foo", "Value").?.name,807    );808    try std.testing.expectEqualStrings(809        "pkg.foo.Part.Value",810        joinedNode(graph, "pkg.foo", ".Part.Value").?.name,811    );812    try std.testing.expectEqualStrings(813        "pkg.foo.@\"dot.name\"",814        joinedNode(graph, "pkg.foo", ".@\"dot.name\"").?.name,815    );816    try std.testing.expectEqualStrings(817        "pkg.foox",818        joinedNode(graph, "pkg.foo", "x").?.name,819    );820    try std.testing.expectEqualStrings(821        "pkg.foo",822        joinedNode(graph, "pkg.foo", "").?.name,823    );824    try std.testing.expectEqualStrings(825        "pkg.foo.",826        joinedNode(graph, "pkg.foo", ".").?.name,827    );828    try std.testing.expectEqualStrings(829        "pkg.foo.",830        joinedChildNode(graph, "pkg.foo", "").?.name,831    );832    try std.testing.expect(joinedNode(graph, "pkg.foo", ".Missing") == null);833}834835test "exact joined nodes preserve indexed and linear semantics" {836    var graph = graph_mod.init(std.testing.allocator);837    defer graph_mod.deinit(&graph);838    for ([_][]const u8{839        "pkg.foo",840        "pkg.foo.Value",841        "pkg.foobar.Value",842        "alt.foo.Value",843        "other.foo.Value",844        "pkg.foo.Part.Value",845        "pkg.foo.@\"dot.name\"",846        "pkg.foox",847        "pkg.foo.",848    }) |name| try graph_mod.addNode(&graph, .{ .name = name, .type = model.NodeType.type });849850    try expectExactJoinedNodes(graph);851    try graph_mod.buildSuffixIndex(&graph);852    try std.testing.expect(graph_mod.suffixIndexReady(graph));853    try expectExactJoinedNodes(graph);854855    try graph_mod.addNode(&graph, .{ .name = "new.foo.Value", .type = model.NodeType.type });856    try std.testing.expect(!graph_mod.suffixIndexReady(graph));857    try expectExactJoinedNodes(graph);858    try std.testing.expectEqualStrings(859        "new.foo.Value",860        joinedChildNode(graph, "new.foo", "Value").?.name,861    );862}863864fn moduleNode(node: model.Node) bool {865    return std.mem.eql(u8, node.type, model.NodeType.module) or866        std.mem.eql(u8, node.type, model.NodeType.package);867}868869fn sameSourceFile(left: model.Node, right: model.Node) bool {870    const left_file = left.file orelse return false;871    const right_file = right.file orelse return false;872    return std.mem.eql(u8, left_file, right_file);873}874875fn declarationLessThan(_: void, left: PublicDeclaration, right: PublicDeclaration) bool {876    return std.mem.lessThan(u8, left.exported.name, right.exported.name);877}878879fn memberLessThan(_: void, left: PublicMember, right: PublicMember) bool {880    if (left.order != right.order) return left.order < right.order;881    return std.mem.lessThan(u8, left.node.name, right.node.name);882}883884fn memberGapLessThan(_: void, left: PublicMemberGap, right: PublicMemberGap) bool {885    if (left.order != right.order) return left.order < right.order;886    return std.mem.lessThan(u8, left.node.name, right.node.name);887}888889test "public declaration spans preserve binding and canonical evidence" {890    const binding_bytes = "pub const Alias";891    const canonical_bytes = "pub const Value = struct {};";892    const binding_hash = std.fmt.bytesToHex(sourceDigest(binding_bytes), .lower);893    const canonical_hash = std.fmt.bytesToHex(sourceDigest(canonical_bytes), .lower);894    const binding_metadata = [_]model.Pair{895        .{ .key = source_start_byte_key, .value = "4" },896        .{ .key = source_end_byte_key, .value = "19" },897        .{ .key = source_hash_key, .value = &binding_hash },898    };899    const canonical_metadata = [_]model.Pair{900        .{ .key = source_start_byte_key, .value = "30" },901        .{ .key = source_end_byte_key, .value = "90" },902        .{ .key = source_hash_key, .value = &canonical_hash },903    };904    const declaration = PublicDeclaration{905        .exported = .{ .name = "root.Alias", .type = model.NodeType.constant, .file = "root.zig", .metadata = &binding_metadata },906        .canonical = .{ .name = "root.Value", .type = model.NodeType.class, .file = "value.zig", .metadata = &canonical_metadata },907    };908    try std.testing.expectEqual(@as(u32, 4), (try declaration.bindingSourceSpan()).start_byte);909    try std.testing.expectEqual(@as(u32, 90), (try declaration.canonicalSourceSpan()).end_byte);910    try std.testing.expectEqualStrings("root.zig", (try declaration.bindingSource()).file);911    try std.testing.expectEqual(binding_hash, std.fmt.bytesToHex(912        (try declaration.bindingSource()).digest,913        .lower,914    ));915    const missing = model.Node{ .name = "root.Missing", .type = model.NodeType.constant };916    try std.testing.expectError(error.SourceSpanUnavailable, declarationSourceSpan(missing));917    try std.testing.expectError(error.SourceFileUnavailable, declarationSource(missing));918    const malformed = [_]model.Pair{919        .{ .key = source_start_byte_key, .value = "9" },920        .{ .key = source_end_byte_key, .value = "9" },921        .{ .key = source_hash_key, .value = "not-a-digest" },922    };923    const invalid = model.Node{924        .name = "root.Invalid",925        .type = model.NodeType.constant,926        .file = "root.zig",927        .metadata = &malformed,928    };929    try std.testing.expectError(error.InvalidSourceSpan, declarationSourceSpan(invalid));930    try std.testing.expectError(error.InvalidSourceDigest, declarationSource(invalid));931}932933test "declaration source requires complete lower-case evidence" {934    const span_only = [_]model.Pair{935        .{ .key = source_start_byte_key, .value = "0" },936        .{ .key = source_end_byte_key, .value = "8" },937    };938    const missing_digest = model.Node{939        .name = "root.MissingDigest",940        .type = model.NodeType.constant,941        .file = "root.zig",942        .metadata = &span_only,943    };944    try std.testing.expectError(945        error.SourceDigestUnavailable,946        declarationSource(missing_digest),947    );948    const upper_hash = [_]model.Pair{949        .{ .key = source_start_byte_key, .value = "0" },950        .{ .key = source_end_byte_key, .value = "8" },951        .{ .key = source_hash_key, .value = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" },952    };953    var invalid = missing_digest;954    invalid.metadata = &upper_hash;955    try std.testing.expectError(error.InvalidSourceDigest, declarationSource(invalid));956}957958test "verified source rejects stale and out-of-range declaration evidence" {959    const contents = "prefix pub fn run() void {} suffix";960    const exact = "pub fn run() void {}";961    const start = std.mem.indexOf(u8, contents, exact).?;962    var evidence = DeclarationSource{963        .file = "root.zig",964        .span = .{965            .start_byte = @intCast(start),966            .end_byte = @intCast(start + exact.len),967        },968        .digest = sourceDigest(exact),969    };970    try std.testing.expectEqualStrings(971        exact,972        try verifiedSource(evidence, contents),973    );974    evidence.digest[0] ^= 1;975    try std.testing.expectError(976        error.SourceDigestMismatch,977        verifiedSource(evidence, contents),978    );979    evidence.span.end_byte = @intCast(contents.len + 1);980    try std.testing.expectError(error.InvalidSourceSpan, verifiedSource(evidence, contents));981}982983test "exact public paths traverse canonical aliases and quoted identifiers" {984    const public = [_]model.Pair{.{ .key = visibility_key, .value = "public" }};985    const alias = [_]model.Pair{986        .{ .key = visibility_key, .value = "public" },987        .{ .key = direct_alias_target_key, .value = "core.Block" },988    };989    var graph = graph_mod.init(std.testing.allocator);990    defer graph_mod.deinit(&graph);991    for ([_]model.Node{992        .{ .name = "root", .type = model.NodeType.module },993        .{ .name = "root.Block", .type = model.NodeType.type, .metadata = &alias },994        .{ .name = "core", .type = model.NodeType.module },995        .{ .name = "core.Block", .type = model.NodeType.class, .metadata = &public },996        .{997            .name = "core.Block.getPredecessors",998            .type = model.NodeType.method,999            .metadata = &public,1000        },1001        .{1002            .name = "core.Block.@\"dot.name\"",1003            .type = model.NodeType.method,1004            .metadata = &public,1005        },1006    }) |node| try graph_mod.addNode(&graph, node);1007    for ([_]model.Edge{1008        .{ .source = "root", .rel = model.RelType.contains, .target = "root.Block" },1009        .{ .source = "core", .rel = model.RelType.contains, .target = "core.Block" },1010        .{1011            .source = "core.Block",1012            .rel = model.RelType.contains,1013            .target = "core.Block.getPredecessors",1014        },1015        .{1016            .source = "core.Block",1017            .rel = model.RelType.contains,1018            .target = "core.Block.@\"dot.name\"",1019        },1020    }) |edge| try graph_mod.addEdge(&graph, edge);10211022    const method = try resolvePublicPath(1023        std.testing.allocator,1024        graph,1025        "root",1026        "Block.getPredecessors",1027        testing_limits,1028    );1029    try std.testing.expectEqualStrings(1030        "core.Block.getPredecessors",1031        method.canonical.name,1032    );1033    const quoted = try resolvePublicPath(1034        std.testing.allocator,1035        graph,1036        "root",1037        "Block.@\"dot.name\"",1038        testing_limits,1039    );1040    try std.testing.expectEqualStrings("core.Block.@\"dot.name\"", quoted.canonical.name);1041    try std.testing.expectError(1042        error.PublicPathNotFound,1043        resolvePublicPath(std.testing.allocator, graph, "root", "Block.missing", testing_limits),1044    );1045    try std.testing.expectError(1046        error.InvalidPublicPath,1047        resolvePublicPath(std.testing.allocator, graph, "root", "Block.", testing_limits),1048    );1049}10501051test "public declarations resolve aliases and retain export facts" {1052    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);1053    defer arena.deinit();1054    const allocator = arena.allocator();1055    var graph = graph_mod.init(allocator);1056    defer graph_mod.deinit(&graph);1057    try addProjectionFixture(&graph);10581059    const owner = try ownerForFile(graph, "lib/api/src/root.zig");1060    try std.testing.expectEqualStrings("lib.api.src.root", owner);1061    const declarations = try publicDeclarations(std.testing.allocator, graph, owner, testing_limits);1062    defer freePublicDeclarations(std.testing.allocator, declarations);10631064    try std.testing.expectEqual(@as(usize, 2), declarations.len);1065    try std.testing.expectEqualStrings("lib.api.src.root.run", declarations[0].exported.name);1066    try std.testing.expectEqualStrings("lib.api.src.site.root.run", declarations[0].canonical.name);1067    try std.testing.expectEqualStrings("Runs the site.", declarations[0].documentation().?);1068    try std.testing.expectEqualStrings("pub const run = site.run;", signature(declarations[0].exported).?);1069    try std.testing.expectEqualStrings("lib.api.src.site.root", declarations[1].canonical.name);1070}10711072test "public declarations resolve local packages through private import bindings" {1073    const public_alias = [_]model.Pair{1074        .{ .key = visibility_key, .value = "public" },1075        .{ .key = direct_alias_target_key, .value = "schema" },1076        .{ .key = signature_key, .value = "pub const event = @import(\"schema\");" },1077    };1078    const public_event_alias = [_]model.Pair{1079        .{ .key = visibility_key, .value = "public" },1080        .{ .key = direct_alias_target_key, .value = "event.Event" },1081    };1082    const public_schema_event_alias = [_]model.Pair{1083        .{ .key = visibility_key, .value = "public" },1084        .{ .key = direct_alias_target_key, .value = "event_data.Event" },1085    };1086    const private_import = [_]model.Pair{1087        .{ .key = visibility_key, .value = "private" },1088        .{ .key = direct_alias_target_key, .value = "pkg.src.schema.event" },1089    };1090    var graph = graph_mod.init(std.testing.allocator);1091    defer graph_mod.deinit(&graph);1092    const nodes = [_]model.Node{1093        .{ .name = "pkg.src.root", .type = model.NodeType.module },1094        .{ .name = "pkg.src.root.event", .type = model.NodeType.constant, .metadata = &public_alias },1095        .{ .name = "pkg.src.root.Event", .type = model.NodeType.type, .metadata = &public_event_alias },1096        .{ .name = "pkg.src.schema", .type = model.NodeType.package },1097        .{ .name = "pkg.src.schema.root", .type = model.NodeType.module },1098        .{ .name = "pkg.src.schema.root.event_data", .type = model.NodeType.constant, .metadata = &private_import },1099        .{ .name = "pkg.src.schema.root.Event", .type = model.NodeType.type, .metadata = &public_schema_event_alias },1100        .{ .name = "pkg.src.schema.event", .type = model.NodeType.module },1101        .{ .name = "pkg.src.schema.event.Event", .type = model.NodeType.class, .docstring = "Durable event." },1102    };1103    for (nodes) |node| try graph_mod.addNode(&graph, node);1104    const edges = [_]model.Edge{1105        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.event" },1106        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.Event" },1107        .{ .source = "pkg.src.schema", .rel = model.RelType.contains, .target = "pkg.src.schema.root" },1108        .{ .source = "pkg.src.schema.root", .rel = model.RelType.contains, .target = "pkg.src.schema.root.event_data" },1109        .{ .source = "pkg.src.schema.root", .rel = model.RelType.contains, .target = "pkg.src.schema.root.Event" },1110        .{ .source = "pkg.src.schema.event", .rel = model.RelType.contains, .target = "pkg.src.schema.event.Event" },1111    };1112    for (edges) |edge| try graph_mod.addEdge(&graph, edge);1113    try graph_mod.buildSuffixIndex(&graph);11141115    const declarations = try publicDeclarations(1116        std.testing.allocator,1117        graph,1118        "pkg.src.root",1119        testing_limits,1120    );1121    defer freePublicDeclarations(std.testing.allocator, declarations);1122    try std.testing.expectEqual(@as(usize, 2), declarations.len);1123    try std.testing.expectEqualStrings(1124        "pkg.src.schema.event.Event",1125        declarations[0].canonical.name,1126    );1127    try std.testing.expectEqualStrings(1128        "pkg.src.schema.root",1129        declarations[1].canonical.name,1130    );1131}11321133test "public declarations resolve local packages through same-name import bindings" {1134    const public_capacity = [_]model.Pair{1135        .{ .key = visibility_key, .value = "public" },1136        .{ .key = direct_alias_target_key, .value = "capacity" },1137        .{ .key = signature_key, .value = "pub const capacity = @import(\"capacity\");" },1138    };1139    const public_helper = [_]model.Pair{1140        .{ .key = visibility_key, .value = "public" },1141        .{ .key = direct_alias_target_key, .value = "support" },1142    };1143    const private_support = [_]model.Pair{1144        .{ .key = visibility_key, .value = "private" },1145    };1146    const public_budget = [_]model.Pair{1147        .{ .key = visibility_key, .value = "public" },1148    };1149    var graph = graph_mod.init(std.testing.allocator);1150    defer graph_mod.deinit(&graph);1151    const nodes = [_]model.Node{1152        .{ .name = "pkg.src.root", .type = model.NodeType.module, .file = "pkg/src/root.zig" },1153        .{ .name = "pkg.src.root.capacity", .type = model.NodeType.constant, .file = "pkg/src/root.zig", .line = 3, .metadata = &public_capacity },1154        .{ .name = "pkg.src.root.helper", .type = model.NodeType.constant, .file = "pkg/src/root.zig", .line = 4, .metadata = &public_helper },1155        .{ .name = "pkg.src.root.support", .type = model.NodeType.constant, .file = "pkg/src/root.zig", .line = 5, .metadata = &private_support },1156        .{ .name = "pkg.src.capacity", .type = model.NodeType.package },1157        .{ .name = "pkg.src.capacity.root", .type = model.NodeType.module, .file = "pkg/src/capacity/root.zig" },1158        .{ .name = "pkg.src.capacity.root.Budget", .type = model.NodeType.class, .file = "pkg/src/capacity/root.zig", .line = 2, .docstring = "Bounded byte budget.", .metadata = &public_budget },1159    };1160    for (nodes) |node| try graph_mod.addNode(&graph, node);1161    const edges = [_]model.Edge{1162        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.capacity" },1163        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.helper" },1164        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.support" },1165        .{ .source = "pkg.src.capacity", .rel = model.RelType.contains, .target = "pkg.src.capacity.root" },1166        .{ .source = "pkg.src.capacity.root", .rel = model.RelType.contains, .target = "pkg.src.capacity.root.Budget" },1167    };1168    for (edges) |edge| try graph_mod.addEdge(&graph, edge);1169    try graph_mod.buildSuffixIndex(&graph);11701171    const declarations = try publicDeclarations(1172        std.testing.allocator,1173        graph,1174        "pkg.src.root",1175        testing_limits,1176    );1177    defer freePublicDeclarations(std.testing.allocator, declarations);1178    try std.testing.expectEqual(@as(usize, 2), declarations.len);1179    try std.testing.expectEqualStrings("pkg.src.root.capacity", declarations[0].exported.name);1180    try std.testing.expectEqualStrings("pkg.src.capacity.root", declarations[0].canonical.name);1181    try std.testing.expectEqualStrings("pkg/src/root.zig", declarations[0].exported.file.?);1182    try std.testing.expectEqualStrings("pkg/src/capacity/root.zig", declarations[0].canonical.file.?);1183    try std.testing.expectEqualStrings("pkg.src.root.helper", declarations[1].exported.name);1184    try std.testing.expectEqualStrings("pkg.src.root.support", declarations[1].canonical.name);11851186    const member = try resolvePublicPath(1187        std.testing.allocator,1188        graph,1189        "pkg.src.root",1190        "capacity.Budget",1191        testing_limits,1192    );1193    try std.testing.expectEqualStrings("pkg.src.capacity.root.Budget", member.canonical.name);1194    try std.testing.expectEqualStrings("Bounded byte budget.", member.documentation().?);1195}11961197test "public declarations keep unresolvable same-name import bindings terminal" {1198    const public_std = [_]model.Pair{1199        .{ .key = visibility_key, .value = "public" },1200        .{ .key = direct_alias_target_key, .value = "std" },1201        .{ .key = signature_key, .value = "pub const std = @import(\"std\");" },1202    };1203    const public_capacity = [_]model.Pair{1204        .{ .key = visibility_key, .value = "public" },1205        .{ .key = direct_alias_target_key, .value = "capacity" },1206        .{ .key = signature_key, .value = "pub const capacity = @import(\"capacity\");" },1207    };1208    var graph = graph_mod.init(std.testing.allocator);1209    defer graph_mod.deinit(&graph);1210    const nodes = [_]model.Node{1211        .{ .name = "pkg.src.root", .type = model.NodeType.module, .file = "pkg/src/root.zig" },1212        .{ .name = "pkg.src.root.std", .type = model.NodeType.constant, .file = "pkg/src/root.zig", .metadata = &public_std },1213        .{ .name = "pkg.src.root.capacity", .type = model.NodeType.constant, .file = "pkg/src/root.zig", .metadata = &public_capacity },1214        .{ .name = "other.src.capacity", .type = model.NodeType.package },1215        .{ .name = "other.src.capacity.root", .type = model.NodeType.module, .file = "other/src/capacity/root.zig" },1216    };1217    for (nodes) |node| try graph_mod.addNode(&graph, node);1218    const edges = [_]model.Edge{1219        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.std" },1220        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.capacity" },1221        .{ .source = "other.src.capacity", .rel = model.RelType.contains, .target = "other.src.capacity.root" },1222    };1223    for (edges) |edge| try graph_mod.addEdge(&graph, edge);1224    try graph_mod.buildSuffixIndex(&graph);12251226    const declarations = try publicDeclarations(1227        std.testing.allocator,1228        graph,1229        "pkg.src.root",1230        testing_limits,1231    );1232    defer freePublicDeclarations(std.testing.allocator, declarations);1233    try std.testing.expectEqual(@as(usize, 2), declarations.len);1234    try std.testing.expectEqualStrings("pkg.src.root.capacity", declarations[0].exported.name);1235    try std.testing.expectEqualStrings("pkg.src.root.capacity", declarations[0].canonical.name);1236    try std.testing.expectEqualStrings("pkg.src.root.std", declarations[1].exported.name);1237    try std.testing.expectEqualStrings("pkg.src.root.std", declarations[1].canonical.name);1238}12391240test "public declarations resolve dotted private alias chains" {1241    const public_harness = [_]model.Pair{1242        .{ .key = visibility_key, .value = "public" },1243        .{ .key = direct_alias_target_key, .value = "harness.Harness" },1244    };1245    const public_agent = [_]model.Pair{1246        .{ .key = visibility_key, .value = "public" },1247        .{ .key = direct_alias_target_key, .value = "pkg.src.agent.root" },1248    };1249    const public_harness_namespace = [_]model.Pair{1250        .{ .key = visibility_key, .value = "public" },1251        .{ .key = direct_alias_target_key, .value = "pkg.src.agent.harness.root" },1252    };1253    const private_harness = [_]model.Pair{1254        .{ .key = visibility_key, .value = "private" },1255        .{ .key = direct_alias_target_key, .value = "agent.harness" },1256    };1257    const public_log = [_]model.Pair{1258        .{ .key = visibility_key, .value = "public" },1259        .{ .key = direct_alias_target_key, .value = "log.Log" },1260    };1261    const private_history = [_]model.Pair{1262        .{ .key = visibility_key, .value = "private" },1263        .{ .key = direct_alias_target_key, .value = "pkg.src.history.root" },1264    };1265    const private_log = [_]model.Pair{1266        .{ .key = visibility_key, .value = "private" },1267        .{ .key = direct_alias_target_key, .value = "history.log" },1268    };1269    const public_history_log = [_]model.Pair{1270        .{ .key = visibility_key, .value = "public" },1271        .{ .key = direct_alias_target_key, .value = "pkg.src.history.log" },1272    };1273    var graph = graph_mod.init(std.testing.allocator);1274    defer graph_mod.deinit(&graph);1275    const nodes = [_]model.Node{1276        .{ .name = "pkg.src.root", .type = model.NodeType.module },1277        .{ .name = "pkg.src.root.agent", .type = model.NodeType.constant, .metadata = &public_agent },1278        .{ .name = "pkg.src.root.harness", .type = model.NodeType.constant, .metadata = &private_harness },1279        .{ .name = "pkg.src.root.Harness", .type = model.NodeType.type, .metadata = &public_harness },1280        .{ .name = "pkg.src.root.history", .type = model.NodeType.constant, .metadata = &private_history },1281        .{ .name = "pkg.src.root.log", .type = model.NodeType.constant, .metadata = &private_log },1282        .{ .name = "pkg.src.root.Log", .type = model.NodeType.type, .metadata = &public_log },1283        .{ .name = "pkg.src.agent.root", .type = model.NodeType.module },1284        .{ .name = "pkg.src.agent.root.harness", .type = model.NodeType.constant, .metadata = &public_harness_namespace },1285        .{ .name = "pkg.src.agent.harness.root", .type = model.NodeType.module },1286        .{ .name = "pkg.src.agent.harness.root.Harness", .type = model.NodeType.class, .docstring = "Deterministic session owner." },1287        .{ .name = "pkg.src.history.root", .type = model.NodeType.module },1288        .{ .name = "pkg.src.history.root.log", .type = model.NodeType.constant, .metadata = &public_history_log },1289        .{ .name = "pkg.src.history.log", .type = model.NodeType.module },1290        .{ .name = "pkg.src.history.log.Log", .type = model.NodeType.class, .docstring = "Committed history owner." },1291    };1292    for (nodes) |node| try graph_mod.addNode(&graph, node);1293    const edges = [_]model.Edge{1294        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.agent" },1295        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.harness" },1296        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.Harness" },1297        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.history" },1298        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.log" },1299        .{ .source = "pkg.src.root", .rel = model.RelType.contains, .target = "pkg.src.root.Log" },1300        .{ .source = "pkg.src.agent.root", .rel = model.RelType.contains, .target = "pkg.src.agent.root.harness" },1301        .{ .source = "pkg.src.agent.harness.root", .rel = model.RelType.contains, .target = "pkg.src.agent.harness.root.Harness" },1302        .{ .source = "pkg.src.history.root", .rel = model.RelType.contains, .target = "pkg.src.history.root.log" },1303        .{ .source = "pkg.src.history.log", .rel = model.RelType.contains, .target = "pkg.src.history.log.Log" },1304    };1305    for (edges) |edge| try graph_mod.addEdge(&graph, edge);1306    try graph_mod.buildSuffixIndex(&graph);13071308    const declarations = try publicDeclarations(1309        std.testing.allocator,1310        graph,1311        "pkg.src.root",1312        testing_limits,1313    );1314    defer freePublicDeclarations(std.testing.allocator, declarations);1315    try std.testing.expectEqual(@as(usize, 3), declarations.len);1316    try std.testing.expectEqualStrings(1317        "pkg.src.agent.harness.root.Harness",1318        declarations[0].canonical.name,1319    );1320    try std.testing.expectEqualStrings(1321        "pkg.src.history.log.Log",1322        declarations[1].canonical.name,1323    );1324    try std.testing.expectEqualStrings("pkg.src.agent.root", declarations[2].canonical.name);1325}13261327test "public declarations stop at self-resolving import bindings" {1328    const public_import = [_]model.Pair{1329        .{ .key = visibility_key, .value = "public" },1330        .{ .key = alias_target_key, .value = "pretty" },1331        .{ .key = direct_alias_target_key, .value = "pretty" },1332    };1333    var graph = graph_mod.init(std.testing.allocator);1334    defer graph_mod.deinit(&graph);1335    try graph_mod.addNode(&graph, .{1336        .name = "root",1337        .type = model.NodeType.module,1338    });1339    try graph_mod.addNode(&graph, .{1340        .name = "root.pretty",1341        .type = model.NodeType.constant,1342        .metadata = &public_import,1343    });1344    try graph_mod.addEdge(&graph, .{1345        .source = "root",1346        .rel = model.RelType.contains,1347        .target = "root.pretty",1348    });13491350    const declarations = try publicDeclarations(std.testing.allocator, graph, "root", testing_limits);1351    defer freePublicDeclarations(std.testing.allocator, declarations);1352    try std.testing.expectEqual(@as(usize, 1), declarations.len);1353    try std.testing.expectEqualStrings("root.pretty", declarations[0].canonical.name);1354}13551356test "public declarations reject nontrivial alias cycles" {1357    const public_first = [_]model.Pair{1358        .{ .key = visibility_key, .value = "public" },1359        .{ .key = alias_target_key, .value = "second" },1360        .{ .key = direct_alias_target_key, .value = "second" },1361    };1362    const private_second = [_]model.Pair{1363        .{ .key = alias_target_key, .value = "first" },1364        .{ .key = direct_alias_target_key, .value = "first" },1365    };1366    var graph = graph_mod.init(std.testing.allocator);1367    defer graph_mod.deinit(&graph);1368    try graph_mod.addNode(&graph, .{ .name = "root", .type = model.NodeType.module });1369    try graph_mod.addNode(&graph, .{1370        .name = "root.first",1371        .type = model.NodeType.constant,1372        .metadata = &public_first,1373    });1374    try graph_mod.addNode(&graph, .{1375        .name = "root.second",1376        .type = model.NodeType.constant,1377        .metadata = &private_second,1378    });1379    try graph_mod.addEdge(&graph, .{1380        .source = "root",1381        .rel = model.RelType.contains,1382        .target = "root.first",1383    });1384    try graph_mod.addEdge(&graph, .{1385        .source = "root",1386        .rel = model.RelType.contains,1387        .target = "root.second",1388    });13891390    try std.testing.expectError(1391        error.AliasCycle,1392        publicDeclarations(std.testing.allocator, graph, "root", testing_limits),1393    );1394}13951396test "public declarations bound recursive dotted alias cycles" {1397    const public_value = [_]model.Pair{1398        .{ .key = visibility_key, .value = "public" },1399        .{ .key = direct_alias_target_key, .value = "first.Value" },1400    };1401    const first = [_]model.Pair{1402        .{ .key = visibility_key, .value = "private" },1403        .{ .key = direct_alias_target_key, .value = "second.Value" },1404    };1405    const second = [_]model.Pair{1406        .{ .key = visibility_key, .value = "private" },1407        .{ .key = direct_alias_target_key, .value = "first.Value" },1408    };1409    var graph = graph_mod.init(std.testing.allocator);1410    defer graph_mod.deinit(&graph);1411    const nodes = [_]model.Node{1412        .{ .name = "root", .type = model.NodeType.module },1413        .{ .name = "root.Value", .type = model.NodeType.type, .metadata = &public_value },1414        .{ .name = "root.first", .type = model.NodeType.constant, .metadata = &first },1415        .{ .name = "root.second", .type = model.NodeType.constant, .metadata = &second },1416    };1417    for (nodes) |node| try graph_mod.addNode(&graph, node);1418    for (nodes[1..]) |node| try graph_mod.addEdge(&graph, .{1419        .source = "root",1420        .rel = model.RelType.contains,1421        .target = node.name,1422    });14231424    try std.testing.expectError(1425        error.AliasCycle,1426        publicDeclarations(std.testing.allocator, graph, "root", testing_limits),1427    );1428}14291430test "public members retain canonical ownership and stable source order" {1431    const public_container = [_]model.Pair{1432        .{ .key = visibility_key, .value = "public" },1433        .{ .key = container_kind_key, .value = "struct" },1434    };1435    const later = memberFixtureMetadata("later", "1", "later: u8", "20", "29");1436    const earlier = memberFixtureMetadata("earlier", "0", "earlier: u8", "5", "16");1437    var graph = graph_mod.init(std.testing.allocator);1438    defer graph_mod.deinit(&graph);1439    try graph_mod.addNode(&graph, .{ .name = "root", .type = model.NodeType.module });1440    try graph_mod.addNode(&graph, .{1441        .name = "root.Options",1442        .type = model.NodeType.class,1443        .file = "root.zig",1444        .metadata = &public_container,1445    });1446    try addMemberFixtureNode(&graph, "root.Options.later", &later);1447    try addMemberFixtureNode(&graph, "root.Options.earlier", &earlier);1448    try graph_mod.addEdge(&graph, .{ .source = "root", .rel = model.RelType.contains, .target = "root.Options" });1449    try graph_mod.addEdge(&graph, .{ .source = "root.Options", .rel = model.RelType.contains, .target = "root.Options.later" });1450    try graph_mod.addEdge(&graph, .{ .source = "root.Options", .rel = model.RelType.contains, .target = "root.Options.earlier" });1451    const declarations = try publicDeclarations(std.testing.allocator, graph, "root", testing_limits);1452    defer freePublicDeclarations(std.testing.allocator, declarations);1453    const members = try publicMembers(std.testing.allocator, graph, declarations[0]);1454    defer freePublicMembers(std.testing.allocator, members);1455    try std.testing.expectEqual(@as(usize, 2), members.len);1456    try std.testing.expectEqualStrings("earlier", members[0].identifier().?);1457    try std.testing.expectEqualStrings(declarations[0].canonical.name, members[0].owner.canonical.name);1458    try std.testing.expectEqual(@as(u32, 5), members[0].sourceSpan().start_byte);1459    const malformed = [_]model.Pair{1460        .{ .key = member_identifier_key, .value = "broken" },1461        .{ .key = member_order_key, .value = "2" },1462        .{ .key = source_spelling_key, .value = "broken: u8" },1463        .{ .key = source_start_byte_key, .value = "30" },1464    };1465    try addMemberFixtureNode(&graph, "root.Options.broken", &malformed);1466    try graph_mod.addEdge(&graph, .{ .source = "root.Options", .rel = model.RelType.contains, .target = "root.Options.broken" });1467    try std.testing.expectError(1468        error.InvalidPublicMember,1469        publicMembers(std.testing.allocator, graph, declarations[0]),1470    );1471}14721473test "public member gaps preserve explicit unsupported source facts" {1474    const public_container = [_]model.Pair{1475        .{ .key = visibility_key, .value = "public" },1476        .{ .key = container_kind_key, .value = "struct" },1477    };1478    const gap_metadata = [_]model.Pair{1479        .{ .key = member_gap_key, .value = "unsupported_member_syntax" },1480        .{ .key = member_order_key, .value = "0" },1481        .{ .key = source_spelling_key, .value = "u8" },1482        .{ .key = source_start_byte_key, .value = "5" },1483        .{ .key = source_end_byte_key, .value = "7" },1484    };1485    var graph = graph_mod.init(std.testing.allocator);1486    defer graph_mod.deinit(&graph);1487    try graph_mod.addNode(&graph, .{ .name = "root", .type = model.NodeType.module });1488    try graph_mod.addNode(&graph, .{1489        .name = "root.Tuple",1490        .type = model.NodeType.class,1491        .file = "root.zig",1492        .metadata = &public_container,1493    });1494    try graph_mod.addNode(&graph, .{1495        .name = "root.Tuple.$smg-gap-0",1496        .type = model.NodeType.member_gap,1497        .file = "root.zig",1498        .line = 1,1499        .end_line = 1,1500        .metadata = &gap_metadata,1501    });1502    try graph_mod.addEdge(&graph, .{ .source = "root", .rel = model.RelType.contains, .target = "root.Tuple" });1503    try graph_mod.addEdge(&graph, .{ .source = "root.Tuple", .rel = model.RelType.contains, .target = "root.Tuple.$smg-gap-0" });1504    const declarations = try publicDeclarations(std.testing.allocator, graph, "root", testing_limits);1505    defer freePublicDeclarations(std.testing.allocator, declarations);1506    const gaps = try publicMemberGaps(std.testing.allocator, graph, declarations[0]);1507    defer freePublicMemberGaps(std.testing.allocator, gaps);1508    try std.testing.expectEqual(@as(usize, 1), gaps.len);1509    try std.testing.expectEqual(MemberGapKind.unsupported_member_syntax, gaps[0].kind);1510    try std.testing.expect(gaps[0].identifier() == null);1511    try std.testing.expectEqualStrings("u8", gaps[0].sourceSpelling());1512    try std.testing.expectEqual(@as(u32, 5), gaps[0].sourceSpan().start_byte);1513}15141515test "public member record allocation propagates out of memory" {1516    const public_container = [_]model.Pair{1517        .{ .key = visibility_key, .value = "public" },1518        .{ .key = container_kind_key, .value = "struct" },1519    };1520    const member_metadata = memberFixtureMetadata("field", "0", "field: u8", "0", "9");1521    var graph = graph_mod.init(std.testing.allocator);1522    defer graph_mod.deinit(&graph);1523    try graph_mod.addNode(&graph, .{1524        .name = "root.Options",1525        .type = model.NodeType.class,1526        .file = "root.zig",1527        .metadata = &public_container,1528    });1529    try addMemberFixtureNode(&graph, "root.Options.field", &member_metadata);1530    try graph_mod.addEdge(&graph, .{ .source = "root.Options", .rel = model.RelType.contains, .target = "root.Options.field" });1531    const owner = graph_mod.getNode(&graph, "root.Options").?;1532    var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{1533        .fail_index = 0,1534    });1535    try std.testing.expectError(1536        error.OutOfMemory,1537        projectPublicMembers(1538            failing.allocator(),1539            graph,1540            .{ .exported = owner, .canonical = owner },1541            owner,1542            .field,1543        ),1544    );1545}15461547fn memberFixtureMetadata(1548    comptime identifier: []const u8,1549    comptime order: []const u8,1550    comptime spelling: []const u8,1551    comptime start: []const u8,1552    comptime end: []const u8,1553) [5]model.Pair {1554    return .{1555        .{ .key = member_identifier_key, .value = identifier },1556        .{ .key = member_order_key, .value = order },1557        .{ .key = source_spelling_key, .value = spelling },1558        .{ .key = source_start_byte_key, .value = start },1559        .{ .key = source_end_byte_key, .value = end },1560    };1561}15621563fn addMemberFixtureNode(1564    graph: *graph_mod.Graph,1565    name: []const u8,1566    metadata: []const model.Pair,1567) !void {1568    try graph_mod.addNode(graph, .{1569        .name = name,1570        .type = model.NodeType.field,1571        .file = "root.zig",1572        .line = 1,1573        .end_line = 1,1574        .metadata = metadata,1575    });1576}15771578fn addProjectionFixture(graph: *graph_mod.Graph) !void {1579    const scanned = [_]model.Pair{.{ .key = "source", .value = "scan" }};1580    const public_site = [_]model.Pair{1581        .{ .key = visibility_key, .value = "public" },1582        .{ .key = alias_target_key, .value = "lib.api.src.site.root" },1583        .{ .key = direct_alias_target_key, .value = "lib.api.src.site.root" },1584    };1585    const public_run = [_]model.Pair{1586        .{ .key = visibility_key, .value = "public" },1587        .{ .key = signature_key, .value = "pub const run = site.run;" },1588        .{ .key = alias_target_key, .value = "site.run" },1589        .{ .key = direct_alias_target_key, .value = "site.run" },1590    };1591    try graph_mod.addNode(graph, .{1592        .name = "lib.api.src.root",1593        .type = model.NodeType.module,1594        .file = "lib/api/src/root.zig",1595        .metadata = &scanned,1596    });1597    try graph_mod.addNode(graph, .{1598        .name = "lib.api.src.root.site",1599        .type = model.NodeType.constant,1600        .metadata = &public_site,1601    });1602    try graph_mod.addNode(graph, .{1603        .name = "lib.api.src.root.run",1604        .type = model.NodeType.constant,1605        .file = "lib/api/src/root.zig",1606        .metadata = &public_run,1607    });1608    try graph_mod.addNode(graph, .{1609        .name = "lib.api.src.root.hidden",1610        .type = model.NodeType.constant,1611        .metadata = &scanned,1612    });1613    try graph_mod.addNode(graph, .{1614        .name = "lib.api.src.site.root",1615        .type = model.NodeType.module,1616        .file = "lib/api/src/site/root.zig",1617        .metadata = &scanned,1618    });1619    try graph_mod.addNode(graph, .{1620        .name = "lib.api.src.site.root.run",1621        .type = model.NodeType.function,1622        .file = "lib/api/src/site/root.zig",1623        .docstring = "Runs the site.",1624        .metadata = &scanned,1625    });1626    const contains = model.RelType.contains;1627    try graph_mod.addEdge(graph, .{ .source = "lib.api.src.root", .rel = contains, .target = "lib.api.src.root.site" });1628    try graph_mod.addEdge(graph, .{ .source = "lib.api.src.root", .rel = contains, .target = "lib.api.src.root.run" });1629    try graph_mod.addEdge(graph, .{ .source = "lib.api.src.root", .rel = contains, .target = "lib.api.src.root.hidden" });1630    try graph_mod.addEdge(graph, .{ .source = "lib.api.src.site.root", .rel = contains, .target = "lib.api.src.site.root.run" });1631}