tiny.smg.context.model

1const std = @import("std");2const sys = @import("sys");34pub const schema = "tiny.smg.context/v1";5pub const targets_max = 8;6pub const entries_max = 32;7pub const rows_max = 256;8pub const input_bytes_max = 8192;9pub const row_bytes_max = 64 * 1024;10pub const output_bytes_max = 64 * 1024;11pub const source_bytes_max = 4 * 1024 * 1024;12pub const wal_bytes_max = 8 * 1024 * 1024;1314pub const Limits = struct {15    entries: u8 = entries_max,16    rows: u16 = rows_max,17    depth: u8 = 2,18    source_bytes: u32 = source_bytes_max,19};2021pub const Options = struct {22    limits: Limits = .{},23    bytes: u32 = output_bytes_max,24    deadline_ms: u16 = 1000,25};2627pub const State = enum { ready, absent, stale, unavailable, incompatible, budget_exhausted };28pub const TargetState = enum { resolved, missing, ambiguous, unsupported, unqueried };29pub const Basis = enum { verified_span, stale, unavailable, unverified, oversized };30pub const Section = enum { target, owner, usages, impact, tests, dependencies };3132pub const Target = struct {33    input: []const u8,34    state: TargetState = .unqueried,35    name: ?[]const u8 = null,36    candidates: []const []const u8 = &.{},37};3839pub const Entry = struct {40    target: []const u8,41    section: Section,42    relation: []const u8,43    name: []const u8,44    path: ?[]const u8,45    line: ?i64,46    source_span: ?@import("../root.zig").api.SourceSpan = null,47    source_sha256: ?[]const u8 = null,48    basis: Basis = .unverified,49};5051pub const Coverage = struct {52    scope: []const u8 = "syntactic-neighborhood",53    source_scope: []const u8 = "declaration-spans",54    graph_sources_verified: bool = false,55    traversal_complete: bool = true,56    requested: u8 = 0,57    resolved: u8 = 0,58    missing: u8 = 0,59    ambiguous: u8 = 0,60    unsupported: u8 = 0,61    verified_spans: u8 = 0,62    unverified_spans: u8 = 0,63    source_bytes: u32 = 0,64};6566pub const Work = struct {67    index_steps: u16 = 0,68    visited_index_rows: u16 = 0,69    visited_edges: u16 = 0,70    loaded_nodes: u16 = 0,71    depth_reached: u8 = 0,72};7374pub const Omissions = struct {75    entries: u16 = 0,76    targets: u8 = 0,77    exact: bool = true,78    rows: bool = false,79    depth: bool = false,80    deadline: bool = false,81    source: bool = false,82    output: bool = false,83};8485pub const Expansion = struct { cwd: []const u8, argv: []const []const u8 };8687pub const Report = struct {88    schema: []const u8 = model_schema,89    state: State = .ready,90    graph_head: ?[]const u8 = null,91    parser_identity: ?[]const u8 = null,92    project_identity: ?[]const u8 = null,93    limits: Limits = .{},94    deadline_ms: u16 = 1000,95    work: Work = .{},96    coverage: Coverage = .{},97    targets: []const Target = &.{},98    entries: []const Entry = &.{},99    omissions: Omissions = .{},100    problems: []const []const u8 = &.{},101    expand: Expansion,102};103104const model_schema = schema;105106/// Retained rows and storage decoding use caller-backed dynamic_unbounded allocation.107/// Fixed record counts and source byte limits bound work, not allocator overhead.108pub const Inspection = struct {109    arena: std.heap.ArenaAllocator,110    result: Report,111112    pub fn deinit(self: *Inspection) void {113        self.arena.deinit();114        self.* = undefined;115    }116};117118pub const Builder = struct {119    allocator: std.mem.Allocator,120    root: []const u8,121    options: Options,122    deadline_ns: i128,123    report: Report,124    targets: [targets_max]Target = undefined,125    target_count: u8 = 0,126    entries: [entries_max]Entry = undefined,127    entry_count: u8 = 0,128129    pub fn active(self: *Builder) bool {130        std.debug.assert(self.target_count <= targets_max);131        std.debug.assert(self.entry_count <= self.options.limits.entries);132        if (sys.time.nanoTimestamp() < self.deadline_ns) return true;133        self.report.omissions.deadline = true;134        self.exhausted();135        return false;136    }137138    pub fn row(self: *Builder) bool {139        const work = self.report.work;140        std.debug.assert(work.visited_edges <= work.visited_index_rows);141        std.debug.assert(work.visited_index_rows <= work.index_steps);142        if (!self.active()) return false;143        if (self.report.work.index_steps == self.options.limits.rows) {144            self.report.omissions.rows = true;145            self.exhausted();146            return false;147        }148        self.report.work.index_steps += 1;149        std.debug.assert(self.report.work.index_steps <= self.options.limits.rows);150        return true;151    }152153    pub fn exhausted(self: *Builder) void {154        std.debug.assert(self.report.work.index_steps <= self.options.limits.rows);155        std.debug.assert(self.report.coverage.source_bytes <= self.options.limits.source_bytes);156        self.report.state = .budget_exhausted;157        self.report.coverage.traversal_complete = false;158        self.report.omissions.exact = false;159    }160161    pub fn add(self: *Builder, entry: Entry) bool {162        std.debug.assert(self.entry_count <= self.options.limits.entries);163        for (self.entries[0..self.entry_count]) |existing| {164            if (existing.section == entry.section and165                std.mem.eql(u8, existing.target, entry.target) and166                std.mem.eql(u8, existing.name, entry.name)) return false;167        }168        if (self.entry_count == self.options.limits.entries) {169            self.report.omissions.entries +|= 1;170            self.exhausted();171            return false;172        }173        std.debug.assert(entry.name.len != 0);174        std.debug.assert(entry.target.len != 0);175        self.entries[self.entry_count] = entry;176        self.entry_count += 1;177        return true;178    }179180    pub fn finish(self: *Builder) !Report {181        std.debug.assert(self.target_count <= targets_max);182        std.debug.assert(self.entry_count <= entries_max);183        std.debug.assert(self.report.work.loaded_nodes <= self.report.work.visited_index_rows);184        std.debug.assert(self.report.work.depth_reached <= self.options.limits.depth);185        self.report.targets = try self.allocator.dupe(Target, self.targets[0..self.target_count]);186        self.report.entries = try self.allocator.dupe(Entry, self.entries[0..self.entry_count]);187        return self.report;188    }189};190191pub fn validate(root: []const u8, targets: []const []const u8, options: Options) !void {192    if (!std.fs.path.isAbsolute(root)) return error.InvalidInspectionRoot;193    if (targets.len == 0 or targets.len > targets_max) return error.InvalidInspectionTargets;194    if (options.bytes < 1024 or options.bytes > output_bytes_max) {195        return error.InvalidInspectionLimit;196    }197    if (options.deadline_ms > 1000) return error.InvalidInspectionLimit;198    const limits = options.limits;199    if (limits.entries == 0 or limits.entries > entries_max) return error.InvalidInspectionLimit;200    if (limits.rows == 0 or limits.rows > rows_max) return error.InvalidInspectionLimit;201    if (limits.depth > 2 or limits.source_bytes > source_bytes_max) {202        return error.InvalidInspectionLimit;203    }204    var bytes: usize = root.len;205    try validText(root);206    for (targets) |target| {207        try validText(target);208        bytes += target.len;209        if (bytes > input_bytes_max) return error.InvalidInspectionTargets;210    }211}212213fn validText(text: []const u8) !void {214    if (text.len == 0 or !std.unicode.utf8ValidateSlice(text)) {215        return error.InvalidInspectionTargets;216    }217    for (text) |byte| if (byte < 32 or byte == 127) return error.InvalidInspectionTargets;218}

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