@gate-forge/core 0.1.0

package/dist/graph/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/graph/schema.ts"],"names":[],"mappings":"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"}

package/dist/graph/symbols.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The resource-graph symbol table (go/no-go first action #2):
+ * cross-module inheritance resolution so inherited tablenames stop
+ * being `unresolved` when statically resolvable.
+ *
+ * Detectors contribute class symbols as resources with the reserved
+ * {@link CLASS_SYMBOL_KIND} kind (see `ClassSymbolAttributesSchema`).
+ * The graph indexes them and resolves a subclass's inherited tablename
+ * by walking declared base names through the repo-wide table:
+ *
+ * 1. a base name matching a symbol's exact `qname` wins first;
+ * 2. then a unique same-file symbol whose last name segment matches
+ *    (lexical-scope preference — function-local shadowing is legal);
+ * 3. then a unique repo-wide last-name match;
+ * 4. ambiguous or missing bases end the walk with a typed cause.
+ *
+ * The walk follows base chains in declaration order (first literal
+ * tablename wins, mirroring MRO-ish expectations) and is cycle-guarded.
+ * Resolution is purely additive: the graph only ever resolves or keeps
+ * the detector's typed unresolved entry — it never rewrites one.
+ */
+import type { Resource } from '../schemas/resource.js';
+import type { GraphFinding } from './schema.js';
+import { type GraphUnresolved } from './schema.js';
+/** A validated class symbol, extracted from a class-symbol resource. */
+export interface ClassSymbol {
+    /** Scope-qualified class name (dotted). */
+    qname: string;
+    /** Kind used for a table materialized from this class. */
+    resourceKind: string;
+    /** Direct base names as written, in declaration order. */
+    baseNames: string[];
+    /** Literal tablename declared on the class itself, if any. */
+    tableName: string | null;
+    /** `__abstract__ = True` base — never materializes directly. */
+    abstract: boolean;
+    /** Detector assertion that this class's tablename is unresolved. */
+    tablenameUnresolved: boolean;
+    /** Repo-root-relative declaration file. */
+    source: string;
+    /** Exact declaration location. */
+    location: {
+        file: string;
+        line: number;
+        col: number;
+    };
+    /** Detector that contributed the symbol. */
+    detectorId: string;
+    /** Detector version at the handshake. */
+    detectorVersion: string;
+}
+/** The repo-wide symbol table: qname index + last-name-segment index. */
+export interface SymbolTable {
+    /** qname → symbol (first by source order on duplicate qnames). */
+    byQname: Map<string, ClassSymbol>;
+    /** Last name segment → symbols sorted by location (may be ambiguous). */
+    byLastName: Map<string, ClassSymbol[]>;
+}
+/** Outcome of resolving one class's inherited tablename. */
+export type InheritanceResolution = {
+    ok: true;
+    name: string;
+    baseQname: string;
+} | {
+    ok: false;
+    cause: string;
+};
+/**
+ * Extracts class symbols from detector resources. Resources that claim
+ * the reserved class-symbol kind but carry malformed attributes are
+ * reported as `INVALID_RESOURCE` findings and skipped — a hostile or
+ * broken symbol payload degrades to "unresolved stays unresolved",
+ * never to a crash or silent drop.
+ *
+ * Args:
+ *   detectors: all detector contributions (symbol table is repo-wide).
+ *   findings: accumulator; malformed class-symbol resources append here.
+ *
+ * Returns:
+ *   SymbolTable: qname and last-name indexes of the valid symbols.
+ */
+export declare function buildSymbolTable(detectors: {
+    detectorId: string;
+    detectorVersion: string;
+    resources: Resource[];
+}[], findings: GraphFinding[]): SymbolTable;
+/**
+ * Resolves the inherited tablename of a class through the symbol
+ * table, following declared base names in order. Per base name:
+ * exact qname match, then unique same-file last-name match, then
+ * unique repo-wide last-name match. The first literal tablename on
+ * any followed chain wins; all failure causes of the first failing
+ * base are reported when none succeeds.
+ *
+ * Args:
+ *   symbol: the class whose tablename is missing.
+ *   table: the repo-wide symbol table.
+ *
+ * Returns:
+ *   InheritanceResolution: the literal name + defining base qname on
+ *   success, or a single-cause typed explanation on failure.
+ */
+export declare function resolveInheritedName(symbol: ClassSymbol, table: SymbolTable): InheritanceResolution;
+/**
+ * Builds a lookup of `file:line` → class symbol for one detector's
+ * symbols. Detector unresolved entries whose location points at a
+ * class statement are matched through this map, which is how a
+ * resolved symbol retires its detector's unresolved entry.
+ *
+ * Args:
+ *   symbols: the detector's own class symbols.
+ *
+ * Returns:
+ *   Map<string, ClassSymbol>: keyed by `${file}:${line}`.
+ */
+export declare function locationIndex(symbols: ClassSymbol[]): Map<string, ClassSymbol>;
+/**
+ * Sorts unresolved entries into their deterministic output order:
+ * location (file, line, col), then reason code, then detail, then
+ * detector id.
+ *
+ * Args:
+ *   entries: unresolved entries in any order.
+ *
+ * Returns:
+ *   GraphUnresolved[]: a new sorted array.
+ */
+export declare function sortUnresolved(entries: GraphUnresolved[]): GraphUnresolved[];
+//# sourceMappingURL=symbols.d.ts.map

package/dist/graph/symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.d.ts","sourceRoot":"","sources":["../../src/graph/symbols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAkD,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnG,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gEAAgE;IAChE,QAAQ,EAAE,OAAO,CAAC;IAClB,oEAAoE;IACpE,mBAAmB,EAAE,OAAO,CAAC;IAC7B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAClC,yEAAyE;IACzE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;CACxC;AAED,4DAA4D;AAC5D,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;CAAE,EAAE,EACnF,QAAQ,EAAE,YAAY,EAAE,GACvB,WAAW,CAuDb;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,WAAW,GACjB,qBAAqB,CAEvB;AAwDD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,WAAW,EAAE,GACrB,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAM1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAU5E"}

package/dist/graph/symbols.js

@@ -0,0 +1,177 @@
+import { CLASS_SYMBOL_KIND, ClassSymbolAttributesSchema } from './schema.js';
+import { compareStrings, compareLocations } from './util.js';
+/**
+ * Extracts class symbols from detector resources. Resources that claim
+ * the reserved class-symbol kind but carry malformed attributes are
+ * reported as `INVALID_RESOURCE` findings and skipped — a hostile or
+ * broken symbol payload degrades to "unresolved stays unresolved",
+ * never to a crash or silent drop.
+ *
+ * Args:
+ *   detectors: all detector contributions (symbol table is repo-wide).
+ *   findings: accumulator; malformed class-symbol resources append here.
+ *
+ * Returns:
+ *   SymbolTable: qname and last-name indexes of the valid symbols.
+ */
+export function buildSymbolTable(detectors, findings) {
+    const candidates = [];
+    for (const detector of detectors) {
+        for (const resource of detector.resources) {
+            if (resource.kind !== CLASS_SYMBOL_KIND)
+                continue;
+            const parsed = ClassSymbolAttributesSchema.safeParse(resource.attributes);
+            if (!parsed.success) {
+                findings.push({
+                    code: 'INVALID_RESOURCE',
+                    detail: `class-symbol resource from ${detector.detectorId} has malformed attributes: ${parsed.error.issues[0]?.message ?? 'unknown issue'}`,
+                    locations: [resource.location],
+                    detectorId: detector.detectorId,
+                });
+                continue;
+            }
+            candidates.push({
+                qname: parsed.data.qname,
+                resourceKind: parsed.data.resourceKind,
+                baseNames: parsed.data.baseNames ?? [],
+                tableName: parsed.data.tableName ?? null,
+                abstract: parsed.data.abstract ?? false,
+                tablenameUnresolved: parsed.data.tablenameUnresolved ?? false,
+                source: resource.source,
+                location: resource.location,
+                detectorId: detector.detectorId,
+                detectorVersion: detector.detectorVersion,
+            });
+        }
+    }
+    candidates.sort((a, b) => compareStrings(a.source, b.source) ||
+        compareLocations(a.location, b.location));
+    const byQname = new Map();
+    const byLastName = new Map();
+    for (const symbol of candidates) {
+        const existing = byQname.get(symbol.qname);
+        if (existing !== undefined) {
+            findings.push({
+                code: 'DUPLICATE_CLASS_QNAME',
+                detail: `class qname '${symbol.qname}' declared by ${symbol.detectorId} duplicates an earlier declaration from ${existing.detectorId}; the earlier symbol (sorted by source, line, col) wins`,
+                locations: [existing.location, symbol.location],
+                detectorId: symbol.detectorId,
+            });
+            continue;
+        }
+        byQname.set(symbol.qname, symbol);
+        const lastName = symbol.qname.split('.').at(-1) ?? symbol.qname;
+        const bucket = byLastName.get(lastName);
+        if (bucket === undefined)
+            byLastName.set(lastName, [symbol]);
+        else
+            bucket.push(symbol);
+    }
+    return { byQname, byLastName };
+}
+/**
+ * Resolves the inherited tablename of a class through the symbol
+ * table, following declared base names in order. Per base name:
+ * exact qname match, then unique same-file last-name match, then
+ * unique repo-wide last-name match. The first literal tablename on
+ * any followed chain wins; all failure causes of the first failing
+ * base are reported when none succeeds.
+ *
+ * Args:
+ *   symbol: the class whose tablename is missing.
+ *   table: the repo-wide symbol table.
+ *
+ * Returns:
+ *   InheritanceResolution: the literal name + defining base qname on
+ *   success, or a single-cause typed explanation on failure.
+ */
+export function resolveInheritedName(symbol, table) {
+    return walk(symbol, new Set([symbol.qname]), table);
+}
+function walk(symbol, visited, table) {
+    let firstFailure = null;
+    for (const baseName of symbol.baseNames) {
+        const base = lookupBase(baseName, symbol, table);
+        if (base === undefined) {
+            const failure = {
+                ok: false,
+                cause: `base class '${baseName}' of '${symbol.qname}' not found in the symbol table`,
+            };
+            firstFailure ??= failure;
+            continue;
+        }
+        if (base.tableName !== null) {
+            return { ok: true, name: base.tableName, baseQname: base.qname };
+        }
+        if (visited.has(base.qname)) {
+            const failure = {
+                ok: false,
+                cause: `inheritance cycle at '${base.qname}' while resolving '${symbol.qname}'`,
+            };
+            firstFailure ??= failure;
+            continue;
+        }
+        visited.add(base.qname);
+        const nested = walk(base, visited, table);
+        if (nested.ok)
+            return nested;
+        firstFailure ??= nested;
+    }
+    return (firstFailure ?? {
+        ok: false,
+        cause: `'${symbol.qname}' declares no base carrying a literal tablename`,
+    });
+}
+function lookupBase(baseName, from, table) {
+    const exact = table.byQname.get(baseName);
+    if (exact !== undefined)
+        return exact;
+    const candidates = table.byLastName.get(baseName) ?? [];
+    const sameFile = candidates.filter((c) => c.source === from.source);
+    if (sameFile.length === 1)
+        return sameFile[0];
+    if (candidates.length === 1)
+        return candidates[0];
+    return undefined;
+}
+/**
+ * Builds a lookup of `file:line` → class symbol for one detector's
+ * symbols. Detector unresolved entries whose location points at a
+ * class statement are matched through this map, which is how a
+ * resolved symbol retires its detector's unresolved entry.
+ *
+ * Args:
+ *   symbols: the detector's own class symbols.
+ *
+ * Returns:
+ *   Map<string, ClassSymbol>: keyed by `${file}:${line}`.
+ */
+export function locationIndex(symbols) {
+    const index = new Map();
+    for (const symbol of symbols) {
+        index.set(`${symbol.location.file}:${symbol.location.line}`, symbol);
+    }
+    return index;
+}
+/**
+ * Sorts unresolved entries into their deterministic output order:
+ * location (file, line, col), then reason code, then detail, then
+ * detector id.
+ *
+ * Args:
+ *   entries: unresolved entries in any order.
+ *
+ * Returns:
+ *   GraphUnresolved[]: a new sorted array.
+ */
+export function sortUnresolved(entries) {
+    return [...entries].sort((a, b) => {
+        const byLocation = compareLocations(a.reason.location, b.reason.location);
+        if (byLocation !== 0)
+            return byLocation;
+        return (compareStrings(a.reason.code, b.reason.code) ||
+            compareStrings(a.reason.detail, b.reason.detail) ||
+            compareStrings(a.detectorId, b.detectorId));
+    });
+}
+//# sourceMappingURL=symbols.js.map

package/dist/graph/symbols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.js","sourceRoot":"","sources":["../../src/graph/symbols.ts"],"names":[],"mappings":"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"}

package/dist/graph/util.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Deterministic comparison helpers for the resource graph and policy
+ * engine. All orderings in gateforge MUST go through these so that
+ * outputs are byte-for-byte stable across locales, runtimes, and
+ * process runs (same inputs → identical graph + obligations).
+ */
+/**
+ * Codepoint-wise string comparison (`a < b ? -1 : a > b ? 1 : 0`).
+ * Never use `localeCompare` — its result varies by ICU locale.
+ *
+ * Args:
+ *   a: first string
+ *   b: second string
+ *
+ * Returns:
+ *   number: negative when a < b, positive when a > b, 0 when equal
+ */
+export declare function compareStrings(a: string, b: string): number;
+/**
+ * Total order over source locations: file (codepoints), then 1-based
+ * line, then 0-based col. Used to keep finding/unresolved location
+ * lists deterministic.
+ *
+ * Args:
+ *   a: first location {file, line, col}
+ *   b: second location {file, line, col}
+ *
+ * Returns:
+ *   number: negative/zero/positive per the ordering above
+ */
+export declare function compareLocations(a: {
+    file: string;
+    line: number;
+    col: number;
+}, b: {
+    file: string;
+    line: number;
+    col: number;
+}): number;
+//# sourceMappingURL=util.d.ts.map

package/dist/graph/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/graph/util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAC9C,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC7C,MAAM,CAKR"}

package/dist/graph/util.js

@@ -0,0 +1,41 @@
+/**
+ * Deterministic comparison helpers for the resource graph and policy
+ * engine. All orderings in gateforge MUST go through these so that
+ * outputs are byte-for-byte stable across locales, runtimes, and
+ * process runs (same inputs → identical graph + obligations).
+ */
+/**
+ * Codepoint-wise string comparison (`a < b ? -1 : a > b ? 1 : 0`).
+ * Never use `localeCompare` — its result varies by ICU locale.
+ *
+ * Args:
+ *   a: first string
+ *   b: second string
+ *
+ * Returns:
+ *   number: negative when a < b, positive when a > b, 0 when equal
+ */
+export function compareStrings(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Total order over source locations: file (codepoints), then 1-based
+ * line, then 0-based col. Used to keep finding/unresolved location
+ * lists deterministic.
+ *
+ * Args:
+ *   a: first location {file, line, col}
+ *   b: second location {file, line, col}
+ *
+ * Returns:
+ *   number: negative/zero/positive per the ordering above
+ */
+export function compareLocations(a, b) {
+    const byFile = compareStrings(a.file, b.file);
+    if (byFile !== 0)
+        return byFile;
+    if (a.line !== b.line)
+        return a.line - b.line;
+    return a.col - b.col;
+}
+//# sourceMappingURL=util.js.map

package/dist/graph/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../../src/graph/util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,CAAS,EAAE,CAAS;IACjD,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,CAA8C,EAC9C,CAA8C;IAE9C,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAChC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;IAC9C,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;AACvB,CAAC"}