@principal-ai/subsystems-react 0.17.0

package/src/graphify/anchor.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from 'bun:test';
+import type { GraphifyNode } from './types';
+import {
+	graphifyFileStem,
+	makeGraphifyId,
+	normalizeGraphifyId,
+} from './ids';
+import { resolveComponentAnchor, symbolLabelVariants } from './anchor';
+
+function node(
+	id: string,
+	label: string,
+	sourceFile: string,
+	location?: string,
+): GraphifyNode {
+	return {
+		id,
+		label,
+		file_type: 'code',
+		source_file: sourceFile,
+		source_location: location ?? '',
+	};
+}
+
+describe('makeGraphifyId', () => {
+	test('matches graphify path+symbol slug shape', () => {
+		const stem = graphifyFileStem(
+			'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx',
+		);
+		expect(stem).toBe(
+			'packages/subsystems-studio/src/mainview/views/SubsystemModelView',
+		);
+		expect(makeGraphifyId(stem, 'SubsystemModelView')).toBe(
+			'packages_trail_viewer_src_mainview_views_subsystemmodelview_subsystemmodelview',
+		);
+	});
+
+	test('normalize is idempotent on ascii', () => {
+		const id = makeGraphifyId('Foo/Bar', 'Baz');
+		expect(normalizeGraphifyId(id)).toBe(id);
+	});
+});
+
+describe('symbolLabelVariants', () => {
+	test('includes call-style labels', () => {
+		expect(symbolLabelVariants('SubsystemModelView')).toContain(
+			'SubsystemModelView()',
+		);
+		expect(symbolLabelVariants('SessionReader.normalize')).toContain('normalize()');
+		expect(symbolLabelVariants('SessionReader.normalize')).toContain('.normalize()');
+	});
+});
+
+describe('resolveComponentAnchor', () => {
+	const file =
+		'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx';
+	const defId = makeGraphifyId(graphifyFileStem(file), 'SubsystemModelView');
+	const corpus: GraphifyNode[] = [
+		node(defId, 'SubsystemModelView()', file, 'L27'),
+		node(
+			makeGraphifyId(graphifyFileStem(file)),
+			'SubsystemModelView.tsx',
+			file,
+			'L1',
+		),
+		node(
+			makeGraphifyId(
+				graphifyFileStem('other/SessionReader.ts'),
+				'SessionReader',
+			),
+			'SessionReader',
+			'other/SessionReader.ts',
+			'L1',
+		),
+	];
+
+	test('exact via make_id reconstruction', () => {
+		const r = resolveComponentAnchor(corpus, {
+			file,
+			symbol: 'SubsystemModelView',
+		});
+		expect(r.resolution).toBe('exact');
+		expect(r.node?.id).toBe(defId);
+		expect(r.node?.source_location).toBe('L27');
+	});
+
+	test('exact via label when id reconstruction misses', () => {
+		const weirdId = 'weird_id_not_from_make_id';
+		const local = [
+			node(weirdId, 'subsystemGraphToExcalidrawScene()', 'packages/x.ts', 'L10'),
+		];
+		const r = resolveComponentAnchor(local, {
+			file: 'packages/x.ts',
+			symbol: 'subsystemGraphToExcalidrawScene',
+		});
+		expect(r.resolution).toBe('exact');
+		expect(r.node?.id).toBe(weirdId);
+	});
+
+	test('file-only when file has nodes but symbol misses', () => {
+		const r = resolveComponentAnchor(corpus, {
+			file,
+			symbol: 'DoesNotExist',
+		});
+		expect(r.resolution).toBe('file-only');
+		expect(r.candidates.length).toBeGreaterThan(0);
+	});
+
+	test('missing when file absent from graph', () => {
+		const r = resolveComponentAnchor(corpus, {
+			file: 'no/such/file.ts',
+			symbol: 'Foo',
+		});
+		expect(r.resolution).toBe('missing');
+	});
+
+	test('does not bind via corpus-wide same name in another file', () => {
+		const r = resolveComponentAnchor(corpus, {
+			file: 'packages/elsewhere/SessionReader.ts',
+			symbol: 'SessionReader',
+		});
+		expect(r.resolution).toBe('missing');
+	});
+});

package/src/graphify/anchor.ts

