@rungs/cli 0.3.0 → 0.4.0

package/src/render.ts

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { walk } from './glob.ts';
+import { preflightEmittedPaths, resolveEmittedPath, type EmittedPathCandidate } from './emitted-path.ts';
+import { semanticText } from './text.ts';
 
 export type Harness = 'claude' | 'copilot' | 'cursor' | 'agents-md';
 
@@ -20,12 +22,18 @@ export interface RenderEntry {
   dropped?: string[];
 }
 
+export interface ProspectiveRule {
+  moduleName: string;
+  target: string;
+  content: string;
+}
+
 const DO_NOT_EDIT = (source: string) =>
   `Generated by \`rungs render\` from ${source}. Do not edit — your changes are overwritten.`;
 
 /** Parse `.ai/rules/*.md`: the neutral source ADR-0001 renders from. */
 export function readRules(repoRoot: string): Rule[] {
-  const dir = join(repoRoot, '.ai', 'rules');
+  const dir = resolveEmittedPath(repoRoot, 'render', '.ai/rules').absolute;
   const rules: Rule[] = [];
   let files: string[];
   try {
@@ -34,21 +42,26 @@ export function readRules(repoRoot: string): Rule[] {
     return rules;
   }
   for (const rel of files) {
-    const raw = readFileSync(join(dir, rel), 'utf8');
-    const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-    if (!m) continue;
-    const [, fm, body] = m;
-    rules.push({
-      file: rel,
-      description: scalar(fm, 'description'),
-      paths: list(fm, 'paths'),
-      enforcement: scalar(fm, 'enforcement'),
-      body: body.trim(),
-    });
+    const raw = semanticText(readFileSync(join(dir, rel), 'utf8'));
+    const rule = parseRule(rel, raw);
+    if (rule) rules.push(rule);
   }
   return rules;
 }
 
+function parseRule(file: string, raw: string): Rule | null {
+  const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) return null;
+  const [, fm, body] = m;
+  return {
+    file,
+    description: scalar(fm, 'description'),
+    paths: list(fm, 'paths'),
+    enforcement: scalar(fm, 'enforcement'),
+    body: body.trim(),
+  };
+}
+
 function scalar(fm: string, key: string): string | undefined {
   const folded = fm.match(new RegExp(`^${key}:\\s*>-?\\s*\\n([\\s\\S]*?)(?=\\n\\S|$)`, 'm'));
   if (folded) return folded[1].split('\n').map((l) => l.trim()).filter(Boolean).join(' ');
@@ -127,10 +140,40 @@ function commonDirPrefix(paths: string[]): string | null {
   return dirs.every((d) => d === first) && first.includes('/') ? first : null;
 }
 
-export function render(repoRoot: string, harnesses: Harness[]): RenderEntry[] {
+interface PreparedRender {
+  entries: RenderEntry[];
+  outputs: { entry: RenderEntry; absolute: string; content: string }[];
+  routingOnly: Rule[];
+}
+
+function prepareRender(
+  repoRoot: string,
+  harnesses: Harness[],
+  prospective: ProspectiveRule[] = [],
+  preceding: EmittedPathCandidate[] = [],
+): PreparedRender {
   const rules = readRules(repoRoot);
+  const owners = new Map(rules.map((rule) => [rule.file, 'render']));
+  const occupied = new Set(rules.map((rule) => `.ai/rules/${rule.file}`));
+
+  // Model the installer's no-overwrite rule: an existing source remains the
+  // one rendered.  New prospective rules are considered in module order, just
+  // as addModule will create the first and keep any later collision.
+  for (const pending of prospective) {
+    const source = resolveEmittedPath(repoRoot, pending.moduleName, pending.target);
+    if (occupied.has(source.target) || existsSync(source.absolute)) continue;
+    occupied.add(source.target);
+    if (!source.target.startsWith('.ai/rules/')) continue;
+    const file = source.target.slice('.ai/rules/'.length);
+    const rule = parseRule(file, pending.content);
+    if (!rule) continue;
+    rules.push(rule);
+    owners.set(file, pending.moduleName);
+  }
+
   const entries: RenderEntry[] = [];
   const routingOnly: Rule[] = [];
+  const planned: { entry: RenderEntry; target: string; content: string; owner: string }[] = [];
 
   for (const rule of rules) {
     for (const harness of harnesses) {
@@ -140,23 +183,62 @@ export function render(repoRoot: string, harnesses: Harness[]): RenderEntry[] {
         if (harness === 'agents-md') routingOnly.push(rule);
         continue;
       }
-      const full = join(repoRoot, out.target);
-      mkdirSync(dirname(full), { recursive: true });
-      writeFileSync(full, out.content);
-      entries.push({ rule: rule.file, harness, target: out.target, dropped: out.dropped });
+      const entry = { rule: rule.file, harness, target: out.target, dropped: out.dropped };
+      entries.push(entry);
+      planned.push({ entry, target: out.target, content: out.content, owner: owners.get(rule.file) ?? 'render' });
     }
   }
 
+  const candidates = [
+    ...preceding,
+    ...planned.map((out) => ({ moduleName: out.owner, target: out.target, writeExisting: true })),
+    ...(harnesses.includes('agents-md')
+      ? [{ moduleName: 'render', target: 'AGENTS.md', shared: true, writeExisting: true }]
+      : []),
+    { moduleName: 'render', target: '.ai/render-report.md', writeExisting: true },
+  ];
+  const resolved = preflightEmittedPaths(repoRoot, candidates);
+  return {
+    entries,
+    outputs: planned.map((out, index) => ({
+      entry: out.entry,
+      content: out.content,
+      absolute: resolved[preceding.length + index].absolute,
+    })),
+    routingOnly,
+  };
+}
+
+/** Validate all current and would-be post-install render outputs without writing. */
+export function preflightRender(
+  repoRoot: string,
+  harnesses: Harness[],
+  prospective: ProspectiveRule[] = [],
+  preceding: EmittedPathCandidate[] = [],
+): void {
+  prepareRender(repoRoot, harnesses, prospective, preceding);
+}
+
+export function render(repoRoot: string, harnesses: Harness[]): RenderEntry[] {
+  const prepared = prepareRender(repoRoot, harnesses);
+
+  for (const output of prepared.outputs) {
+    mkdirSync(dirname(output.absolute), { recursive: true });
+    writeFileSync(output.absolute, output.content);
+  }
+
   // The report said root AGENTS.md "gets a pointer" and nothing wrote one — a
   // degradation notice that was itself a silent drop, in the function whose
   // whole job is not to have those. Written now, as a managed block.
-  writeRoutingBlock(repoRoot, routingOnly, harnesses);
-  return entries;
+  writeRoutingBlock(repoRoot, prepared.routingOnly, harnesses);
+  return prepared.entries;
 }
 
 function writeRoutingBlock(repoRoot: string, rules: Rule[], harnesses: Harness[]) {
   if (!harnesses.includes('agents-md')) return;
-  const target = join(repoRoot, 'AGENTS.md');
+  const target = preflightEmittedPaths(repoRoot, [
+    { moduleName: 'render', target: 'AGENTS.md', shared: true, writeExisting: true },
+  ])[0].absolute;
   if (!existsSync(target)) return;
   const begin = '<!-- rungs:begin rules-routing -->';
   const end = '<!-- rungs:end rules-routing -->';
@@ -217,6 +299,9 @@ export function writeReport(repoRoot: string, entries: RenderEntry[], harnesses:
     '',
   );
   const content = lines.join('\n');
-  writeFileSync(join(repoRoot, '.ai', 'render-report.md'), content);
+  const target = preflightEmittedPaths(repoRoot, [
+    { moduleName: 'render', target: '.ai/render-report.md', writeExisting: true },
+  ])[0].absolute;
+  writeFileSync(target, content);
   return content;
 }

package/src/selftest.ts

@@ -1,4 +1,5 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { ENGINES, type Finding } from './engines.ts';
@@ -68,6 +69,49 @@ function build(root: string, table: any, fx: any, input?: string): string[] | nu
   if (typeof input === 'string') return [write(targetPath(table), `${input}\n`)];
   if (!fx || typeof fx !== 'object') return null;
 
+  // A branch delta plus the companion files it carries. Unlike content-only
+  // fixtures this needs a real repository: the engine deliberately observes
+  // committed, staged, unstaged and untracked Git state rather than trusting a
+  // fixture's list as the answer.
+  if (Array.isArray(fx.changed) && Array.isArray(fx.fragments)) {
+    const git = (...args: string[]) =>
+      execFileSync('git', args, { cwd: root, stdio: 'pipe' }).toString().trim();
+    const changed = fx.changed.map(String);
+    git('init', '-q', '-b', 'main', '.');
+    git('config', 'user.email', 'selftest@rungs.local');
+    git('config', 'user.name', 'rungs-selftest');
+    const written = [write('.fixture-base', 'base\n')];
+    if (changed.length && typeof fx.inherited_exempt === 'string') {
+      written.push(write(
+        changed[0],
+        `// ${fx.inherited_exempt}\nexport const fixtureState = 'base';\n`,
+      ));
+    }
+    git('add', '--all');
+    git('commit', '-q', '-m', 'base');
+    git('switch', '-q', '-c', 'fixture/change');
+
+    for (const [index, rel] of changed.entries()) {
+      const evidence = index === 0 && typeof fx.exempt === 'string'
+        ? fx.exempt
+        : index === 0 && typeof fx.inherited_exempt === 'string'
+          ? fx.inherited_exempt
+          : undefined;
+      const body = evidence
+        ? `// ${evidence}\nexport const fixtureState = 'branch';\n`
+        : 'fixture change\n';
+      written.push(write(rel, body));
+    }
+    const changelogDir = fx.dir ?? 'changelog.d';
+    for (const rel of fx.fragments) {
+      const concrete = String(rel).replace(/\{\{changelog_dir\}\}/g, changelogDir);
+      written.push(write(concrete, '# fixture fragment\n'));
+    }
+    git('add', '--all');
+    git('commit', '-q', '-m', 'fixture change');
+    return [...new Set(written)];
+  }
+
   // A set of manifests and the version each states — the computed-claim shapes.
   // `{ "package.json": "1.2.0", "site/package.json": "1.1.0" }`.
   if (fx.packages && typeof fx.packages === 'object') {
@@ -76,6 +120,26 @@ function build(root: string, table: any, fx: any, input?: string): string[] | nu
     );
   }
 
+  // Format-aware release-version sources. Values are rendered into the real
+  // source shape so one fixture can prove JSON, TOML and Directory.Build.props
+  // all participate in the same comparison.
+  if (fx.versions && typeof fx.versions === 'object') {
+    return Object.entries(fx.versions).map(([rel, version]) => {
+      const value = String(version).replace(/"/g, '\\"');
+      if (rel.endsWith('.toml')) return write(rel, `[project]\nversion = "${value}"\n`);
+      if (rel.endsWith('.props')) {
+        return write(rel, `<Project><PropertyGroup><Version>${String(version)}</Version></PropertyGroup></Project>\n`);
+      }
+      return write(rel, JSON.stringify({ name: rel.replace(/\W/g, '-'), version }));
+    });
+  }
+
+  // Raw version-source fixtures preserve malformed documents and missing or
+  // non-scalar values exactly; normalising them would erase the failure under test.
+  if (fx.version_files && typeof fx.version_files === 'object') {
+    return Object.entries(fx.version_files).map(([rel, content]) => write(rel, String(content)));
+  }
+
   // Named files in a parameterised directory, plus the version they are judged
   // against — the changelog shapes. `dir` is stated by the fixture rather than
   // assumed here, because the self-test sees the module's *raw* table and a
@@ -87,7 +151,19 @@ function build(root: string, table: any, fx: any, input?: string): string[] | nu
     // `changelog.d/*.md` does not match. The gate then reports "did not fire"
     // about the harness rather than the fixture.
     const written = fx.fragments.map((n: string) => write(`${dir}/${n}`, `# ${n}\n`));
-    written.push(write('package.json', JSON.stringify({ version: fx.version })));
+    if (fx.version_file === 'Directory.Build.props') {
+      written.push(write('Directory.Build.props', `<Project><PropertyGroup><Version>${fx.version}</Version></PropertyGroup></Project>\n`));
+    } else if (fx.version_file === 'pyproject.toml') {
+      written.push(write('pyproject.toml', `[project]\nversion = "${fx.version}"\n`));
+    } else {
+      written.push(write('package.json', JSON.stringify({ version: fx.version })));
+    }
+    // `consumed_through` is intentionally presence-sensitive: omitting it builds
+    // the missing-marker failure, while an empty string builds the blank-marker
+    // failure. Truthiness would collapse both into the same fixture.
+    if ('consumed_through' in fx) {
+      written.push(write(`${dir}/CONSUMED_THROUGH`, `${fx.consumed_through}\n`));
+    }
     return written;
   }
 
@@ -128,8 +204,9 @@ function build(root: string, table: any, fx: any, input?: string): string[] | nu
 }
 
 /**
- * Engines whose verdict depends **only on the content of the file the fixture
- * describes**, so a fixture can be executed faithfully in an empty directory.
+ * Engines whose verdict can be reproduced completely by a fixture builder.
+ * Most depend only on content in an empty directory; `change-requires-file`
+ * gets the explicit Git repository built above.
  *
  * The rest need context the fixture does not carry, and running them anyway
  * produces confident nonsense. `gates-links-resolve`'s `pass` fixture is
@@ -152,6 +229,7 @@ const CONTEXT_FREE: ReadonlySet<string> = new Set([
   'register-schema',
   'file-population',
   'changelog-freshness',
+  'change-requires-file',
   'computed-claim',
 ]);
 
@@ -168,7 +246,7 @@ const CONTEXT_FREE: ReadonlySet<string> = new Set([
  */
 function deparam<T>(spec: T, dir: string): T {
   const walk = (v: any): any =>
-    typeof v === 'string' ? v.replace(/\{\{[^}]+\}\}/g, dir)
+    typeof v === 'string' ? v.replace(/\{\{changelog_dir\}\}/g, dir)
       : Array.isArray(v) ? v.map(walk)
       : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]))
       : v;
