@rungs/cli 0.3.0 → 0.4.0

package/src/engines2.ts

@@ -1,12 +1,16 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { execSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
+import { TextDecoder } from 'node:util';
+import { resolveEmittedPath } from './emitted-path.ts';
 import { matchAny } from './glob.ts';
+import { readVersionSource } from './version-source.ts';
 import type { Engine, Finding } from './engines.ts';
+import { semanticText } from './text.ts';
 
 const read = (root: string, rel: string) => {
   try {
-    return readFileSync(join(root, rel), 'utf8');
+    return semanticText(readFileSync(join(root, rel), 'utf8'));
   } catch {
     return '';
   }
@@ -159,6 +163,12 @@ export const registerSchema: Engine = (t, root, files) => {
       }
       for (const row of table.rows) {
         if (Object.values(row).every((v) => !v || v === '—')) continue;
+        // An em dash in the identity column is an explicit no-record row. The
+        // generated findings register uses it to keep an empty table legible:
+        // `| — | | | *nothing open* | ... |`. Looking only for an entirely
+        // blank row made that label turn the placeholder into a malformed real
+        // finding on the first `rungs check` in a fresh tracked consumer.
+        if (strip(Object.values(row)[0]) === '—') continue;
         examined++;
         for (const [key, values] of Object.entries<any>(t.enum ?? {})) {
           const v = strip(row[key]);
@@ -344,12 +354,394 @@ export const crossReference: Engine = (t, root, files) => {
  * this repo does not use — it deletes branches on merge — and it is the
  * direction to be wrong in, because the alternative is the daily false positive.
  */
+/**
+ * `git` as an argv array, never a shell string.
+ *
+ * `--format=%(refname:short)` is a **bash syntax error** — unquoted parentheses —
+ * so `backlog-merged-status` threw on every Linux and macOS repo, hit its catch,
+ * and reported "cannot read git branches; status not reconciled" as a finding.
+ * The gate ships in four of five profiles and had never once worked off Windows,
+ * where `execSync` goes through cmd.exe and parentheses are ordinary characters.
+ * Found by the CI matrix on its first run (F-033).
+ *
+ * Branch names come out of work-item frontmatter, so this is also the difference
+ * between reading a field and passing it to a shell.
+ */
+const gitArgs = (root: string, args: string[]) =>
+  execFileSync('git', args, { cwd: root, stdio: 'pipe' }).toString().trim();
+
+export const parseGitPathList = (output: string): string[] =>
+  output.split('\0').filter(Boolean);
+
+const gitPaths = (root: string, args: string[]) =>
+  parseGitPathList(execFileSync('git', args, { cwd: root, stdio: 'pipe' }).toString());
+
+const gitRefExists = (root: string, ref: string): boolean => {
+  try {
+    gitArgs(root, ['show-ref', '--verify', '--quiet', ref]);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export type IntegrationRefResolution =
+  | { ref: string; finding?: never }
+  | { ref?: never; finding: string };
+
+/**
+ * Resolve a configured branch name without Git's short-name DWIM rules.
+ *
+ * CI checkouts commonly have `origin/main` but no local `main`. Conversely, a
+ * developer checkout can carry both, temporarily at different commits. The
+ * precedence here is deliberate and stable as more remotes appear: local,
+ * exact `origin`, then a sole matching remote. More than one non-origin match
+ * is unknown, not permission to choose whichever ref Git happens to prefer.
+ */
+export function resolveIntegrationRef(root: string, branch: string): IntegrationRefResolution {
+  const local = `refs/heads/${branch}`;
+  if (gitRefExists(root, local)) return { ref: local };
+
+  const origin = `refs/remotes/origin/${branch}`;
+  if (gitRefExists(root, origin)) return { ref: origin };
+
+  const remotes = gitArgs(root, ['remote'])
+    .split('\n')
+    .map((remote) => remote.trim())
+    .filter((remote) => remote && remote !== 'origin');
+  const matches = remotes
+    .map((remote) => `refs/remotes/${remote}/${branch}`)
+    .filter((ref) => gitRefExists(root, ref))
+    .sort();
+
+  if (matches.length === 1) return { ref: matches[0] };
+  if (matches.length > 1) {
+    return {
+      finding: `integration branch '${branch}' is ambiguous across ${matches.join(', ')}`,
+    };
+  }
+  return {
+    finding: `integration branch '${branch}' has no local or remote-tracking ref`,
+  };
+}
+
+const matchesAny = (rel: string, patterns: string[] | undefined) =>
+  (patterns ?? []).some((pattern) => matchAny([rel], pattern).length > 0);
+
+const patternList = (value: unknown, allowEmpty = false): value is string[] =>
+  Array.isArray(value) && (allowEmpty || value.length > 0) &&
+  value.every((pattern) => typeof pattern === 'string' && pattern.trim().length > 0);
+
+type ExemptionWrapper = { kind: 'plain' | 'line' | 'block' | 'html' | 'quote'; close?: string };
+
+function wrapperCloseAt(reason: string, wrapper: ExemptionWrapper): number {
+  if (!wrapper.close) return -1;
+  if (wrapper.kind !== 'quote') return reason.indexOf(wrapper.close);
+  for (let index = 0; index < reason.length; index++) {
+    if (reason[index] === '\\') {
+      index++;
+    } else if (reason[index] === wrapper.close) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Extract substantive same-line reasons while retaining wrapper state across
+ * the whole document. A marker on the second line of a block, HTML comment or
+ * quoted string must still stop at that wrapper's close token; otherwise an
+ * adjacent code-only edit would be mistaken for a new reason.
+ */
+function exemptionEvidence(text: string, marker: string): string[] {
+  const evidence: string[] = [];
+  let wrapper: ExemptionWrapper = { kind: 'plain' };
+
+  for (let index = 0; index < text.length; index++) {
+    if (text.startsWith(marker, index)) {
+      const reasonAt = index + marker.length;
+      const cr = text.indexOf('\r', reasonAt);
+      const lf = text.indexOf('\n', reasonAt);
+      const lineEnd = cr < 0 ? (lf < 0 ? text.length : lf) :
+        (lf < 0 ? cr : Math.min(cr, lf));
+      const rawTail = text.slice(reasonAt, lineEnd);
+      const leading = rawTail.match(/^[ \t]*/)?.[0].length ?? 0;
+      if (/[\p{L}\p{N}]/u.test(rawTail[leading] ?? '')) {
+        let reason = rawTail.slice(leading);
+        const closeAt = wrapperCloseAt(reason, wrapper);
+        if (closeAt >= 0) reason = reason.slice(0, closeAt);
+        reason = reason.trimEnd();
+        if (reason) evidence.push(reason);
+      }
+    }
+
+    if (wrapper.kind === 'line') {
+      if (text[index] === '\r' || text[index] === '\n') wrapper = { kind: 'plain' };
+      continue;
+    }
+    if (wrapper.kind === 'block') {
+      if (text.startsWith('*/', index)) {
+        wrapper = { kind: 'plain' };
+        index++;
+      }
+      continue;
+    }
+    if (wrapper.kind === 'html') {
+      if (text.startsWith('-->', index)) {
+        wrapper = { kind: 'plain' };
+        index += 2;
+      }
+      continue;
+    }
+    if (wrapper.kind === 'quote') {
+      if (text[index] === '\\') {
+        index++;
+      } else if (text[index] === wrapper.close) {
+        wrapper = { kind: 'plain' };
+      }
+      continue;
+    }
+
+    if (text.startsWith('//', index)) {
+      wrapper = { kind: 'line' };
+      index++;
+    } else if (text.startsWith('/*', index)) {
+      wrapper = { kind: 'block', close: '*/' };
+      index++;
+    } else if (text.startsWith('<!--', index)) {
+      wrapper = { kind: 'html', close: '-->' };
+      index += 3;
+    } else if (text[index] === '"' || text[index] === "'" || text[index] === '`') {
+      wrapper = { kind: 'quote', close: text[index] };
+    }
+  }
+  return evidence;
+}
+
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+
+type GitTreeEntry = { mode: string; type: string; oid: string };
+
+function gitTreeEntry(root: string, treeish: string, rel: string): GitTreeEntry | undefined {
+  const output = execFileSync(
+    'git',
+    ['--literal-pathspecs', 'ls-tree', '-z', treeish, '--', rel],
+    { cwd: root, stdio: 'pipe' },
+  );
+  if (!output.length) return undefined;
+  const records = output.toString('utf8').split('\0').filter(Boolean);
+  if (records.length !== 1) throw new Error(`unexpected tree entry count for ${rel}`);
+  const match = records[0].match(/^([0-7]{6}) ([a-z]+) ([0-9a-f]+)\t/);
+  if (!match) throw new Error(`cannot parse tree entry for ${rel}`);
+  return { mode: match[1], type: match[2], oid: match[3] };
+}
+
+function candidateGitModesAreRegular(root: string, rel: string): boolean {
+  const output = execFileSync(
+    'git',
+    ['--literal-pathspecs', 'ls-files', '--stage', '-z', '--', rel],
+    { cwd: root, stdio: 'pipe' },
+  );
+  const entries = output.toString('utf8').split('\0').filter(Boolean).map((record) => {
+    const match = record.match(/^([0-7]{6}) [0-9a-f]+ ([0-3])\t/);
+    if (!match) throw new Error(`cannot parse index entry for ${rel}`);
+    return { mode: match[1], stage: match[2] };
+  });
+
+  // The index is the current proposed Git object when it has an entry. An
+  // absent entry is an untracked path whose canonical filesystem leaf was
+  // already proven regular above. HEAD is deliberately irrelevant here: its
+  // historical mode must not veto a staged conversion to an ordinary blob.
+  return entries.length === 0 ||
+    (entries.length === 1 && entries[0].stage === '0' &&
+      ['100644', '100755'].includes(entries[0].mode));
+}
+
+function candidateExemptionText(root: string, rel: string): string | undefined {
+  let resolved;
+  try {
+    resolved = resolveEmittedPath(root, 'release exemption evidence', rel);
+    if (resolved.leafAlias || !lstatSync(resolved.absolute).isFile()) return undefined;
+  } catch {
+    return undefined;
+  }
+  if (!candidateGitModesAreRegular(root, rel)) return undefined;
+
+  const attributes = execFileSync(
+    'git',
+    ['check-attr', '-z', 'diff', 'text', 'binary', '--', rel],
+    { cwd: root, stdio: 'pipe' },
+  ).toString().split('\0');
+  for (let index = 0; index + 2 < attributes.length; index += 3) {
+    const attribute = attributes[index + 1];
+    const value = attributes[index + 2];
+    if ((attribute === 'diff' && value === 'unset') || (attribute === 'binary' && value === 'set')) {
+      return undefined;
+    }
+  }
+
+  try {
+    const bytes = readFileSync(resolved.absolute);
+    if (bytes.includes(0)) return undefined;
+    return utf8.decode(bytes);
+  } catch {
+    return undefined;
+  }
+}
+
+function inheritedExemptionEvidence(root: string, mergeBase: string, marker: string): Set<string> {
+  let paths = Buffer.alloc(0);
+  try {
+    paths = execFileSync(
+      'git',
+      ['grep', '-I', '-l', '-z', '-F', '-e', marker, mergeBase, '--'],
+      { cwd: root, stdio: 'pipe' },
+    );
+  } catch (error: any) {
+    if (error?.status !== 1) throw error;
+    paths = Buffer.isBuffer(error?.stdout) ? error.stdout : Buffer.from(error?.stdout ?? '');
+  }
+
+  const prefix = `${mergeBase}:`;
+  const inherited = new Set<string>();
+  for (const named of utf8.decode(paths).split('\0').filter(Boolean)) {
+    if (!named.startsWith(prefix)) throw new Error('cannot parse historical exemption path');
+    const rel = named.slice(prefix.length);
+    const entry = gitTreeEntry(root, mergeBase, rel);
+    if (!entry || entry.type !== 'blob') throw new Error(`cannot resolve historical exemption blob for ${rel}`);
+    const bytes = execFileSync('git', ['cat-file', 'blob', entry.oid], { cwd: root, stdio: 'pipe' });
+    if (bytes.includes(0)) throw new Error(`historical exemption blob is not text: ${rel}`);
+    for (const reason of exemptionEvidence(utf8.decode(bytes), marker)) inherited.add(reason);
+  }
+  return inherited;
+}
+
+/**
+ * Return only exemption evidence introduced by the complete current delta.
+ *
+ * Current files are read only through a canonical, regular-file, UTF-8 text
+ * boundary. The caller's complete changed-path set already spans committed,
+ * staged, unstaged and non-ignored untracked work, so staging does not select a
+ * different evidence path.
+ *
+ * A reason must be novel relative to every marker/reason line in the merge-base
+ * tree. That conservative rule makes the otherwise unknowable copy-vs-coincidence
+ * case deterministic in every Git state: reuse or relocation requires rewording
+ * the reason to explain why this branch is safe.
+ */
+function hasBranchLocalExemption(
+  root: string,
+  mergeBase: string,
+  changed: string[],
+  marker: string,
+): boolean {
+  const inherited = inheritedExemptionEvidence(root, mergeBase, marker);
+
+  return changed.some((rel) => {
+    const text = candidateExemptionText(root, rel);
+    return text !== undefined && exemptionEvidence(text, marker)
+      .some((reason) => !inherited.has(reason));
+  });
+}
+
+/**
+ * Require a changed companion file when a branch changes a configured path.
+ *
+ * A fragment that merely exists is not evidence for this branch: inherited and
+ * deleted fragments must not discharge its release-note obligation. Git state
+ * is read as four explicit sets so the verdict is the same before and after a
+ * developer stages or commits the work.
+ */
+export const changeRequiresFile: Engine = (t, root) => {
+  if (!patternList(t.require_when_changed) || !patternList(t.requires_one_of)) {
+    return {
+      findings: [{
+        message: "change-requires-file requires non-empty 'require_when_changed' and 'requires_one_of' pattern arrays",
+      }],
+      examined: 0,
+    };
+  }
+  if (t.ignore_when_only !== undefined && !patternList(t.ignore_when_only, true)) {
+    return {
+      findings: [{ message: "change-requires-file 'ignore_when_only' must be an array of non-empty patterns" }],
+      examined: 0,
+    };
+  }
+  if (t.exempt_marker !== undefined &&
+      (typeof t.exempt_marker !== 'string' || !t.exempt_marker.trim())) {
+    return {
+      findings: [{ message: "change-requires-file 'exempt_marker' must be a non-empty string when configured" }],
+      examined: 0,
+    };
+  }
+
+  const baseName = String(t.base_branch ?? 'main');
+  let changed: string[];
+  let mergeBase: string;
+  let untracked: string[];
+  try {
+    const resolved = resolveIntegrationRef(root, baseName);
+    if (!resolved.ref) {
+      return {
+        findings: [{ message: `${resolved.finding}; required companion file not evaluated` }],
+        examined: 0,
+      };
+    }
+    mergeBase = gitArgs(root, ['merge-base', 'HEAD', resolved.ref]);
+    untracked = gitPaths(root, ['ls-files', '--others', '--exclude-standard', '-z']);
+    changed = [...new Set([
+      ...gitPaths(root, ['diff', '--name-only', '--no-renames', '-z', mergeBase, 'HEAD']),
+      ...gitPaths(root, ['diff', '--cached', '--name-only', '--no-renames', '-z']),
+      ...gitPaths(root, ['diff', '--name-only', '--no-renames', '-z']),
+      ...untracked,
+    ])].sort();
+  } catch {
+    return {
+      findings: [{ message: `cannot read git changes against '${baseName}'; required companion file not evaluated` }],
+      examined: 0,
+    };
+  }
+
+  const examined = changed.length;
+  const ignore = t.ignore_when_only as string[] | undefined;
+  if (ignore?.length && changed.length && changed.every((rel) => matchesAny(rel, ignore))) {
+    return { findings: [], examined };
+  }
+
+  if (!changed.some((rel) => matchesAny(rel, t.require_when_changed))) {
+    return { findings: [], examined };
+  }
+
+  const companion = changed.find(
+    (rel) => matchesAny(rel, t.requires_one_of) && existsSync(join(root, rel)),
+  );
+  if (companion) return { findings: [], examined };
+
+  if (t.exempt_marker) {
+    try {
+      if (hasBranchLocalExemption(root, mergeBase, changed, t.exempt_marker)) {
+        return { findings: [], examined };
+      }
+    } catch {
+      return {
+        findings: [{ message: `cannot read git exemption provenance against '${baseName}'; required companion file not evaluated` }],
+        examined: 0,
+      };
+    }
+  }
+
+  return {
+    findings: [{ message: String(t.message ?? 'changed shipping code requires a companion file').trim() }],
+    examined,
+  };
+};
+
 function landedWork(root: string, branch: string, base: string): boolean {
-  const git = (cmd: string) => execSync(`git ${cmd}`, { cwd: root, stdio: 'pipe' }).toString().trim();
+  const git = (...args: string[]) => gitArgs(root, args);
   try {
-    const tip = git(`rev-parse ${branch}`);
-    if (tip === git(`rev-parse ${base}`)) return false;
-    return git(`log ${base} --merges --format=%P`)
+    const tip = git('rev-parse', branch);
+    if (tip === git('rev-parse', base)) return false;
+    return git('log', base, '--merges', '--format=%P')
       .split('\n')
       .some((line) => line.trim().split(/\s+/).slice(1).includes(tip));
   } catch {
@@ -362,13 +754,14 @@ function landedWork(root: string, branch: string, base: string): boolean {
 export const gitStatusReconcile: Engine = (t, root, files) => {
   const findings: Finding[] = [];
   let merged: Set<string>;
+  let integrationRef: string;
   try {
+    const integration = String(t.integration_branch ?? 'main');
+    const resolved = resolveIntegrationRef(root, integration);
+    if (!resolved.ref) return { findings: [{ message: `${resolved.finding}; status not reconciled` }], examined: 0 };
+    integrationRef = resolved.ref;
     merged = new Set(
-      execSync(`git branch --merged ${t.integration_branch ?? 'main'} --format=%(refname:short)`, {
-        cwd: root,
-        stdio: 'pipe',
-      })
-        .toString()
+      gitArgs(root, ['branch', '--merged', integrationRef, '--format=%(refname:short)'])
         .split('\n')
         .map((s) => s.trim())
         .filter(Boolean),
@@ -388,7 +781,7 @@ export const gitStatusReconcile: Engine = (t, root, files) => {
     if (
       merged.has(branch) &&
       (t.pre_review_statuses ?? []).includes(status) &&
-      landedWork(root, branch, t.integration_branch ?? 'main')
+      landedWork(root, branch, integrationRef)
     ) {
       findings.push({ file: rel, message: `branch ${branch} is merged but status is '${status}'` });
     }
@@ -403,6 +796,7 @@ export const computedClaim: Engine = (t, root, files) => {
   let examined = 0;
   for (const spec of specs) {
     const values = new Map<string, string>();
+    let specExamined = 0;
     // Which files share a version is the repo's judgement, not something to infer
     // (F-023). The default sources glob `*/package.json`, which is right for a
     // monorepo released in lockstep and wrong for a sibling that is deliberately
@@ -410,27 +804,28 @@ export const computedClaim: Engine = (t, root, files) => {
     // package, correctly, and installing the gate would have failed a healthy
     // layout. So a repo states the exceptions rather than the engine guessing
     // them, and `all-agree` keeps needing no opinion about which file is right.
-    const excluded = (rel: string) => (spec.exclude ?? []).some((p: string) => matchAny([rel], p).length > 0);
+    const excludePatterns = (spec.exclude ?? []).filter((pattern: unknown): pattern is string =>
+      typeof pattern === 'string' && pattern.trim().length > 0,
+    );
+    const excluded = (rel: string) => excludePatterns.some((pattern: string) => matchAny([rel], pattern).length > 0);
     for (const src of spec.sources ?? []) {
       for (const rel of matchAny(files, src.file)) {
         if (excluded(rel)) continue;
-        const text = read(root, rel);
-        let v: string | undefined;
-        if (src.path && rel.endsWith('.json')) {
-          try {
-            v = src.path.split('.').reduce((o: any, k: string) => o?.[k], JSON.parse(text));
-          } catch {
-            /* unparseable is not a disagreement */
-          }
-        } else if (src.xpath) {
-          v = text.match(new RegExp(`<${src.xpath.split('//')[1]}>(.*?)<`))?.[1];
-        }
-        if (v) {
-          examined++;
-          values.set(rel, String(v));
+        examined++;
+        specExamined++;
+        const result = readVersionSource(root, rel, src);
+        if (!result.ok) {
+          findings.push({ file: rel, message: `${spec.id} version source ${result.reason}` });
+          continue;
         }
+        values.set(rel, result.value);
       }
     }
+    if (specExamined === 0) {
+      findings.push({
+        message: `${spec.id} found no configured version sources; check the source globs and exclusions`,
+      });
+    }
     const distinct = new Set(values.values());
     if (spec.rule === 'all-agree' && distinct.size > 1) {
       // Name the file beside its value. The message used to list the distinct
@@ -444,7 +839,7 @@ export const computedClaim: Engine = (t, root, files) => {
         message:
           `${spec.id} disagrees across ${values.size} locations: ${where}` +
           (spec.autofix ? ` — run \`${spec.autofix}\`` : '') +
-          (spec.exclude?.length ? '' : '. If one of these is versioned independently, list it in `exclude`.'),
+          (excludePatterns.length ? '' : '. If one of these is versioned independently, set `release.version_exclude`.'),
       });
     }
   }