@beignet/cli 0.0.49 → 0.0.51

package/src/app-map-changes.ts

@@ -0,0 +1,1462 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import {
+  type LocalImportReference,
+  localImportReferences,
+} from "./analysis/source-index.js";
+import {
+  createAnalysisWorkspace,
+  listProjectFiles,
+  resolveLocalModulePath,
+} from "./analysis/workspace.js";
+import {
+  type AppMapEdge,
+  type AppMapEdgeKind,
+  type AppMapNode,
+  type AppMapNodeKind,
+  mapApp,
+} from "./app-map.js";
+import {
+  type GitChangeComparison,
+  type GitChangedFile,
+  type GitChangedFileStatus,
+  hashGitChanges,
+  readGitChangeSet,
+} from "./git-changes.js";
+
+const changedFileLimit = 200;
+const impactedNodeLimit = 250;
+const relationshipLimit = 400;
+const gapLimit = 100;
+const reasonLimitPerNode = 3;
+
+const edgeImpactBehavior = {
+  owns: "context",
+  binds: "consumer",
+  executes: "consumer",
+  authorizes: "consumer",
+  emits: "consumer",
+  dispatches: "consumer",
+  sends: "consumer",
+  publishes: "consumer",
+  provides: "consumer",
+  registers: "consumer",
+  "listens-to": "consumer",
+  exposes: "consumer",
+  "depends-on": "consumer",
+  "contains-test": "context",
+} as const satisfies Record<AppMapEdgeKind, "consumer" | "context">;
+
+const containerExpansionKinds = {
+  feature: new Set<AppMapEdgeKind>(["owns"]),
+  entrypoint: new Set<AppMapEdgeKind>(["exposes", "registers"]),
+  openapi: new Set<AppMapEdgeKind>(["exposes"]),
+  registry: new Set<AppMapEdgeKind>(["registers"]),
+  "route-group": new Set<AppMapEdgeKind>(["registers"]),
+} as const satisfies Partial<
+  Record<AppMapNodeKind, ReadonlySet<AppMapEdgeKind>>
+>;
+
+/** Relationship between one changed repository file and the selected app. */
+export type AppChangeFileScope =
+  | "app"
+  | "governing"
+  | "outside"
+  | "workspace-dependency";
+
+/** One Git change classified relative to the selected Beignet app. */
+export type AppChangedFile = {
+  status: GitChangedFileStatus;
+  path: string;
+  oldPath?: string;
+  scope: AppChangeFileScope;
+};
+
+/** Why one mapped concept appears in a changed-app report. */
+export type AppChangeImpact =
+  | "app-wide"
+  | "consumer"
+  | "context"
+  | "direct"
+  | "related";
+
+/** Source-backed reason connecting a Git change to one mapped concept. */
+export type AppChangeReason = {
+  kind: "app-wide" | "import" | "ownership" | "relationship" | "source";
+  changedFile: string;
+  message: string;
+  evidence?: {
+    file: string;
+    line?: number;
+    column?: number;
+    confidence: "exact" | "partial";
+  };
+  relationship?: {
+    kind: AppMapEdgeKind;
+    from: string;
+    to: string;
+  };
+};
+
+/** App-map node annotated with its strongest change-impact classification. */
+export type AppChangeImpactedNode = AppMapNode & {
+  impact: AppChangeImpact;
+  reasons: AppChangeReason[];
+  reasonCount: number;
+  reasonsTruncated: boolean;
+};
+
+/** App-map edge used as semantic change-impact evidence. */
+export type AppChangeRelationship = AppMapEdge & {
+  impact: "consumer" | "related";
+};
+
+/** Static-analysis blind spot retained in a changed-app report. */
+export type AppChangeGap = {
+  code: string;
+  message: string;
+  /** Repository-relative file associated with this gap. */
+  file?: string;
+};
+
+/** Deterministically bounded report section with complete item counts. */
+export type BoundedAppChangeSection<T> = {
+  items: T[];
+  returned: number;
+  total: number;
+  truncated: boolean;
+};
+
+/** Bounded gap examples plus exhaustive counts for every gap code. */
+export type BoundedAppChangeGapSection =
+  BoundedAppChangeSection<AppChangeGap> & {
+    countsByCode: Record<string, number>;
+  };
+
+/** Version 1 report mapping a Git change set to Beignet application concepts. */
+export type AppChangeImpactResult = {
+  schemaVersion: 1;
+  targetDir: string;
+  repository: {
+    root: string;
+    workspaceRoot?: string;
+    comparison: GitChangeComparison;
+    repositoryChangeHash: string;
+    scopedChangeHash: string;
+  };
+  classification: {
+    appWide: boolean;
+    docsOnly: boolean;
+  };
+  summary: {
+    changedFiles: number;
+    scopedChangedFiles: number;
+    outsideChangedFiles: number;
+    impactedFeatures: number;
+    impactedNodes: number;
+    direct: number;
+    consumers: number;
+    related: number;
+    contexts: number;
+    appWide: number;
+    relationships: number;
+    gaps: number;
+  };
+  changedFiles: BoundedAppChangeSection<AppChangedFile>;
+  impactedNodes: BoundedAppChangeSection<AppChangeImpactedNode>;
+  relationships: BoundedAppChangeSection<AppChangeRelationship>;
+  gaps: BoundedAppChangeGapSection;
+};
+
+/** Options for mapping the current Git change set. */
+export type AppMapChangesOptions = {
+  cwd?: string;
+  base?: string;
+};
+
+type PackageJson = {
+  name?: string;
+  workspaces?: string[] | { packages?: string[] };
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+};
+
+type WorkspaceScope = {
+  workspaceRoot?: string;
+  dependencyDirectories: Set<string>;
+  gaps: AppChangeGap[];
+};
+
+type ImpactRecord = {
+  node: AppMapNode;
+  impact: AppChangeImpact;
+  reasons: AppChangeReason[];
+};
+
+/** Map the current Git change set to bounded, source-backed Beignet concepts. */
+export async function mapAppChanges(
+  options: AppMapChangesOptions = {},
+): Promise<AppChangeImpactResult> {
+  const targetDir = path.resolve(options.cwd ?? process.cwd());
+  const git = await readGitChangeSet({ cwd: targetDir, base: options.base });
+  const canonicalTargetDir = await realpath(targetDir);
+  assertInsideRepository(canonicalTargetDir, git.repositoryRoot);
+  const appRepositoryPrefix = normalizePath(
+    path.relative(git.repositoryRoot, canonicalTargetDir),
+  );
+
+  const [appMap, workspace, workspaceScope] = await Promise.all([
+    mapApp({ cwd: targetDir, strict: true }),
+    createAnalysisWorkspace(targetDir),
+    resolveWorkspaceScope(git.repositoryRoot, canonicalTargetDir),
+  ]);
+  const governingFiles = new Set(
+    workspace.compilerConfigFiles
+      .map((file) =>
+        path.resolve(
+          canonicalTargetDir,
+          path.relative(workspace.targetDir, file),
+        ),
+      )
+      .filter((file) => isAbsoluteWithin(file, git.repositoryRoot))
+      .map((file) => normalizePath(path.relative(git.repositoryRoot, file))),
+  );
+  const changedFiles = classifyChangedFiles({
+    files: git.files,
+    governingFiles,
+    repositoryRoot: git.repositoryRoot,
+    targetDir: canonicalTargetDir,
+    workspaceScope,
+  });
+  const documentationRoots = [
+    normalizePath(path.relative(git.repositoryRoot, canonicalTargetDir)),
+    ...workspaceScope.dependencyDirectories,
+  ];
+  const isDocumentationChangePath = (file: string): boolean =>
+    isDocumentationPath(file, documentationRoots);
+  const scopedFiles = changedFiles.filter((file) => file.scope !== "outside");
+  const appWideFiles = scopedFiles.filter(
+    (file) =>
+      (file.scope === "governing" || file.scope === "workspace-dependency") &&
+      !changedFilePaths(file).every(isDocumentationChangePath),
+  );
+  const docsOnly =
+    scopedFiles.length > 0 &&
+    scopedFiles.every((file) =>
+      changedFilePaths(file).every(isDocumentationChangePath),
+    );
+  const appWide = appWideFiles.length > 0 && !docsOnly;
+  const impacts = new Map<string, ImpactRecord>();
+  const relationships: AppChangeRelationship[] = [];
+  const workspaceRelationshipRelevant =
+    changedFiles.some((file) => file.scope === "outside") ||
+    changedFiles.some(
+      (file) =>
+        file.scope === "governing" &&
+        path.posix.basename(file.path) === "package.json",
+    );
+  const gaps = workspaceScope.gaps.filter(isAppDependencyGap);
+  if (workspaceRelationshipRelevant) {
+    gaps.push(...workspaceScope.gaps.filter((gap) => !isAppDependencyGap(gap)));
+  }
+  const nodesById = new Map(appMap.nodes.map((node) => [node.id, node]));
+  const nodesByFile = groupNodesByFile(appMap.nodes);
+  const directNodeIds = new Set<string>();
+
+  if (appWide) {
+    const reasons = appWideChangeReasons(
+      appWideFiles,
+      isDocumentationChangePath,
+    );
+    for (const node of appMap.nodes) {
+      for (const reason of reasons) {
+        addImpact(impacts, node, "app-wide", reason);
+      }
+    }
+  }
+
+  const appSourceChanges = appRelativeSourceChanges(
+    changedFiles,
+    git.repositoryRoot,
+    canonicalTargetDir,
+  );
+  for (const change of appSourceChanges) {
+    const directNodes = nodesByFile.get(change.file) ?? [];
+    for (const node of directNodes) {
+      directNodeIds.add(node.id);
+      addImpact(impacts, node, "direct", {
+        kind: "source",
+        changedFile: change.repositoryPath,
+        message: `Source ${change.repositoryPath} changed directly.`,
+        evidence: {
+          file: node.source.file,
+          ...(node.source.line ? { line: node.source.line } : {}),
+          ...(node.source.column ? { column: node.source.column } : {}),
+          confidence: "exact",
+        },
+      });
+    }
+  }
+
+  await addImportConsumers({
+    workspace,
+    changes: appSourceChanges,
+    nodesByFile,
+    impacts,
+  });
+  addSemanticConsumers({
+    directNodeIds,
+    appMapEdges: appMap.edges,
+    nodesById,
+    impacts,
+    relationships,
+  });
+  addFeatureContext({
+    changes: appSourceChanges,
+    appMapEdges: appMap.edges,
+    nodes: appMap.nodes,
+    nodesById,
+    impacts,
+  });
+
+  addUnmappedChangeGaps({
+    changes: appSourceChanges,
+    impacts,
+    gaps,
+  });
+  addAppMapGaps(
+    appMap.unresolved,
+    appSourceChanges,
+    impacts,
+    gaps,
+    appRepositoryPrefix,
+  );
+  for (const file of changedFiles) {
+    if (file.status === "unmerged" || file.status === "unknown") {
+      gaps.push({
+        code: "git_change_status_unresolved",
+        file: file.path,
+        message: `Git reported ${file.status} status for ${file.path}; Beignet cannot classify its impact completely.`,
+      });
+    }
+  }
+
+  const sortedFiles = [...changedFiles].sort(compareAppChangedFiles);
+  const sortedImpacts = finalizeImpacts(impacts);
+  const sortedRelationships =
+    dedupeRelationships(relationships).sort(compareRelationships);
+  const sortedGaps = dedupeGaps(gaps).sort(compareGaps);
+  const impactedFeatures = new Set(
+    sortedImpacts
+      .map(
+        (item) =>
+          item.feature ?? (item.kind === "feature" ? item.name : undefined),
+      )
+      .filter((feature): feature is string => Boolean(feature)),
+  );
+  const repositoryChangeHash = await hashGitChanges(git);
+  const scopedRawFiles = git.files.filter((file) =>
+    scopedFiles.some(
+      (scoped) => scoped.path === file.path && scoped.oldPath === file.oldPath,
+    ),
+  );
+  const scopedChangeHash = await hashGitChanges(git, scopedRawFiles);
+
+  return {
+    schemaVersion: 1,
+    targetDir,
+    repository: {
+      root: git.repositoryRoot,
+      ...(workspaceScope.workspaceRoot
+        ? { workspaceRoot: workspaceScope.workspaceRoot }
+        : {}),
+      comparison: git.comparison,
+      repositoryChangeHash,
+      scopedChangeHash,
+    },
+    classification: { appWide, docsOnly },
+    summary: {
+      changedFiles: sortedFiles.length,
+      scopedChangedFiles: scopedFiles.length,
+      outsideChangedFiles: sortedFiles.length - scopedFiles.length,
+      impactedFeatures: impactedFeatures.size,
+      impactedNodes: sortedImpacts.length,
+      direct: countImpact(sortedImpacts, "direct"),
+      consumers: countImpact(sortedImpacts, "consumer"),
+      related: countImpact(sortedImpacts, "related"),
+      contexts: countImpact(sortedImpacts, "context"),
+      appWide: countImpact(sortedImpacts, "app-wide"),
+      relationships: sortedRelationships.length,
+      gaps: sortedGaps.length,
+    },
+    changedFiles: bounded(sortedFiles, changedFileLimit),
+    impactedNodes: bounded(sortedImpacts, impactedNodeLimit),
+    relationships: bounded(sortedRelationships, relationshipLimit),
+    gaps: boundedGaps(sortedGaps),
+  };
+}
+
+/** Format the report-only changed app map for a terminal. */
+export function formatAppChangeImpact(result: AppChangeImpactResult): string {
+  const comparison =
+    result.repository.comparison.mode === "base"
+      ? `${terminalText(result.repository.comparison.base)} at ${shortId(result.repository.comparison.baseCommit)} (merge base ${shortId(result.repository.comparison.mergeBase)}) → HEAD/index/worktree`
+      : result.repository.comparison.head
+        ? `HEAD at ${shortId(result.repository.comparison.head)} → index/worktree`
+        : "empty Git tree → index/worktree";
+  const lines = [
+    `Beignet change map for ${terminalText(result.targetDir)}`,
+    `Comparison: ${comparison}`,
+    `Changes: ${result.summary.scopedChangedFiles} scoped, ${result.summary.outsideChangedFiles} outside app`,
+    `Impact: ${result.summary.direct} direct, ${result.summary.consumers} consumers, ${result.summary.related} related, ${result.summary.contexts} context, ${result.summary.appWide} app-wide`,
+  ];
+
+  if (result.classification.appWide) lines.push("Scope: app-wide");
+  if (result.classification.docsOnly) lines.push("Scope: documentation only");
+
+  const scopedChanges = result.changedFiles.items.filter(
+    (file) => file.scope !== "outside",
+  );
+  lines.push("", "Changed files");
+  if (scopedChanges.length === 0) {
+    lines.push("  No scoped changes found.");
+  } else {
+    for (const file of scopedChanges.slice(0, 30)) {
+      const rename = file.oldPath ? `${terminalText(file.oldPath)} → ` : "";
+      lines.push(
+        `  ${statusMark(file.status)}  ${rename}${terminalText(file.path)} (${file.scope})`,
+      );
+    }
+    if (
+      scopedChanges.length > 30 ||
+      result.summary.scopedChangedFiles > scopedChanges.length
+    ) {
+      lines.push(
+        `  … showing ${Math.min(scopedChanges.length, 30)} of ${result.summary.scopedChangedFiles} scoped changes`,
+      );
+    }
+  }
+
+  lines.push("", "Potential impact");
+  if (result.impactedNodes.items.length === 0) {
+    lines.push(
+      "  No mapped application concepts were connected to this change set.",
+    );
+  } else {
+    for (const item of result.impactedNodes.items.slice(0, 30)) {
+      lines.push(
+        `  ${item.kind.padEnd(18)} ${terminalText(item.id)} [${item.impact}]`,
+      );
+      const reason = item.reasons[0];
+      if (reason) lines.push(`    ${terminalText(reason.message)}`);
+    }
+    if (result.impactedNodes.total > 30) {
+      lines.push(
+        `  … showing 30 of ${result.impactedNodes.total} impacted concepts`,
+      );
+    }
+  }
+
+  lines.push("", "Unresolved evidence");
+  if (result.gaps.total === 0) {
+    lines.push("  None");
+  } else {
+    for (const gap of result.gaps.items.slice(0, 20)) {
+      lines.push(
+        `  ${gap.code}${gap.file ? ` (${terminalText(gap.file)})` : ""}`,
+      );
+      lines.push(`    ${terminalText(gap.message)}`);
+    }
+    if (result.gaps.total > 20) {
+      lines.push(`  … showing 20 of ${result.gaps.total} gaps`);
+    }
+  }
+
+  lines.push(
+    "",
+    `Scoped hash: ${shortHash(result.repository.scopedChangeHash)}`,
+    "Run beignet map --changed --json for the bounded source-backed report.",
+  );
+  return lines.join("\n");
+}
+
+async function resolveWorkspaceScope(
+  repositoryRoot: string,
+  targetDir: string,
+): Promise<WorkspaceScope> {
+  const repositoryFiles = await listProjectFiles(repositoryRoot);
+  const packageFiles = repositoryFiles.filter(
+    (file) => path.posix.basename(file) === "package.json",
+  );
+  const packageFileSet = new Set(packageFiles);
+  const gaps: AppChangeGap[] = [];
+  const manifests = new Map<string, PackageJson>();
+  const attemptedManifests = new Set<string>();
+
+  const readManifest = async (
+    file: string,
+  ): Promise<PackageJson | undefined> => {
+    const existing = manifests.get(file);
+    if (existing) return existing;
+    if (attemptedManifests.has(file)) return undefined;
+    attemptedManifests.add(file);
+    try {
+      const manifest = await readPackageJson(path.join(repositoryRoot, file));
+      if (manifest) manifests.set(file, manifest);
+      return manifest;
+    } catch (error) {
+      gaps.push({
+        code: "workspace_manifest_unresolved",
+        file,
+        message: `Could not inspect workspace manifest ${file}: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      return undefined;
+    }
+  };
+
+  const ancestorFiles = ancestorPackageFiles(repositoryRoot, targetDir).filter(
+    (file) => packageFileSet.has(file),
+  );
+  await Promise.all(ancestorFiles.map(readManifest));
+  const appPackageFile = normalizePath(
+    path.relative(repositoryRoot, path.join(targetDir, "package.json")),
+  );
+  const appPackage = manifests.get(appPackageFile);
+  if (!appPackage) return { dependencyDirectories: new Set(), gaps };
+
+  const workspaceManifest = ancestorFiles
+    .map((file) => ({ file, manifest: manifests.get(file) }))
+    .find(({ manifest }) => workspacePatterns(manifest).length > 0);
+  const workspaceRoot = workspaceManifest
+    ? path.join(repositoryRoot, path.posix.dirname(workspaceManifest.file))
+    : undefined;
+  const patterns = workspacePatterns(workspaceManifest?.manifest);
+  for (const pattern of patterns.filter(hasUnsupportedWorkspacePattern)) {
+    gaps.push({
+      code: "workspace_pattern_unresolved",
+      message: `Workspace pattern ${JSON.stringify(pattern)} uses syntax changed mapping cannot resolve statically.`,
+    });
+  }
+  const workspaceRelativeRoot = workspaceRoot
+    ? normalizePath(path.relative(repositoryRoot, workspaceRoot))
+    : "";
+  const workspacePackageFiles = workspaceRoot
+    ? packageFiles.filter((file) => {
+        const directory = normalizePath(path.posix.dirname(file));
+        const relative = normalizePath(
+          path.posix.relative(workspaceRelativeRoot, directory),
+        );
+        return patterns.some((pattern) =>
+          matchesWorkspacePattern(relative, pattern),
+        );
+      })
+    : [];
+  await Promise.all(workspacePackageFiles.map(readManifest));
+
+  const packages = new Map<
+    string,
+    { directory: string; file: string; manifest: PackageJson }
+  >();
+  const duplicatePackageNames = new Set<string>();
+  for (const file of workspacePackageFiles) {
+    const manifest = manifests.get(file);
+    if (!manifest) continue;
+    if (manifest.name) {
+      if (packages.has(manifest.name)) {
+        duplicatePackageNames.add(manifest.name);
+        packages.delete(manifest.name);
+        continue;
+      }
+      if (duplicatePackageNames.has(manifest.name)) continue;
+      packages.set(manifest.name, {
+        directory: normalizePath(path.posix.dirname(file)),
+        file,
+        manifest,
+      });
+    }
+  }
+
+  for (const name of [...duplicatePackageNames].sort()) {
+    gaps.push({
+      code: "workspace_package_ambiguous",
+      message: `Multiple repository packages declare the name ${JSON.stringify(name)}; direct dependency impact cannot be scoped uniquely.`,
+    });
+  }
+  const workspacePackages = new Map(
+    [...packages.entries()].filter(([, pkg]) => {
+      if (!workspaceRoot) return false;
+      const relative = normalizePath(
+        path.posix.relative(workspaceRelativeRoot, pkg.directory),
+      );
+      return patterns.some((pattern) =>
+        matchesWorkspacePattern(relative, pattern),
+      );
+    }),
+  );
+
+  const dependencyDirectories = new Set<string>();
+  for (const [name, version] of Object.entries(
+    packageDependencies(appPackage),
+  )) {
+    const local = workspacePackages.get(name);
+    if (local) {
+      dependencyDirectories.add(local.directory);
+      continue;
+    }
+    if (version.startsWith("file:") || version.startsWith("link:")) {
+      const requested = version.slice(version.indexOf(":") + 1);
+      const absolute = path.resolve(targetDir, requested);
+      const relative = normalizePath(path.relative(repositoryRoot, absolute));
+      if (relative === ".." || relative.startsWith("../")) {
+        gaps.push({
+          code: "local_dependency_outside_repository",
+          message: `Local dependency ${name} resolves outside the Git repository and cannot be scoped.`,
+        });
+      } else {
+        try {
+          const manifest = await readPackageJson(
+            path.join(absolute, "package.json"),
+          );
+          if (manifest) dependencyDirectories.add(relative);
+          else {
+            gaps.push({
+              code: "local_dependency_unresolved",
+              file: relative,
+              message: `Local dependency ${name} points to ${relative}, but no package.json was found there.`,
+            });
+          }
+        } catch (error) {
+          dependencyDirectories.add(relative);
+          gaps.push({
+            code: "local_dependency_manifest_unresolved",
+            file: normalizePath(path.posix.join(relative, "package.json")),
+            message: `Could not inspect local dependency ${name} at ${relative}: ${error instanceof Error ? error.message : String(error)}`,
+          });
+        }
+      }
+    } else if (version.startsWith("workspace:")) {
+      gaps.push({
+        code: "workspace_dependency_unresolved",
+        message: `Workspace dependency ${name} is declared but no matching local workspace package was found.`,
+      });
+    }
+  }
+
+  return {
+    ...(workspaceRoot ? { workspaceRoot } : {}),
+    dependencyDirectories,
+    gaps,
+  };
+}
+
+function classifyChangedFiles(args: {
+  files: GitChangedFile[];
+  governingFiles: ReadonlySet<string>;
+  repositoryRoot: string;
+  targetDir: string;
+  workspaceScope: WorkspaceScope;
+}): AppChangedFile[] {
+  const targetPrefix = normalizePath(
+    path.relative(args.repositoryRoot, args.targetDir),
+  );
+  return args.files.map((file) => ({
+    ...file,
+    scope: highestPriorityScope(
+      changedFilePaths(file).map((value) =>
+        classifyChangedFile(
+          value,
+          args.governingFiles,
+          targetPrefix,
+          args.workspaceScope,
+          args.repositoryRoot,
+        ),
+      ),
+    ),
+  }));
+}
+
+function classifyChangedFile(
+  file: string,
+  governingFiles: ReadonlySet<string>,
+  targetPrefix: string,
+  workspaceScope: WorkspaceScope,
+  repositoryRoot: string,
+): AppChangeFileScope {
+  if (governingFiles.has(file)) return "governing";
+  const workspacePrefix = workspaceScope.workspaceRoot
+    ? normalizePath(path.relative(repositoryRoot, workspaceScope.workspaceRoot))
+    : undefined;
+  if (isGoverningFile(file, targetPrefix, workspacePrefix)) {
+    return "governing";
+  }
+  if (isWithin(file, targetPrefix)) return "app";
+  if (
+    [...workspaceScope.dependencyDirectories].some((directory) =>
+      isWithin(file, directory),
+    )
+  ) {
+    return "workspace-dependency";
+  }
+  return "outside";
+}
+
+function isGoverningFile(
+  file: string,
+  targetPrefix: string,
+  workspacePrefix: string | undefined,
+): boolean {
+  const basename = path.posix.basename(file);
+  const directory = normalizePath(path.posix.dirname(file));
+  const targetAncestors = pathAncestors(targetPrefix);
+  const isTargetOrAncestor =
+    isWithin(file, targetPrefix) || targetAncestors.includes(directory);
+  const isWorkspaceRoot =
+    workspacePrefix !== undefined && directory === workspacePrefix;
+  if (!isTargetOrAncestor && !isWorkspaceRoot) {
+    return false;
+  }
+  if (
+    [
+      "bun.lock",
+      "bun.lockb",
+      "package-lock.json",
+      "pnpm-lock.yaml",
+      "yarn.lock",
+      "package.json",
+      "turbo.json",
+      "bunfig.toml",
+      "biome.json",
+      "biome.jsonc",
+      "beignet.config.json",
+      ".npmrc",
+    ].includes(basename)
+  ) {
+    return true;
+  }
+  return (
+    /^(?:beignet|drizzle|eslint|next|postcss|tailwind|vite)\.config\.(?:cjs|cts|js|mjs|mts|ts)$/.test(
+      basename,
+    ) || /^tsconfig(?:\.[^.]+)?\.json$/.test(basename)
+  );
+}
+
+function appRelativeSourceChanges(
+  files: AppChangedFile[],
+  repositoryRoot: string,
+  canonicalTargetDir: string,
+): Array<{
+  file: string;
+  repositoryPath: string;
+  status: GitChangedFileStatus;
+}> {
+  const targetPrefix = normalizePath(
+    path.relative(repositoryRoot, canonicalTargetDir),
+  );
+  const changes: Array<{
+    file: string;
+    repositoryPath: string;
+    status: GitChangedFileStatus;
+  }> = [];
+  for (const changed of files) {
+    if (changed.scope !== "app") continue;
+    for (const repositoryPath of changedFilePaths(changed)) {
+      if (!isWithin(repositoryPath, targetPrefix)) continue;
+      const file = targetPrefix
+        ? normalizePath(path.posix.relative(targetPrefix, repositoryPath))
+        : repositoryPath;
+      if (isDocumentationPath(file, [""])) continue;
+      changes.push({
+        file,
+        repositoryPath,
+        status: changed.status,
+      });
+    }
+  }
+  return uniqueBy(
+    changes,
+    (change) => `${change.repositoryPath}:${change.status}`,
+  );
+}
+
+async function addImportConsumers(args: {
+  workspace: Awaited<ReturnType<typeof createAnalysisWorkspace>>;
+  changes: Array<{ file: string; repositoryPath: string }>;
+  nodesByFile: Map<string, AppMapNode[]>;
+  impacts: Map<string, ImpactRecord>;
+}): Promise<void> {
+  const reverseImports = new Map<
+    string,
+    Array<{
+      confidence: "exact" | "partial";
+      importer: string;
+      reference: LocalImportReference;
+    }>
+  >();
+  const sourceFiles = args.workspace.files.filter(isSourceFile);
+  await Promise.all(
+    sourceFiles.map(async (file) => {
+      for (const reference of await localImportReferences(
+        args.workspace,
+        file,
+      )) {
+        const target =
+          reference.resolvedFile ??
+          resolveLocalModulePath(args.workspace, file, reference.importPath);
+        if (!target) continue;
+        const confidence = reference.resolvedFile ? "exact" : "partial";
+        const keys = reference.resolvedFile
+          ? [resolvedModuleKey(target)]
+          : unresolvedModuleKeys(target);
+        for (const key of keys) {
+          const references = reverseImports.get(key) ?? [];
+          references.push({ confidence, importer: file, reference });
+          reverseImports.set(key, references);
+        }
+      }
+    }),
+  );
+
+  for (const references of reverseImports.values()) {
+    references.sort((left, right) =>
+      `${left.importer}:${left.reference.line}:${left.reference.column}`.localeCompare(
+        `${right.importer}:${right.reference.line}:${right.reference.column}`,
+      ),
+    );
+  }
+
+  for (const change of args.changes.filter((item) => isSourceFile(item.file))) {
+    const queue: Array<{
+      confidence: "exact" | "partial";
+      depth: number;
+      file: string;
+    }> = [{ confidence: "exact", file: change.file, depth: 0 }];
+    const visited = new Set([resolvedModuleKey(change.file)]);
+    for (let index = 0; index < queue.length; index += 1) {
+      const current = queue[index];
+      for (const key of moduleLookupKeys(current.file)) {
+        for (const {
+          confidence: edgeConfidence,
+          importer,
+          reference,
+        } of reverseImports.get(key) ?? []) {
+          const importerKey = resolvedModuleKey(importer);
+          if (visited.has(importerKey)) continue;
+          visited.add(importerKey);
+          const depth = current.depth + 1;
+          const confidence =
+            current.confidence === "partial" || edgeConfidence === "partial"
+              ? "partial"
+              : "exact";
+          for (const node of args.nodesByFile.get(importer) ?? []) {
+            addImpact(args.impacts, node, "consumer", {
+              kind: "import",
+              changedFile: change.repositoryPath,
+              message: importReasonMessage({
+                changedFile: change.file,
+                confidence,
+                depth,
+                importer,
+              }),
+              evidence: {
+                file: importer,
+                line: reference.line,
+                column: reference.column,
+                confidence,
+              },
+            });
+          }
+          queue.push({ confidence, file: importer, depth });
+        }
+      }
+    }
+  }
+}
+
+function importReasonMessage(args: {
+  changedFile: string;
+  confidence: "exact" | "partial";
+  depth: number;
+  importer: string;
+}): string {
+  const dependency =
+    args.confidence === "exact" ? "depends on" : "may depend on";
+  const depth = args.depth > 1 ? ` through ${args.depth} local imports` : "";
+  const uncertainty =
+    args.confidence === "partial"
+      ? "; at least one import could not be resolved exactly"
+      : "";
+  return `${args.importer} ${dependency} changed source ${args.changedFile}${depth}${uncertainty}.`;
+}
+
+function addSemanticConsumers(args: {
+  directNodeIds: Set<string>;
+  appMapEdges: AppMapEdge[];
+  nodesById: Map<string, AppMapNode>;
+  impacts: Map<string, ImpactRecord>;
+  relationships: AppChangeRelationship[];
+}): void {
+  for (const edge of args.appMapEdges) {
+    if (
+      args.directNodeIds.has(edge.to) &&
+      edgeImpactBehavior[edge.kind] === "consumer"
+    ) {
+      const consumer = args.nodesById.get(edge.from);
+      const changed = args.nodesById.get(edge.to);
+      const changedFile = changed
+        ? primaryChangeReason(args.impacts.get(changed.id))?.changedFile
+        : undefined;
+      if (consumer && changed && changedFile) {
+        addImpact(args.impacts, consumer, "consumer", {
+          kind: "relationship",
+          changedFile,
+          message: `${consumer.id} ${edge.kind} changed ${changed.id}.`,
+          evidence: edge.evidence,
+          relationship: { kind: edge.kind, from: edge.from, to: edge.to },
+        });
+        args.relationships.push({ ...edge, impact: "consumer" });
+      }
+    }
+
+    if (!args.directNodeIds.has(edge.from)) continue;
+    const container = args.nodesById.get(edge.from);
+    const expansionKinds = container
+      ? containerExpansionKinds[
+          container.kind as keyof typeof containerExpansionKinds
+        ]
+      : undefined;
+    if (!container || !expansionKinds?.has(edge.kind)) continue;
+    const related = args.nodesById.get(edge.to);
+    if (!related) continue;
+    addImpact(args.impacts, related, "related", {
+      kind: "relationship",
+      changedFile:
+        primaryChangeReason(args.impacts.get(container.id))?.changedFile ??
+        container.source.file,
+      message: `${related.id} is connected to the directly changed ${container.id} container.`,
+      evidence: edge.evidence,
+      relationship: { kind: edge.kind, from: edge.from, to: edge.to },
+    });
+    args.relationships.push({ ...edge, impact: "related" });
+  }
+}
+
+function addFeatureContext(args: {
+  changes: Array<{ file: string; repositoryPath: string }>;
+  appMapEdges: AppMapEdge[];
+  nodes: AppMapNode[];
+  nodesById: Map<string, AppMapNode>;
+  impacts: Map<string, ImpactRecord>;
+}): void {
+  for (const change of args.changes) {
+    for (const feature of args.nodes.filter(
+      (node) => node.kind === "feature",
+    )) {
+      if (!isWithin(change.file, feature.source.file)) continue;
+      addImpact(args.impacts, feature, "context", {
+        kind: "ownership",
+        changedFile: change.repositoryPath,
+        message: `${change.file} belongs to feature ${feature.name}.`,
+        evidence: { file: change.file, confidence: "exact" },
+      });
+    }
+  }
+
+  const impactedIds = new Set(args.impacts.keys());
+  for (const edge of args.appMapEdges) {
+    if (
+      !impactedIds.has(edge.to) ||
+      (edge.kind !== "owns" && edge.kind !== "contains-test")
+    ) {
+      continue;
+    }
+    const feature = args.nodesById.get(edge.from);
+    const member = args.nodesById.get(edge.to);
+    const memberImpact = member ? args.impacts.get(member.id) : undefined;
+    if (!feature || !member || memberImpact?.impact === "app-wide") continue;
+    addImpact(args.impacts, feature, "context", {
+      kind: "ownership",
+      changedFile:
+        primaryChangeReason(memberImpact)?.changedFile ?? member.source.file,
+      message: `${feature.id} owns impacted ${member.id}.`,
+      evidence: edge.evidence,
+      relationship: { kind: edge.kind, from: edge.from, to: edge.to },
+    });
+  }
+}
+
+function addUnmappedChangeGaps(args: {
+  changes: Array<{
+    file: string;
+    repositoryPath: string;
+    status: GitChangedFileStatus;
+  }>;
+  impacts: Map<string, ImpactRecord>;
+  gaps: AppChangeGap[];
+}): void {
+  const reasons = [...args.impacts.values()].flatMap(
+    (impact) => impact.reasons,
+  );
+  for (const change of args.changes) {
+    const represented = reasons.some(
+      (reason) => reason.changedFile === change.repositoryPath,
+    );
+    const sourceFile = isSourceFile(change.file);
+    if (sourceFile && change.status === "deleted") {
+      args.gaps.push({
+        code: "deleted_source_unresolved",
+        file: change.repositoryPath,
+        message:
+          "The declaration is absent from the current app map, so Beignet can report surviving importers and feature context but cannot reconstruct every previous semantic relationship.",
+      });
+    } else if (!represented) {
+      args.gaps.push({
+        code: sourceFile ? "changed_source_unmapped" : "changed_file_unmapped",
+        file: change.repositoryPath,
+        message: sourceFile
+          ? "No mapped concept, feature, or surviving local importer could be connected to this changed source file."
+          : "No mapped concept or feature context could be connected to this changed file.",
+      });
+    }
+  }
+}
+
+function addAppMapGaps(
+  unresolved: Array<{
+    code: string;
+    message: string;
+    source: { file: string };
+  }>,
+  changes: Array<{ file: string }>,
+  impacts: Map<string, ImpactRecord>,
+  gaps: AppChangeGap[],
+  appRepositoryPrefix: string,
+): void {
+  const relevantFiles = new Set(
+    [
+      ...changes.map((change) => change.file),
+      ...[...impacts.values()].flatMap((impact) => [
+        impact.node.source.file,
+        ...impact.reasons
+          .map((reason) => reason.evidence?.file)
+          .filter(Boolean),
+      ]),
+    ].filter((file): file is string => Boolean(file)),
+  );
+  for (const item of unresolved) {
+    if (!relevantFiles.has(item.source.file)) continue;
+    gaps.push({
+      code: "app_map_unresolved_reference",
+      file: normalizePath(
+        path.posix.join(appRepositoryPrefix, item.source.file),
+      ),
+      message: `${item.code}: ${item.message}`,
+    });
+  }
+}
+
+function addImpact(
+  impacts: Map<string, ImpactRecord>,
+  node: AppMapNode,
+  impact: AppChangeImpact,
+  reason: AppChangeReason,
+): void {
+  const existing = impacts.get(node.id);
+  if (!existing) {
+    impacts.set(node.id, { node, impact, reasons: [reason] });
+    return;
+  }
+  if (impactRank(impact) > impactRank(existing.impact))
+    existing.impact = impact;
+  if (!existing.reasons.some((item) => reasonKey(item) === reasonKey(reason))) {
+    existing.reasons.push(reason);
+  }
+}
+
+function finalizeImpacts(
+  impacts: Map<string, ImpactRecord>,
+): AppChangeImpactedNode[] {
+  return [...impacts.values()]
+    .map(({ node, impact, reasons }) => {
+      const sortedReasons = [...reasons].sort(
+        (left, right) =>
+          reasonKindSort(left.kind) - reasonKindSort(right.kind) ||
+          reasonKey(left).localeCompare(reasonKey(right)),
+      );
+      return {
+        ...node,
+        impact,
+        reasons: sortedReasons.slice(0, reasonLimitPerNode),
+        reasonCount: sortedReasons.length,
+        reasonsTruncated: sortedReasons.length > reasonLimitPerNode,
+      };
+    })
+    .sort((left, right) =>
+      `${impactSort(left.impact)}:${left.kind}:${left.id}`.localeCompare(
+        `${impactSort(right.impact)}:${right.kind}:${right.id}`,
+      ),
+    );
+}
+
+function groupNodesByFile(nodes: AppMapNode[]): Map<string, AppMapNode[]> {
+  const grouped = new Map<string, AppMapNode[]>();
+  for (const node of nodes) {
+    const values = grouped.get(node.source.file) ?? [];
+    values.push(node);
+    grouped.set(node.source.file, values);
+  }
+  return grouped;
+}
+
+function packageDependencies(manifest: PackageJson): Record<string, string> {
+  return {
+    ...manifest.dependencies,
+    ...manifest.devDependencies,
+    ...manifest.optionalDependencies,
+    ...manifest.peerDependencies,
+  };
+}
+
+function workspacePatterns(manifest: PackageJson | undefined): string[] {
+  if (!manifest?.workspaces) return [];
+  return Array.isArray(manifest.workspaces)
+    ? manifest.workspaces
+    : (manifest.workspaces.packages ?? []);
+}
+
+function matchesWorkspacePattern(file: string, pattern: string): boolean {
+  const source = normalizePath(pattern).replace(/^\.\//, "").replace(/\/$/, "");
+  let expression = "";
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index];
+    if (character === "*" && source[index + 1] === "*") {
+      expression += ".*";
+      index += 1;
+    } else if (character === "*") expression += "[^/]*";
+    else if (character === "?") expression += "[^/]";
+    else expression += character.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+  }
+  return new RegExp(`^${expression}$`).test(file);
+}
+
+function hasUnsupportedWorkspacePattern(pattern: string): boolean {
+  return [...pattern].some((character) => "!{}[]".includes(character));
+}
+
+function ancestorPackageFiles(
+  repositoryRoot: string,
+  targetDir: string,
+): string[] {
+  const files: string[] = [];
+  let directory = targetDir;
+  while (true) {
+    files.push(
+      normalizePath(
+        path.relative(repositoryRoot, path.join(directory, "package.json")),
+      ),
+    );
+    if (directory === repositoryRoot) break;
+    const parent = path.dirname(directory);
+    if (parent === directory || !isAbsoluteWithin(parent, repositoryRoot))
+      break;
+    directory = parent;
+  }
+  return files;
+}
+
+async function readPackageJson(file: string): Promise<PackageJson | undefined> {
+  try {
+    return JSON.parse(await readFile(file, "utf8")) as PackageJson;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new Error(
+      `Could not read workspace manifest ${file}: ${String(error)}`,
+    );
+  }
+}
+
+function bounded<T>(items: T[], limit: number): BoundedAppChangeSection<T> {
+  return {
+    items: items.slice(0, limit),
+    returned: Math.min(items.length, limit),
+    total: items.length,
+    truncated: items.length > limit,
+  };
+}
+
+function boundedGaps(gaps: AppChangeGap[]): BoundedAppChangeGapSection {
+  const section = bounded(gaps, gapLimit);
+  const countsByCode: Record<string, number> = {};
+  for (const gap of gaps) {
+    countsByCode[gap.code] = (countsByCode[gap.code] ?? 0) + 1;
+  }
+  return { ...section, countsByCode };
+}
+
+function dedupeRelationships(
+  relationships: AppChangeRelationship[],
+): AppChangeRelationship[] {
+  return uniqueBy(
+    relationships,
+    (edge) => `${edge.impact}:${edge.kind}:${edge.from}:${edge.to}`,
+  );
+}
+
+function dedupeGaps(gaps: AppChangeGap[]): AppChangeGap[] {
+  return uniqueBy(
+    gaps,
+    (gap) => `${gap.code}:${gap.file ?? ""}:${gap.message}`,
+  );
+}
+
+function uniqueBy<T>(items: T[], key: (item: T) => string): T[] {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const value = key(item);
+    if (seen.has(value)) return false;
+    seen.add(value);
+    return true;
+  });
+}
+
+function compareAppChangedFiles(
+  left: AppChangedFile,
+  right: AppChangedFile,
+): number {
+  return `${scopeSort(left.scope)}:${left.path}:${left.oldPath ?? ""}`.localeCompare(
+    `${scopeSort(right.scope)}:${right.path}:${right.oldPath ?? ""}`,
+  );
+}
+
+function compareRelationships(
+  left: AppChangeRelationship,
+  right: AppChangeRelationship,
+): number {
+  return `${left.impact}:${left.kind}:${left.from}:${left.to}`.localeCompare(
+    `${right.impact}:${right.kind}:${right.from}:${right.to}`,
+  );
+}
+
+function compareGaps(left: AppChangeGap, right: AppChangeGap): number {
+  return `${left.code}:${left.file ?? ""}:${left.message}`.localeCompare(
+    `${right.code}:${right.file ?? ""}:${right.message}`,
+  );
+}
+
+function isAppDependencyGap(gap: AppChangeGap): boolean {
+  return (
+    gap.code.startsWith("local_dependency_") ||
+    gap.code === "workspace_dependency_unresolved"
+  );
+}
+
+function countImpact(
+  items: AppChangeImpactedNode[],
+  impact: AppChangeImpact,
+): number {
+  return items.filter((item) => item.impact === impact).length;
+}
+
+function reasonKey(reason: AppChangeReason): string {
+  return `${reason.kind}:${reason.changedFile}:${reason.relationship?.kind ?? ""}:${reason.relationship?.from ?? ""}:${reason.relationship?.to ?? ""}:${reason.evidence?.file ?? ""}:${reason.evidence?.line ?? 0}:${reason.evidence?.column ?? 0}`;
+}
+
+function reasonKindSort(kind: AppChangeReason["kind"]): number {
+  return {
+    source: 0,
+    relationship: 1,
+    import: 2,
+    ownership: 3,
+    "app-wide": 4,
+  }[kind];
+}
+
+function impactRank(impact: AppChangeImpact): number {
+  return { "app-wide": 0, context: 1, related: 2, consumer: 3, direct: 4 }[
+    impact
+  ];
+}
+
+function impactSort(impact: AppChangeImpact): number {
+  return { direct: 0, consumer: 1, related: 2, context: 3, "app-wide": 4 }[
+    impact
+  ];
+}
+
+function scopeSort(scope: AppChangeFileScope): number {
+  return { governing: 0, app: 1, "workspace-dependency": 2, outside: 3 }[scope];
+}
+
+function moduleStem(file: string): string {
+  return normalizePath(file).replace(/\.(?:c|m)?[jt]sx?$/, "");
+}
+
+function resolvedModuleKey(file: string): string {
+  return `resolved:${normalizePath(file)}`;
+}
+
+function unresolvedModuleKeys(file: string): string[] {
+  const stem = moduleStem(file);
+  return stem.endsWith("/index")
+    ? [`unresolved:${stem}`]
+    : [`unresolved:${stem}`, `unresolved:${stem}/index`];
+}
+
+function moduleLookupKeys(file: string): string[] {
+  return [resolvedModuleKey(file), ...unresolvedModuleKeys(file)];
+}
+
+function changedFilePaths(
+  file: Pick<AppChangedFile, "oldPath" | "path" | "status">,
+): string[] {
+  return file.status === "renamed" && file.oldPath
+    ? [file.path, file.oldPath]
+    : [file.path];
+}
+
+function primaryChangeReason(
+  impact: ImpactRecord | undefined,
+): AppChangeReason | undefined {
+  return (
+    impact?.reasons.find((reason) => reason.kind === "source") ??
+    impact?.reasons[0]
+  );
+}
+
+function highestPriorityScope(
+  scopes: AppChangeFileScope[],
+): AppChangeFileScope {
+  return (
+    [...scopes].sort((left, right) => scopeSort(left) - scopeSort(right))[0] ??
+    "outside"
+  );
+}
+
+function isSourceFile(file: string): boolean {
+  return /\.(?:c|m)?[jt]sx?$/.test(file) && !file.endsWith(".d.ts");
+}
+
+function isDocumentationPath(file: string, roots: string[]): boolean {
+  const normalized = normalizePath(file);
+  const basename = path.posix.basename(normalized);
+  if (
+    /^(?:AGENTS|CLAUDE|README|CHANGELOG|CONTRIBUTING|SECURITY|CODE_OF_CONDUCT|LICENSE|NOTICE)$/i.test(
+      basename,
+    ) ||
+    /^(?:AGENTS|CLAUDE|README|CHANGELOG|CONTRIBUTING|SECURITY|CODE_OF_CONDUCT|LICENSE|NOTICE)(?:\.[a-z0-9_-]+)?\.(?:md|mdx|txt)$/i.test(
+      basename,
+    )
+  ) {
+    return true;
+  }
+  return (
+    /\.(?:md|mdx|txt)$/i.test(normalized) &&
+    roots.some((root) => {
+      if (!isWithin(normalized, root)) return false;
+      const relative = root
+        ? normalizePath(path.posix.relative(root, normalized))
+        : normalized;
+      return /^(?:docs|documentation)\//i.test(relative);
+    })
+  );
+}
+
+function appWideChangeReasons(
+  files: AppChangedFile[],
+  isDocumentation: (file: string) => boolean,
+): AppChangeReason[] {
+  return (["governing", "workspace-dependency"] as const).flatMap((scope) => {
+    const scoped = files.filter((file) => file.scope === scope);
+    if (scoped.length === 0) return [];
+    const first = scoped[0];
+    const changedFile =
+      changedFilePaths(first).find((file) => !isDocumentation(file)) ??
+      first.path;
+    const message =
+      scope === "workspace-dependency"
+        ? scoped.length === 1
+          ? `Direct local dependency ${changedFile} changed.`
+          : `${scoped.length} direct local dependency files changed, including ${changedFile}.`
+        : scoped.length === 1
+          ? `Governing file ${changedFile} changed.`
+          : `${scoped.length} governing files changed, including ${changedFile}.`;
+    return [{ kind: "app-wide" as const, changedFile, message }];
+  });
+}
+
+function isWithin(file: string, directory: string): boolean {
+  if (!directory || directory === ".") return true;
+  return file === directory || file.startsWith(`${directory}/`);
+}
+
+function isAbsoluteWithin(file: string, directory: string): boolean {
+  const relative = path.relative(directory, file);
+  return (
+    relative === "" ||
+    (relative !== ".." && !relative.startsWith(`..${path.sep}`))
+  );
+}
+
+function assertInsideRepository(
+  targetDir: string,
+  repositoryRoot: string,
+): void {
+  if (!isAbsoluteWithin(targetDir, repositoryRoot)) {
+    throw new Error(
+      `App directory ${targetDir} is outside Git repository ${repositoryRoot}.`,
+    );
+  }
+}
+
+function pathAncestors(relativePath: string): string[] {
+  const values: string[] = [];
+  let current = relativePath;
+  while (true) {
+    values.push(current || ".");
+    if (!current || current === ".") break;
+    const parent = path.posix.dirname(current);
+    if (parent === current) break;
+    current = parent === "." ? "" : parent;
+  }
+  return values;
+}
+
+function normalizePath(file: string): string {
+  const normalized = file.replaceAll("\\", "/");
+  return normalized === "." ? "" : normalized;
+}
+
+function statusMark(status: GitChangedFileStatus): string {
+  return {
+    added: "A",
+    copied: "C",
+    deleted: "D",
+    modified: "M",
+    renamed: "R",
+    "type-changed": "T",
+    unmerged: "U",
+    unknown: "?",
+    untracked: "?",
+  }[status];
+}
+
+function shortId(value: string): string {
+  return value.slice(0, 8);
+}
+
+function shortHash(value: string): string {
+  return `${value.slice(0, 15)}…`;
+}
+
+function terminalText(value: string): string {
+  return JSON.stringify(value)
+    .slice(1, -1)
+    .replace(/[\u007f-\u009f\u2028\u2029\p{Cf}]/gu, (character) => {
+      const codePoint = character.codePointAt(0);
+      if (codePoint === undefined) return "";
+      return codePoint <= 0xffff
+        ? `\\u${codePoint.toString(16).padStart(4, "0")}`
+        : `\\u{${codePoint.toString(16)}}`;
+    });
+}