@rungs/cli 0.3.1 → 0.4.0

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' };
+}