@principal-ai/subsystems-react 0.17.0

package/src/graphify/kind.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from 'bun:test';
+import type { GraphifyEdge, GraphifyNode } from './types';
+import { inferGraphifyKind, kindsMatch } from './kind';
+
+function node(
+	id: string,
+	label: string,
+	sourceFile = 'src/Foo.ts',
+	extra?: Partial<GraphifyNode>,
+): GraphifyNode {
+	return {
+		id,
+		label,
+		file_type: 'code',
+		source_file: sourceFile,
+		source_location: 'L1',
+		...extra,
+	};
+}
+
+function edge(
+	source: string,
+	target: string,
+	relation: string,
+): GraphifyEdge {
+	return {
+		source,
+		target,
+		relation,
+		confidence: 'EXTRACTED',
+		source_file: 'src/Foo.ts',
+	};
+}
+
+describe('inferGraphifyKind', () => {
+	test('outgoing method edges → class', () => {
+		const n = node('cls', 'SessionReader');
+		const edges = [edge('cls', 'cls_get', 'method')];
+		const r = inferGraphifyKind(n, edges);
+		expect(r.kind).toBe('class');
+		expect(r.evidence[0]).toContain('outgoing method');
+	});
+
+	test('call-style label + no methods → function', () => {
+		const n = node('fn', 'SubsystemModelView()');
+		const r = inferGraphifyKind(n, []);
+		expect(r.kind).toBe('function');
+	});
+
+	test('method-style label + incoming method → method', () => {
+		const n = node('m', '.validate()');
+		const edges = [edge('cls', 'm', 'method')];
+		const r = inferGraphifyKind(n, edges);
+		expect(r.kind).toBe('method');
+	});
+
+	test('method takes priority over call-style function', () => {
+		const n = node('m', '.generate()');
+		const edges = [edge('CodeGenerator', 'm', 'method')];
+		expect(inferGraphifyKind(n, edges).kind).toBe('method');
+	});
+
+	test('incoming implements → type', () => {
+		const n = node('iface', 'StoryboardRegistryInterface');
+		const edges = [edge('MockRegistry', 'iface', 'implements')];
+		expect(inferGraphifyKind(n, edges).kind).toBe('type');
+	});
+
+	test('filename label → module', () => {
+		const n = node(
+			'mod',
+			'SubsystemModelView.tsx',
+			'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx',
+		);
+		expect(inferGraphifyKind(n, []).kind).toBe('module');
+	});
+
+	test('bare symbol with no edges → unknown', () => {
+		const n = node('x', 'INSPECTOR_KEYS');
+		expect(inferGraphifyKind(n, []).kind).toBe('unknown');
+	});
+
+	test('class wins over implements on same node', () => {
+		const n = node('cls', 'TypeScriptGenerator');
+		const edges = [
+			edge('cls', 'cls_gen', 'method'),
+			edge('Other', 'cls', 'implements'),
+		];
+		expect(inferGraphifyKind(n, edges).kind).toBe('class');
+	});
+});
+
+describe('kindsMatch', () => {
+	test('exact string equality', () => {
+		expect(kindsMatch('function', 'function')).toBe(true);
+		expect(kindsMatch('class', 'function')).toBe(false);
+	});
+
+	test('external / missing claimed skips', () => {
+		expect(kindsMatch('external', 'function')).toBe(true);
+		expect(kindsMatch(undefined, 'unknown')).toBe(true);
+	});
+
+	test('no class≈function alias', () => {
+		expect(kindsMatch('class', 'function')).toBe(false);
+		expect(kindsMatch('function', 'class')).toBe(false);
+	});
+});

package/src/graphify/kind.ts

