@davidvornholt/standards 0.18.0 → 0.20.0

package/src/managed-files.ts

@@ -1,4 +1,12 @@
-import { readdir, readFile, stat } from 'node:fs/promises';
+import {
+  lstat,
+  readdir,
+  readFile,
+  readlink,
+  rm,
+  symlink,
+  writeFile,
+} from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 
 // Never mirrored, even under a managed directory path: build output, VCS
@@ -16,34 +24,76 @@ const directiveToken = Buffer.from(['biome', 'ignore'].join('-'));
 
 const toPosix = (path: string): string => path.split(sep).join('/');
 
+// A managed path is a file or a symlink. A symlink's identity is its target,
+// never the content it resolves to: mirroring must reproduce the link itself,
+// and following it would copy the whole target tree into every consumer.
+export type ManagedEntry =
+  | { readonly kind: 'file'; readonly absolutePath: string }
+  | {
+      readonly kind: 'symlink';
+      readonly absolutePath: string;
+      readonly target: string;
+    }
+  // Only ever observed when inspecting a destination a consumer replaced; the
+  // upstream walk descends into directories instead of recording them.
+  | { readonly kind: 'directory'; readonly absolutePath: string };
+
+// Built rather than written as an escape so this source file stays plain ASCII
+// and greppable. File digests remain plain content hashes, so existing consumer
+// locks keep validating; the markers only need to be unreachable content for a
+// canonical file, and no text file begins with a NUL byte.
+const nul = String.fromCharCode(0);
+const SYMLINK_DIGEST_PREFIX = `${nul}standards-symlink${nul}`;
+const DIRECTORY_DIGEST = `${nul}standards-directory${nul}`;
+
+export const inspectManagedPath = async (
+  path: string,
+): Promise<ManagedEntry | null> => {
+  const info = await lstat(path).catch(() => null);
+  if (info === null) {
+    return null;
+  }
+  if (info.isSymbolicLink()) {
+    return {
+      kind: 'symlink',
+      absolutePath: path,
+      target: toPosix(await readlink(path)),
+    };
+  }
+  if (info.isDirectory()) {
+    return { kind: 'directory', absolutePath: path };
+  }
+  return { kind: 'file', absolutePath: path };
+};
+
 const walkManagedFiles = async (
   path: string,
   repositoryRoot: string,
-  files: Map<string, string>,
+  files: Map<string, ManagedEntry>,
 ): Promise<void> => {
-  const info = await stat(path).catch(() => null);
-  if (info === null) {
+  const entry = await inspectManagedPath(path);
+  if (entry === null) {
     return;
   }
-  if (info.isDirectory()) {
+  if (entry.kind === 'directory') {
     const entries = await readdir(path);
     await Promise.all(
       entries
-        .filter((entry) => !IGNORED_DIRECTORIES.has(entry))
-        .map((entry) =>
-          walkManagedFiles(join(path, entry), repositoryRoot, files),
+        .filter((name) => !IGNORED_DIRECTORIES.has(name))
+        .map((name) =>
+          walkManagedFiles(join(path, name), repositoryRoot, files),
         ),
     );
     return;
   }
-  files.set(toPosix(relative(repositoryRoot, path)), path);
+  files.set(toPosix(relative(repositoryRoot, path)), entry);
 };
 
 export const listManagedFiles = async (
   repositoryRoot: string,
   paths: ReadonlyArray<string>,
-): Promise<ReadonlyMap<string, string>> => {
-  const files = new Map<string, string>();
+): Promise<ReadonlyMap<string, ManagedEntry>> => {
+  const files = new Map<string, ManagedEntry>();
   await Promise.all(
     paths.map((path) =>
       walkManagedFiles(join(repositoryRoot, path), repositoryRoot, files),
@@ -52,12 +102,64 @@ export const listManagedFiles = async (
   return files;
 };
 
+// What the lock hashes for an entry: file content, or the marker-prefixed link
+// target. Retargeting a link therefore reads as drift the same way an edited
+// file does.
+export const managedEntryDigestInput = (
+  entry: ManagedEntry,
+): Promise<Buffer> => {
+  if (entry.kind === 'symlink') {
+    return Promise.resolve(
+      Buffer.from(`${SYMLINK_DIGEST_PREFIX}${entry.target}`),
+    );
+  }
+  if (entry.kind === 'directory') {
+    return Promise.resolve(Buffer.from(DIRECTORY_DIGEST));
+  }
+  return readFile(entry.absolutePath);
+};
+
+// Plant one managed entry, replacing a file or a link that occupies the
+// destination. Never recursive: a directory at the destination is unbounded
+// consumer content, so removing it is the caller's decision to make explicitly
+// once it has proven the path was engine-owned.
+export const writeManagedEntry = async (
+  dest: string,
+  entry: ManagedEntry,
+): Promise<void> => {
+  if (entry.kind === 'directory') {
+    throw new Error(`cannot mirror a directory as a managed path: ${dest}`);
+  }
+  const existing = await inspectManagedPath(dest);
+  if (existing?.kind === 'directory') {
+    throw new Error(
+      `refusing to replace the directory ${dest} with a managed ${entry.kind}; move or delete it first`,
+    );
+  }
+  // `symlink` refuses an existing path, and writing a file through a stale link
+  // would clobber that link's target instead of replacing the managed path.
+  if (
+    existing !== null &&
+    (entry.kind === 'symlink' || existing.kind === 'symlink')
+  ) {
+    await rm(dest, { force: true });
+  }
+  if (entry.kind === 'symlink') {
+    await symlink(entry.target, dest);
+    return;
+  }
+  await writeFile(dest, await readFile(entry.absolutePath));
+};
+
 export const findManagedFilesContainingBiomeDirectiveToken = async (
-  files: ReadonlyMap<string, string>,
+  files: ReadonlyMap<string, ManagedEntry>,
 ): Promise<ReadonlyArray<string>> => {
   const matches = await Promise.all(
-    [...files].map(async ([path, absolutePath]) =>
-      (await readFile(absolutePath)).includes(directiveToken) ? path : null,
+    [...files].map(async ([path, entry]) =>
+      entry.kind === 'file' &&
+      (await readFile(entry.absolutePath)).includes(directiveToken)
+        ? path
+        : null,
     ),
   );
   return matches.filter((path): path is string => path !== null).sort();

package/src/managed-path-ownership.ts

@@ -0,0 +1,85 @@
+// Ownership questions about a destination path, asked before init/sync writes
+// to it or deletes it. Both answers come from the lock: it is the only record of
+// what this engine put in a consumer, so anything absent from it is consumer
+// work that a mirror must never destroy.
+
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inspectManagedPath, type ManagedEntry } from './managed-files';
+
+const collectPaths = async (
+  root: string,
+  rel: string,
+  found: Array<string>,
+): Promise<void> => {
+  const entry = await inspectManagedPath(join(root, rel));
+  if (entry === null) {
+    return;
+  }
+  if (entry.kind === 'directory') {
+    const names = await readdir(join(root, rel));
+    await Promise.all(
+      names.map((name) => collectPaths(root, `${rel}/${name}`, found)),
+    );
+    return;
+  }
+  found.push(rel);
+};
+
+// Paths inside `rel` that the lock never recorded, so a caller can tell an
+// engine-owned tree from consumer work. An older CLI that followed a canonical
+// link materialized its whole target tree and locked every path in it; a
+// consumer's own file under the same directory is absent from the lock. Nothing
+// here follows a symlink: every entry is judged where it sits.
+export const unlockedPathsUnder = async (
+  root: string,
+  rel: string,
+  locked: ReadonlySet<string>,
+): Promise<ReadonlyArray<string>> => {
+  const found: Array<string> = [];
+  await collectPaths(root, rel, found);
+  return found.filter((path) => !locked.has(path)).sort();
+};
+
+// An ancestor that is not a directory, so nothing can sit below it under the
+// name the lock recorded. The kind is part of the answer: below a symlink the
+// name still resolves, to somebody else's content, while below a file it
+// resolves to nothing at all.
+export type InterposedAncestor = {
+  readonly rel: string;
+  readonly kind: 'file' | 'symlink';
+};
+
+// The shallowest ancestor of `rel` inside `root` that is not a directory, or
+// null when the whole parent chain is directories.
+//
+// `planned` is the payload this run mirrors, and it wins over the disk: every
+// path in it has the kind upstream gives it once the mirror has finished, and
+// the caller runs after the mirror. A dry run, which writes nothing, therefore
+// reaches the same answer the matching real run does.
+//
+// A path whose parent chain crosses a link does not name what the caller thinks
+// it names: reading or removing it reaches into the link's target tree, which
+// is somebody else's content.
+export const interposedAncestor = async (
+  root: string,
+  rel: string,
+  planned: ReadonlyMap<string, ManagedEntry>,
+): Promise<InterposedAncestor | null> => {
+  const segments = rel.split('/').slice(0, -1);
+  const prefixes = segments.map((_, depth) =>
+    segments.slice(0, depth + 1).join('/'),
+  );
+  const entries = await Promise.all(
+    prefixes.map(
+      (prefix) => planned.get(prefix) ?? inspectManagedPath(join(root, prefix)),
+    ),
+  );
+  for (const [index, prefix] of prefixes.entries()) {
+    const entry = entries[index] ?? null;
+    if (entry !== null && entry.kind !== 'directory') {
+      return { rel: prefix, kind: entry.kind };
+    }
+  }
+  return null;
+};

package/src/poller-closing-reference.ts

@@ -0,0 +1,179 @@
+const CLOSING_KEYWORD_PATTERN = String.raw`(?:close(?:s|d)?|fix(?:es|ed)?|resolve(?:s|d)?):?[ \t]+#`;
+const FENCE_OPEN_PATTERN = /^ {0,3}(?<marker>`{3,}|~{3,})(?<info>[^\r\n]*)$/u;
+const BODY_LINE_PATTERN = /\r?\n/u;
+const INDENTED_CODE_PATTERN = /^ {0,3}\t|^ {4}/u;
+const COMMENT_START = '<!--';
+const COMMENT_END = '-->';
+
+type BacktickRun = {
+  readonly start: number;
+  readonly end: number;
+};
+
+const isEscaped = (line: string, index: number): boolean => {
+  let backslashes = 0;
+  for (
+    let cursor = index - 1;
+    cursor >= 0 && line[cursor] === '\\';
+    cursor -= 1
+  ) {
+    backslashes += 1;
+  }
+  return backslashes % 2 === 1;
+};
+
+const nextBacktickRun = (line: string, from: number): BacktickRun | null => {
+  let start = line.indexOf('`', from);
+  while (start !== -1) {
+    let end = start + 1;
+    while (line[end] === '`') {
+      end += 1;
+    }
+    if (!isEscaped(line, start)) {
+      return { start, end };
+    }
+    start = line.indexOf('`', end);
+  }
+  return null;
+};
+
+const matchingBacktickRun = (
+  line: string,
+  opener: BacktickRun,
+): BacktickRun | null => {
+  const ticks = opener.end - opener.start;
+  let candidate = nextBacktickRun(line, opener.end);
+  while (candidate !== null) {
+    if (candidate.end - candidate.start === ticks) {
+      return candidate;
+    }
+    candidate = nextBacktickRun(line, candidate.end);
+  }
+  return null;
+};
+
+const nextActiveCommentStart = (line: string, from: number): number => {
+  let cursor = from;
+  while (cursor < line.length) {
+    const comment = line.indexOf(COMMENT_START, cursor);
+    const opener = nextBacktickRun(line, cursor);
+    if (
+      comment !== -1 &&
+      !isEscaped(line, comment) &&
+      (opener === null || comment < opener.start)
+    ) {
+      return comment;
+    }
+    if (opener === null) {
+      return -1;
+    }
+    const closer = matchingBacktickRun(line, opener);
+    cursor = closer === null ? opener.end : closer.end;
+  }
+  return -1;
+};
+
+const commentIsOpenAfter = (line: string, initiallyOpen: boolean): boolean => {
+  let open = initiallyOpen;
+  let cursor = 0;
+  while (cursor < line.length) {
+    const marker = open
+      ? line.indexOf(COMMENT_END, cursor)
+      : nextActiveCommentStart(line, cursor);
+    if (marker === -1) {
+      return open;
+    }
+    open = !open;
+    cursor = marker + (open ? COMMENT_START.length : COMMENT_END.length);
+  }
+  return open;
+};
+
+const isIndentedCodeLine = (
+  lines: ReadonlyArray<string>,
+  index: number,
+): boolean => {
+  if (!INDENTED_CODE_PATTERN.test(lines[index] ?? '')) {
+    return false;
+  }
+  for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+    const previous = lines[cursor] ?? '';
+    if (previous.trim().length === 0) {
+      return true;
+    }
+    if (!INDENTED_CODE_PATTERN.test(previous)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+const commentStateAfterContentLine = (
+  lines: ReadonlyArray<string>,
+  index: number,
+  initiallyOpen: boolean,
+): boolean => {
+  if (!initiallyOpen && isIndentedCodeLine(lines, index)) {
+    return false;
+  }
+  return commentIsOpenAfter(lines[index] ?? '', initiallyOpen);
+};
+
+const fenceCloseForLine = (line: string): RegExp | null => {
+  const groups = FENCE_OPEN_PATTERN.exec(line)?.groups;
+  const marker = groups?.marker;
+  if (
+    marker === undefined ||
+    (marker[0] === '`' && (groups?.info ?? '').includes('`'))
+  ) {
+    return null;
+  }
+  return new RegExp(`^ {0,3}${marker[0]}{${marker.length},}[ \\t]*$`, 'u');
+};
+
+type MarkdownState = {
+  readonly fenceClose: RegExp | null;
+  readonly commentOpen: boolean;
+};
+
+const markdownStateAfterContentLine = (
+  lines: ReadonlyArray<string>,
+  index: number,
+  state: MarkdownState,
+): MarkdownState => {
+  const line = lines[index] ?? '';
+  if (state.fenceClose !== null) {
+    return {
+      fenceClose: state.fenceClose.test(line) ? null : state.fenceClose,
+      commentOpen: state.commentOpen,
+    };
+  }
+  const fenceClose = state.commentOpen ? null : fenceCloseForLine(line);
+  return {
+    fenceClose,
+    commentOpen:
+      fenceClose === null
+        ? commentStateAfterContentLine(lines, index, state.commentOpen)
+        : state.commentOpen,
+  };
+};
+
+export const hasClosingReferenceToIssue = (
+  body: string,
+  issueNumber: number,
+): boolean => {
+  const reference = new RegExp(
+    `^${CLOSING_KEYWORD_PATTERN}${issueNumber}$`,
+    'iu',
+  );
+  const lines = body.split(BODY_LINE_PATTERN);
+  if (!reference.test(lines.at(-1) ?? '')) {
+    return false;
+  }
+  let state: MarkdownState = { fenceClose: null, commentOpen: false };
+  const content = lines.slice(0, -1);
+  for (const [index] of content.entries()) {
+    state = markdownStateAfterContentLine(content, index, state);
+  }
+  return state.fenceClose === null && !state.commentOpen;
+};

package/src/poller-fix-outcome.ts

@@ -1,3 +1,4 @@
+import type { CodexRunResult } from './poller-codex';
 import type { FixPublication } from './poller-fix-publication';
 import { createComment } from './poller-github-write';
 import {
@@ -6,8 +7,16 @@ import {
   type JobLabels,
   releaseLabels,
 } from './poller-job-shared';
+import { readFixOutcome } from './poller-outcome';
 import type { FixOutcome } from './poller-protocol';
 
+export const readFixRunOutcome = (
+  run: CodexRunResult,
+  workDir: string,
+  issueNumber: number,
+): Promise<FixOutcome | null> =>
+  run.succeeded ? readFixOutcome(workDir, issueNumber) : Promise.resolve(null);
+
 export const handleNonFixedOutcome = async (
   job: FixPublication,
   labels: JobLabels,

package/src/poller-fix-publication.ts

@@ -16,10 +16,7 @@ import {
   type JobLabels,
   releaseLabels,
 } from './poller-job-shared';
-import {
-  changedWorkspaceQualityManifests,
-  lockedPathsOf,
-} from './poller-protected-paths';
+import { lockedPathsOf } from './poller-protected-paths';
 import {
   APPROVED_FOR_REVIEW,
   type FixOutcome,
@@ -150,14 +147,10 @@ export const finishFixedJob = async (
     return `#${issue.number}: failed (fixed without commits)`;
   }
   const paths = changedPaths(workspace.dir, workspace.baseSha);
-  const forbidden = [
-    ...forbiddenDiffPaths(paths, await lockedPathsOf(workspace.dir)),
-    ...changedWorkspaceQualityManifests(
-      workspace.dir,
-      workspace.baseSha,
-      paths,
-    ),
-  ];
+  const forbidden = forbiddenDiffPaths(
+    paths,
+    await lockedPathsOf(workspace.dir),
+  );
   if (forbidden.length > 0) {
     await failJob(
       deps,

package/src/poller-fix-run.ts

@@ -5,7 +5,7 @@ import { hasLabel } from './github-label-identity';
 import { approvalIsCurrent, issueRevision } from './poller-approval';
 import { startClaim, withClaimReleasedOnFailure } from './poller-claim';
 import { runCodex } from './poller-codex';
-import { handleNonFixedOutcome } from './poller-fix-outcome';
+import { handleNonFixedOutcome, readFixRunOutcome } from './poller-fix-outcome';
 import { readSealedFixOutput } from './poller-fix-output';
 import {
   type FixPublication,
@@ -21,7 +21,6 @@ import {
   type JobResult,
   jobPreamble,
 } from './poller-job-shared';
-import { readFixOutcome } from './poller-outcome';
 import { fixPrompt } from './poller-prompts';
 import {
   APPROVED_FOR_FIX,
@@ -170,7 +169,7 @@ export const runFixJob = async (
       config,
     });
     await validateFixClaim(job);
-    const outcome = run.succeeded ? await readFixOutcome(workspace.dir) : null;
+    const outcome = await readFixRunOutcome(run, workspace.dir, issue.number);
     if (outcome === null) {
       await failJob(
         deps,

package/src/poller-fix-validation.ts

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { hasClosingReferenceToIssue } from './poller-closing-reference';
 import type { SealedFixOutput } from './poller-fix-output';
 import type { JobDeps } from './poller-job-shared';
 import {
@@ -7,10 +8,7 @@ import {
   createValidationWorktree,
   isAncestor,
 } from './poller-output-integrity';
-import {
-  changedWorkspaceQualityManifests,
-  lockedPathsOf,
-} from './poller-protected-paths';
+import { lockedPathsOf } from './poller-protected-paths';
 import { forbiddenDiffPaths } from './poller-protocol';
 
 export const validateSealedFixOutput = async (
@@ -27,6 +25,7 @@ export const validateSealedFixOutput = async (
     output.repo !== job.deps.repo ||
     output.issueNumber !== job.issueNumber ||
     output.approvalId !== job.approvalId ||
+    !hasClosingReferenceToIssue(output.body, job.issueNumber) ||
     !isAncestor(job.cloneDir, output.baseSha, job.defaultBranch) ||
     !isAncestor(job.cloneDir, output.baseSha, output.generatedHead) ||
     commitCountBetween(job.cloneDir, output.baseSha, output.generatedHead) !==
@@ -49,10 +48,10 @@ export const validateSealedFixOutput = async (
     ),
   );
   try {
-    const forbidden = [
-      ...forbiddenDiffPaths(paths, await lockedPathsOf(workspace.dir)),
-      ...changedWorkspaceQualityManifests(workspace.dir, output.baseSha, paths),
-    ];
+    const forbidden = forbiddenDiffPaths(
+      paths,
+      await lockedPathsOf(workspace.dir),
+    );
     if (forbidden.length > 0) {
       throw new Error(
         `sealed fix output modified protected paths:\n${forbidden.join('\n')}`,

package/src/poller-outcome.ts

@@ -7,6 +7,7 @@ import { existsSync, rmSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isNonEmptyString, isRecord } from './github-settings-parse';
+import { hasClosingReferenceToIssue } from './poller-closing-reference';
 import {
   type FixOutcome,
   OUTCOME_FILE,
@@ -59,6 +60,7 @@ const PR_TITLE_PATTERN = /^[a-z]+(?:\([^)]+\))?!?: .+/u;
 
 export const readFixOutcome = async (
   workDir: string,
+  issueNumber: number,
 ): Promise<FixOutcome | null> => {
   const raw = await readOutcomeRaw(workDir);
   if (
@@ -78,7 +80,8 @@ export const readFixOutcome = async (
     !(
       isNonEmptyString(raw.prTitle) &&
       PR_TITLE_PATTERN.test(raw.prTitle) &&
-      isNonEmptyString(raw.prBody)
+      isNonEmptyString(raw.prBody) &&
+      hasClosingReferenceToIssue(raw.prBody, issueNumber)
     )
   ) {
     return null;

package/src/poller-protected-paths.ts

@@ -1,11 +1,7 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isRecord } from './github-settings-parse';
-import { changesWorkspaceQualityScripts } from './poller-protocol';
-import { runGit } from './poller-workspace';
-
-const WORKSPACE_MANIFEST = /^(?:apps|packages)\/[^/]+\/package\.json$/u;
 
 export const lockedPathsOf = async (
   workDir: string,
@@ -29,23 +25,3 @@ export const lockedPathsOf = async (
     );
   }
 };
-
-export const changedWorkspaceQualityManifests = (
-  workDir: string,
-  baseSha: string,
-  paths: ReadonlyArray<string>,
-): ReadonlyArray<string> =>
-  paths.filter((path) => {
-    if (!WORKSPACE_MANIFEST.test(path)) {
-      return false;
-    }
-    try {
-      return changesWorkspaceQualityScripts(
-        path,
-        runGit(['-C', workDir, 'show', `${baseSha}:${path}`], null),
-        readFileSync(join(workDir, path), 'utf8'),
-      );
-    } catch {
-      return true;
-    }
-  });

package/src/poller-protocol.ts

@@ -76,8 +76,6 @@ const GATE_WIRING_FILES: ReadonlySet<string> = new Set([
 const HOST_SECRETS_FILE = /(?:^|\/)secrets\.yaml$/u;
 const WORKSPACE_GATE_CONFIG =
   /(?:^|\/)(?:biome\.jsonc|turbo\.json|tsconfig(?:\.[^.]+)?\.json|vitest\.config\.[cm]?[jt]s|playwright\.config\.[cm]?[jt]s)$/u;
-const QUALITY_SCRIPT = /^(?:check|lint|test|typecheck)(?::|$)/u;
-const WORKSPACE_MANIFEST = /^(?:apps|packages)\/[^/]+\/package\.json$/u;
 
 const isEncryptedSecret = (path: string): boolean =>
   !path.endsWith('.example.yaml') &&
@@ -101,46 +99,6 @@ export const forbiddenDiffPaths = (
   );
 };
 
-const qualityScripts = (
-  manifest: unknown,
-): Readonly<Record<string, string>> => {
-  if (
-    typeof manifest !== 'object' ||
-    manifest === null ||
-    !('scripts' in manifest) ||
-    typeof manifest.scripts !== 'object' ||
-    manifest.scripts === null
-  ) {
-    return {};
-  }
-  return Object.fromEntries(
-    Object.entries(manifest.scripts)
-      .filter(
-        (entry): entry is [string, string] =>
-          QUALITY_SCRIPT.test(entry[0]) && typeof entry[1] === 'string',
-      )
-      .sort(([left], [right]) => left.localeCompare(right)),
-  );
-};
-
-export const changesWorkspaceQualityScripts = (
-  path: string,
-  before: string,
-  after: string,
-): boolean => {
-  if (path === 'package.json' || !WORKSPACE_MANIFEST.test(path)) {
-    return false;
-  }
-  try {
-    return (
-      JSON.stringify(qualityScripts(JSON.parse(before) as unknown)) !==
-      JSON.stringify(qualityScripts(JSON.parse(after) as unknown))
-    );
-  } catch {
-    return true;
-  }
-};
-
 export const branchNameForIssue = (
   issueNumber: number,
   approvalId: string,