@principal-ai/principal-view-react 0.16.49 → 0.16.50

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/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

@@ -43,3 +43,29 @@ export {
   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';

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', 'SubsystemGraphView()');
+		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',
+			'SubsystemGraphView.tsx',
+			'packages/trail-viewer/src/mainview/views/SubsystemGraphView.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,114 @@
+/**
+ * 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 };
+}
+
+/** Strict claimed-vs-inferred check (no class≈function alias). */
+export function kindsMatch(
+	claimed: string | undefined,
+	inferred: InferredGraphifyKind,
+): boolean {
+	if (!claimed || claimed === 'external') return true;
+	return claimed === inferred;
+}