@@ -0,0 +1,160 @@
+/**
+ * Resolve a subsystem component (file + symbol) to a graphify definition node.
+ *
+ * This is component *anchoring*, not type-ref stub rewiring (`resolve.ts`).
+ * Conservative: never bind via corpus-wide same-name alone.
+ */
+
+import type { GraphifyNode } from './types';
+import type { GraphifyAnchorResolution } from './consolidated';
+import { normalizeGraphifyLabel } from './resolve';
+import {
+	graphifyFileStem,
+	makeGraphifyId,
+	normalizeSourcePath,
+} from './ids';
+
+export interface ComponentAnchorInput {
+	file?: string;
+	symbol?: string;
+	kind?: string;
+	purl?: string;
+}
+
+export interface ComponentAnchorResult {
+	resolution: GraphifyAnchorResolution;
+	node: GraphifyNode | null;
+	candidates: GraphifyNode[];
+	/** make_id strings attempted on the fast path. */
+	triedIds: string[];
+}
+
+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);
+}
+
+/** Label forms that might match a subsystem symbol on a graphify node. */
+export function symbolLabelVariants(symbol: string): string[] {
+	const raw = symbol.trim();
+	if (!raw) return [];
+	const last = raw.includes('.') ? (raw.split('.').pop() ?? raw) : raw;
+	const variants = new Set<string>([
+		raw,
+		last,
+		`${raw}()`,
+		`${last}()`,
+		`.${last}()`,
+		`.${last}`,
+	]);
+	return [...variants];
+}
+
+function labelMatchesSymbol(label: string, symbol: string): boolean {
+	const variants = symbolLabelVariants(symbol);
+	const trimmed = label.trim();
+	if (variants.includes(trimmed)) return true;
+	const foldedLabel = normalizeGraphifyLabel(trimmed);
+	return variants.some((v) => normalizeGraphifyLabel(v) === foldedLabel);
+}
+
+function candidateIdsFor(file: string, symbol: string): string[] {
+	const stem = graphifyFileStem(file);
+	if (!stem) return [];
+	const parts = symbol.split('.').map((p) => p.trim()).filter(Boolean);
+	const ids = new Set<string>();
+	ids.add(makeGraphifyId(stem, symbol));
+	if (parts.length > 0) ids.add(makeGraphifyId(stem, ...parts));
+	if (parts.length === 2) {
+		// Class method: make_id(class_id, method) ≈ make_id(stem, Class, method)
+		ids.add(makeGraphifyId(stem, parts[0]!, parts[1]!));
+	}
+	return [...ids];
+}
+
+/**
+ * Anchor a subsystem component onto a graphify definition node.
+ */
+export function resolveComponentAnchor(
+	nodes: readonly GraphifyNode[],
+	input: ComponentAnchorInput,
+): ComponentAnchorResult {
+	const file = input.file?.trim() ? normalizeSourcePath(input.file) : '';
+	const symbol = input.symbol?.trim() ?? '';
+	if (!file || !symbol) {
+		return { resolution: 'missing', node: null, candidates: [], triedIds: [] };
+	}
+
+	const byId = new Map<string, GraphifyNode>();
+	const inFile: GraphifyNode[] = [];
+	for (const node of nodes) {
+		byId.set(String(node.id), node);
+		if (!isDefinition(node)) continue;
+		const sf = normalizeSourcePath(String(node.source_file ?? ''));
+		if (sf === file) inFile.push(node);
+	}
+
+	const triedIds = candidateIdsFor(file, symbol);
+	const idHits: GraphifyNode[] = [];
+	for (const id of triedIds) {
+		const hit = byId.get(id);
+		if (!hit || !isDefinition(hit)) continue;
+		const sf = normalizeSourcePath(String(hit.source_file ?? ''));
+		if (sf === file) idHits.push(hit);
+	}
+	const uniqueIdHits = [...new Map(idHits.map((n) => [String(n.id), n])).values()];
+	if (uniqueIdHits.length === 1) {
+		return {
+			resolution: 'exact',
+			node: uniqueIdHits[0]!,
+			candidates: [],
+			triedIds,
+		};
+	}
+	if (uniqueIdHits.length > 1) {
+		return {
+			resolution: 'ambiguous',
+			node: null,
+			candidates: uniqueIdHits,
+			triedIds,
+		};
+	}
+
+	if (inFile.length === 0) {
+		return { resolution: 'missing', node: null, candidates: [], triedIds };
+	}
+
+	const labelHits = inFile.filter((n) =>
+		labelMatchesSymbol(String(n.label ?? ''), symbol),
+	);
+	if (labelHits.length === 1) {
+		return {
+			resolution: 'exact',
+			node: labelHits[0]!,
+			candidates: [],
+			triedIds,
+		};
+	}
+	if (labelHits.length > 1) {
+		return {
+			resolution: 'ambiguous',
+			node: null,
+			candidates: labelHits,
+			triedIds,
+		};
+	}
+
+	// File has code nodes but none matched the symbol.
+	return {
+		resolution: 'file-only',
+		node: null,
+		candidates: inFile.slice(0, 8),
+		triedIds,
+	};
+}

