@untangle-code/parser-registry 0.0.0-stage → 0.1.1

package/src/languages/structured-text/index.ts

@@ -0,0 +1,192 @@
+/**
+ * `LanguageAdapter` fuer strukturierte, verfasste Daten — JSON, YAML, TOML,
+ * XML (vision.md §1c, spec.md §7.1/§7.2, WP-217).
+ *
+ * DIE ENTSCHEIDUNG, DIE HIER GETROFFEN IST
+ *
+ * Bei der Selbstanalyse fielen 80 JSON-, 6 TOML-, 4 YAML- und 2 XML-Dateien
+ * unter `unsupported_language`. Dieser Grund war falsch: die Formate SIND
+ * unterstuetzt, sie haben nur keinen Graphen und keinen Kontrollfluss. Nach
+ * spec.md §7.2 gehoeren sie ausdruecklich in die Stufe `text`.
+ *
+ * Sie bekommen deshalb hier `text` — mit voller Suche und sicheren
+ * Textchunks. Eine `package.json`, eine `untangle.toml`, ein Manifest
+ * beantworten echte Fragen; sie aus dem Index zu halten waere ein Verlust.
+ *
+ * WAS SIE NICHT BEKOMMEN, UND WARUM DAS KEINE ABSTUFUNG IST
+ *
+ * - Keine Symbole und keine `symbolScopes`: ein Schluessel in einer
+ *   `package.json` ist kein Symbol mit Signatur, Callern und Callees. Ein
+ *   erfundenes Symbol waere schlimmer als keins.
+ * - Keine Komplexitaetszahlen: es gibt keine Entscheidungspunkte. Wer diese
+ *   Dateien in einer Metrikauswertung uebergeht, benennt das mit dem Grund
+ *   `no_metric_defined` (domain `skip-ledger.ts`) — nicht mit
+ *   `unsupported_language`, denn verstanden sind sie.
+ * - Auch KEINE Prosa-Metriken: eine YAML-Datei hat keine Abschnittstiefe im
+ *   Sinne von Ueberschriften und keine Verweisdichte im Sinne von
+ *   Querverweisen. Die Prosa-Familie ist fuer Prosa.
+ *
+ * WIE GESCHNITTEN WIRD
+ *
+ * Nur an Grenzen, die im Format EXAKT und ohne Parser bestimmbar sind:
+ *
+ * - TOML: eine Zeile, die (nach Leerraum) mit `[` beginnt, eroeffnet eine
+ *   neue Tabelle — das ist die Gliederung des Formats.
+ * - YAML: `---` trennt Dokumente in einem Strom.
+ *
+ * Fuer JSON und XML gibt es keine solche Grenze ohne echten Parser. Sie
+ * bekommen EINEN Bereich ueber die ganze Datei, den der Chunker bei Bedarf
+ * am Tokenbudget teilt. Das ist die ehrliche Antwort und ausdruecklich
+ * KEINE ueberschriftenbewusste Gliederung, wie Markdown sie bekommt — sie
+ * zu behaupten, wo das Format sie nicht hergibt, waere die Sorte
+ * Beschoenigung, die E4 verbietet.
+ */
+import type {
+  AstRegion,
+  ComplexityFacts,
+  ExtractedSymbol,
+  HalsteadTokens,
+  LanguageAdapter,
+  ParsedAst,
+  ParseResult,
+  RawCall,
+  RawImport,
+  SourceFile,
+  SourceRange,
+} from "@untangle-code/domain";
+import { textFormatExtensions, textFormatExtensionOf } from "@untangle-code/domain";
+
+import { buildLineByteIndex, rangeForLines, type LineByteIndex } from "../prose/line-bytes.js";
+
+/** Sprachkennung dieses Adapters. Bewusst formatuebergreifend: die Behandlung ist dieselbe. */
+export const STRUCTURED_TEXT_LANGUAGE_ID = "structured-text";
+
+interface StructuredAstRoot {
+  readonly fileId: string;
+  readonly index: LineByteIndex;
+  readonly blocks: readonly SourceRange[];
+}
+
+const TOML_TABLE = /^\s*\[/;
+const YAML_DOCUMENT_SEPARATOR = /^---\s*$/;
+
+/** Zeilen, an denen ein neuer Block beginnt (1-basiert), aufsteigend, ohne Zeile 1. */
+function blockStartLines(path: string, lines: readonly string[]): number[] {
+  const extension = textFormatExtensionOf(path);
+  const isToml = extension === ".toml";
+  const isYaml = extension === ".yaml" || extension === ".yml";
+  if (!isToml && !isYaml) return [];
+
+  const starts: number[] = [];
+  for (const [index, rawLine] of lines.entries()) {
+    if (index === 0) continue;
+    if (isToml && TOML_TABLE.test(rawLine)) starts.push(index + 1);
+    if (isYaml && YAML_DOCUMENT_SEPARATOR.test(rawLine)) starts.push(index + 1);
+  }
+  return starts;
+}
+
+function buildBlocks(path: string, content: string, index: LineByteIndex): SourceRange[] {
+  const lines = content.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+  const totalLines = Math.max(index.lineCount, 1);
+  const starts = [1, ...blockStartLines(path, lines)];
+  return starts.map((startLine, position) => {
+    const next = starts[position + 1];
+    return rangeForLines(index, startLine, next !== undefined ? next - 1 : totalLines);
+  });
+}
+
+function rootOf(ast: ParsedAst): StructuredAstRoot {
+  return ast.root as StructuredAstRoot;
+}
+
+export function createStructuredTextAdapter(): LanguageAdapter {
+  return {
+    languageId: STRUCTURED_TEXT_LANGUAGE_ID,
+    extensions: textFormatExtensions("structured_data"),
+    supportLevel: "text",
+
+    parse(source: SourceFile): ParseResult {
+      const index = buildLineByteIndex(source.content);
+      const root: StructuredAstRoot = {
+        fileId: source.fileId,
+        index,
+        blocks: buildBlocks(source.path, source.content, index),
+      };
+      // Es wird nichts geparst, also kann nichts scheitern. `"complete"` ist
+      // hier eine Aussage ueber die Textzerlegung, nicht ueber eine
+      // Grammatik: eine ungueltige JSON-Datei wird trotzdem vollstaendig
+      // erfasst und durchsuchbar — sie bekommt nur keine Struktur.
+      return {
+        parseQuality: "complete",
+        ast: {
+          languageId: STRUCTURED_TEXT_LANGUAGE_ID,
+          parseQuality: "complete",
+          root,
+          diagnostics: [],
+        },
+        diagnostics: [],
+        errorNodeCount: 0,
+        missingNodeCount: 0,
+      };
+    },
+
+    extractChunks(ast: ParsedAst): AstRegion[] {
+      const root = rootOf(ast);
+      const children: AstRegion[] = root.blocks.map((range, ordinal) => ({
+        chunkKind: "configuration",
+        range,
+        scopeId: `${root.fileId}#block#${String(ordinal)}`,
+        splittable: false,
+      }));
+      return [
+        {
+          chunkKind: "module",
+          range: {
+            startLine: 1,
+            endLine: root.index.lineCount,
+            startByte: 0,
+            endByte: root.index.totalBytes,
+          },
+          scopeId: root.fileId,
+          // Ein einziger Block ueber die ganze Datei traegt keine
+          // Information; dann bleibt der Wurzelbereich kinderlos und der
+          // Chunker schneidet selbst am Tokenbudget.
+          splittable: children.length > 1,
+          ...(children.length > 1 ? { children } : {}),
+        },
+      ];
+    },
+
+    extractSymbols(_ast: ParsedAst): ExtractedSymbol[] {
+      return [];
+    },
+
+    extractImports(_ast: ParsedAst): RawImport[] {
+      return [];
+    },
+
+    extractCalls(_ast: ParsedAst): RawCall[] {
+      return [];
+    },
+
+    computeComplexity(ast: ParsedAst): ComplexityFacts {
+      return {
+        symbolScopes: [],
+        decisions: [],
+        nestingEvents: [],
+        operators: [],
+        operands: [],
+        nodeKinds: [],
+        comments: [],
+        identifiers: [],
+        literals: [],
+        parseDiagnostics: ast.diagnostics,
+      };
+    },
+
+    tokenizeForHalstead(_ast: ParsedAst): HalsteadTokens {
+      return { operators: [], operands: [] };
+    },
+  };
+}

package/src/languages/tsx/index.ts

@@ -0,0 +1,9 @@
+import type { LanguageAdapter } from "@untangle-code/domain";
+
+import { createTreeSitterAdapter } from "../shared/create-adapter.js";
+import { TSX_DIALECT } from "../shared/dialect.js";
+
+/** TSX `LanguageAdapter` (`.tsx`), support level "deep" (spec.md §7.2). */
+export function createTsxAdapter(): LanguageAdapter {
+  return createTreeSitterAdapter(TSX_DIALECT);
+}

package/src/languages/typescript/index.ts

@@ -0,0 +1,9 @@
+import type { LanguageAdapter } from "@untangle-code/domain";
+
+import { createTreeSitterAdapter } from "../shared/create-adapter.js";
+import { TYPESCRIPT_DIALECT } from "../shared/dialect.js";
+
+/** TypeScript `LanguageAdapter` (`.ts`, `.mts`, `.cts`), support level "deep" (spec.md §7.2). */
+export function createTypeScriptAdapter(): LanguageAdapter {
+  return createTreeSitterAdapter(TYPESCRIPT_DIALECT);
+}

package/src/languages/vue/index.ts

@@ -0,0 +1,312 @@
+import { createRequire } from "node:module";
+
+import type {
+  AstRegion,
+  ComplexityFacts,
+  LanguageAdapter,
+  ParseDiagnostic,
+  ParsedAst,
+  ParseResult,
+  SourceFile,
+  SourceRange,
+} from "@untangle-code/domain";
+import { AdapterParseError, sha256Hex } from "@untangle-code/domain";
+import type { SFCBlock, SFCParseResult, SFCScriptBlock } from "@vue/compiler-sfc";
+import type * as VueCompiler from "@vue/compiler-sfc";
+
+import { buildByteOffsetTable } from "../../text/byte-offset-table.js";
+import { createJavaScriptAdapter } from "../javascript/index.js";
+import { createJsxAdapter } from "../jsx/index.js";
+import { MAX_PARSE_SOURCE_BYTES } from "../shared/parse-limits.js";
+import { createTsxAdapter } from "../tsx/index.js";
+import { createTypeScriptAdapter } from "../typescript/index.js";
+
+import { shiftVueRange, vueFacts, vueRegion, vueScopeId, vueSymbol } from "./mapping.js";
+
+export { shiftVueRange, vueQualifiedName, vueScopeId } from "./mapping.js";
+
+export interface VueScriptAst {
+  context: "script" | "setup";
+  /** Only dual-script SFCs need explicit context names to keep equal bindings distinct. */
+  qualifier: string;
+  adapter: LanguageAdapter;
+  ast: ParsedAst;
+  source: SourceFile;
+  /** Content range in the original SFC, not the surrounding script tags. */
+  range: SourceRange;
+}
+
+export interface VueAstRoot {
+  kind: "vue-sfc";
+  fileId: string;
+  range: SourceRange;
+  scripts: VueScriptAst[];
+}
+
+const require = createRequire(import.meta.url);
+let parseSfc:
+  | ((
+      source: string,
+      options: { filename: string; sourceMap: false; ignoreEmpty: false },
+    ) => SFCParseResult)
+  | undefined;
+
+function parseDescriptor(source: SourceFile): SFCParseResult {
+  // Loading the registry must not load Vue's compiler or any native grammar.
+  parseSfc ??= (require("@vue/compiler-sfc") as typeof VueCompiler).parse;
+  return parseSfc(source.content, { filename: source.path, sourceMap: false, ignoreEmpty: false });
+}
+
+function rootOf(ast: ParsedAst): VueAstRoot {
+  return ast.root as VueAstRoot;
+}
+
+function emptyFacts(diagnostics: ParseDiagnostic[]): ComplexityFacts {
+  return {
+    symbolScopes: [],
+    decisions: [],
+    nestingEvents: [],
+    operators: [],
+    operands: [],
+    nodeKinds: [],
+    comments: [],
+    identifiers: [],
+    literals: [],
+    parseDiagnostics: diagnostics,
+  };
+}
+
+function combinedFacts(ast: ParsedAst): ComplexityFacts {
+  const root = rootOf(ast);
+  const facts = emptyFacts(ast.diagnostics);
+  // A template-only component has no executable-code scope and no invented base complexity.
+  if (root.scripts.length === 0) return facts;
+  facts.symbolScopes.push({
+    symbolScopeId: root.fileId,
+    name: "",
+    qualifiedName: "",
+    kind: "file",
+    range: root.range,
+    executable: true,
+  });
+  for (const script of root.scripts) {
+    const part = vueFacts(script, root.fileId);
+    facts.symbolScopes.push(...part.symbolScopes);
+    facts.decisions.push(...part.decisions);
+    facts.nestingEvents.push(...part.nestingEvents);
+    facts.operators.push(...part.operators);
+    facts.operands.push(...part.operands);
+    facts.nodeKinds.push(...part.nodeKinds);
+    facts.comments.push(...part.comments);
+    facts.identifiers.push(...part.identifiers);
+    facts.literals.push(...part.literals);
+  }
+  return facts;
+}
+
+function blockRange(source: SourceFile, block: Pick<SFCBlock, "loc">): SourceRange {
+  const offsets = buildByteOffsetTable(source.content);
+  return {
+    startLine: block.loc.start.line,
+    endLine: block.loc.end.line,
+    startByte: offsets.toByteOffset(block.loc.start.offset),
+    endByte: offsets.toByteOffset(block.loc.end.offset),
+  };
+}
+
+function diagnostic(
+  message: string,
+  range: SourceRange,
+  kind: ParseDiagnostic["kind"] = "fallback",
+): ParseDiagnostic {
+  return { severity: "warning", kind, message, range };
+}
+
+function parseVue(source: SourceFile, adapters: ReadonlyMap<string, LanguageAdapter>): ParseResult {
+  const bytes = Buffer.byteLength(source.content, "utf8");
+  if (bytes > MAX_PARSE_SOURCE_BYTES) {
+    throw new AdapterParseError("file_too_large", "Vue SFC exceeds the parser source-byte limit.", {
+      measurements: { sizeBytes: bytes, limitBytes: MAX_PARSE_SOURCE_BYTES },
+    });
+  }
+  const parsed = parseDescriptor(source);
+  const range: SourceRange = {
+    startByte: 0,
+    endByte: bytes,
+    startLine: 1,
+    endLine: source.content.split("\n").length,
+  };
+  const diagnostics: ParseDiagnostic[] = parsed.errors.map((error) => ({
+    severity: "error",
+    kind: "error_node",
+    message: `Vue SFC: ${error.message}`,
+    range:
+      "loc" in error && error.loc !== undefined ? blockRange(source, { loc: error.loc }) : range,
+  }));
+  let errorNodeCount = parsed.errors.length;
+  let missingNodeCount = 0;
+  let incomplete = parsed.errors.length > 0;
+  const scripts: VueScriptAst[] = [];
+  const descriptor = parsed.descriptor;
+  const blocks: ["script" | "setup", SFCScriptBlock | null][] = [
+    ["script", descriptor.script],
+    ["setup", descriptor.scriptSetup],
+  ];
+  blocks.sort(
+    (left, right) =>
+      (left[1]?.loc.start.offset ?? Number.POSITIVE_INFINITY) -
+      (right[1]?.loc.start.offset ?? Number.POSITIVE_INFINITY),
+  );
+  const dual = descriptor.script !== null && descriptor.scriptSetup !== null;
+  if (dual && (descriptor.script?.lang ?? "js") !== (descriptor.scriptSetup?.lang ?? "js")) {
+    incomplete = true;
+    diagnostics.push(
+      diagnostic(
+        "Vue script and script setup must use the same language; cross-block compilation is not validated.",
+        range,
+      ),
+    );
+  }
+  for (const [context, block] of blocks) {
+    if (block === null) continue;
+    const partRange = blockRange(source, block);
+    const lang = block.lang ?? "js";
+    const adapter = adapters.get(lang);
+    if (block.src !== undefined || adapter === undefined) {
+      incomplete = true;
+      diagnostics.push(
+        diagnostic(
+          block.src !== undefined
+            ? `Vue ${context}: external script src is not analyzed; analyze its source file separately.`
+            : `Vue ${context}: unsupported script language "${lang}".`,
+          partRange,
+        ),
+      );
+      continue;
+    }
+    const scriptSource: SourceFile = {
+      ...source,
+      fileId: `${source.fileId}\u001fvue-${context}`,
+      languageId: adapter.languageId,
+      content: block.content,
+      contentHash: sha256Hex(block.content),
+      sizeBytes: Buffer.byteLength(block.content, "utf8"),
+    };
+    const part = adapter.parse(scriptSource);
+    const script = {
+      context,
+      qualifier: dual ? context : "",
+      adapter,
+      source: scriptSource,
+      range: partRange,
+    };
+    diagnostics.push(
+      ...part.diagnostics.map((item) => ({
+        ...item,
+        range: shiftVueRange(script, item.range),
+      })),
+    );
+    errorNodeCount += part.errorNodeCount;
+    missingNodeCount += part.missingNodeCount;
+    incomplete ||= part.parseQuality !== "complete";
+    if (part.ast !== null) scripts.push({ ...script, ast: part.ast });
+  }
+  if (blocks.every(([, block]) => block === null)) {
+    incomplete = true;
+    diagnostics.push(
+      diagnostic("Vue SFC contains no inline script; template logic is not analyzed.", range),
+    );
+  }
+  // Valid syntax is distinct from analysis scope: these warnings do not invent syntax errors.
+  const unmeasuredBlocks = [descriptor.template, ...descriptor.styles, ...descriptor.customBlocks];
+  for (const block of unmeasuredBlocks) {
+    if (block === null) continue;
+    diagnostics.push({
+      ...diagnostic(
+        `Vue analysis scope: inline script code only; ${block.type} block complexity and runtime bindings are not measured. The original block remains text-searchable.`,
+        blockRange(source, block),
+        "other",
+      ),
+      code: "analysis_scope_limited",
+    });
+  }
+  const parseQuality = incomplete ? "partial" : "complete";
+  const ast: ParsedAst = {
+    languageId: "vue",
+    parseQuality,
+    diagnostics,
+    root: { kind: "vue-sfc", fileId: source.fileId, range, scripts } satisfies VueAstRoot,
+  };
+  return { parseQuality, ast, diagnostics, errorNodeCount, missingNodeCount };
+}
+
+/** Vue SFC adapter: source-level inline scripts, never generated render/setup code. */
+export function createVueAdapter(): LanguageAdapter {
+  const adapters = new Map([
+    ["js", createJavaScriptAdapter()],
+    ["javascript", createJavaScriptAdapter()],
+    ["ts", createTypeScriptAdapter()],
+    ["typescript", createTypeScriptAdapter()],
+    ["tsx", createTsxAdapter()],
+    ["jsx", createJsxAdapter()],
+  ]);
+  const cache = new WeakMap<ParsedAst, ComplexityFacts>();
+  const facts = (ast: ParsedAst): ComplexityFacts => {
+    const previous = cache.get(ast);
+    if (previous !== undefined) return previous;
+    const computed = combinedFacts(ast);
+    cache.set(ast, computed);
+    return computed;
+  };
+  return {
+    languageId: "vue",
+    extensions: [".vue"],
+    supportLevel: "structural",
+    parse: (source) => parseVue(source, adapters),
+    extractChunks(ast): AstRegion[] {
+      const root = rootOf(ast);
+      const children = root.scripts
+        .flatMap((script) =>
+          script.adapter
+            .extractChunks(script.ast)
+            .flatMap((region) => region.children ?? [])
+            .map((region) => vueRegion(script, region, root.fileId)),
+        )
+        .sort((left, right) => left.range.startByte - right.range.startByte);
+      return [
+        {
+          chunkKind: "module",
+          range: root.range,
+          scopeId: root.fileId,
+          splittable: children.length > 0,
+          children,
+        },
+      ];
+    },
+    extractSymbols: (ast) =>
+      rootOf(ast).scripts.flatMap((script) =>
+        script.adapter.extractSymbols(script.ast).map((symbol) => vueSymbol(script, symbol)),
+      ),
+    extractImports: (ast) =>
+      rootOf(ast).scripts.flatMap((script) =>
+        script.adapter
+          .extractImports(script.ast)
+          .map((item) => ({ ...item, range: shiftVueRange(script, item.range) })),
+      ),
+    extractCalls: (ast) => {
+      const root = rootOf(ast);
+      return root.scripts.flatMap((script) =>
+        script.adapter.extractCalls(script.ast).map((call) => ({
+          ...call,
+          callerScopeId: vueScopeId(script, call.callerScopeId, root.fileId),
+          range: shiftVueRange(script, call.range),
+        })),
+      );
+    },
+    computeComplexity: facts,
+    tokenizeForHalstead(ast) {
+      const { operators, operands } = facts(ast);
+      return { operators, operands };
+    },
+  };
+}

package/src/languages/vue/mapping.ts

@@ -0,0 +1,93 @@
+import type {
+  AstRegion,
+  ComplexityFacts,
+  ExtractedSymbol,
+  SourceRange,
+} from "@untangle-code/domain";
+
+import type { VueScriptAst } from "./index.js";
+
+/** Vue compiler locations use UTF-16; the block range is already converted to UTF-8. */
+export function shiftVueRange(
+  script: Pick<VueScriptAst, "range">,
+  range: SourceRange,
+): SourceRange {
+  return {
+    startByte: script.range.startByte + range.startByte,
+    endByte: script.range.startByte + range.endByte,
+    startLine: script.range.startLine + range.startLine - 1,
+    endLine: script.range.startLine + range.endLine - 1,
+  };
+}
+
+export function vueQualifiedName(script: VueScriptAst, name: string): string {
+  return script.qualifier.length === 0 ? name : `${script.qualifier}.${name}`;
+}
+
+/** Both inline blocks share the enclosing file scope, but their child identities stay distinct. */
+export function vueScopeId(script: VueScriptAst, scopeId: string, fileId: string): string {
+  return scopeId === script.source.fileId ? fileId : scopeId;
+}
+
+export function vueSymbol(script: VueScriptAst, symbol: ExtractedSymbol): ExtractedSymbol {
+  return {
+    ...symbol,
+    qualifiedName: vueQualifiedName(script, symbol.qualifiedName),
+    range: shiftVueRange(script, symbol.range),
+    ...(symbol.docRange !== undefined ? { docRange: shiftVueRange(script, symbol.docRange) } : {}),
+    ...(symbol.parentQualifiedName !== undefined
+      ? { parentQualifiedName: vueQualifiedName(script, symbol.parentQualifiedName) }
+      : {}),
+  };
+}
+
+export function vueRegion(script: VueScriptAst, region: AstRegion, fileId: string): AstRegion {
+  return {
+    ...region,
+    range: shiftVueRange(script, region.range),
+    scopeId: vueScopeId(script, region.scopeId, fileId),
+    ...(region.symbolFqn !== undefined
+      ? { symbolFqn: vueQualifiedName(script, region.symbolFqn) }
+      : {}),
+    ...(region.children !== undefined
+      ? { children: region.children.map((child) => vueRegion(script, child, fileId)) }
+      : {}),
+  };
+}
+
+export function vueFacts(script: VueScriptAst, fileId: string): ComplexityFacts {
+  const facts = script.adapter.computeComplexity(script.ast);
+  const scoped = <T extends { symbolScopeId: string }>(fact: T): T => ({
+    ...fact,
+    symbolScopeId: vueScopeId(script, fact.symbolScopeId, fileId),
+  });
+  const ranged = <T extends { range: SourceRange }>(fact: T): T => ({
+    ...fact,
+    range: shiftVueRange(script, fact.range),
+  });
+  return {
+    symbolScopes: facts.symbolScopes
+      .filter((scope) => scope.symbolScopeId !== script.source.fileId)
+      .map((scope) => ({
+        ...ranged(scoped(scope)),
+        qualifiedName: vueQualifiedName(script, scope.qualifiedName),
+        ...(scope.parentScopeId !== undefined
+          ? { parentScopeId: vueScopeId(script, scope.parentScopeId, fileId) }
+          : {}),
+      })),
+    decisions: facts.decisions.map((fact) => ({
+      ...ranged(scoped(fact)),
+      ...(fact.logicalGroupId !== undefined
+        ? { logicalGroupId: `${script.context}:${fact.logicalGroupId}` }
+        : {}),
+    })),
+    nestingEvents: facts.nestingEvents.map((fact) => ranged(scoped(fact))),
+    operators: facts.operators.map((fact) => ranged(scoped(fact))),
+    operands: facts.operands.map((fact) => ranged(scoped(fact))),
+    nodeKinds: facts.nodeKinds.map(scoped),
+    comments: facts.comments.map((range) => shiftVueRange(script, range)),
+    identifiers: facts.identifiers.map((fact) => ranged(scoped(fact))),
+    literals: facts.literals.map((fact) => ranged(scoped(fact))),
+    parseDiagnostics: facts.parseDiagnostics.map(ranged),
+  };
+}

package/src/registry.ts

@@ -0,0 +1,61 @@
+/**
+ * `ParserRegistry` (domain `ports.ts`) implementation: registration plus
+ * resolution by extension / language id (architecture.md §6.5).
+ *
+ * Registering an adapter here does NOT load its grammar — `createTreeSitterAdapter`
+ * (see `languages/shared/create-adapter.ts`) only touches the native
+ * `tree-sitter` module and the specific grammar module inside `parse()`,
+ * via `grammar-loader.ts`'s lazy, cached `require`. A CLI can therefore call
+ * `createParserRegistry()` and list/resolve adapters at startup without
+ * loading a single native grammar; the first grammar load happens on the
+ * first `parse()` call for that language, and only that language's grammar
+ * is ever touched if a workspace has, say, TypeScript files only.
+ */
+import type { LanguageAdapter, ParserRegistry, SupportLevel } from "@untangle-code/domain";
+
+export class LazyParserRegistry implements ParserRegistry {
+  private readonly adaptersByLanguageId = new Map<string, LanguageAdapter>();
+  private readonly adaptersByExtension = new Map<string, LanguageAdapter>();
+
+  register(adapter: LanguageAdapter): void {
+    this.adaptersByLanguageId.set(adapter.languageId, adapter);
+    for (const extension of adapter.extensions) {
+      this.adaptersByExtension.set(extension.toLowerCase(), adapter);
+    }
+  }
+
+  listAdapters(): LanguageAdapter[] {
+    return [...this.adaptersByLanguageId.values()];
+  }
+
+  getAdapterByLanguage(languageId: string): LanguageAdapter | null {
+    return this.adaptersByLanguageId.get(languageId) ?? null;
+  }
+
+  getAdapterForPath(path: string, _contentSample?: string): LanguageAdapter | null {
+    const extension = extensionOf(path);
+    if (extension === null) {
+      // Extensionless-file content probing (spec.md §6.1) has no MVP use
+      // case in this package — every language it supports (TS/JS/TSX/JSX)
+      // is always extension-identified. `_contentSample` is accepted (per
+      // the domain port signature) but unused; a future adapter that needs
+      // it (e.g. a shebang-sniffed shell/Python script) implements the
+      // probe itself.
+      return null;
+    }
+    return this.adaptersByExtension.get(extension) ?? null;
+  }
+
+  supportLevelOf(languageId: string): SupportLevel | null {
+    return this.adaptersByLanguageId.get(languageId)?.supportLevel ?? null;
+  }
+}
+
+function extensionOf(path: string): string | null {
+  const normalized = path.replace(/\\/g, "/");
+  const lastSlash = normalized.lastIndexOf("/");
+  const fileName = lastSlash === -1 ? normalized : normalized.slice(lastSlash + 1);
+  const lastDot = fileName.lastIndexOf(".");
+  if (lastDot <= 0) return null; // no dot, or a dotfile like ".gitignore" (no extension)
+  return fileName.slice(lastDot).toLowerCase();
+}