@@ -0,0 +1,120 @@
+/**
+ * Infer a subsystem-style kind from a graphify node + edges.
+ *
+ * Graphify does not store `kind` on nodes (everything is `file_type: "code"`).
+ * Class vs function vs type is derived from structure — same rules as
+ * `GraphifyComponentDetail` in consolidated.ts.
+ */
+
+import type { GraphifyEdge, GraphifyNode } from './types';
+
+/** Kind inferred from graph structure (never read off the node). */
+export type InferredGraphifyKind =
+	| 'class'
+	| 'function'
+	| 'method'
+	| 'type'
+	| 'module'
+	| 'unknown';
+
+export interface InferGraphifyKindResult {
+	kind: InferredGraphifyKind;
+	evidence: string[];
+}
+
+const FILE_LABEL_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 isMethodStyleLabel(label: string): boolean {
+	return label.trim().startsWith('.');
+}
+
+function isCallStyleLabel(label: string): boolean {
+	return label.trim().endsWith('()');
+}
+
+function isFilenameLabel(label: string, sourceFile: string): boolean {
+	const trimmed = label.trim();
+	if (FILE_LABEL_RE.test(trimmed)) return true;
+	if (!sourceFile) return false;
+	const base = sourceFile.replace(/\\/g, '/').split('/').pop() ?? '';
+	return !!base && trimmed === base;
+}
+
+/**
+ * Infer kind for a definition node from its label and incident edges.
+ *
+ * Priority: class → method → function → type → module → unknown.
+ */
+export function inferGraphifyKind(
+	node: GraphifyNode,
+	edges: readonly GraphifyEdge[],
+): InferGraphifyKindResult {
+	const id = String(node.id);
+	const label = String(node.label ?? '').trim();
+	const sourceFile =
+		typeof node.source_file === 'string' ? node.source_file : '';
+	const evidence: string[] = [];
+
+	const outgoingMethod = edges.filter(
+		(e) => String(e.source) === id && e.relation === 'method',
+	);
+	if (outgoingMethod.length > 0) {
+		evidence.push(`${outgoingMethod.length} outgoing method edge(s)`);
+		return { kind: 'class', evidence };
+	}
+
+	const incomingMethod = edges.filter(
+		(e) => String(e.target) === id && e.relation === 'method',
+	);
+	if (incomingMethod.length > 0 && isMethodStyleLabel(label)) {
+		evidence.push(
+			`incoming method edge from ${String(incomingMethod[0]!.source)}`,
+			`label ${label}`,
+		);
+		return { kind: 'method', evidence };
+	}
+
+	if (isCallStyleLabel(label)) {
+		evidence.push(`call-style label ${label}`);
+		return { kind: 'function', evidence };
+	}
+
+	const incomingImplements = edges.filter(
+		(e) => String(e.target) === id && e.relation === 'implements',
+	);
+	if (incomingImplements.length > 0) {
+		evidence.push(
+			`${incomingImplements.length} incoming implements edge(s)`,
+		);
+		return { kind: 'type', evidence };
+	}
+
+	if (node.type === 'module' || isFilenameLabel(label, sourceFile)) {
+		evidence.push(
+			node.type === 'module'
+				? 'node.type=module'
+				: `filename label ${label}`,
+		);
+		return { kind: 'module', evidence };
+	}
+
+	if (label) evidence.push(`unclassified label ${label}`);
+	else evidence.push('no classifying signals');
+	return { kind: 'unknown', evidence };
+}
+
+/** Type-family constructs all infer as the coarse 'type' — graph structure
+ *  (implements/references edges) cannot sub-classify interface vs alias vs
+ *  enum vs variable; only the source declaration can. */
+const TYPE_FAMILY: ReadonlySet<string> = new Set(['interface', 'type_alias', 'enum']);
+
+/** Strict claimed-vs-inferred check, with type-family compatibility. */
+export function kindsMatch(
+	claimed: string | undefined,
+	inferred: InferredGraphifyKind,
+): boolean {
+	if (!claimed || claimed === 'external') return true;
+	if (TYPE_FAMILY.has(claimed)) return inferred === 'type';
+	return claimed === inferred;
+}