package/src/graphify/consolidated.ts

@@ -0,0 +1,246 @@
+/**
+ * Graphify consolidated / drill-down types.
+ *
+ * graphify stores the graph in flat, normalized form — class vs function vs
+ * type is NOT a node attribute (every code node is `file_type: "code"`); it is
+ * derived from graph structure. These types rebuild that structure from the raw
+ * edges so a UI can show a drill-down modal for a subsystem component or jump
+ * to its definition file.
+ */
+
+import type {
+  GraphifyConfidence,
+  GraphifyFileType,
+  GraphifyRelation,
+} from './types';
+
+/** How a subsystem component resolved to a graphify node. */
+export type GraphifyAnchorResolution = 'exact' | 'file-only' | 'ambiguous' | 'missing';
+
+/**
+ * The bridge between a facet component and the graphify graph.
+ *
+ * `nodeId` is reconstructed from the component's `file` + `symbol` via the id
+ * slug scheme; `resolution` says how confident that reconstruction is.
+ * `source_file` + `source_location` are the "open the definition" primitive.
+ */
+export interface SubsystemGraphifyAnchor {
+  /** Resolved graphify node id. */
+  nodeId: string;
+  /** PURL of the repo the node lives in (pkg:github/owner/repo). */
+  purl: string;
+  /** How the anchor resolved — the honesty signal for verification. */
+  resolution: GraphifyAnchorResolution;
+  /** Human-readable node label from the graph. */
+  label: string;
+  /** Repo-relative path of the node's source file. */
+  source_file: string;
+  /** `L<line>` — the line of the definition for a file-open jump. */
+  source_location?: string;
+  /** Node classification from the graph. */
+  file_type: GraphifyFileType;
+  /** Leiden community id. */
+  community?: number | null;
+  /** Human-readable community label. */
+  community_name?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Leaf info types — each backed by a specific graphify edge pattern
+// ---------------------------------------------------------------------------
+
+/** A method on a class-like node (`method` edge from the class). */
+export interface GraphifyMethodInfo {
+  /** The method's own node id. */
+  nodeId: string;
+  /** Display name from the label (`.get()` → `get`). */
+  name: string;
+  /** Typed parameters from `references` edges with context `parameter_type`. */
+  parameters?: GraphifyParamInfo[];
+  /** Return type from a `references` edge with context `return_type`. */
+  returnType?: string;
+  /** Backing edge target for `returnType`, when the graph had one. */
+  returnTypeRef?: GraphifyReferenceInfo;
+}
+
+/** A property/field on a class- or type-like node. */
+export interface GraphifyPropertyInfo {
+  /** Field name — present when graphify emits a `defines` node (C++). */
+  name: string;
+  /** Field type from a `references` edge with context `field`. */
+  type?: string;
+  /** Backing edge target for `type`, when the graph had one. */
+  typeRef?: GraphifyReferenceInfo;
+  /** The field's own node id when it exists (e.g. C++ `defines` nodes). */
+  nodeId?: string;
+}
+
+/**
+ * A single typed parameter of a function (`references` context `parameter_type`).
+ *
+ * `ref.nodeId` is the resolvable half: it targets the type's definition node
+ * when graphify resolved the reference, or a sourceless stub node when the
+ * name was ambiguous / external (see `resolveGraphifyTypeRef`).
+ */
+export interface GraphifyParamInfo {
+  /** Parameter name — not captured by graphify; left undefined. */
+  name?: string;
+  /** Parameter type. */
+  type: string;
+  /** Backing `references[parameter_type|generic_arg]` edge target. */
+  ref?: GraphifyReferenceInfo;
+}
+
+/** One call relationship, in either direction. */
+export interface GraphifyCallInfo {
+  /** The other endpoint's node id (caller for `callers`, callee for `callees`). */
+  nodeId: string;
+  /** The other endpoint's display label. */
+  name: string;
+  /** `L<line>` of the call site. */
+  source_location?: string;
+}
+
+/** A type-name reference to a node (`references` edge with a context). */
+export interface GraphifyReferenceInfo {
+  /** The referenced node id. */
+  nodeId: string;
+  /** The referenced node's display label. */
+  name: string;
+  /** Reference context (e.g. `type`, `field`, `generic_arg`, `attribute`). */
+  context?: string;
+  /** `L<line>` of the reference site. */
+  source_location?: string;
+}
+
+/** An import relationship (`imports` / `imports_from` / `re_exports`). */
+export interface GraphifyImportInfo {
+  /** The imported module/file node id. */
+  nodeId: string;
+  /** The imported module/file label. */
+  name: string;
+  /** Which relation carried the import. */
+  relation?: GraphifyRelation;
+  /** `L<line>` of the import statement. */
+  source_location?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Discriminated union — the drill-down payload
+// ---------------------------------------------------------------------------
+
+/** A class-like node: owns outgoing `method` edges. */
+export interface GraphifyClassDetail {
+  kind: 'class';
+  /** Methods connected via `method` edges. */
+  methods: GraphifyMethodInfo[];
+  /** Fields from `defines`/`references` context `field`. */
+  properties: GraphifyPropertyInfo[];
+  /** `inherits` edge targets. */
+  extends: string[];
+  /** `implements` edge targets. */
+  implements: string[];
+  /** Incoming `calls` — graphify models constructor calls as calls into the class. */
+  instantiations: GraphifyCallInfo[];
+  /** Everywhere the type name is referenced (`references` edges). */
+  references: GraphifyReferenceInfo[];
+}
+
+/** A function-like node: label ends `name()` with no `method` edges. */
+export interface GraphifyFunctionDetail {
+  kind: 'function';
+  /** Parameter types from `references` context `parameter_type`. */
+  parameters: GraphifyParamInfo[];
+  /** Return type from `references` context `return_type`. */
+  returnType?: string;
+  /** Backing edge target for `returnType`, when the graph had one. */
+  returnTypeRef?: GraphifyReferenceInfo;
+  /** Incoming `calls` edges. */
+  callers: GraphifyCallInfo[];
+  /** Outgoing `calls` edges. */
+  callees: GraphifyCallInfo[];
+}
+
+/** A type-like node (interface/struct): revealed by incoming `implements` edges. */
+export interface GraphifyTypeDetail {
+  kind: 'type';
+  /** Struct/interface fields. */
+  properties: GraphifyPropertyInfo[];
+  /** Nodes referencing this type name. */
+  usedBy: GraphifyReferenceInfo[];
+  /** Nodes that `inherits`/`implements` this type. */
+  implementors: string[];
+}
+
+/** A module/file-like node: a `contains` target with a filename label. */
+export interface GraphifyModuleDetail {
+  kind: 'module';
+  /** `re_exports` targets / contained public symbols. */
+  exports: string[];
+  /** `imports` / `imports_from` relationships. */
+  imports: GraphifyImportInfo[];
+  /** Symbols contained in the module (`contains` targets). */
+  symbols: string[];
+}
+
+/** A facet-only component with no graphify node (external consumer stub). */
+export interface GraphifyExternalDetail {
+  kind: 'external';
+  /** Facet-only label; there is no backing graph data. */
+  label: string;
+}
+
+/**
+ * A retained-state node (`kind: 'store'`): state and its contract, no
+ * behavior. `kind` is the node's verifiable anchor — a store anchors to a
+ * *state location* (module consts, a file or db), not to a declaration.
+ * When a class manages the store's access, that is a SEPARATE node
+ * (`kind: 'class'`, methods = the access mechanism) joined by
+ * `writes`/`reads` — never merged into one hybrid node. This payload
+ * renders as state declarations (`declare const …`), never as a class
+ * stub.
+ */
+export interface GraphifyStoreDetail {
+  kind: 'store';
+  /** The retained state members (module-level consts or class fields). */
+  properties: GraphifyPropertyInfo[];
+}
+
+/** A standalone method selected from its owning class. */
+export interface GraphifyMethodDetail {
+  kind: 'method';
+  /** The class that owns this method. */
+  hostClass: string;
+  /** Parameter types from `references` context `parameter_type`. */
+  parameters?: GraphifyParamInfo[];
+  /** Return type from `references` context `return_type`. */
+  returnType?: string;
+}
+
+/**
+ * The drill-down payload for a subsystem component.
+ *
+ * The discriminant is derived from graph structure, not read off the node:
+ * method edges → class; `()` label + no method edges → function; incoming
+ * `implements` → type; else module. `external` covers consumer stubs.
+ * `method` covers standalone method components selected from a class.
+ */
+export type GraphifyComponentDetail =
+  | GraphifyClassDetail
+  | GraphifyFunctionDetail
+  | GraphifyMethodDetail
+  | GraphifyTypeDetail
+  | GraphifyModuleDetail
+  | GraphifyExternalDetail
+  | GraphifyStoreDetail;
+
+/** A raw graphify edge backing a facet claim (verification + provenance). */
+export interface GraphifyEdgeRef {
+  source: string;
+  target: string;
+  relation: GraphifyRelation;
+  confidence: GraphifyConfidence;
+  confidence_score?: number;
+  source_file: string;
+  source_location?: string;
+}

package/src/graphify/ids.ts

@@ -0,0 +1,48 @@
+/**
+ * Mirror of graphify/ids.py — NFKC + casefold-ish + non-word → `_`.
+ *
+ * Definition node ids are `makeId(fileStem, ...symbolParts)`. Stub ids are
+ * intentionally different (name-only / `ref_…`); this module is for the
+ * definition path used by component anchoring.
+ */
+
+/** Normalize one id string to graphify's canonical form. */
+export function normalizeGraphifyId(s: string): string {
+	let out = s.normalize("NFKC");
+	// JS has no Unicode casefold; lowercasing + second NFKC is close enough
+	// for the Latin/ASCII identifiers we resolve in practice.
+	out = out.toLowerCase().normalize("NFKC");
+	out = out.replace(/[^\w]+/gu, "_");
+	out = out.replace(/_+/g, "_");
+	return out.replace(/^_|_$/g, "");
+}
+
+/** Build a canonical node id from path/symbol parts (graphify `make_id`). */
+export function makeGraphifyId(...parts: string[]): string {
+	const joined = parts
+		.filter((p) => typeof p === "string" && p.length > 0)
+		.map((p) => p.replace(/^[_.]+|[_.]+$/g, ""))
+		.filter(Boolean)
+		.join("_");
+	return normalizeGraphifyId(joined);
+}
+
+/**
+ * File stem used as the node-id prefix (graphify `_file_stem`):
+ * full path with extension dropped, posix separators.
+ */
+export function graphifyFileStem(file: string): string {
+	const posix = file.replace(/\\/g, "/").replace(/^\.\//, "");
+	const lastSlash = posix.lastIndexOf("/");
+	const base = lastSlash >= 0 ? posix.slice(lastSlash + 1) : posix;
+	const dir = lastSlash >= 0 ? posix.slice(0, lastSlash + 1) : "";
+	if (!base || base === ".") return "";
+	const dot = base.lastIndexOf(".");
+	const stemBase = dot > 0 ? base.slice(0, dot) : base;
+	return `${dir}${stemBase}`;
+}
+
+/** Normalize a repo-relative path for source_file comparison. */
+export function normalizeSourcePath(file: string): string {
+	return file.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/");
+}

package/src/graphify/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Graphify integration types.
+ *
+ * Type-compatible view of graphify's graph.json data model for consuming
+ * graphify output (nodes, links, hyperedges) inside this library.
+ */
+
+export type {
+  JsonValue,
+  GraphifyFileType,
+  GraphifyConfidence,
+  GraphifyNodeType,
+  GraphifyRelation,
+  GraphifyNode,
+  GraphifyEdge,
+  GraphifyHyperedge,
+  GraphifyGraphMetadata,
+  GraphifyGraph,
+} from './types';
+export type {
+  GraphifyAnchorResolution,
+  SubsystemGraphifyAnchor,
+  GraphifyMethodInfo,
+  GraphifyPropertyInfo,
+  GraphifyParamInfo,
+  GraphifyCallInfo,
+  GraphifyReferenceInfo,
+  GraphifyImportInfo,
+  GraphifyClassDetail,
+  GraphifyFunctionDetail,
+  GraphifyTypeDetail,
+  GraphifyModuleDetail,
+  GraphifyExternalDetail,
+  GraphifyStoreDetail,
+  GraphifyComponentDetail,
+  GraphifyEdgeRef,
+} from './consolidated';
+export type {
+  GraphifyTypeRefStatus,
+  GraphifyTypeRefResolution,
+} from './resolve';
+export {
+  normalizeGraphifyLabel,
+  createGraphifyTypeResolver,
+  resolveGraphifyTypeRef,
+} from './resolve';
+export {
+  normalizeGraphifyId,
+  makeGraphifyId,
+  graphifyFileStem,
+  normalizeSourcePath,
+} from './ids';
+export type {
+  ComponentAnchorInput,
+  ComponentAnchorResult,
+} from './anchor';
+export {
+  resolveComponentAnchor,
+  symbolLabelVariants,
+} from './anchor';
+export type { InferredGraphifyKind, InferGraphifyKindResult } from './kind';
+export { inferGraphifyKind, kindsMatch } from './kind';
+export type {
+  GraphifyInferredSignature,
+  ClaimedSignature,
+  SignatureCompareResult,
+} from './signature';
+export {
+  extractNamedTypes,
+  extractGraphifySignature,
+  compareSignatures,
+} from './signature';