@nimiplatform/nimi-coding 0.5.0 → 0.6.1

package/cli/lib/code/context.mjs

@@ -0,0 +1,710 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const TYPESCRIPT_VERSION = "5.9.3";
+
+export class CodeContextFailure extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "CodeContextFailure";
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new CodeContextFailure(code, message);
+}
+
+function pathWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function posixPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function cleanGitEnvironment() {
+  const environment = { ...process.env };
+  for (const key of Object.keys(environment)) {
+    if (key === "GIT_DIR" || key === "GIT_WORK_TREE" || key === "GIT_INDEX_FILE" || key.startsWith("GIT_CONFIG_")) {
+      delete environment[key];
+    }
+  }
+  return {
+    ...environment,
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_OPTIONAL_LOCKS: "0",
+    GIT_TERMINAL_PROMPT: "0",
+    LC_ALL: "C",
+  };
+}
+
+async function gitLine(repository, args) {
+  try {
+    const result = await execFileAsync("git", args, {
+      cwd: repository,
+      env: cleanGitEnvironment(),
+      encoding: "utf8",
+      maxBuffer: 64 * 1024,
+      windowsHide: true,
+    });
+    const text = result.stdout.endsWith("\n") ? result.stdout.slice(0, -1) : result.stdout;
+    if (text.length === 0 || text.includes("\n") || text.includes("\r")) throw new Error("Git returned no single line");
+    return text;
+  } catch {
+    fail("CODE_REPOSITORY_INVALID", "repository must be one exact readable Git worktree root");
+  }
+}
+
+async function resolveExactRepository(repositoryInput) {
+  const requested = path.resolve(process.cwd(), repositoryInput);
+  let info;
+  try {
+    info = await lstat(requested);
+  } catch {
+    fail("CODE_REPOSITORY_INVALID", "repository must be one exact readable Git worktree root");
+  }
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    fail("CODE_REPOSITORY_INVALID", "repository must be one exact readable Git worktree root");
+  }
+  const repository = await realpath(requested);
+  if (await gitLine(repository, ["rev-parse", "--is-inside-work-tree"]) !== "true") {
+    fail("CODE_REPOSITORY_INVALID", "repository must be one exact readable Git worktree root");
+  }
+  let top;
+  try {
+    top = await realpath(await gitLine(repository, ["rev-parse", "--path-format=absolute", "--show-toplevel"]));
+  } catch {
+    fail("CODE_REPOSITORY_INVALID", "repository must be one exact readable Git worktree root");
+  }
+  if (path.relative(repository, top) !== "") {
+    fail("CODE_REPOSITORY_INVALID", "repository must be one exact readable Git worktree root");
+  }
+  return repository;
+}
+
+async function resolveContainedFile(repository, input, kind) {
+  if (typeof input !== "string" || input.length === 0 || input.includes("\0") || path.isAbsolute(input)) {
+    fail("CODE_PATH_INVALID", `${kind} must be one contained repository-relative file`);
+  }
+  const requested = path.resolve(repository, input);
+  if (!pathWithin(repository, requested)) fail("CODE_PATH_INVALID", `${kind} must be one contained repository-relative file`);
+  let resolved;
+  let info;
+  try {
+    resolved = await realpath(requested);
+    info = await stat(resolved);
+  } catch {
+    fail("CODE_PATH_INVALID", `${kind} must be one contained repository-relative file`);
+  }
+  if (!pathWithin(repository, resolved) || !info.isFile()) {
+    fail("CODE_PATH_INVALID", `${kind} must be one contained repository-relative file`);
+  }
+  return { absolute: resolved, relative: posixPath(path.relative(repository, resolved)) };
+}
+
+async function nearestPackageManifest(repository, startDirectory) {
+  let current = startDirectory;
+  while (pathWithin(repository, current)) {
+    const manifest = path.join(current, "package.json");
+    try {
+      const resolved = await realpath(manifest);
+      if (!pathWithin(repository, resolved)) {
+        fail("CODE_TYPESCRIPT_UNSUPPORTED", "tsconfig owner package manifest must remain inside the repository");
+      }
+      if ((await stat(resolved)).isFile()) return resolved;
+    } catch (error) {
+      if (error instanceof CodeContextFailure) throw error;
+      // Continue to the next repository-contained parent.
+    }
+    if (current === repository) break;
+    current = path.dirname(current);
+  }
+  fail("CODE_TYPESCRIPT_UNSUPPORTED", "tsconfig owner has no repository-contained package manifest");
+}
+
+async function loadProjectTypeScript(repository, tsconfigPath) {
+  const manifest = await nearestPackageManifest(repository, path.dirname(tsconfigPath));
+  const requireFromOwner = createRequire(manifest);
+  let packagePath;
+  let compiler;
+  try {
+    packagePath = requireFromOwner.resolve("typescript/package.json");
+    compiler = requireFromOwner("typescript");
+  } catch {
+    fail("CODE_TYPESCRIPT_UNSUPPORTED", "tsconfig owner cannot resolve project-local TypeScript 5.9.3");
+  }
+  let packageManifest;
+  try {
+    packageManifest = JSON.parse(await readFile(packagePath, "utf8"));
+  } catch {
+    fail("CODE_TYPESCRIPT_UNSUPPORTED", "project-local TypeScript package metadata is unreadable");
+  }
+  if (packageManifest.version !== TYPESCRIPT_VERSION || compiler.version !== TYPESCRIPT_VERSION) {
+    fail("CODE_TYPESCRIPT_UNSUPPORTED", "project-local TypeScript version must be exactly 5.9.3");
+  }
+  for (const capability of ["readConfigFile", "parseJsonConfigFileContent", "createProgram", "isIdentifier"]) {
+    if (typeof compiler[capability] !== "function") {
+      fail("CODE_TYPESCRIPT_UNSUPPORTED", "project-local TypeScript lacks a required public capability");
+    }
+  }
+  return {
+    compiler,
+    compilerRoot: await realpath(path.dirname(packagePath)),
+    compilerVersion: TYPESCRIPT_VERSION,
+  };
+}
+
+function diagnosticHasError(compiler, diagnostics) {
+  return diagnostics.some((diagnostic) => diagnostic.category === compiler.DiagnosticCategory.Error);
+}
+
+function canonicalCompilerPath(compiler, value) {
+  const normalized = path.normalize(path.resolve(value));
+  return compiler.sys.useCaseSensitiveFileNames ? normalized : normalized.toLowerCase();
+}
+
+function sourceFileForPath(compiler, program, sourcePath) {
+  const direct = program.getSourceFile(sourcePath) ?? program.getSourceFile(compiler.sys.resolvePath(sourcePath));
+  if (direct !== undefined) return direct;
+  const expected = canonicalCompilerPath(compiler, sourcePath);
+  return program.getSourceFiles().find((sourceFile) => {
+    let candidate = sourceFile.fileName;
+    try {
+      candidate = compiler.sys.realpath?.(candidate) ?? candidate;
+    } catch {
+      // A compiler-resolved virtual path cannot prove membership in the requested real file.
+    }
+    return canonicalCompilerPath(compiler, candidate) === expected;
+  });
+}
+
+function createSelectedProgram(compiler, tsconfigPath, sourcePath) {
+  const config = compiler.readConfigFile(tsconfigPath, compiler.sys.readFile);
+  if (config.error !== undefined) fail("CODE_CONFIG_INVALID", "tsconfig could not be read with TypeScript 5.9.3");
+  const parsed = compiler.parseJsonConfigFileContent(
+    config.config,
+    compiler.sys,
+    path.dirname(tsconfigPath),
+    undefined,
+    tsconfigPath,
+  );
+  if (diagnosticHasError(compiler, parsed.errors)) {
+    fail("CODE_CONFIG_INVALID", "tsconfig could not produce one complete TypeScript Program");
+  }
+  if ((parsed.projectReferences?.length ?? 0) > 0) {
+    fail("CODE_PROJECT_REFERENCES_UNSUPPORTED", "TypeScript project references are not supported by code context v1");
+  }
+  let program;
+  try {
+    program = compiler.createProgram({ rootNames: parsed.fileNames, options: parsed.options });
+  } catch {
+    fail("CODE_CONFIG_INVALID", "tsconfig could not produce one complete TypeScript Program");
+  }
+  const sourceFile = sourceFileForPath(compiler, program, sourcePath);
+  if (sourceFile === undefined) fail("CODE_SOURCE_NOT_IN_PROGRAM", "source is not a member of the selected TypeScript Program");
+  if (sourceFile.isDeclarationFile || !/[.]tsx?$/u.test(sourceFile.fileName) || /[.]d[.]ts$/u.test(sourceFile.fileName)) {
+    fail("CODE_SOURCE_UNSUPPORTED", "root source must be one non-declaration .ts or .tsx file");
+  }
+  return { program, sourceFile, checker: program.getTypeChecker() };
+}
+
+function admittedRoot(compiler, statement, symbolName) {
+  if (
+    (compiler.isFunctionDeclaration(statement)
+      || compiler.isClassDeclaration(statement)
+      || compiler.isInterfaceDeclaration(statement)
+      || compiler.isTypeAliasDeclaration(statement))
+    && statement.name !== undefined
+    && compiler.isIdentifier(statement.name)
+    && statement.name.text === symbolName
+  ) {
+    return { declaration: statement, sourceNode: statement, name: statement.name };
+  }
+  if (!compiler.isVariableStatement(statement) || statement.declarationList.declarations.length !== 1) return null;
+  const declaration = statement.declarationList.declarations[0];
+  if (!compiler.isIdentifier(declaration.name) || declaration.name.text !== symbolName) return null;
+  return { declaration, sourceNode: statement, name: declaration.name };
+}
+
+function rootKind(compiler, declaration) {
+  if (compiler.isFunctionDeclaration(declaration)) return "function";
+  if (compiler.isClassDeclaration(declaration)) return "class";
+  if (compiler.isInterfaceDeclaration(declaration)) return "interface";
+  if (compiler.isTypeAliasDeclaration(declaration)) return "type_alias";
+  return "variable";
+}
+
+function selectRoot(compiler, checker, sourceFile, symbolName) {
+  const matches = sourceFile.statements
+    .map((statement) => admittedRoot(compiler, statement, symbolName))
+    .filter((entry) => entry !== null);
+  if (matches.length !== 1) fail("CODE_SYMBOL_NOT_FOUND", "symbol must match one supported top-level declaration");
+  const selected = matches[0];
+  const symbol = checker.getSymbolAtLocation(selected.name);
+  const declarations = symbol?.getDeclarations?.() ?? symbol?.declarations;
+  if (symbol === undefined || declarations === undefined || declarations.length !== 1 || declarations[0] !== selected.declaration) {
+    fail("CODE_SYMBOL_UNSUPPORTED", "root symbol must have one unmerged supported declaration");
+  }
+  return { ...selected, symbol, kind: rootKind(compiler, selected.declaration) };
+}
+
+function nodeRange(compiler, sourceFile, node) {
+  const start = node.getStart(sourceFile, false);
+  const end = node.getEnd();
+  const startPosition = sourceFile.getLineAndCharacterOfPosition(start);
+  const endPosition = sourceFile.getLineAndCharacterOfPosition(end);
+  return {
+    start,
+    end,
+    portable: {
+      start_line: startPosition.line + 1,
+      start_column: startPosition.character + 1,
+      end_line: endPosition.line + 1,
+      end_column: endPosition.character + 1,
+    },
+  };
+}
+
+function owningDependencyPackage(filePath) {
+  let current = path.dirname(filePath);
+  while (true) {
+    const manifestPath = path.join(current, "package.json");
+    if (existsSync(manifestPath)) {
+      try {
+        if (statSync(manifestPath).isFile()) {
+          const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+          if (typeof manifest.name === "string" && manifest.name.length > 0) {
+            return {
+              root: realpathSync(current),
+              name: manifest.name,
+              version: typeof manifest.version === "string" ? manifest.version : null,
+            };
+          }
+        }
+      } catch {
+        return null;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function sourceIdentity(repository, compilerRoot, compilerVersion, sourceFile) {
+  let filePath;
+  try {
+    filePath = realpathSync(sourceFile.fileName);
+  } catch {
+    return null;
+  }
+  if (pathWithin(compilerRoot, filePath)) {
+    return {
+      origin: "typescript_lib",
+      path: posixPath(path.relative(compilerRoot, filePath)),
+      package: { name: "typescript", version: compilerVersion },
+    };
+  }
+  const repositoryRelative = path.relative(repository, filePath);
+  const repositorySegments = repositoryRelative.split(path.sep);
+  if (pathWithin(repository, filePath) && !repositorySegments.includes("node_modules")) {
+    return { origin: "repository", path: posixPath(repositoryRelative), package: null };
+  }
+  const dependency = owningDependencyPackage(filePath);
+  if (dependency === null || !pathWithin(dependency.root, filePath)) return null;
+  return {
+    origin: "dependency",
+    path: posixPath(path.relative(dependency.root, filePath)),
+    package: { name: dependency.name, version: dependency.version },
+  };
+}
+
+function portableLocus(compiler, repository, compilerRoot, compilerVersion, node) {
+  const sourceFile = node.getSourceFile?.();
+  if (sourceFile === undefined) return null;
+  const identity = sourceIdentity(repository, compilerRoot, compilerVersion, sourceFile);
+  if (identity === null) return null;
+  try {
+    return { ...identity, range: nodeRange(compiler, sourceFile, node).portable };
+  } catch {
+    return null;
+  }
+}
+
+function compareLoci(left, right) {
+  return left.origin.localeCompare(right.origin)
+    || (left.package?.name ?? "").localeCompare(right.package?.name ?? "")
+    || (left.package?.version ?? "").localeCompare(right.package?.version ?? "")
+    || left.path.localeCompare(right.path)
+    || left.range.start_line - right.range.start_line
+    || left.range.start_column - right.range.start_column
+    || left.range.end_line - right.range.end_line
+    || left.range.end_column - right.range.end_column;
+}
+
+function symbolKind(compiler, symbol) {
+  const flags = symbol.flags;
+  for (const [flag, label] of [
+    [compiler.SymbolFlags.Class, "class"],
+    [compiler.SymbolFlags.Interface, "interface"],
+    [compiler.SymbolFlags.TypeAlias, "type_alias"],
+    [compiler.SymbolFlags.Enum, "enum"],
+    [compiler.SymbolFlags.Function, "function"],
+    [compiler.SymbolFlags.Method, "method"],
+    [compiler.SymbolFlags.Property, "property"],
+    [compiler.SymbolFlags.Variable, "variable"],
+    [compiler.SymbolFlags.Module, "module"],
+    [compiler.SymbolFlags.TypeParameter, "type_parameter"],
+  ]) {
+    if ((flags & flag) !== 0) return label;
+  }
+  return "other";
+}
+
+function terminalJsxName(compiler, tagName) {
+  if (compiler.isIdentifier(tagName)) return tagName;
+  if (compiler.isPropertyAccessExpression(tagName)) return tagName.name;
+  if (compiler.isJsxNamespacedName?.(tagName)) return tagName.name;
+  return null;
+}
+
+function jsxTagForNode(compiler, node) {
+  let current = node;
+  let parent = node.parent;
+  while (parent !== undefined && (compiler.isPropertyAccessExpression(parent) || compiler.isJsxNamespacedName?.(parent))) {
+    current = parent;
+    parent = parent.parent;
+  }
+  if (
+    parent !== undefined
+    && (compiler.isJsxOpeningElement(parent) || compiler.isJsxClosingElement(parent) || compiler.isJsxSelfClosingElement(parent))
+    && parent.tagName === current
+  ) {
+    return parent.tagName;
+  }
+  return null;
+}
+
+function isLiteralModuleSite(compiler, node) {
+  if (!compiler.isStringLiteral(node)) return false;
+  const parent = node.parent;
+  if (
+    compiler.isCallExpression(parent)
+    && parent.expression.kind === compiler.SyntaxKind.ImportKeyword
+    && parent.arguments[0] === node
+  ) return true;
+  return compiler.isLiteralTypeNode(parent)
+    && parent.literal === node
+    && compiler.isImportTypeNode(parent.parent)
+    && parent.parent.argument === parent;
+}
+
+function siteRole(compiler, node) {
+  if (isLiteralModuleSite(compiler, node)) return "module";
+  if (!compiler.isIdentifier(node)) return null;
+  const tagName = jsxTagForNode(compiler, node);
+  if (tagName !== null) return terminalJsxName(compiler, tagName) === node ? "jsx" : null;
+  const parent = node.parent;
+  if (compiler.isPropertyAccessExpression(parent) && parent.name === node) return "member";
+  if (compiler.isQualifiedName(parent) && parent.right === node) return "member";
+  if (compiler.isShorthandPropertyAssignment(parent) && parent.name === node) return "identifier";
+  if (parent?.name === node || parent?.propertyName === node || parent?.label === node) return null;
+  return "identifier";
+}
+
+function collectSites(compiler, rootNode) {
+  const sites = [];
+  const seen = new Set();
+  function visit(node) {
+    const role = siteRole(compiler, node);
+    if (role !== null) {
+      const key = `${node.pos}:${node.end}:${role}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        sites.push({ node, role });
+      }
+    }
+    compiler.forEachChild(node, visit);
+  }
+  compiler.forEachChild(rootNode, visit);
+  return sites.sort((left, right) => (
+    left.node.getStart() - right.node.getStart()
+    || left.node.getEnd() - right.node.getEnd()
+    || left.role.localeCompare(right.role)
+  ));
+}
+
+function isTypePosition(compiler, node, rootNode) {
+  let current = node;
+  while (current !== rootNode && current.parent !== undefined) {
+    current = current.parent;
+    if (compiler.isTypeNode(current)) return true;
+    if (compiler.isExpression(current) && current !== node) return false;
+  }
+  return false;
+}
+
+function isDirectCalleeTerminal(compiler, node, expression) {
+  if (expression === node) return true;
+  if (compiler.isPropertyAccessExpression(expression)) return expression.name === node;
+  return false;
+}
+
+function bindingKind(compiler, site, rootNode) {
+  if (site.role === "jsx") return "resolved_jsx_binding";
+  let ancestor = site.node;
+  while (ancestor.parent !== undefined && (compiler.isPropertyAccessExpression(ancestor.parent) || compiler.isElementAccessExpression(ancestor.parent))) {
+    ancestor = ancestor.parent;
+  }
+  if (
+    compiler.isNewExpression(ancestor.parent)
+    && ancestor.parent.expression === ancestor
+    && isDirectCalleeTerminal(compiler, site.node, ancestor)
+  ) return "resolved_constructor_binding";
+  if (
+    (site.role === "module" && compiler.isLiteralTypeNode(site.node.parent))
+    || isTypePosition(compiler, site.node, rootNode)
+  ) return "resolved_type_binding";
+  return "resolved_value_binding";
+}
+
+function moduleSpecifierForAlias(compiler, declaration) {
+  let current = declaration;
+  while (current !== undefined) {
+    if (compiler.isImportDeclaration(current) || compiler.isExportDeclaration(current)) {
+      return compiler.isStringLiteral(current.moduleSpecifier) ? current.moduleSpecifier.text : null;
+    }
+    if (compiler.isImportEqualsDeclaration(current)) {
+      const reference = current.moduleReference;
+      return compiler.isExternalModuleReference(reference) && compiler.isStringLiteral(reference.expression)
+        ? reference.expression.text
+        : null;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
+function aliasNames(compiler, declaration) {
+  if (compiler.isImportSpecifier(declaration) || compiler.isExportSpecifier(declaration)) {
+    return {
+      imported_name: (declaration.propertyName ?? declaration.name).text,
+      local_name: declaration.name.text,
+    };
+  }
+  if (compiler.isImportClause(declaration) && declaration.name !== undefined) {
+    return { imported_name: "default", local_name: declaration.name.text };
+  }
+  if (compiler.isNamespaceImport(declaration)) return { imported_name: "*", local_name: declaration.name.text };
+  if (compiler.isImportEqualsDeclaration(declaration)) return { imported_name: "export=", local_name: declaration.name.text };
+  return { imported_name: null, local_name: declaration.name?.text ?? null };
+}
+
+function declarationSet(symbol) {
+  const declarations = symbol.getDeclarations?.() ?? symbol.declarations;
+  return Array.isArray(declarations) && declarations.length > 0 ? declarations : null;
+}
+
+function declarationsAreRootLocal(declarations, sourceFile, rootStart, rootEnd) {
+  return declarations.every((declaration) => {
+    if (declaration.getSourceFile() !== sourceFile) return false;
+    const start = declaration.getStart(sourceFile, false);
+    const end = declaration.getEnd();
+    return start >= rootStart && end <= rootEnd;
+  });
+}
+
+function resolveSiteSymbol(compiler, checker, site) {
+  if (compiler.isShorthandPropertyAssignment(site.node.parent)) {
+    return checker.getShorthandAssignmentValueSymbol(site.node.parent);
+  }
+  return checker.getSymbolAtLocation(site.node);
+}
+
+function aliasChain({ compiler, checker, repository, compilerRoot, compilerVersion, initial }) {
+  const steps = [];
+  const visited = new Set();
+  let symbol = initial;
+  while ((symbol.flags & compiler.SymbolFlags.Alias) !== 0) {
+    if (visited.has(symbol)) return { ok: false };
+    visited.add(symbol);
+    const declarations = declarationSet(symbol);
+    if (declarations === null || declarations.length !== 1) return { ok: false };
+    const declaration = declarations[0];
+    const locus = portableLocus(compiler, repository, compilerRoot, compilerVersion, declaration);
+    const moduleSpecifier = moduleSpecifierForAlias(compiler, declaration);
+    if (locus === null || moduleSpecifier === null) return { ok: false };
+    const next = checker.getImmediateAliasedSymbol(symbol);
+    if (next === undefined) return { ok: false };
+    steps.push({ locus, module_specifier: moduleSpecifier, ...aliasNames(compiler, declaration) });
+    symbol = next;
+  }
+  return { ok: true, symbol, steps };
+}
+
+function targetDescriptor({ compiler, checker, repository, compilerRoot, compilerVersion, symbol }) {
+  const exactSymbol = checker.getMergedSymbol(symbol);
+  const declarations = declarationSet(exactSymbol);
+  if (declarations === null) return { ok: false, reason: "portable_target_unavailable" };
+  const loci = declarations.map((declaration) => (
+    portableLocus(compiler, repository, compilerRoot, compilerVersion, declaration)
+  ));
+  if (loci.some((locus) => locus === null)) return { ok: false, reason: "portable_target_unavailable" };
+  return {
+    ok: true,
+    symbol: exactSymbol,
+    declarations,
+    descriptor: {
+      id: null,
+      name: exactSymbol.getName(),
+      kind: symbolKind(compiler, exactSymbol),
+      declaration_loci: loci.sort(compareLoci),
+    },
+  };
+}
+
+function sourceNodeForDeclaration(compiler, declaration) {
+  if (compiler.isSourceFile(declaration)) return null;
+  if (!compiler.isVariableDeclaration(declaration)) return declaration;
+  const declarationList = declaration.parent;
+  const statement = declarationList?.parent;
+  if (
+    !compiler.isVariableDeclarationList(declarationList)
+    || declarationList.declarations.length !== 1
+    || !compiler.isVariableStatement(statement)
+  ) return null;
+  return statement;
+}
+
+function sourceUnitForTarget(compiler, repository, compilerRoot, compilerVersion, targetId, declarations, rootSourceFile, rootStart, rootEnd) {
+  if (declarations.length !== 1) return null;
+  const declaration = declarations[0];
+  if (declaration.getSourceFile() === rootSourceFile) {
+    const start = declaration.getStart(rootSourceFile, false);
+    const end = declaration.getEnd();
+    if (start >= rootStart && end <= rootEnd) return null;
+  }
+  const sourceNode = sourceNodeForDeclaration(compiler, declaration);
+  if (sourceNode === null) return null;
+  const locus = portableLocus(compiler, repository, compilerRoot, compilerVersion, sourceNode);
+  if (locus?.origin !== "repository") return null;
+  const sourceFile = sourceNode.getSourceFile();
+  const range = nodeRange(compiler, sourceFile, sourceNode);
+  return { target_id: targetId, locus, source: sourceFile.text.slice(range.start, range.end) };
+}
+
+function projectRoot({ compiler, compilerRoot, compilerVersion, repository, sourceFile, checker, root }) {
+  const rootRange = nodeRange(compiler, sourceFile, root.sourceNode);
+  const rootLocus = portableLocus(compiler, repository, compilerRoot, compilerVersion, root.sourceNode);
+  if (rootLocus === null || rootLocus.origin !== "repository") {
+    fail("CODE_SOURCE_UNSUPPORTED", "root source could not produce one portable repository locus");
+  }
+  const targets = [];
+  const semanticItems = [];
+  const sourceUnits = [];
+  const targetBySymbol = new Map();
+
+  for (const site of collectSites(compiler, root.declaration)) {
+    const siteLocus = portableLocus(compiler, repository, compilerRoot, compilerVersion, site.node);
+    if (siteLocus === null || siteLocus.origin !== "repository") {
+      semanticItems.push({ kind: "unresolved", site: rootLocus, reason: "compiler_resolution_failed" });
+      continue;
+    }
+    const initial = resolveSiteSymbol(compiler, checker, site);
+    if (initial === undefined) {
+      semanticItems.push({ kind: "unresolved", site: siteLocus, reason: "compiler_resolution_failed" });
+      continue;
+    }
+    const chain = aliasChain({ compiler, checker, repository, compilerRoot, compilerVersion, initial });
+    if (!chain.ok) {
+      semanticItems.push({ kind: "unresolved", site: siteLocus, reason: "alias_resolution_not_unique" });
+      continue;
+    }
+    const target = targetDescriptor({
+      compiler,
+      checker,
+      repository,
+      compilerRoot,
+      compilerVersion,
+      symbol: chain.symbol,
+    });
+    if (!target.ok) {
+      semanticItems.push({ kind: "unresolved", site: siteLocus, reason: target.reason });
+      continue;
+    }
+    if (declarationsAreRootLocal(target.declarations, sourceFile, rootRange.start, rootRange.end)) continue;
+    let descriptor = targetBySymbol.get(target.symbol);
+    if (descriptor === undefined) {
+      descriptor = { ...target.descriptor, id: `t${targets.length + 1}` };
+      targetBySymbol.set(target.symbol, descriptor);
+      targets.push(descriptor);
+      const sourceUnit = sourceUnitForTarget(
+        compiler,
+        repository,
+        compilerRoot,
+        compilerVersion,
+        descriptor.id,
+        target.declarations,
+        sourceFile,
+        rootRange.start,
+        rootRange.end,
+      );
+      if (sourceUnit !== null) sourceUnits.push(sourceUnit);
+    }
+    semanticItems.push({
+      kind: bindingKind(compiler, site, root.declaration),
+      site: siteLocus,
+      alias_steps: chain.steps,
+      target_id: descriptor.id,
+    });
+  }
+
+  return {
+    root: {
+      symbol: root.symbol.getName(),
+      kind: root.kind,
+      locus: rootLocus,
+      source: sourceFile.text.slice(rootRange.start, rootRange.end),
+    },
+    targets,
+    semanticItems,
+    sourceUnits,
+  };
+}
+
+export async function contextForTypeScript({ repository: repositoryInput, source: sourceInput, symbol, tsconfig: tsconfigInput }) {
+  const repository = await resolveExactRepository(repositoryInput);
+  const source = await resolveContainedFile(repository, sourceInput, "source");
+  const tsconfig = await resolveContainedFile(repository, tsconfigInput, "tsconfig");
+  if (!/[.]tsx?$/u.test(source.relative) || /[.]d[.]ts$/u.test(source.relative)) {
+    fail("CODE_SOURCE_UNSUPPORTED", "root source must be one non-declaration .ts or .tsx file");
+  }
+  const { compiler, compilerRoot, compilerVersion } = await loadProjectTypeScript(repository, tsconfig.absolute);
+  const { sourceFile, checker } = createSelectedProgram(compiler, tsconfig.absolute, source.absolute);
+  const root = selectRoot(compiler, checker, sourceFile, symbol);
+  const projection = projectRoot({
+    compiler,
+    compilerRoot,
+    compilerVersion,
+    repository,
+    sourceFile,
+    checker,
+    root,
+  });
+  return {
+    scope: {
+      source_path: source.relative,
+      symbol,
+      tsconfig_path: tsconfig.relative,
+      typescript_version: compilerVersion,
+    },
+    projection,
+  };
+}