@@ -205,12 +283,11 @@ export function runSelfTests(
       // Same bridge, for paths: a fixture that names a parameterised directory
       // has to hand the spec the same literal it wrote the files into.
       if (Array.isArray(b.fixture?.fragments)) spec = deparam(spec, b.fixture.dir ?? 'changelog.d');
-      // And for `exclude`, which is the thing under test in half these fixtures:
-      // the table ships it empty by default, so a fixture proving exclusion works
-      // has to set it, exactly as a repo would.
-      if (Array.isArray(b.fixture?.exclude)) {
-        const ex = b.fixture.exclude;
-        spec = Array.isArray(spec) ? spec.map((s: any) => ({ ...s, exclude: ex })) : { ...spec, exclude: ex };
+      if (Array.isArray(b.fixture?.changed)) {
+        const base = b.fixture.base_branch ?? 'main';
+        spec = Array.isArray(spec)
+          ? spec.map((s: any) => ({ ...s, base_branch: base }))
+          : { ...spec, base_branch: base };
       }
       if (!files) {
         out.push({ gate: gateId, expect, outcome: 'unrun', detail: `no builder for fixture ${JSON.stringify(b.fixture).slice(0, 60)}` });

package/src/storage-key.ts

@@ -0,0 +1,20 @@
+/**
+ * A conservative, locale-independent key for one already-separated storage
+ * segment that may move between a case-sensitive checkout, Windows, and
+ * default case-insensitive macOS APFS.
+ *
+ * NFKD exposes compatibility forms, while the lower/upper sequence expands
+ * multi-code-point case forms such as sharp-S. The final normalization catches
+ * decompositions introduced by case conversion itself.
+ *
+ * Do not pass a complete path or ref here. Compatibility decomposition can
+ * turn U+FF3C or U+FF0F into a separator; callers must split first so folding
+ * cannot manufacture path structure.
+ */
+export function canonicalCaselessSegmentKey(segment: string): string {
+  return segment.normalize('NFKD').toLowerCase().toUpperCase().normalize('NFKD');
+}
+
+export function canonicalCaselessSegmentEqual(left: string, right: string): boolean {
+  return canonicalCaselessSegmentKey(left) === canonicalCaselessSegmentKey(right);
+}

package/src/substitute.ts

@@ -1,4 +1,6 @@
-import { basename, resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import type { Manifest } from './types.ts';
 
 export type Params = Record<string, Record<string, unknown>>;
@@ -42,6 +44,20 @@ function repoFacts(repoRoot?: string): Record<string, unknown> {
   return repoRoot ? { dirname: basename(resolve(repoRoot)) } : {};
 }
 
+/**
+ * Facts about the Rungs artifact doing the rendering. Source execution and the
+ * published bundle live in `src/` and `dist/` respectively, so the package
+ * manifest is one directory above `import.meta.url` in both cases.
+ *
+ * This is deliberately not a module parameter. Parameters are copied into an
+ * install record and retained on upgrade; a CLI version must instead advance
+ * when the consumer explicitly invokes a newer artifact.
+ */
+function rungsFacts(): Record<string, unknown> {
+  const packageJson = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+  return { version: JSON.parse(readFileSync(packageJson, 'utf8')).version };
+}
+
 /**
  * Defaults from every manifest, with explicit overrides applied on top.
  *
@@ -51,7 +67,7 @@ function repoFacts(repoRoot?: string): Record<string, unknown> {
  * the reason a missing root shows up as a wrong-looking file instead of a silently blank heading.
  */
 export function resolveParams(mods: Manifest[], overrides: Params = {}, repoRoot?: string): Params {
-  const out: Params = { repo: repoFacts(repoRoot) };
+  const out: Params = {};
   for (const m of mods) {
     out[m.name] = {};
     for (const [k, spec] of Object.entries(m.params)) out[m.name][k] = spec.default;
@@ -68,6 +84,11 @@ export function resolveParams(mods: Manifest[], overrides: Params = {}, repoRoot
     out[mod] = { ...(out[mod] ?? {}), ...vals };
   }
 
+  // Facts win over manifests and overrides: both namespaces describe the
+  // execution context, not consumer configuration.
+  out.repo = repoFacts(repoRoot);
+  out.rungs = rungsFacts();
+
   // A default may reference another module's parameter, e.g. findings' register
   // living at `docs/{{backlog.root}}/FINDINGS.md`. One level only — a chain
   // would be a template language arriving through the back door.
@@ -95,14 +116,35 @@ export function markers(targetPath: string, module: string, version: string) {
  * mechanical and divergence a decision rather than an error.
  */
 export function mergeBlock(existing: string, fragment: string, module: string): string {
-  const beginRe = new RegExp(`^[ \\t]*(?:<!--|#)\\s*rungs:begin ${module}(?:@[\\w.\\-]+)?\\s*(?:-->)?[ \\t]*$`, 'm');
-  const endRe = new RegExp(`^[ \\t]*(?:<!--|#)\\s*rungs:end ${module}\\s*(?:-->)?[ \\t]*$`, 'm');
+  // Marker whitespace belongs to the marker line. `\\s*` also consumes newlines,
+  // which made the end match swallow inter-block separators and the file's final
+  // newline whenever an unchanged gate block was registered again (F-040). The
+  // match deliberately stops before CR/LF so those surrounding bytes stay outside
+  // the managed block.
+  const beginRe = new RegExp(
+    `^[ \\t]*(?:<!--|#)[ \\t]*rungs:begin ${module}(?:@[\\w.\\-]+)?[ \\t]*(?:-->)?[ \\t]*$`,
+    'm',
+  );
+  const endRe = new RegExp(
+    `^[ \\t]*(?:<!--|#)[ \\t]*rungs:end ${module}[ \\t]*(?:-->)?[ \\t]*$`,
+    'm',
+  );
   const b = existing.match(beginRe);
   const e = existing.match(endRe);
   if (b && e && b.index !== undefined && e.index !== undefined && e.index > b.index) {
     const before = existing.slice(0, b.index);
     const after = existing.slice(e.index + e[0].length);
-    return `${before}${fragment.trim()}${after}`;
+    const current = existing.slice(b.index, e.index + e[0].length);
+    const normalise = (value: string) => value.replace(/\r\n|\r|\n/g, '\n');
+    const replacement = fragment.trim();
+
+    // Registration builds fragments with LF on every platform. If the managed
+    // content is otherwise identical, preserve the original bytes—including a
+    // consumer checkout's CRLF convention—rather than manufacturing a diff.
+    if (normalise(current) === normalise(replacement)) return existing;
+
+    const newline = current.match(/\r\n|\r|\n/)?.[0] ?? existing.match(/\r\n|\r|\n/)?.[0] ?? '\n';
+    return `${before}${normalise(replacement).replace(/\n/g, newline)}${after}`;
   }
   const sep = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
   return `${existing}${sep}${fragment.trim()}\n`;

package/src/text.ts

@@ -0,0 +1,11 @@
+/**
+ * Normalize decoded repository text for semantic parsing only.
+ *
+ * Git may materialize tracked text as CRLF in a consumer even when the package
+ * source is LF. Parsers should not change their verdict with that checkout
+ * policy. Callers that compare ownership hashes or promise byte preservation
+ * must continue reading the original bytes instead.
+ */
+export function semanticText(text: string): string {
+  return text.replace(/\r\n?/g, '\n');
+}

package/src/types.ts

@@ -89,9 +89,22 @@ export interface DetectSpec {
 }
 
 export interface Provenance {
-  sources: string[];
-  patterns: string[];
-  incident: string;
+  /**
+   * Whether the module was **extracted** from a repo that already paid for it,
+   * or **designed** by somebody who thought it was a good idea.
+   *
+   * Absent means `extracted`: all fifteen bundled modules are, and normalising
+   * fifteen manifests to declare what they already said would be a migration
+   * rather than a distinction. `loadManifest` fills it in, so a reader may rely
+   * on it.
+   */
+  kind: 'extracted' | 'designed';
+  /** Required for `extracted`; forbidden for `designed` — see `loadManifest`. */
+  sources?: string[];
+  patterns?: string[];
+  incident?: string;
+  /** Required for `designed`: why it exists, in the first person. */
+  rationale?: string;
 }
 
 export interface Manifest {

package/src/version-source.ts

@@ -0,0 +1,144 @@
+import { readFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { SaxesParser } from 'saxes';
+import { parse as parseToml } from 'smol-toml';
+
+/** A version location declared by a gate table. Pattern matching stays with the caller. */
+export interface VersionSource {
+  file?: string;
+  path?: string;
+  xpath?: string;
+}
+
+/**
+ * A matched source either contributes one comparable value or explains why it cannot.
+ * There is deliberately no "not found" result: callers own globs and only call this
+ * reader after a concrete file matched.
+ */
+export type VersionSourceResult =
+  | { ok: true; value: string }
+  | { ok: false; reason: string };
+
+const invalidScalar = (where: string): VersionSourceResult => ({
+  ok: false,
+  reason: `${where} is not a non-empty string or finite number`,
+});
+
+function scalar(value: unknown, where: string): VersionSourceResult {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed ? { ok: true, value: trimmed } : invalidScalar(where);
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return { ok: true, value: String(value) };
+  }
+  return invalidScalar(where);
+}
+
+function dottedValue(parsed: unknown, path: string): { found: true; value: unknown } | { found: false } {
+  if (!path.trim()) return { found: false };
+  let value: unknown = parsed;
+  for (const key of path.split('.')) {
+    if (!value || typeof value !== 'object' || !Object.hasOwn(value, key)) return { found: false };
+    value = (value as Record<string, unknown>)[key];
+  }
+  return { found: true, value };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function xmlElement(text: string, rel: string, xpath: string): VersionSourceResult {
+  const match = /^\/\/([A-Za-z_][A-Za-z0-9_.:-]*)$/.exec(xpath);
+  if (!match) return { ok: false, reason: `unsupported XML xpath '${xpath}'; expected //Element` };
+
+  const element = match[1];
+  const values: { text: string; nested: boolean }[] = [];
+  const active: number[] = [];
+
+  try {
+    // Saxes validates a complete XML document and does not expand declarations
+    // from a DTD. Refuse the DTD outright so a version is always literal document
+    // evidence rather than an entity whose definition lives elsewhere.
+    const parser = new SaxesParser({ fragment: false, xmlns: false, fileName: rel });
+    parser.on('doctype', () => {
+      throw new Error('DOCTYPE declarations are not supported in version sources');
+    });
+    parser.on('opentag', (tag) => {
+      for (const index of active) values[index].nested = true;
+      if (tag.name === element) {
+        values.push({ text: '', nested: false });
+        active.push(values.length - 1);
+      }
+    });
+    const append = (value: string) => {
+      for (const index of active) values[index].text += value;
+    };
+    parser.on('text', append);
+    parser.on('cdata', append);
+    parser.on('closetag', (tag) => {
+      if (tag.name === element) active.pop();
+    });
+    parser.write(text).close();
+  } catch (error) {
+    return { ok: false, reason: `contains invalid XML: ${errorMessage(error)}` };
+  }
+
+  if (!values.length) return { ok: false, reason: `does not contain configured element '${xpath}'` };
+  if (values.length > 1) {
+    return { ok: false, reason: `configured element '${xpath}' matched ${values.length} values; expected one` };
+  }
+  if (values[0].nested) {
+    return { ok: false, reason: `configured element '${xpath}' contains nested XML; expected scalar text` };
+  }
+  return scalar(values[0].text, `configured element '${xpath}'`);
+}
+
+/**
+ * Read one already-matched version source.
+ *
+ * `path` means dotted JSON/TOML lookup, selected from the concrete filename.
+ * `xpath` intentionally supports only the release module's narrow `//Element`
+ * shape; pretending to implement general XPath would make a green result false.
+ */
+export function readVersionSource(root: string, rel: string, source: VersionSource): VersionSourceResult {
+  let text: string;
+  try {
+    text = readFileSync(join(root, rel), 'utf8');
+  } catch (error) {
+    return { ok: false, reason: `could not read version source: ${errorMessage(error)}` };
+  }
+
+  if (source.path && source.xpath) {
+    return { ok: false, reason: 'declares both `path` and `xpath`; choose one version lookup' };
+  }
+
+  if (source.path) {
+    const extension = extname(rel).toLowerCase();
+    let parsed: unknown;
+    try {
+      if (extension === '.json') parsed = JSON.parse(text);
+      else if (extension === '.toml') parsed = parseToml(text);
+      else {
+        return {
+          ok: false,
+          reason: `cannot read dotted path '${source.path}' from '${extension || '(no extension)'}'; use JSON or TOML`,
+        };
+      }
+    } catch (error) {
+      const format = extension === '.toml' ? 'TOML' : 'JSON';
+      return { ok: false, reason: `contains invalid ${format}: ${errorMessage(error)}` };
+    }
+
+    const found = dottedValue(parsed, source.path);
+    if (!found.found) return { ok: false, reason: `does not contain configured path '${source.path}'` };
+    return scalar(found.value, `configured path '${source.path}'`);
+  }
+
+  if (source.xpath) {
+    return xmlElement(text, rel, source.xpath);
+  }
+
+  return { ok: false, reason: 'declares neither `path` nor `xpath` for its version value' };
+}