@shapeshift-labs/frontier-lang-compiler 0.2.149 → 0.2.151

package/dist/internal/index-impl/typeScriptCompilerFacts.js

@@ -0,0 +1,294 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { idFragment } from '../../native-import-utils.js';
+
+const TypeScriptRefactorEvidenceKey = 'typescript-language-service-refactor-evidence';
+const TypeScriptRefactorEvidenceMissingCode = 'project-typescript-refactor-evidence-missing';
+
+function withTypeScriptRefactorEvidence(input = {}, classifications = [], files = []) {
+  if (!requiresTypeScriptRefactorEvidence(input)) return classifications;
+  return classifications.map((classification) => {
+    const evidence = typeScriptRefactorEvidenceForClassification(input, classification, files);
+    if (!evidence) return classification;
+    const requiredEvidence = uniqueStrings([
+      ...(classification.details?.requiredEvidence ?? []),
+      TypeScriptRefactorEvidenceKey
+    ]);
+    const details = compactRecord({
+      ...(classification.details ?? {}),
+      requiredEvidence,
+      typeScriptRefactorEvidence: evidence
+    });
+    if (evidence.status !== 'failed') return { ...classification, details };
+    return {
+      ...classification,
+      code: TypeScriptRefactorEvidenceMissingCode,
+      operation: `blocked-${classification.branch}-typescript-refactor-evidence`,
+      details: compactRecord({
+        ...details,
+        reasonCode: TypeScriptRefactorEvidenceMissingCode,
+        originalReasonCode: classification.code,
+        originalConflictKey: classification.details?.conflictKey,
+        conflictKey: `project-typescript-refactor-evidence#${classification.details?.conflictKey ?? classification.code}`
+      })
+    };
+  });
+}
+
+function hasFailedTypeScriptRefactorEvidence(classifications = []) {
+  return classifications.some((classification) => classification.details?.typeScriptRefactorEvidence?.status === 'failed');
+}
+
+function typeScriptRefactorEvidenceRecordsFromClassifications(classifications = []) {
+  const records = classifications
+    .map((classification) => classification.details?.typeScriptRefactorEvidence)
+    .filter((record) => record?.id);
+  const seen = new Set();
+  return records.filter((record) => {
+    if (seen.has(record.id)) return false;
+    seen.add(record.id);
+    return true;
+  });
+}
+
+function typeScriptRefactorEvidenceForClassification(input, classification, files) {
+  const requirements = typeScriptRefactorEvidenceRequirements(classification);
+  if (!requirements.length) return undefined;
+  const observations = requirements.map((requirement) => observeTypeScriptRefactorEvidenceRequirement(input, files, requirement));
+  const missing = observations.filter((observation) => observation.status !== 'passed');
+  const id = `evidence_${idFragment(hashSemanticValue([
+    classification.details?.conflictKey ?? classification.code,
+    TypeScriptRefactorEvidenceKey
+  ]))}_typescript_refactor`;
+  return {
+    id,
+    kind: 'typescript-language-service-refactor-evidence-oracle',
+    status: missing.length ? 'failed' : 'passed',
+    scope: 'project-refactor',
+    branch: classification.branch,
+    sourcePaths: classification.sourcePaths ?? [],
+    summary: missing.length
+      ? `Missing TypeScript refactor evidence for ${missing.length} project rename/move requirement(s).`
+      : `TypeScript refactor evidence covered ${observations.length} project rename/move requirement(s).`,
+    metadata: compactRecord({
+      code: missing.length ? TypeScriptRefactorEvidenceMissingCode : undefined,
+      refactorKind: classification.kind,
+      branch: classification.branch,
+      requiredEvidence: TypeScriptRefactorEvidenceKey,
+      requirements: observations,
+      missing,
+      missingRequirements: missing.length,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    })
+  };
+}
+
+function typeScriptRefactorEvidenceRequirements(classification) {
+  const branch = classification?.branch;
+  const details = classification?.details ?? {};
+  if (!branch) return [];
+  if (classification.kind === 'cross-file-symbol-rename') {
+    return uniqueRequirements([
+      requirement('base', details.exportSourcePath, 'declaration', 'base-export-declaration', details.fromName),
+      requirement('base', details.importSourcePath, 'reference', 'base-import-reference', details.fromName),
+      requirement(branch, details.exportSourcePath, 'declaration', 'branch-export-declaration', details.toName),
+      requirement(branch, details.importSourcePath, 'reference', 'branch-import-reference', details.toName)
+    ]);
+  }
+  if (classification.kind === 'imported-symbol-move') {
+    return uniqueRequirements([
+      requirement('base', details.fromSourcePath, 'declaration', 'base-export-declaration', details.symbolName),
+      requirement('base', details.importerSourcePath, 'reference', 'base-import-reference', details.symbolName),
+      requirement(branch, details.toSourcePath, 'declaration', 'branch-export-declaration', details.symbolName),
+      requirement(branch, details.importerSourcePath, 'reference', 'branch-import-reference', details.symbolName)
+    ]);
+  }
+  if (classification.kind === 'exported-symbol-move') {
+    return uniqueRequirements([
+      requirement('base', details.fromSourcePath, 'declaration', 'base-export-declaration', details.symbolName ?? details.exportedName),
+      requirement(branch, details.toSourcePath, 'declaration', 'branch-export-declaration', details.symbolName ?? details.exportedName)
+    ]);
+  }
+  return [];
+}
+
+function observeTypeScriptRefactorEvidenceRequirement(input, files, requirement) {
+  const expectedSourceHash = expectedProjectSourceHash(files, requirement.stage, requirement.sourcePath);
+  const importResult = matchingProjectImport(input, requirement.stage, requirement.sourcePath, expectedSourceHash);
+  const signals = typeScriptCompilerEvidenceSignals(importResult);
+  const passed = requirement.requirement === 'reference'
+    ? signals.compilerReferences > 0
+    : signals.compilerSymbols > 0 || signals.compilerTypes > 0;
+  return compactRecord({
+    ...requirement,
+    status: passed ? 'passed' : 'missing',
+    code: passed ? undefined : missingRequirementCode(requirement, importResult, expectedSourceHash, signals),
+    expectedSourceHash,
+    sourceImportMatched: Boolean(importResult),
+    importSourceHash: sourceHashForImport(importResult),
+    parser: signals.parser,
+    astFormat: signals.astFormat,
+    compilerSymbols: signals.compilerSymbols,
+    compilerTypes: signals.compilerTypes,
+    compilerReferences: signals.compilerReferences,
+    referenceRelations: signals.referenceRelations,
+    referenceGraphReferences: signals.referenceGraphReferences,
+    evidenceIds: signals.evidenceIds
+  });
+}
+
+function matchingProjectImport(input, stage, sourcePath, expectedSourceHash) {
+  if (!sourcePath) return undefined;
+  return normalizeProjectImports(projectImportsForStage(input, stage)).find((importResult) => {
+    if (sourcePathForImport(importResult) !== sourcePath) return false;
+    if (!expectedSourceHash) return true;
+    return sourceHashForImport(importResult) === expectedSourceHash;
+  });
+}
+
+function typeScriptCompilerEvidenceSignals(importResult) {
+  const semanticIndex = importResult?.semanticIndex;
+  const facts = semanticIndex?.facts ?? [];
+  const relations = semanticIndex?.relations ?? [];
+  const evidence = uniqueEvidenceRecords([
+    ...(importResult?.evidence ?? []),
+    ...(semanticIndex?.evidence ?? [])
+  ]);
+  const compilerReferences = facts.filter((fact) => fact.predicate === 'compilerSymbolReference').length;
+  const referenceRelations = relations.filter((relation) => relation.predicate === 'references' && relation.metadata?.compilerReference === true).length;
+  const referenceGraphReferences = Number(
+    semanticIndex?.metadata?.compilerReferenceGraph?.references
+    ?? importResult?.metadata?.compilerReferenceGraph?.references
+    ?? 0
+  );
+  return {
+    parser: firstString(importResult?.adapter?.parser, importResult?.nativeAst?.parser, semanticIndex?.metadata?.parser),
+    astFormat: firstString(importResult?.metadata?.astFormat, semanticIndex?.metadata?.astFormat),
+    compilerSymbols: facts.filter((fact) => fact.predicate === 'compilerSymbol').length,
+    compilerTypes: facts.filter((fact) => fact.predicate === 'compilerType').length,
+    compilerReferences: compilerReferences + referenceRelations + referenceGraphReferences,
+    referenceRelations,
+    referenceGraphReferences,
+    evidenceIds: uniqueStrings([
+      ...evidence
+        .filter((record) => record.kind === 'typescript-compiler-reference-graph' || record.metadata?.graphRecords?.compilerSymbols || record.metadata?.references)
+        .map((record) => record.id),
+      ...facts.flatMap((fact) => fact.evidenceIds ?? [])
+    ])
+  };
+}
+
+function expectedProjectSourceHash(files, stage, sourcePath) {
+  const sourceText = stageSourceText(files.find((file) => file.sourcePath === sourcePath), stage);
+  return typeof sourceText === 'string' ? hashSemanticValue(sourceText) : undefined;
+}
+
+function stageSourceText(file, stage) {
+  if (!file) return undefined;
+  if (stage === 'base') return file.baseSourceText;
+  if (stage === 'worker') return file.workerDeleted ? undefined : file.workerSourceText ?? file.baseSourceText;
+  if (stage === 'head') return file.headDeleted ? undefined : file.headSourceText ?? file.baseSourceText;
+  return undefined;
+}
+
+function projectImportsForStage(input, stage) {
+  if (stage === 'base') return input.baseProjectImports ?? input.projectGraphImports?.base;
+  if (stage === 'worker') return input.workerProjectImports ?? input.projectGraphImports?.worker;
+  if (stage === 'head') return input.headProjectImports ?? input.projectGraphImports?.head;
+  if (stage === 'output') return input.outputProjectImports ?? input.projectGraphImports?.output;
+  return input.projectGraphImports?.[stage];
+}
+
+function sourcePathForImport(importResult) {
+  return firstString(
+    importResult?.sourcePath,
+    importResult?.nativeSource?.sourcePath,
+    importResult?.nativeAst?.sourcePath,
+    importResult?.semanticIndex?.documents?.[0]?.path
+  );
+}
+
+function sourceHashForImport(importResult) {
+  return firstString(
+    importResult?.sourceHash,
+    importResult?.nativeSource?.sourceHash,
+    importResult?.nativeAst?.sourceHash,
+    importResult?.semanticIndex?.documents?.[0]?.sourceHash
+  );
+}
+
+function missingRequirementCode(requirement, importResult, expectedSourceHash, signals) {
+  if (!importResult) return 'typescript-refactor-project-import-missing';
+  if (expectedSourceHash && sourceHashForImport(importResult) !== expectedSourceHash) return 'typescript-refactor-project-import-stale';
+  if (requirement.requirement === 'reference' && signals.compilerReferences === 0) return 'typescript-refactor-reference-evidence-missing';
+  return 'typescript-refactor-symbol-evidence-missing';
+}
+
+function requirement(stage, sourcePath, requirementKind, role, symbolName) {
+  return compactRecord({
+    stage,
+    sourcePath,
+    requirement: requirementKind,
+    role,
+    symbolName
+  });
+}
+
+function requiresTypeScriptRefactorEvidence(input = {}) {
+  return input.requireTypeScriptRefactorEvidence === true
+    || input.requireTypeScriptLanguageServiceRefactorEvidence === true
+    || input.requireCompilerRefactorEvidence === true;
+}
+
+function normalizeProjectImports(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.filter(Boolean);
+  if (value instanceof Map) return [...value.values()].filter(Boolean);
+  if (typeof value === 'object') return Object.values(value).filter(Boolean);
+  return [];
+}
+
+function uniqueRequirements(requirements) {
+  const seen = new Set();
+  return requirements.filter((item) => {
+    if (!item.sourcePath) return false;
+    const key = `${item.stage}\0${item.sourcePath}\0${item.requirement}\0${item.role}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function uniqueEvidenceRecords(records) {
+  const seen = new Set();
+  return records.filter((record) => {
+    const key = record?.id;
+    if (!key || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (value !== undefined && value !== null && String(value)) return String(value);
+  }
+  return undefined;
+}
+
+function compactRecord(record) {
+  return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
+}
+
+export {
+  TypeScriptRefactorEvidenceKey,
+  TypeScriptRefactorEvidenceMissingCode,
+  hasFailedTypeScriptRefactorEvidence,
+  requiresTypeScriptRefactorEvidence,
+  typeScriptRefactorEvidenceRecordsFromClassifications,
+  withTypeScriptRefactorEvidence
+};

package/dist/internal/index-impl/typeScriptCompilerInferenceSyntax.js

@@ -0,0 +1,170 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+
+const TypeInferenceSyntaxProofKind = 'typescript-checker-public-api-type-inference-syntax-evidence';
+
+function compilerTypeInferenceSyntaxRecord(checker, identitySymbol, location, ts) {
+  const records = compilerTypeInferenceSyntaxRecords(checker, identitySymbol, location, ts);
+  if (!records.length) return {};
+  const counts = inferenceSyntaxCounts(records);
+  const typeInferenceSyntaxHash = hashSemanticValue({
+    kind: 'frontier.lang.typescript.compilerTypeInferenceSyntaxEvidence.v1',
+    records: records.map(canonicalInferenceSyntaxRecord)
+  });
+  return {
+    typeInferenceSyntax: records,
+    typeInferenceSyntaxKinds: uniqueStrings(records.map((record) => record.kind)),
+    typeInferenceSyntaxCount: records.length,
+    satisfiesExpressionCount: counts.satisfiesExpressionCount || undefined,
+    asConstAssertionCount: counts.asConstAssertionCount || undefined,
+    constTypeParameterCount: counts.constTypeParameterCount || undefined,
+    typeInferenceSyntaxHash,
+    typeInferenceSyntaxProof: {
+      kind: TypeInferenceSyntaxProofKind,
+      status: 'passed',
+      proofLevel: 'typescript-checker-public-api-type-inference-syntax',
+      checkerInvariant: 'inference syntax node/type texts complete',
+      requiredSignals: [
+        'compiler-type-inference-syntax-node-texts',
+        'compiler-type-inference-syntax-expression-texts',
+        'compiler-type-inference-syntax-type-texts'
+      ],
+      typeInferenceSyntaxHash,
+      ...counts,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  };
+}
+
+function compilerTypeInferenceSyntaxRecords(checker, identitySymbol, location, ts) {
+  const records = [];
+  for (const declaration of Array.isArray(identitySymbol?.declarations) ? identitySymbol.declarations : []) {
+    visitSyntaxNodes(ts, declaration, (node) => {
+      const record = inferenceSyntaxNodeRecord(checker, node, location, ts);
+      if (record) records.push(record);
+    });
+  }
+  return uniqueRecords(records, (record) => [record.kind, record.nodeText, record.typeText].join('\0'));
+}
+
+function inferenceSyntaxNodeRecord(checker, node, location, ts) {
+  if (isSyntaxKind(ts, node, 'SatisfiesExpression')) return satisfiesExpressionRecord(checker, node, location, ts);
+  if (isAsConstAssertion(node, ts)) return asConstAssertionRecord(checker, node, location, ts);
+  if (isConstTypeParameter(node, ts)) return constTypeParameterRecord(checker, node, location, ts);
+  return undefined;
+}
+
+function satisfiesExpressionRecord(checker, node, location, ts) {
+  return compactRecord({
+    kind: 'satisfies-expression',
+    syntaxKind: syntaxKindName(ts, node.kind),
+    nodeText: nodeText(node),
+    expressionText: nodeText(node.expression),
+    expressionTypeText: typeTextAt(checker, node.expression, location),
+    typeText: typeTextFromTypeNode(checker, node.type, location)
+  });
+}
+
+function asConstAssertionRecord(checker, node, location, ts) {
+  return compactRecord({
+    kind: 'as-const-assertion',
+    syntaxKind: syntaxKindName(ts, node.kind),
+    nodeText: nodeText(node),
+    expressionText: nodeText(node.expression),
+    expressionTypeText: typeTextAt(checker, node.expression, location),
+    typeText: typeTextAt(checker, node, location)
+  });
+}
+
+function constTypeParameterRecord(checker, node, location, ts) {
+  return compactRecord({
+    kind: 'const-type-parameter',
+    syntaxKind: syntaxKindName(ts, node.kind),
+    nodeText: nodeText(node),
+    name: stringValue(node.name?.escapedText ?? node.name?.text),
+    typeText: typeTextAt(checker, node.name ?? node, location),
+    constraintTypeText: typeTextFromTypeNode(checker, node.constraint, location),
+    defaultTypeText: typeTextFromTypeNode(checker, node.default, location)
+  });
+}
+
+function visitSyntaxNodes(ts, node, visit) {
+  if (!node || typeof node !== 'object') return;
+  visit(node);
+  if (typeof ts?.forEachChild === 'function') {
+    ts.forEachChild(node, (child) => visitSyntaxNodes(ts, child, visit));
+    return;
+  }
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) value.forEach((child) => visitSyntaxNodes(ts, child, visit));
+    else if (value && typeof value === 'object' && Number.isFinite(value.kind)) visitSyntaxNodes(ts, value, visit);
+  }
+}
+
+function isAsConstAssertion(node, ts) {
+  if (!isSyntaxKind(ts, node, 'AsExpression')) return false;
+  return /\bas\s+const\b/.test(nodeText(node));
+}
+
+function isConstTypeParameter(node, ts) {
+  if (!isSyntaxKind(ts, node, 'TypeParameter')) return false;
+  const constKeyword = syntaxKind(ts, 'ConstKeyword');
+  return constKeyword !== undefined && Array.isArray(node.modifiers)
+    && node.modifiers.some((modifier) => modifier.kind === constKeyword);
+}
+
+function inferenceSyntaxCounts(records) {
+  return {
+    satisfiesExpressionCount: countKind(records, 'satisfies-expression'),
+    asConstAssertionCount: countKind(records, 'as-const-assertion'),
+    constTypeParameterCount: countKind(records, 'const-type-parameter')
+  };
+}
+
+function canonicalInferenceSyntaxRecord(record) {
+  return compactRecord({
+    kind: record.kind,
+    nodeText: record.nodeText,
+    expressionText: record.expressionText,
+    expressionTypeText: record.expressionTypeText,
+    typeText: record.typeText,
+    constraintTypeText: record.constraintTypeText,
+    defaultTypeText: record.defaultTypeText,
+    name: record.name
+  });
+}
+
+function typeTextFromTypeNode(checker, node, location) {
+  const type = safeCall(checker?.getTypeFromTypeNode, checker, node) ?? safeCall(checker?.getTypeAtLocation, checker, node ?? location);
+  return type ? stringValue(safeCall(checker?.typeToString, checker, type)) : nodeText(node);
+}
+
+function typeTextAt(checker, node, location) {
+  const type = safeCall(checker?.getTypeAtLocation, checker, node ?? location);
+  return type ? stringValue(safeCall(checker?.typeToString, checker, type)) : nodeText(node);
+}
+
+function syntaxKind(ts, name) { return numberValue(ts?.SyntaxKind?.[name]); }
+function isSyntaxKind(ts, node, name) { return node?.kind === syntaxKind(ts, name); }
+function syntaxKindName(ts, kind) { return stringValue(ts?.SyntaxKind?.[kind]) ?? (Number.isFinite(kind) ? String(kind) : undefined); }
+function nodeText(node) { return stringValue(safeCall(node?.getText, node)); }
+function countKind(records, kind) { return records.filter((record) => record.kind === kind).length; }
+function safeCall(fn, receiver, ...args) {
+  if (typeof fn !== 'function') return undefined;
+  try { return fn.apply(receiver, args); } catch { return undefined; }
+}
+function stringValue(value) { return value === undefined || value === null || value === '' ? undefined : String(value); }
+function numberValue(value) { return Number.isFinite(value) ? value : undefined; }
+function compactRecord(record) { return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)); }
+function uniqueStrings(values) { return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))]; }
+function uniqueRecords(records, keyFn) {
+  const seen = new Set();
+  return records.filter((record) => {
+    const key = keyFn(record);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export { compilerTypeInferenceSyntaxRecord };

package/dist/internal/index-impl/typeScriptCompilerReferenceGraph.js

@@ -0,0 +1,186 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { idFragment } from '../../native-import-utils.js';
+import { spanFromTypeScriptNode } from './spanFromTypeScriptNode.js';
+import { typeScriptCompilerSymbolRecordForNode } from './typeScriptCompilerSymbolIdentity.js';
+import { typeScriptKindName } from './typeScriptKindName.js';
+
+function createTypeScriptCompilerReferenceGraph(sourceFile, input, options = {}, context, semanticIndex) {
+  const checker = options.typeChecker ?? options.checker ?? options.program?.getTypeChecker?.();
+  if (!checker || !sourceFile) return emptyReferenceGraph();
+  const documentId = semanticIndex?.documents?.[0]?.id ?? `doc_${idFragment(input.sourcePath ?? input.language)}_${idFragment(input.sourceHash)}`;
+  const evidenceId = `evidence_${idFragment(input.sourcePath ?? input.language)}_${idFragment(options.astFormat ?? options.parser)}_compiler_references`;
+  const records = [];
+  visitCompilerReferenceNodes(sourceFile, undefined, options.ts, (node, parent) => {
+    if (isDeclarationName(node, parent, options.ts)) return;
+    const spanNode = compilerReferenceSpanNode(node, parent, options.ts);
+    const compiler = typeScriptCompilerSymbolRecordForNode(node, input, options);
+    if (!compiler) return;
+    const nativeAstNodeId = context?.objectIds?.get?.(spanNode) ?? context?.objectIds?.get?.(node);
+    const span = spanFromTypeScriptNode(spanNode, sourceFile);
+    const key = `${compiler.symbolId}\0${nativeAstNodeId ?? spanKey(span)}`;
+    if (records.some((record) => record.key === key)) return;
+    records.push({ key, node, nativeAstNodeId, span, compiler });
+  });
+  if (!records.length) return emptyReferenceGraph();
+  const occurrences = records.map((record, index) => referenceOccurrence(record, documentId, index));
+  const relations = records.map((record, index) => referenceRelation(record, documentId, occurrences[index], evidenceId));
+  const facts = records.map((record, index) => referenceFact(record, occurrences[index], relations[index], evidenceId));
+  const semanticSymbolIds = new Set((semanticIndex?.symbols ?? []).map((symbol) => symbol.id));
+  const mappings = records
+    .map((record, index) => referenceMapping(record, occurrences[index], evidenceId, index, semanticSymbolIds))
+    .filter(Boolean);
+  const evidence = [referenceEvidence(evidenceId, input, options, records)];
+  return {
+    occurrences,
+    relations,
+    facts,
+    mappings,
+    evidence,
+    summary: {
+      references: records.length,
+      symbols: new Set(records.map((record) => record.compiler.symbolId)).size,
+      evidenceId
+    }
+  };
+}
+
+function attachTypeScriptCompilerReferenceGraph(semanticIndex, graph) {
+  if (!graph?.summary?.references) return semanticIndex;
+  return {
+    ...semanticIndex,
+    occurrences: [...(semanticIndex.occurrences ?? []), ...graph.occurrences],
+    relations: [...(semanticIndex.relations ?? []), ...graph.relations],
+    facts: [...(semanticIndex.facts ?? []), ...graph.facts],
+    evidence: [...(semanticIndex.evidence ?? []), ...graph.evidence],
+    metadata: {
+      ...(semanticIndex.metadata ?? {}),
+      graphCoverage: 'module-edge-declarations+compiler-references',
+      compilerReferenceGraph: graph.summary
+    }
+  };
+}
+
+function visitCompilerReferenceNodes(node, parent, ts, visit) {
+  if (!node || typeof node !== 'object') return;
+  if (isCompilerReferenceNode(node, ts)) visit(node, parent);
+  const each = (child) => visitCompilerReferenceNodes(child, node, ts, visit);
+  if (ts && typeof ts.forEachChild === 'function') ts.forEachChild(node, each);
+  else if (typeof node.forEachChild === 'function') node.forEachChild(each);
+  else if (Array.isArray(node.children)) node.children.forEach(each);
+}
+
+function isCompilerReferenceNode(node, ts) {
+  const kind = typeScriptKindName(node, ts);
+  return kind === 'Identifier' || kind === 'PrivateIdentifier';
+}
+
+function compilerReferenceSpanNode(node, parent, ts) {
+  return isReceiverMemberName(node, parent, ts) ? parent : node;
+}
+
+function isReceiverMemberName(node, parent, ts) {
+  if (parent?.name !== node) return false;
+  if (typeScriptKindName(parent, ts) !== 'PropertyAccessExpression') return false;
+  const receiverKind = typeScriptKindName(parent.expression, ts);
+  return receiverKind === 'ThisKeyword' || receiverKind === 'SuperKeyword';
+}
+
+function referenceOccurrence(record, documentId, index) {
+  return compactRecord({
+    id: `occ_${idFragment(record.nativeAstNodeId ?? record.key)}_${index + 1}_compiler_reference`,
+    documentId,
+    symbolId: record.compiler.symbolId,
+    role: 'reference',
+    span: record.span,
+    nativeAstNodeId: record.nativeAstNodeId,
+    metadata: { compilerReference: true, compilerSymbol: record.compiler.compilerSymbol }
+  });
+}
+
+function referenceRelation(record, documentId, occurrence, evidenceId) {
+  return {
+    id: `rel_${idFragment(hashSemanticValue([documentId, occurrence.id, record.compiler.symbolId, 'compiler-reference']))}`,
+    sourceId: occurrence.id,
+    predicate: 'references',
+    targetId: record.compiler.symbolId,
+    evidenceIds: [evidenceId],
+    metadata: { compilerReference: true }
+  };
+}
+
+function referenceFact(record, occurrence, relation, evidenceId) {
+  return {
+    id: `fact_${idFragment(hashSemanticValue([occurrence.id, relation.id, 'compiler-symbol-reference']))}_compiler_symbol_reference`,
+    predicate: 'compilerSymbolReference',
+    subjectId: occurrence.id,
+    objectId: record.compiler.symbolId,
+    value: { ...record.compiler.compilerSymbol, identityHash: record.compiler.compilerSymbolIdentityHash },
+    evidenceIds: [evidenceId]
+  };
+}
+
+function referenceMapping(record, occurrence, evidenceId, index, semanticSymbolIds) {
+  if (!semanticSymbolIds.has(record.compiler.symbolId)) return undefined;
+  return compactRecord({
+    id: `map_${idFragment(record.nativeAstNodeId ?? occurrence.id)}_${index + 1}_compiler_reference`,
+    nativeAstNodeId: record.nativeAstNodeId,
+    semanticSymbolId: record.compiler.symbolId,
+    semanticOccurrenceId: occurrence.id,
+    sourceSpan: record.span,
+    evidenceIds: [evidenceId],
+    lossIds: [],
+    precision: record.span ? 'reference' : 'unknown'
+  });
+}
+
+function referenceEvidence(evidenceId, input, options, records) {
+  return {
+    id: evidenceId,
+    kind: 'typescript-compiler-reference-graph',
+    status: 'passed',
+    path: input.sourcePath,
+    summary: `Resolved ${records.length} TypeScript compiler reference(s).`,
+    metadata: {
+      parser: options.parser,
+      astFormat: options.astFormat,
+      language: input.language,
+      references: records.length,
+      symbols: new Set(records.map((record) => record.compiler.symbolId)).size
+    }
+  };
+}
+
+function isDeclarationName(node, parent, ts) {
+  return parent?.name === node && DeclarationNameParentKinds.has(typeScriptKindName(parent, ts));
+}
+function spanKey(span) { return `${span?.path ?? ''}:${span?.startLine ?? ''}:${span?.startColumn ?? ''}:${span?.endLine ?? ''}:${span?.endColumn ?? ''}`; }
+function compactRecord(record) { return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)); }
+function emptyReferenceGraph() { return { occurrences: [], relations: [], facts: [], mappings: [], evidence: [], summary: { references: 0, symbols: 0 } }; }
+
+const DeclarationNameParentKinds = new Set([
+  'BindingElement',
+  'ClassDeclaration',
+  'ClassExpression',
+  'EnumDeclaration',
+  'EnumMember',
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'GetAccessor',
+  'ImportClause',
+  'ImportEqualsDeclaration',
+  'ImportSpecifier',
+  'InterfaceDeclaration',
+  'MethodDeclaration',
+  'MethodSignature',
+  'ModuleDeclaration',
+  'NamespaceImport',
+  'Parameter',
+  'PropertyDeclaration',
+  'PropertySignature',
+  'SetAccessor',
+  'TypeAliasDeclaration',
+  'TypeParameter',
+  'VariableDeclaration'
+]);
+
+export { attachTypeScriptCompilerReferenceGraph, createTypeScriptCompilerReferenceGraph };