no-mistakes 0.51.3 → 0.52.2

package/README.md

@@ -1,7 +1,12 @@
 # no-mistakes
 
 Unified static codebase intelligence CLI for TS/JS module graphs, symbols,
-React traits, queue hops, server routes, and project checks.
+React traits, queue hops, server routes, configured language graphs, and project
+checks.
+
+Use it when an agent needs a deterministic impact map or focused test plan in
+the same process as a Node tool. The async N-API facade avoids subprocess
+parsing and reuses one prepared analysis for related reports.
 
 ```bash
 npm install --save-dev no-mistakes
@@ -14,6 +19,26 @@ npx no-mistakes check --json
 
 Programmatic Node usage loads the same Rust analysis through N-API:
 
+```js
+const { analyzeProject } = require("no-mistakes");
+
+const report = await analyzeProject({
+  root: process.cwd(),
+  reports: [
+    { type: "dependents", files: ["src/api.mts"] },
+    { type: "symbols", files: ["src/api.mts"], include: "both" },
+    {
+      type: "testsPlan",
+      framework: "vitest",
+      changedFiles: ["src/api.mts"],
+    },
+  ],
+});
+```
+
+Use `analyzeProject()` when reports share a root and configuration. Dedicated
+functions remain convenient for a single query:
+
 ````js
 const {
   dependencies,
@@ -66,7 +91,7 @@ const {
   });
   const plan = await testsPlan({
     root: process.cwd(),
-    framework: "vitest", // also python, go, cargo, rails, php, playwright, dotnet, swift
+    framework: "vitest", // also jest, python, go, cargo, rails, php, java, kotlin, elixir, dart, playwright, dotnet, swift
     changedFiles: ["src/utils.mts"],
   });
   // Complete changed-file inventory, including paths that selected no tests.
@@ -155,4 +180,5 @@ npx no-mistakes rust-max-lines-per-file crates/*/src crates/*/tests
 
 See the full documentation in [docs/](../../docs/README.md), the
 [CLI command index](../../docs/cli/README.md), and the
-[Node/N-API guide](../../docs/node-api.md).
+[Node/N-API guide](../../docs/node-api.md). Agents can use the compact
+[packaged skill](../../skills/no-mistakes/SKILL.md).

package/index.d.ts

@@ -53,6 +53,8 @@ import type {
   TraverseOptions,
   WhyStep,
   WithInvocationOptions,
+  WritePlanningImpactArtifactsOptions,
+  PlanningImpactArtifacts,
 } from "./types";
 
 export * from "./types";
@@ -68,6 +70,9 @@ export function related(options: WithInvocationOptions<TraverseOptions>): Promis
 export function analyzeProject(
   options: WithInvocationOptions<AnalyzeProjectOptions>,
 ): Promise<AnalyzeProjectResult>;
+export function writePlanningImpactArtifacts(
+  options: WithInvocationOptions<WritePlanningImpactArtifactsOptions>,
+): Promise<PlanningImpactArtifacts>;
 export function symbols(
   options: WithInvocationOptions<SymbolsSignatureImpactOptions>,
 ): Promise<SignatureImpactResult>;

package/index.js

@@ -4,6 +4,8 @@
 // overwriting the package's checked-in install placeholder.
 const native = require(process.env.NO_MISTAKES_TEST_NAPI_ADDON_PATH || "./bin/no-mistakes.node");
 const planning = require("./planning");
+const { writePlanningImpactArtifacts: writeArtifacts } = require("./planning-impact-artifacts");
+const { createPlanningArtifactLock } = require("./planning-impact-artifacts-lock");
 const { createWorkflowTopologyIndex } = require("./workflow-topology-index");
 const fs = require("node:fs");
 const path = require("node:path");
@@ -64,6 +66,7 @@ const jsonApis = createJsonApis({
 
 const PLAN_INPUT_REPORTS = new Set(["testsComment", "testsGraph", "testsGraphMermaid"]);
 const CAMELIZE_REPORTS = new Set(["testsPlan", "testsImpact", "testsTargets", "testsGraph"]);
+const acquirePlanningArtifactLock = createPlanningArtifactLock(native);
 
 async function analyzeProject(options = {}) {
   const request = { ...options };
@@ -97,6 +100,20 @@ async function analyzeProject(options = {}) {
   }
 }
 
+async function writePlanningImpactArtifacts(options) {
+  return writeArtifacts(
+    options,
+    analyzeProject,
+    async (from, to) => {
+      if (await native.renameNoReplace(from, to)) return true;
+      const error = new Error("output directory path changed during planning artifact generation");
+      error.code = "EEXIST";
+      throw error;
+    },
+    acquirePlanningArtifactLock,
+  );
+}
+
 const topologyMemo = new Map();
 
 async function ciTopology(options) {
@@ -140,6 +157,7 @@ async function version() {
 module.exports.createWorkflowTopologyIndex = createWorkflowTopologyIndex;
 module.exports.version = version;
 module.exports.analyzeProject = analyzeProject;
+module.exports.writePlanningImpactArtifacts = writePlanningImpactArtifacts;
 module.exports.callSites = jsonApis.callSites;
 module.exports.check = jsonApis.check;
 module.exports.resolveConfig = jsonApis.resolveConfig;

package/index.mjs

@@ -60,6 +60,7 @@ export const {
   testsWhy,
   validateMermaidMarkdown,
   version,
+  writePlanningImpactArtifacts,
 } = cjs;
 
 export default cjs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "no-mistakes",
-  "version": "0.51.3",
+  "version": "0.52.2",
   "description": "Static codebase analysis tools for TS/JS dependencies, dependents, and symbols",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,12 @@
     "*.d.ts",
     "index.js",
     "index.mjs",
+    "planning-impact-artifacts.js",
+    "planning-impact-artifacts-errors.js",
+    "planning-impact-artifacts-files.js",
+    "planning-impact-artifacts-inputs.js",
+    "planning-impact-artifacts-lock.js",
+    "planning-impact-artifacts-privacy.js",
     "planning.js",
     "workflow-topology-index.js",
     "workflow-topology-index-helpers.js",

package/planning-impact-artifacts-errors.js

@@ -0,0 +1,49 @@
+"use strict";
+
+const RESTORATION_FAILURE = Symbol("planning artifact output restoration failure");
+
+function outputRestorationFailure(restoreError, parked, outputPath, updateError, restored = false) {
+  const recoveryPath = restored ? outputPath : parked;
+  const error = new AggregateError(
+    updateError ? [restoreError, updateError] : [restoreError],
+    restored
+      ? `planning artifact output directory failed validation after restoration at ${recoveryPath}`
+      : `planning artifact output restoration failed; recover the parked directory at ${recoveryPath}`,
+    { cause: restoreError },
+  );
+  error.code = restoreError.code;
+  error[RESTORATION_FAILURE] = true;
+  return error;
+}
+
+function isOutputRestorationFailure(error) {
+  return error?.[RESTORATION_FAILURE] === true;
+}
+
+function preserveFailureReportingError(originalError, failureReportingError) {
+  if (
+    (typeof originalError === "object" && originalError !== null) ||
+    typeof originalError === "function"
+  ) {
+    try {
+      Object.defineProperty(originalError, "failureReportingError", {
+        configurable: true,
+        value: failureReportingError,
+      });
+      return originalError;
+    } catch {
+      // Fall through when a caller throws a frozen or otherwise non-extensible value.
+    }
+  }
+  return new AggregateError(
+    [originalError, failureReportingError],
+    `planning artifact generation failed and failure reporting could not restore the output directory: ${failureReportingError.message}`,
+    { cause: originalError },
+  );
+}
+
+module.exports = {
+  isOutputRestorationFailure,
+  outputRestorationFailure,
+  preserveFailureReportingError,
+};

package/planning-impact-artifacts-files.js

@@ -0,0 +1,211 @@
+"use strict";
+const { lstat, open, realpath, rename, rm, stat } = require("node:fs/promises");
+const { constants } = require("node:fs");
+const { basename, dirname, join } = require("node:path");
+const { randomUUID } = require("node:crypto");
+const { outputRestorationFailure } = require("./planning-impact-artifacts-errors");
+const privacy = require("./planning-impact-artifacts-privacy");
+const MANIFEST_OPEN_FLAGS =
+  constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+
+async function validateOutputDirectory(outputDirectory) {
+  const directory = await realpath(outputDirectory);
+  const metadata = await stat(directory);
+  if (!privacy.isPrivateDirectory(metadata)) {
+    throw privacy.privatePermissionError("output directory", 0o700);
+  }
+  const parentMetadata = await stat(dirname(directory));
+  if (!parentMetadata.isDirectory() || parentMetadata.dev !== metadata.dev) {
+    throw new Error(
+      "output directory must share its parent's filesystem for atomic planning artifact publication",
+    );
+  }
+  let handle;
+  try {
+    handle = await open(directory, "r");
+  } catch (error) {
+    if (!["EISDIR", "EPERM"].includes(error.code)) throw error;
+  }
+  const output = { path: directory, identity: metadata, handle };
+  try {
+    await assertOutputDirectory(output);
+    return output;
+  } catch (error) {
+    if (handle) await handle.close().catch(() => {});
+    throw error;
+  }
+}
+
+async function validateManifest(output, manifestPath) {
+  const manifest = await resolveManifestPath(output, manifestPath);
+  const handle = await open(manifest, MANIFEST_OPEN_FLAGS);
+  try {
+    const metadata = await handle.stat();
+    if (!metadata.isFile()) throw new Error("changed-files manifest must be a regular file");
+    const pathMetadata = await lstat(manifest);
+    if (
+      metadata.nlink !== 1 ||
+      pathMetadata.nlink !== 1 ||
+      !pathMetadata.isFile() ||
+      !sameFileIdentity(metadata, pathMetadata)
+    ) {
+      throw new Error("changed-files manifest changed during validation");
+    }
+    await assertOutputDirectory(output);
+    return { path: manifest, handle };
+  } catch (error) {
+    await handle.close().catch(() => {});
+    throw error;
+  }
+}
+
+async function resolveManifestPath(output, manifestPath) {
+  await assertOutputDirectory(output);
+  const manifest = await realpath(manifestPath);
+  if (dirname(manifest) !== output.path) {
+    throw new Error("manifest must be inside the private output directory");
+  }
+  return manifest;
+}
+
+async function publishArtifact(output, name, contents) {
+  await assertOutputDirectory(output);
+  const staged = join(output.path, `.${name}.${randomUUID()}.tmp`);
+  const destination = join(output.path, name);
+  let file;
+  let identity;
+  try {
+    file = await open(staged, "wx", 0o600);
+    try {
+      await file.chmod(0o600);
+      await file.writeFile(contents);
+      identity = await file.stat();
+      if (!privacy.isPrivateRegularFile(identity) || identity.nlink !== 1) {
+        throw privacy.privatePermissionError(
+          `staged artifact is not a private regular file: ${name}`,
+          0o600,
+        );
+      }
+    } finally {
+      await file.close();
+      file = undefined;
+    }
+    const stagedMetadata = await lstat(staged);
+    if (!sameFileIdentity(identity, stagedMetadata) || stagedMetadata.nlink !== 1) {
+      throw new Error(`staged artifact changed before publication: ${name}`);
+    }
+    await assertOutputDirectory(output);
+    await rename(staged, destination);
+    await assertOutputDirectory(output);
+    const published = await lstat(destination);
+    if (
+      !sameFileIdentity(identity, published) ||
+      !privacy.isPrivateRegularFile(published) ||
+      published.nlink !== 1
+    ) {
+      await removePath(output, destination).catch(() => {});
+      throw new Error(`published artifact changed during publication: ${name}`);
+    }
+  } catch (error) {
+    if (file) await file.close().catch(() => {});
+    await removePath(output, staged).catch(() => {});
+    throw error;
+  }
+}
+
+async function removeArtifact(output, name) {
+  return removePath(output, join(output.path, name));
+}
+
+async function updateOutputDirectory(output, update, renameNoReplace) {
+  await assertOutputDirectory(output);
+  const parked = join(
+    dirname(output.path),
+    `.${basename(output.path)}.planning-impact-${randomUUID()}`,
+  );
+  await rename(output.path, parked);
+  const privateOutput = { ...output, path: parked };
+  let result;
+  let updateError;
+  try {
+    await assertOutputDirectory(privateOutput);
+    result = await update(privateOutput);
+  } catch (error) {
+    updateError = error;
+  }
+  let restoreError;
+  let restored = false;
+  try {
+    await assertOutputDirectory(privateOutput);
+    await assertPathVacant(output.path);
+    if (!(await renameNoReplace(parked, output.path))) {
+      const error = new Error("output directory path changed during planning artifact generation");
+      error.code = "EEXIST";
+      throw error;
+    }
+    restored = true;
+    await assertOutputDirectory(output);
+  } catch (error) {
+    restoreError = error;
+  }
+  if (restoreError)
+    throw outputRestorationFailure(restoreError, parked, output.path, updateError, restored);
+  if (updateError) throw updateError;
+  return result;
+}
+
+async function removePath(output, target) {
+  await assertOutputDirectory(output);
+  let metadata;
+  try {
+    metadata = await lstat(target);
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  if (metadata.isDirectory()) return;
+  await rm(target, { force: true });
+  await assertOutputDirectory(output);
+}
+
+async function assertOutputDirectory(output) {
+  if ((await realpath(output.path)) !== output.path) {
+    throw new Error("output directory path changed during planning artifact generation");
+  }
+  const metadata = await stat(output.path);
+  if (!privacy.isPrivateDirectory(metadata) || !sameFileIdentity(output.identity, metadata)) {
+    throw new Error("output directory changed during planning artifact generation");
+  }
+  if (output.handle) {
+    const descriptorMetadata = await output.handle.stat();
+    if (
+      !privacy.isPrivateDirectory(descriptorMetadata) ||
+      !sameFileIdentity(output.identity, descriptorMetadata)
+    ) {
+      throw new Error("output directory descriptor changed during planning artifact generation");
+    }
+  }
+}
+
+async function assertPathVacant(path) {
+  try {
+    await lstat(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  throw new Error("output directory path changed during planning artifact generation");
+}
+
+function sameFileIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+module.exports = {
+  assertOutputDirectory,
+  publishArtifact,
+  removeArtifact,
+  updateOutputDirectory,
+  validateManifest,
+  validateOutputDirectory,
+};

package/planning-impact-artifacts-inputs.js

@@ -0,0 +1,87 @@
+"use strict";
+
+const { lstat, stat } = require("node:fs/promises");
+const { basename, dirname, join } = require("node:path");
+
+const RESERVED_ARTIFACT_NAME =
+  /^(?:dependencies|dependents|symbols|plan)\.(?:json|stderr|status)$/u;
+const RESERVED_ARTIFACT_NAMES = ["dependencies", "dependents", "symbols", "plan"].flatMap((name) =>
+  ["json", "stderr", "status"].map((extension) => `${name}.${extension}`),
+);
+
+async function isReservedArtifactPath(path) {
+  if (RESERVED_ARTIFACT_NAME.test(basename(path))) return true;
+  const identity = await stat(path);
+  for (const name of RESERVED_ARTIFACT_NAMES) {
+    try {
+      const candidate = await lstat(join(dirname(path), name));
+      if (candidate.dev === identity.dev && candidate.ino === identity.ino) return true;
+    } catch (error) {
+      if (!["ENOENT", "ENOTDIR"].includes(error.code)) throw error;
+    }
+  }
+  return false;
+}
+
+async function existingFiles(root, files) {
+  try {
+    await stat(root);
+  } catch (error) {
+    if (error.code === "ENOENT") return files;
+    throw error;
+  }
+  const existing = await Promise.all(
+    files.map(async (file) => {
+      try {
+        return (await stat(join(root, file))).isFile() ? file : undefined;
+      } catch (error) {
+        if (["ENOENT", "ENOTDIR"].includes(error.code)) return undefined;
+        throw error;
+      }
+    }),
+  );
+  return existing.filter((file) => file !== undefined);
+}
+
+async function buildRequest(root, changedFiles, broad) {
+  const structuralFiles = changedFiles.filter((file) => /\.[cm]?[jt]sx?(?:#.*)?$/u.test(file));
+  const traversalFiles = structuralFiles.map((file) => ({ file }));
+  const symbolFiles = await existingFiles(root, structuralFiles);
+  const relationships = broad ? {} : { relationships: ["import", "workspace"] };
+  const reports = structuralFiles.length
+    ? [
+        ...["dependencies", "dependents"].map((type) => ({
+          id: type,
+          type,
+          files: traversalFiles,
+          depth: 1,
+          ...relationships,
+        })),
+        ...(symbolFiles.length
+          ? [{ id: "symbols", type: "symbols", files: symbolFiles, include: "both" }]
+          : []),
+      ]
+    : [];
+  reports.push({
+    id: "plan",
+    type: "testsPlan",
+    framework: "vitest",
+    environment: "prePush",
+    changedFiles,
+  });
+  return { root, reports };
+}
+
+function completeResult(result, requestedReports) {
+  const requested = new Set(requestedReports.map((report) => report.id));
+  const traversal = { roots: [], files: [], diagnostics: [], tsconfig_provenance: [] };
+  const omitted = [
+    { id: "dependencies", type: "dependencies", result: traversal },
+    { id: "dependents", type: "dependents", result: traversal },
+    { id: "symbols", type: "symbols", result: { roots: [], files: [] } },
+  ].filter((report) => !requested.has(report.id));
+  if (!omitted.length) return result;
+  return { reports: [...omitted, ...result.reports] };
+}
+
+module.exports = { buildRequest, completeResult, isReservedArtifactPath };

package/planning-impact-artifacts-lock.js

@@ -0,0 +1,72 @@
+"use strict";
+
+const { lstat, readlink, realpath } = require("node:fs/promises");
+const path = require("node:path");
+const { setTimeout: delay } = require("node:timers/promises");
+
+const BUSY_LOCK = /planning artifact lock is busy/u;
+const INITIAL_LOCK_RETRY_MS = 10;
+const MAX_LOCK_RETRY_MS = 100;
+
+const outputUpdates = new Map();
+
+async function serializeOutputUpdate(outputPath, update) {
+  const previous = outputUpdates.get(outputPath) || Promise.resolve();
+  let release;
+  const current = new Promise((resolveCurrent) => {
+    release = resolveCurrent;
+  });
+  outputUpdates.set(outputPath, current);
+  await previous;
+  try {
+    return await update();
+  } finally {
+    release();
+    if (outputUpdates.get(outputPath) === current) outputUpdates.delete(outputPath);
+  }
+}
+
+async function canonicalOutputKey(outputPath, visited = new Set()) {
+  const lexicalPath = path.resolve(outputPath);
+  if (visited.has(lexicalPath)) {
+    const error = new Error("output directory contains a symbolic link cycle");
+    error.code = "ELOOP";
+    throw error;
+  }
+  visited.add(lexicalPath);
+  try {
+    const metadata = await lstat(lexicalPath);
+    if (metadata.isSymbolicLink()) {
+      const target = path.resolve(path.dirname(lexicalPath), await readlink(lexicalPath));
+      return canonicalOutputKey(target, visited);
+    }
+    return await realpath(lexicalPath);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return path.join(await realpath(path.dirname(lexicalPath)), path.basename(lexicalPath));
+  }
+}
+
+function createPlanningArtifactLock(native) {
+  return async (outputPath) => {
+    const lockPath = path.join(
+      path.dirname(outputPath),
+      `.${path.basename(outputPath)}.planning-impact.lock`,
+    );
+    const token = await acquirePlanningArtifactLock(native, lockPath);
+    return async () => native.releasePlanningArtifactLock(token);
+  };
+}
+
+async function acquirePlanningArtifactLock(native, lockPath) {
+  for (let delayMs = INITIAL_LOCK_RETRY_MS; ; delayMs = Math.min(delayMs * 2, MAX_LOCK_RETRY_MS)) {
+    try {
+      return await native.acquirePlanningArtifactLock(lockPath);
+    } catch (error) {
+      if (!BUSY_LOCK.test(String(error && error.message))) throw error;
+      await delay(delayMs);
+    }
+  }
+}
+
+module.exports = { canonicalOutputKey, createPlanningArtifactLock, serializeOutputUpdate };

package/planning-impact-artifacts-privacy.js

@@ -0,0 +1,24 @@
+"use strict";
+
+function isPrivateDirectory(metadata, platform = process.platform) {
+  return metadata.isDirectory() && hasPrivateMode(metadata, 0o700, platform);
+}
+
+function isPrivateRegularFile(metadata, platform = process.platform) {
+  return metadata.isFile() && hasPrivateMode(metadata, 0o600, platform);
+}
+
+function hasPrivateMode(metadata, mode, platform) {
+  return platform !== "win32" && (metadata.mode & 0o7777) === mode;
+}
+
+function privatePermissionError(subject, mode, platform = process.platform) {
+  if (platform === "win32") {
+    return new Error(
+      "planning impact artifacts are unavailable on Windows because Node cannot verify private Windows ACLs",
+    );
+  }
+  return new Error(`${subject} must have mode ${mode.toString(8).padStart(4, "0")}`);
+}
+
+module.exports = { isPrivateDirectory, isPrivateRegularFile, privatePermissionError };

package/planning-impact-artifacts-types.d.ts

@@ -0,0 +1,25 @@
+import type { DependencyResult, SymbolsResult, TestPlan } from "./types";
+
+/** Input for writing a private, CLI-compatible planning-impact artifact set. */
+export interface WritePlanningImpactArtifactsOptions {
+  /** Repository root passed to the prepared `analyzeProject()` request. */
+  root: string;
+  /**
+   * Path to a private regular manifest directly inside `outputDirectory`. Its newline-delimited
+   * contents are literal repository-relative changed-file paths; only empty records are ignored.
+   */
+  changedFilesManifest: string;
+  /** Existing private directory with exactly mode `0700` that receives artifacts; unavailable on Windows. */
+  outputDirectory: string;
+  /** Omit the import/workspace relationship filter for structural reports. */
+  broad?: boolean;
+}
+
+/** Structured result mirrored by `dependencies.json`, `dependents.json`, `symbols.json`, and `plan.json`. */
+export interface PlanningImpactArtifacts {
+  outputDirectory: string;
+  dependencies: DependencyResult;
+  dependents: DependencyResult;
+  symbols: SymbolsResult;
+  plan: TestPlan;
+}

package/planning-impact-artifacts.js

@@ -0,0 +1,213 @@
+"use strict";
+
+const {
+  publishArtifact,
+  removeArtifact,
+  updateOutputDirectory,
+  validateManifest,
+  validateOutputDirectory,
+} = require("./planning-impact-artifacts-files");
+const artifactErrors = require("./planning-impact-artifacts-errors");
+const { canonicalOutputKey, serializeOutputUpdate } = require("./planning-impact-artifacts-lock");
+const { realpath } = require("node:fs/promises");
+const {
+  buildRequest,
+  completeResult,
+  isReservedArtifactPath,
+} = require("./planning-impact-artifacts-inputs");
+const { basename, isAbsolute, posix, resolve, win32 } = require("node:path");
+const { TextDecoder } = require("node:util");
+
+const REPORTS = ["dependencies", "dependents", "symbols", "plan"];
+const REPORT_TYPES = {
+  dependencies: "dependencies",
+  dependents: "dependents",
+  symbols: "symbols",
+  plan: "testsPlan",
+};
+const RESERVED_ARTIFACT_NAME =
+  /^(?:dependencies|dependents|symbols|plan)\.(?:json|stderr|status)$/u;
+const RESERVED_MANIFEST_ERROR =
+  "changed-files manifest must not use a reserved artifact destination";
+// Node keeps U+FEFF when ignoreBOM is true; the default strips a UTF-8 BOM.
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+
+async function writePlanningImpactArtifacts(
+  options,
+  analyzeProject,
+  renameNoReplace,
+  acquireOutputLock = async () => async () => {},
+) {
+  const outputKey = await canonicalOutputKey(resolve(options.outputDirectory));
+  return serializeOutputUpdate(outputKey, async () => {
+    const releaseOutputLock = await acquireOutputLock(outputKey);
+    try {
+      const outputPath = await realpath(outputKey);
+      return await writePlanningImpactArtifactsUnlocked(
+        { ...options, outputDirectory: outputPath },
+        analyzeProject,
+        renameNoReplace,
+      );
+    } finally {
+      await releaseOutputLock();
+    }
+  });
+}
+
+async function writePlanningImpactArtifactsUnlocked(options, analyzeProject, renameNoReplace) {
+  const output = await validateOutputDirectory(options.outputDirectory);
+  let manifestHandle;
+  let mayWriteFailureArtifacts = false;
+  try {
+    const requestedManifestPath = resolve(options.changedFilesManifest);
+    mayWriteFailureArtifacts = !RESERVED_ARTIFACT_NAME.test(basename(requestedManifestPath));
+    if (!mayWriteFailureArtifacts) throw new Error(RESERVED_MANIFEST_ERROR);
+    const manifestPath = await realpath(requestedManifestPath);
+    mayWriteFailureArtifacts = false;
+    if (await isReservedArtifactPath(manifestPath)) throw new Error(RESERVED_MANIFEST_ERROR);
+    mayWriteFailureArtifacts = true;
+    const manifest = await validateManifest(output, manifestPath);
+    manifestHandle = manifest.handle;
+    mayWriteFailureArtifacts = false;
+    if (await isReservedArtifactPath(manifest.path)) throw new Error(RESERVED_MANIFEST_ERROR);
+    mayWriteFailureArtifacts = true;
+    const changedFiles = parseChangedFiles(decodeManifest(await manifestHandle.readFile()));
+    await manifestHandle.close();
+    manifestHandle = undefined;
+    await updateOutputDirectory(output, invalidateStatuses, renameNoReplace);
+    const request = {
+      ...(await buildRequest(options.root, changedFiles, options.broad === true)),
+      ...invocationOptions(options),
+    };
+    const result = await analyzeProject(request);
+    const completed = completeResult(result, request.reports);
+    const artifacts = reportArtifacts(completed);
+    await updateOutputDirectory(
+      output,
+      (privateOutput) => writeSuccess(privateOutput, artifacts),
+      renameNoReplace,
+    );
+    return { outputDirectory: output.path, ...artifacts };
+  } catch (error) {
+    if (manifestHandle) {
+      await manifestHandle.close().catch(() => {});
+      manifestHandle = undefined;
+    }
+    if (mayWriteFailureArtifacts && !artifactErrors.isOutputRestorationFailure(error)) {
+      try {
+        await updateOutputDirectory(
+          output,
+          (privateOutput) => writeFailure(privateOutput, error),
+          renameNoReplace,
+        );
+      } catch (failureReportingError) {
+        if (artifactErrors.isOutputRestorationFailure(failureReportingError)) {
+          throw artifactErrors.preserveFailureReportingError(error, failureReportingError);
+        }
+      }
+    }
+    throw error;
+  } finally {
+    if (manifestHandle) await manifestHandle.close().catch(() => {});
+    if (output.handle) await output.handle.close().catch(() => {});
+  }
+}
+function decodeManifest(contents) {
+  try {
+    return UTF8_DECODER.decode(contents);
+  } catch {
+    throw new Error("changed-files manifest must be valid UTF-8");
+  }
+}
+function invocationOptions(options) {
+  return Object.fromEntries(
+    ["timeout", "lockTimeout", "failOnLock", "jobs", "profile"]
+      .filter((name) => Object.hasOwn(options, name))
+      .map((name) => [name, options[name]]),
+  );
+}
+function parseChangedFiles(source) {
+  const files = [...new Set(source.split(/\r\n|[\r\n]/u).filter((line) => line.length > 0))];
+  if (!files.length) throw new Error("changed-files manifest is empty");
+  for (const file of files) {
+    if (
+      isAbsolute(file) ||
+      posix.isAbsolute(file) ||
+      win32.isAbsolute(file) ||
+      /^[A-Za-z]:/u.test(file) ||
+      file.split(/[\\/]/u).includes("..")
+    ) {
+      throw new Error(`changed file must be repository-relative: ${file}`);
+    }
+  }
+  return files;
+}
+function reportArtifacts(result) {
+  const reports = new Map(result.reports.map((report) => [report.id, report]));
+  return Object.fromEntries(
+    REPORTS.map((name) => {
+      const report = reports.get(name);
+      if (!report) throw new Error(`no-mistakes omitted the ${name} report`);
+      if (report.type !== REPORT_TYPES[name]) {
+        throw new Error(`${name} type ${report.type}; expected ${REPORT_TYPES[name]}`);
+      }
+      return [name, report.result];
+    }),
+  );
+}
+
+async function writeSuccess(output, artifacts) {
+  for (const name of REPORTS) {
+    await publishArtifact(
+      output,
+      `${name}.json`,
+      `${JSON.stringify(toCliValue(artifacts[name]))}\n`,
+    );
+    await publishArtifact(output, `${name}.stderr`, "");
+  }
+  for (const name of REPORTS) await publishArtifact(output, `${name}.status`, "0\n");
+}
+
+async function writeFailure(output, error) {
+  const diagnostic = boundedDiagnostic(error);
+  for (const name of REPORTS) {
+    await attempt(() => removeArtifact(output, `${name}.json`));
+    await attempt(() => publishArtifact(output, `${name}.stderr`, diagnostic));
+    await attempt(() => publishArtifact(output, `${name}.status`, "1\n"));
+  }
+}
+
+async function invalidateStatuses(output) {
+  for (const name of REPORTS) {
+    await publishArtifact(output, `${name}.status`, "1\n");
+  }
+}
+
+async function attempt(operation) {
+  try {
+    await operation();
+  } catch {
+    // Failure reporting must preserve the original analysis/publication error.
+  }
+}
+
+function toCliValue(value) {
+  if (Array.isArray(value)) return value.map(toCliValue);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key.replace(/[A-Z]/gu, (letter) => `_${letter.toLowerCase()}`),
+      toCliValue(child),
+    ]),
+  );
+}
+
+function boundedDiagnostic(error) {
+  const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+  return Buffer.from(`${detail}\n`)
+    .subarray(0, 4096)
+    .toString("utf8")
+    .replace(/\ufffd+$/u, "");
+}
+
+module.exports = { writePlanningImpactArtifacts };

package/types.d.ts

@@ -12,3 +12,4 @@ export * from "./query-types";
 export * from "./named-query-types";
 export * from "./mermaid-types";
 export * from "./resolve-config-types";
+export * from "./planning-impact-artifacts-types";