package/src/graphify/resolve.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from 'bun:test';
+import type { GraphifyNode } from './types';
+import {
+  createGraphifyTypeResolver,
+  normalizeGraphifyLabel,
+  resolveGraphifyTypeRef,
+} from './resolve';
+
+function node(id: string, label: string, sourceFile: string, location?: string): GraphifyNode {
+  return { id, label, file_type: 'code', source_file: sourceFile, source_location: location ?? '' };
+}
+
+const corpus: GraphifyNode[] = [
+  // Real definition of SessionReader in another file.
+  node('src/session_reader.ts#sessionreader', 'SessionReader', 'src/session_reader.ts', 'L12'),
+  // Same-name class in a second package → ambiguous stub target.
+  node('other/pkg/reader.ts#sessionreader', 'SessionReader', 'other/pkg/reader.ts', 'L3'),
+  // Sourceless stub left behind by an ambiguous reference.
+  node('stub-sessionreader', 'SessionReader', ''),
+  // A file node — never a resolution candidate.
+  node('src/session_reader_ts', 'session_reader.ts', 'src/session_reader.ts'),
+];
+
+describe('normalizeGraphifyLabel', () => {
+  test('mirrors graphify normalise_callable_label', () => {
+    expect(normalizeGraphifyLabel(' SessionReader() ')).toBe('sessionreader');
+    expect(normalizeGraphifyLabel('.method()')).toBe('method');
+    expect(normalizeGraphifyLabel('SessionReader')).toBe('sessionreader');
+  });
+});
+
+describe('createGraphifyTypeResolver', () => {
+  test('resolved when the target is a real definition', () => {
+    const resolver = createGraphifyTypeResolver(corpus);
+    const r = resolver.resolve('src/session_reader.ts#sessionreader');
+    expect(r.status).toBe('resolved');
+    expect(r.node?.source_file).toBe('src/session_reader.ts');
+    expect(r.node?.source_location).toBe('L12');
+    expect(r.candidates).toHaveLength(0);
+  });
+
+  test('unique same-label definition folds onto the stub (rewire parity)', () => {
+    const single = [node('a.ts#parser', 'Parser', 'a.ts', 'L1'), node('stub-parser', 'Parser', '')];
+    const r = createGraphifyTypeResolver(single).resolve('stub-parser');
+    expect(r.status).toBe('resolved');
+    expect(r.node?.id).toBe('a.ts#parser');
+  });
+
+  test('ambiguous when multiple definitions share the label', () => {
+    const r = createGraphifyTypeResolver(corpus).resolve('stub-sessionreader', 'SessionReader');
+    expect(r.status).toBe('ambiguous');
+    expect(r.candidates).toHaveLength(2);
+    // The stub itself is returned as the node.
+    expect(r.node?.id).toBe('stub-sessionreader');
+  });
+
+  test('unresolved when nothing defines the name (primitives / externals)', () => {
+    const withStub = [...corpus, node('stub-string', 'string', '')];
+    const r = createGraphifyTypeResolver(withStub).resolve('stub-string', 'string');
+    expect(r.status).toBe('unresolved');
+    expect(r.candidates).toHaveLength(0);
+  });
+
+  test('missing for absent ids and missing nodeIds', () => {
+    const resolver = createGraphifyTypeResolver(corpus);
+    expect(resolver.resolve(undefined).status).toBe('missing');
+    expect(resolver.resolve('nope').status).toBe('missing');
+  });
+
+  test('file nodes are not candidates; folded tier matches case-insensitively', () => {
+    const corpus2 = [
+      node('f_ts', 'reader.ts', 'x/reader.ts'),
+      node('x/reader_ts', 'Reader', 'x/Reader.ts'),
+      node('stub-reader', 'Reader', ''),
+    ];
+    const r = createGraphifyTypeResolver(corpus2).resolve('stub-reader');
+    expect(r.status).toBe('resolved');
+    expect(r.node?.id).toBe('x/reader_ts');
+  });
+});
+
+describe('resolveGraphifyTypeRef', () => {
+  test('one-shot wrapper reads nodeId off the ref', () => {
+    const resolved = resolveGraphifyTypeRef(corpus, { nodeId: 'src/session_reader.ts#sessionreader' });
+    expect(resolved.status).toBe('resolved');
+    const missing = resolveGraphifyTypeRef(corpus, undefined);
+    expect(missing.status).toBe('missing');
+  });
+});

package/src/graphify/resolve.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 function normalizeGraphifyLabel(label: string): string {
+  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: GraphifyNode): boolean {
+  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);
+}
+
+/** Prebuilt lookup state — build once per graph, resolve many refs. */
+export interface GraphifyTypeResolver {
+  resolve(nodeId: string | undefined, fallbackLabel?: string): GraphifyTypeRefResolution;
+}
+
+export function createGraphifyTypeResolver(nodes: readonly GraphifyNode[]): GraphifyTypeResolver {
+  const byId = new Map<string, GraphifyNode>();
+  const defsByExactLabel = new Map<string, GraphifyNode[]>();
+  const defsByFoldedLabel = new Map<string, GraphifyNode[]>();
+
+  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: string | undefined, fallbackLabel?: string): GraphifyTypeRefResolution {
+    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: readonly GraphifyNode[],
+  ref: Pick<GraphifyReferenceInfo, 'nodeId'> | { nodeId?: string } | undefined,
+  fallbackLabel?: string,
+): GraphifyTypeRefResolution {
+  return createGraphifyTypeResolver(nodes).resolve(ref?.nodeId, fallbackLabel);
+}