@principal-ai/subsystems-react 0.17.0

package/dist/graphify/resolve.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Resolve graphify type-name references to their defining nodes.
+ *
+ * A `references` edge (`parameter_type`, `return_type`, `field`,
+ * `generic_arg`) targets either the type's real definition node or a
+ * *sourceless stub* graphify left behind when the name could not be uniquely
+ * resolved at extraction time (mirrors `_rewire_unique_stub_nodes` there:
+ * ambiguous same-label definitions and never-defined names stay stubs).
+ *
+ * This module applies the same conservative matching from the consumer side so
+ * UI click targets can distinguish "jump to definition" from "N candidates"
+ * from "not in this corpus".
+ */
+import type { GraphifyNode } from './types';
+import type { GraphifyReferenceInfo } from './consolidated';
+/** Outcome of resolving one type reference. */
+export type GraphifyTypeRefStatus = 
+/** Target node is a real definition — jump to its `source_file`. */
+'resolved'
+/** Target was a stub and multiple same-label definitions exist. */
+ | 'ambiguous'
+/** Target was a stub and nothing in the corpus defines the name. */
+ | 'unresolved'
+/** No nodeId on the ref, or the id is not in the graph. */
+ | 'missing';
+export interface GraphifyTypeRefResolution {
+    status: GraphifyTypeRefStatus;
+    /** The definition node when resolved; the stub itself otherwise. */
+    node: GraphifyNode | null;
+    /** Same-label definitions when the target was an unresolved stub. */
+    candidates: GraphifyNode[];
+}
+/**
+ * Mirror graphify's `normalise_callable_label`: trim, strip surrounding
+ * parens/leading dots, lowercase. `SessionReader()` and `sessionreader`
+ * collapse to the same key.
+ */
+export declare function normalizeGraphifyLabel(label: string): string;
+/** Prebuilt lookup state — build once per graph, resolve many refs. */
+export interface GraphifyTypeResolver {
+    resolve(nodeId: string | undefined, fallbackLabel?: string): GraphifyTypeRefResolution;
+}
+export declare function createGraphifyTypeResolver(nodes: readonly GraphifyNode[]): GraphifyTypeResolver;
+/** One-shot convenience over {@link createGraphifyTypeResolver}. */
+export declare function resolveGraphifyTypeRef(nodes: readonly GraphifyNode[], ref: Pick<GraphifyReferenceInfo, 'nodeId'> | {
+    nodeId?: string;
+} | undefined, fallbackLabel?: string): GraphifyTypeRefResolution;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/graphify/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/graphify/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAE5D,+CAA+C;AAC/C,MAAM,MAAM,qBAAqB;AAC/B,oEAAoE;AAClE,UAAU;AACZ,mEAAmE;GACjE,WAAW;AACb,oEAAoE;GAClE,YAAY;AACd,2DAA2D;GACzD,SAAS,CAAC;AAEd,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,oEAAoE;IACpE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,qEAAqE;IACrE,UAAU,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM5D;AAaD,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,yBAAyB,CAAC;CACxF;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,oBAAoB,CAwC/F;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,GAAG,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EAC5E,aAAa,CAAC,EAAE,MAAM,GACrB,yBAAyB,CAE3B"}

package/dist/graphify/resolve.js

@@ -0,0 +1,83 @@
+/**
+ * Resolve graphify type-name references to their defining nodes.
+ *
+ * A `references` edge (`parameter_type`, `return_type`, `field`,
+ * `generic_arg`) targets either the type's real definition node or a
+ * *sourceless stub* graphify left behind when the name could not be uniquely
+ * resolved at extraction time (mirrors `_rewire_unique_stub_nodes` there:
+ * ambiguous same-label definitions and never-defined names stay stubs).
+ *
+ * This module applies the same conservative matching from the consumer side so
+ * UI click targets can distinguish "jump to definition" from "N candidates"
+ * from "not in this corpus".
+ */
+/**
+ * Mirror graphify's `normalise_callable_label`: trim, strip surrounding
+ * parens/leading dots, lowercase. `SessionReader()` and `sessionreader`
+ * collapse to the same key.
+ */
+export function normalizeGraphifyLabel(label) {
+    return label
+        .trim()
+        .replace(/^[()]+|[()]+$/g, '')
+        .replace(/^\.+/, '')
+        .toLowerCase();
+}
+const FILE_SUFFIX_RE = /\.(py|js|jsx|ts|tsx|mjs|cjs|java|go|rs|rb|php|cs|cpp|cc|c|h|hpp|pas|pp|dpr|swift|kt|scala|dart|lua|pl|pm|ex|exs|zig|vue|svelte)$/i;
+function isDefinition(node) {
+    if (node.file_type !== 'code')
+        return false;
+    const file = typeof node.source_file === 'string' ? node.source_file : '';
+    if (!file)
+        return false;
+    const label = typeof node.label === 'string' ? node.label.trim() : '';
+    return !!label && !FILE_SUFFIX_RE.test(label);
+}
+export function createGraphifyTypeResolver(nodes) {
+    const byId = new Map();
+    const defsByExactLabel = new Map();
+    const defsByFoldedLabel = new Map();
+    for (const node of nodes) {
+        byId.set(String(node.id), node);
+        if (!isDefinition(node))
+            continue;
+        const label = String(node.label).trim();
+        (defsByExactLabel.get(label) ?? defsByExactLabel.set(label, []).get(label)).push(node);
+        const folded = normalizeGraphifyLabel(label);
+        if (!folded)
+            continue;
+        (defsByFoldedLabel.get(folded) ?? defsByFoldedLabel.set(folded, []).get(folded)).push(node);
+    }
+    function resolve(nodeId, fallbackLabel) {
+        if (!nodeId)
+            return { status: 'missing', node: null, candidates: [] };
+        const target = byId.get(nodeId);
+        if (!target)
+            return { status: 'missing', node: null, candidates: [] };
+        // Real definition (graphify rewired the reference onto it, or it lived in
+        // the referencing file all along).
+        if (isDefinition(target))
+            return { status: 'resolved', node: target, candidates: [] };
+        // Sourceless stub — try the rewire tiers: exact label, then folded.
+        const label = typeof target.label === 'string' && target.label.trim() ? target.label.trim() : (fallbackLabel ?? '');
+        let candidates = defsByExactLabel.get(label) ?? [];
+        if (candidates.length !== 1) {
+            const folded = normalizeGraphifyLabel(label);
+            candidates = folded ? (defsByFoldedLabel.get(folded) ?? []) : [];
+        }
+        if (candidates.length === 1) {
+            // Unique match — same fold `_rewire_unique_stub_nodes` performs at
+            // extraction time; graphs built before that pass land here instead.
+            return { status: 'resolved', node: candidates[0], candidates };
+        }
+        if (candidates.length > 1)
+            return { status: 'ambiguous', node: target, candidates };
+        return { status: 'unresolved', node: target, candidates: [] };
+    }
+    return { resolve };
+}
+/** One-shot convenience over {@link createGraphifyTypeResolver}. */
+export function resolveGraphifyTypeRef(nodes, ref, fallbackLabel) {
+    return createGraphifyTypeResolver(nodes).resolve(ref?.nodeId, fallbackLabel);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/graphify/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/graphify/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwBH;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,OAAO,KAAK;SACT,IAAI,EAAE;SACN,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;SAC7B,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,MAAM,cAAc,GAClB,mIAAmI,CAAC;AAEtI,SAAS,YAAY,CAAC,IAAkB;IACtC,IAAI,IAAI,CAAC,SAAS,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAOD,MAAM,UAAU,0BAA0B,CAAC,KAA8B;IACvE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC7C,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC3D,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE5D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE;QACxB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;YAAE,SAAS;QAClC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACxC,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxF,MAAM,MAAM,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KAC9F;IAED,SAAS,OAAO,CAAC,MAA0B,EAAE,aAAsB;QACjE,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;QACtE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;QACtE,0EAA0E;QAC1E,mCAAmC;QACnC,IAAI,YAAY,CAAC,MAAM,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;QAEtF,oEAAoE;QACpE,MAAM,KAAK,GAAG,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;QACpH,IAAI,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACnD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;YAC3B,MAAM,MAAM,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;YAC7C,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAClE;QACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;YAC3B,mEAAmE;YACnE,oEAAoE;YACpE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAE,EAAE,UAAU,EAAE,CAAC;SACjE;QACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QACpF,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAChE,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,sBAAsB,CACpC,KAA8B,EAC9B,GAA4E,EAC5E,aAAsB;IAEtB,OAAO,0BAA0B,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;AAC/E,CAAC"}

package/dist/graphify/signature.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Signature / params verification against graphify `references` edges.
+ *
+ * Graphify does not store arity or parameter names — only `parameter_type` /
+ * `return_type` edges to type nodes (unions become multiple edges). Comparison
+ * is therefore **named type bags**, not positional arity.
+ *
+ * Many TS/JS functions have no such edges yet. When graphify has no signature
+ * signal, the check is skipped (not a hard fail) so Verify can still gate on
+ * kind. When graphify *does* emit types, claimed detail must match.
+ */
+import type { GraphifyEdge, GraphifyNode } from './types';
+/** Inferred signature from graphify edges (no param names). */
+export interface GraphifyInferredSignature {
+    parameters: Array<{
+        type: string;
+        nodeId: string;
+    }>;
+    returnType?: string;
+    returnTypeNodeId?: string;
+    /**
+     * Types reachable only via `generic_arg` edges (Promise<X>, Array<X>,
+     * Omit<X,…>, Map<…>). Kept out of `parameters`/`returnType` — not read
+     * by the bag comparison — so skipped cases can be told apart.
+     */
+    genericArgs?: Array<{
+        type: string;
+        nodeId: string;
+    }>;
+    /**
+     * Count of `inline_parameter` self-edges (anonymous object-literal params).
+     * Graphify emits one per anon param only with its `--inline-params` flag.
+     */
+    inlineParameters?: number;
+    /** True when at least one parameter_type or return_type edge exists. */
+    hasSignal: boolean;
+}
+export interface ClaimedSignature {
+    parameters?: Array<{
+        name?: string;
+        type: string;
+    }>;
+    returnType?: string;
+}
+/**
+ * Granular skip classification. `signature_skipped` means "graphify has no
+ * parameter_type/return_type edges to compare", but *why* matters for future
+ * work:
+ * - `no_claimed_types`: authored detail has no named types (primitives/inline).
+ * - `generic_arg_only`: claimed types resolve, but only as `generic_arg`
+ *   (Promise/Omit/Map/Array wrappers) — this extractor does not read them.
+ * - `partially_generic_arg`: some, not all, claimed types resolve as generic_arg.
+ * - `unresolved_claimed_types`: claimed names have no edges at all
+ *   (global/npm types, or a dropped same-file label collision).
+ */
+export type SignatureSkipCode = 'no_claimed_types' | 'generic_arg_only' | 'partially_generic_arg' | 'unresolved_claimed_types';
+export interface SignatureCompareResult {
+    match: boolean;
+    /** Skipped because graphify had no parameter/return type edges. */
+    skipped: boolean;
+    reason?: string;
+    /** Granular skip classification when `skipped` is true. */
+    skipCode?: SignatureSkipCode;
+    claimed: {
+        parameterTypes: string[];
+        returnTypes: string[];
+    };
+    inferred: {
+        parameterTypes: string[];
+        returnTypes: string[];
+    };
+}
+/**
+ * Pull comparable named type identifiers out of an authored / graphify type
+ * string. Skips primitives, inline object types, and known wrappers.
+ */
+export declare function extractNamedTypes(typeStr: string): string[];
+/** Collect parameter_type / return_type edges for a callable node. */
+export declare function extractGraphifySignature(nodeId: string, edges: readonly GraphifyEdge[], nodesById: ReadonlyMap<string, GraphifyNode>): GraphifyInferredSignature;
+/**
+ * Compare authored function/method detail signature to graphify edges.
+ *
+ * - No graphify signal → skipped (match=true).
+ * - Otherwise named-type bags for params and return must match exactly.
+ */
+export declare function compareSignatures(claimed: ClaimedSignature | undefined, inferred: GraphifyInferredSignature): SignatureCompareResult;
+//# sourceMappingURL=signature.d.ts.map

package/dist/graphify/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/graphify/signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACzC,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAChC,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAC1B,kBAAkB,GAClB,kBAAkB,GAClB,uBAAuB,GACvB,0BAA0B,CAAC;AAE9B,MAAM,WAAW,sBAAsB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE;QAAE,cAAc,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC7D,QAAQ,EAAE;QAAE,cAAc,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC9D;AA4CD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA4B3D;AAWD,sEAAsE;AACtE,wBAAgB,wBAAwB,CACvC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,GAC1C,yBAAyB,CAgC3B;AA8CD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,QAAQ,EAAE,yBAAyB,GACjC,sBAAsB,CA6GxB"}

package/dist/graphify/signature.js

@@ -0,0 +1,276 @@
+/**
+ * Signature / params verification against graphify `references` edges.
+ *
+ * Graphify does not store arity or parameter names — only `parameter_type` /
+ * `return_type` edges to type nodes (unions become multiple edges). Comparison
+ * is therefore **named type bags**, not positional arity.
+ *
+ * Many TS/JS functions have no such edges yet. When graphify has no signature
+ * signal, the check is skipped (not a hard fail) so Verify can still gate on
+ * kind. When graphify *does* emit types, claimed detail must match.
+ */
+const PRIMITIVES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'void',
+    'null',
+    'undefined',
+    'any',
+    'unknown',
+    'never',
+    'object',
+    'symbol',
+    'bigint',
+    'true',
+    'false',
+    'this',
+]);
+/** Common generic wrappers — keep inner type names, drop the wrapper. */
+const TYPE_WRAPPERS = new Set([
+    'Promise',
+    'Array',
+    'ReadonlyArray',
+    'Map',
+    'Set',
+    'WeakMap',
+    'WeakSet',
+    'Record',
+    'Partial',
+    'Required',
+    'Readonly',
+    'Awaited',
+    'NonNullable',
+    'ReturnType',
+    'Parameters',
+    'InstanceType',
+    'Pick',
+    'Omit',
+    'Exclude',
+    'Extract',
+]);
+/**
+ * Pull comparable named type identifiers out of an authored / graphify type
+ * string. Skips primitives, inline object types, and known wrappers.
+ */
+export function extractNamedTypes(typeStr) {
+    if (!typeStr || !typeStr.trim())
+        return [];
+    let s = typeStr;
+    // Drop string/template literals so their contents aren't tokens.
+    s = s.replace(/`(?:\\.|[^`\\])*`/g, ' ');
+    s = s.replace(/'(?:\\.|[^'\\])*'/g, ' ');
+    s = s.replace(/"(?:\\.|[^"\\])*"/g, ' ');
+    // Drop inline object / mapped types (non-greedy, repeated for nesting).
+    for (let i = 0; i < 8; i++) {
+        const next = s.replace(/\{[^{}]*\}/g, ' ');
+        if (next === s)
+            break;
+        s = next;
+    }
+    const found = new Set();
+    const re = /[A-Za-z_][A-Za-z0-9_.]*/g;
+    let m;
+    while ((m = re.exec(s)) !== null) {
+        const raw = m[0];
+        const base = raw.includes('.') ? (raw.split('.').pop() ?? raw) : raw;
+        if (PRIMITIVES.has(base))
+            continue;
+        if (TYPE_WRAPPERS.has(base))
+            continue;
+        // Skip lone lowercase keywords that aren't types we care about.
+        if (base === 'typeof' || base === 'keyof' || base === 'infer' || base === 'extends') {
+            continue;
+        }
+        found.add(base);
+    }
+    return [...found].sort();
+}
+function labelOf(nodeId, nodesById) {
+    const n = nodesById.get(nodeId);
+    const label = n && typeof n.label === 'string' ? n.label.trim() : '';
+    return label || nodeId;
+}
+/** Collect parameter_type / return_type edges for a callable node. */
+export function extractGraphifySignature(nodeId, edges, nodesById) {
+    const id = String(nodeId);
+    const parameters = [];
+    const genericArgs = [];
+    let returnType;
+    let returnTypeNodeId;
+    let inlineParameters = 0;
+    for (const e of edges) {
+        if (String(e.source) !== id || e.relation !== 'references')
+            continue;
+        const ctx = e.context;
+        const target = String(e.target);
+        if (ctx === 'parameter_type') {
+            parameters.push({ type: labelOf(target, nodesById), nodeId: target });
+        }
+        else if (ctx === 'return_type' && returnType === undefined) {
+            returnType = labelOf(target, nodesById);
+            returnTypeNodeId = target;
+        }
+        else if (ctx === 'generic_arg') {
+            genericArgs.push({ type: labelOf(target, nodesById), nodeId: target });
+        }
+        else if (ctx === 'inline_parameter') {
+            inlineParameters += 1;
+        }
+    }
+    return {
+        parameters,
+        genericArgs,
+        returnType,
+        returnTypeNodeId,
+        inlineParameters,
+        hasSignal: parameters.length > 0 || returnType !== undefined,
+    };
+}
+function bagsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function claimedBags(claimed) {
+    const parameterTypes = new Set();
+    for (const p of claimed?.parameters ?? []) {
+        for (const t of extractNamedTypes(p.type))
+            parameterTypes.add(t);
+    }
+    const returnTypes = new Set();
+    if (claimed?.returnType) {
+        for (const t of extractNamedTypes(claimed.returnType))
+            returnTypes.add(t);
+    }
+    return {
+        parameterTypes: [...parameterTypes].sort(),
+        returnTypes: [...returnTypes].sort(),
+    };
+}
+function inferredBags(inferred) {
+    const parameterTypes = new Set();
+    for (const p of inferred.parameters) {
+        for (const t of extractNamedTypes(p.type))
+            parameterTypes.add(t);
+    }
+    const returnTypes = new Set();
+    if (inferred.returnType) {
+        for (const t of extractNamedTypes(inferred.returnType))
+            returnTypes.add(t);
+    }
+    return {
+        parameterTypes: [...parameterTypes].sort(),
+        returnTypes: [...returnTypes].sort(),
+    };
+}
+/**
+ * Compare authored function/method detail signature to graphify edges.
+ *
+ * - No graphify signal → skipped (match=true).
+ * - Otherwise named-type bags for params and return must match exactly.
+ */
+export function compareSignatures(claimed, inferred) {
+    const claimedBagsResult = claimedBags(claimed);
+    const inferredBagsResult = inferredBags(inferred);
+    // Anonymous object-literal params ("inline") carry no named types, so they
+    // only ever surface via graphify's `inline_parameter` markers. A claim of an
+    // inline param against a graph with no marker proves nothing (the store
+    // graph may predate the flag), so absence alone keeps the skip path. When
+    // the graph DOES emit a marker, anon-count parity is compared like any
+    // parameter signal.
+    const claimedAnonCount = (claimed?.parameters ?? []).filter((p) => (p.type ?? '').trim().startsWith('{')).length;
+    const inferredAnonCount = inferred.inlineParameters ?? 0;
+    const hasAnonSignal = inferredAnonCount > 0;
+    if (!inferred.hasSignal && !hasAnonSignal) {
+        const claimedTypes = new Set([
+            ...claimedBagsResult.parameterTypes,
+            ...claimedBagsResult.returnTypes,
+        ]);
+        const genericArgTypes = new Set((inferred.genericArgs ?? []).map((a) => a.type));
+        const sorted = [...claimedTypes].sort();
+        let skipCode;
+        let reason;
+        if (sorted.length === 0) {
+            skipCode = 'no_claimed_types';
+            reason = 'no claimable named types in authored signature (primitives/inline only)';
+        }
+        else {
+            const found = sorted.filter((t) => genericArgTypes.has(t));
+            if (found.length === sorted.length) {
+                skipCode = 'generic_arg_only';
+                reason = `claimed types ([${sorted.join(', ')}]) present only as generic_arg (wrapper-indirected: Promise/Omit/Map/Array) — extractor does not read generic_arg`;
+            }
+            else if (found.length > 0) {
+                skipCode = 'partially_generic_arg';
+                reason = `claimed types resolve only via generic_arg for ${found.join(', ')}; rest unresolved (${sorted.filter((t) => !genericArgTypes.has(t)).join(', ')})`;
+            }
+            else {
+                skipCode = 'unresolved_claimed_types';
+                reason = `claimed types ([${sorted.join(', ')}]) have no parameter_type/return_type/generic_arg edges (global/npm types or dropped same-file label collision)`;
+            }
+        }
+        return {
+            match: true,
+            skipped: true,
+            reason,
+            skipCode,
+            claimed: claimedBagsResult,
+            inferred: inferredBagsResult,
+        };
+    }
+    const paramsOk = bagsEqual(claimedBagsResult.parameterTypes, inferredBagsResult.parameterTypes);
+    const anonParamsOk = claimedAnonCount === inferredAnonCount;
+    const returnOk = bagsEqual(claimedBagsResult.returnTypes, inferredBagsResult.returnTypes);
+    const match = paramsOk && anonParamsOk && returnOk;
+    if (paramsOk && anonParamsOk && !returnOk) {
+        // Params verified, but the claimed return types can't be backed. When
+        // every claimed return type is either wrapper-indirected (generic_arg:
+        // Promise<X>, Omit<X,…>) or entirely unresolved (global/npm/DOM types),
+        // that's a coverage gap, not a lie — mark the check skipped instead of
+        // hard-failing, mirroring the pre-signal skip classification. A mixed
+        // bag (some generic, some unresolved) stays a hard mismatch.
+        const claimReturn = claimedBagsResult.returnTypes;
+        if (claimReturn.length > 0) {
+            const genericArgTypes = new Set((inferred.genericArgs ?? []).map((a) => a.type));
+            const gen = claimReturn.filter((t) => genericArgTypes.has(t));
+            const unresolved = claimReturn.filter((t) => !genericArgTypes.has(t));
+            let skipCode;
+            let reason;
+            if (gen.length === claimReturn.length) {
+                skipCode = 'generic_arg_only';
+                reason = `claimed return types ([${claimReturn.join(', ')}]) present only as generic_arg (wrapper-indirected: Promise/Omit/Map/Array) — extractor does not read generic_arg; params verified`;
+            }
+            else if (unresolved.length === claimReturn.length) {
+                skipCode = 'unresolved_claimed_types';
+                reason = `claimed return types ([${claimReturn.join(', ')}]) have no parameter_type/return_type/generic_arg edges (global/npm types or dropped same-file label collision); params verified`;
+            }
+            if (skipCode) {
+                return {
+                    match: true,
+                    skipped: true,
+                    reason,
+                    skipCode,
+                    claimed: claimedBagsResult,
+                    inferred: inferredBagsResult,
+                };
+            }
+        }
+    }
+    return {
+        match,
+        skipped: false,
+        reason: match
+            ? undefined
+            : !paramsOk || !anonParamsOk
+                ? 'parameter_types_mismatch'
+                : 'return_type_mismatch',
+        claimed: claimedBagsResult,
+        inferred: inferredBagsResult,
+    };
+}
+//# sourceMappingURL=signature.js.map

package/dist/graphify/signature.js.map

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

package/dist/graphify/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Graphify graph.json schema types.
+ *
+ * Mirrors the graphify data model (graphify/validate.py, graphify/export.py)
+ * so graphify output can be consumed by this library in a type-compatible way.
+ */
+/** Any JSON-serializable value carried in node/edge metadata. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Node classification (graphify/validate.py VALID_FILE_TYPES). */
+export type GraphifyFileType = 'code' | 'document' | 'paper' | 'image' | 'rationale' | 'concept';
+/** Edge provenance tag (graphify/validate.py VALID_CONFIDENCES). */
+export type GraphifyConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+/** Optional semantic kind carried on nodes (e.g. `module`, `namespace`). */
+export type GraphifyNodeType = 'module' | 'namespace' | string;
+/** Canonical relation verbs emitted by graphify extractors and resolvers. */
+export type GraphifyRelation = 'calls' | 'imports' | 'imports_from' | 're_exports' | 'references' | 'inherits' | 'implements' | 'mixes_in' | 'uses' | 'contains' | 'defines' | 'method' | 'decorator' | 'rationale_for' | 'semantically_similar_to' | string;
+/**
+ * A graphify node.
+ *
+ * Required fields are enforced by graphify/validate.py:
+ * `id`, `label`, `file_type`, `source_file`. The rest are populated by the
+ * extractors (`source_location`, optional `type`/`metadata`) and by the build
+ * writer (`community`, `community_name`, `norm_label`).
+ */
+export interface GraphifyNode {
+    /** Stable identifier: repo-relative path + symbol names (make_id slug). */
+    id: string;
+    /** Human-readable name. */
+    label: string;
+    /** Classification used as the primary node kind. */
+    file_type: GraphifyFileType;
+    /** Repo-relative path of the source file this node came from. */
+    source_file: string;
+    /** `L<line>` location, or `''` for sourceless stub nodes. */
+    source_location?: string | null;
+    /** Optional semantic kind (e.g. `module`, `namespace`). */
+    type?: GraphifyNodeType;
+    /** Node state / extra node definitions. */
+    state?: string;
+    /** Arbitrary per-extractor metadata (e.g. `{ kind: "csharp_namespace" }`). */
+    metadata?: Record<string, JsonValue>;
+    /** Leiden community id, stamped at build time. */
+    community?: number | null;
+    /** Human-readable community label, stamped at build time. */
+    community_name?: string;
+    /** Diacritic-stripped lowercased label, stamped at build time. */
+    norm_label?: string;
+    /** Extra fields tolerated for forward compatibility. */
+    [key: string]: unknown;
+}
+/**
+ * A graphify edge.
+ *
+ * Required fields: `source`, `target`, `relation`, `confidence`, `source_file`.
+ * `context` is populated for `references` edges (e.g. `type`, `return_type`,
+ * `field`, `generic_arg`).
+ */
+export interface GraphifyEdge {
+    /** Source node id. */
+    source: string;
+    /** Target node id. */
+    target: string;
+    /** Canonical relation verb. */
+    relation: GraphifyRelation;
+    /** Provenance: read directly from source vs. resolved by graphify. */
+    confidence: GraphifyConfidence;
+    /** Float 0.0-1.0; 1.0 for EXTRACTED, discrete rubric for INFERRED. */
+    confidence_score?: number;
+    /** Repo-relative path where the relationship was found. */
+    source_file: string;
+    /** `L<line>` location of the relationship. */
+    source_location?: string | null;
+    /** Edge weight. */
+    weight?: number;
+    /** Reference context for `references` edges. */
+    context?: string;
+    /** Arbitrary per-extractor metadata. */
+    metadata?: Record<string, JsonValue>;
+    /** Extra fields tolerated for forward compatibility. */
+    [key: string]: unknown;
+}
+/**
+ * A graphify hyperedge — a group relationship connecting 3+ nodes.
+ *
+ * Member list is canonical on `nodes` (aliases `members`/`node_ids` are folded
+ * by graphify/export.py build normalization).
+ */
+export interface GraphifyHyperedge {
+    /** Stable identifier. */
+    id: string;
+    /** Human-readable label. */
+    label?: string;
+    /** Member node ids (canonical key). */
+    nodes: string[];
+    /** Group relation verb (e.g. `participate_in`, `implement`, `form`). */
+    relation?: GraphifyRelation;
+    /** Provenance tag. */
+    confidence?: GraphifyConfidence;
+    /** Float 0.0-1.0. */
+    confidence_score?: number;
+    /** Repo-relative path where the relationship was found. */
+    source_file?: string;
+    /** Extra fields tolerated for forward compatibility. */
+    [key: string]: unknown;
+}
+/** Graph-level metadata stored on the graph (`graph` key). */
+export interface GraphifyGraphMetadata {
+    directed?: boolean;
+    multigraph?: boolean;
+    /** Edges may be serialized under `links` (NetworkX node-link) or `edges`. */
+    hyperedges?: GraphifyHyperedge[];
+    [key: string]: unknown;
+}
+/**
+ * The full graph.json document.
+ *
+ * graphify writes NetworkX node-link format: nodes under `nodes`, edges under
+ * `links`. Older/legacy payloads may use `edges` instead of `links`.
+ */
+export interface GraphifyGraph {
+    /** Graph nodes. */
+    nodes: GraphifyNode[];
+    /** Graph edges (NetworkX node-link key). */
+    links?: GraphifyEdge[];
+    /** Legacy alias for `links`. */
+    edges?: GraphifyEdge[];
+    /** Group relationships connecting 3+ nodes. */
+    hyperedges?: GraphifyHyperedge[];
+    /** Graph-level metadata (directed, multigraph, hyperedges). */
+    graph?: GraphifyGraphMetadata;
+    /** Top-level directed flag (NetworkX). */
+    directed?: boolean;
+    /** Top-level multigraph flag (NetworkX). */
+    multigraph?: boolean;
+    /** Git HEAD the graph was built against, when available. */
+    built_at_commit?: string;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map