ddduck 0.1.0

package/scripts/audit-fr-to-code.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "yaml";
+import { verifyFrToCodeAudit } from "./lib/fr-to-code-audit.mjs";
+import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
+
+export function runFrToCodeAudit(args, { stdout = process.stdout } = {}) {
+  if (args.length === 1 && args[0] === "--help") {
+    stdout.write(renderHelp("audit-fr-to-code"));
+    return;
+  }
+  const { options } = parseCommandArgs(args, {
+    options: { input: { value: true }, "source-root": { value: true, repeatable: true }, json: {} },
+  });
+  options.sourceRoots = options["source-root"].map(parseSourceRoot);
+  if (!options.json) throw new CliUsageError("audit-fr-to-code requires --json");
+  if (!options.input) throw new CliUsageError("audit-fr-to-code requires --input <audit.yaml>");
+
+  const record = readAuditRecord(options.input);
+  const sourceReader = createGitSourceReader(record, options.sourceRoots);
+  const report = verifyFrToCodeAudit(record, sourceReader);
+  stdout.write(`${JSON.stringify(report)}\n`);
+}
+
+function parseSourceRoot(value) {
+  const separator = value.indexOf("=");
+  if (separator <= 0 || separator === value.length - 1) {
+    throw new Error("--source-root requires <source-id>=<checkout>");
+  }
+  return { id: value.slice(0, separator), root: value.slice(separator + 1) };
+}
+
+function readAuditRecord(filePath) {
+  const document = parseDocument(readFileSync(filePath, "utf8"), { strict: true, uniqueKeys: true });
+  if (document.errors.length > 0) {
+    throw new Error(`invalid YAML in ${filePath}: ${document.errors.map((error) => error.message).join("; ")}`);
+  }
+  const record = document.toJSON();
+  if (!isPlainObject(record)) throw new Error(`audit input must contain a YAML mapping: ${filePath}`);
+  validateDeclaredSources(record, filePath);
+  return record;
+}
+
+function validateDeclaredSources(record, filePath) {
+  if (!Array.isArray(record.sources) || record.sources.length === 0) {
+    throw new Error(`audit input must declare sources: ${filePath}`);
+  }
+  for (const source of record.sources) {
+    if (!isPlainObject(source) || typeof source.id !== "string" || source.id.length === 0) {
+      throw new Error(`audit source id must be a non-empty string: ${filePath}`);
+    }
+    if (typeof source.repository !== "string" || source.repository.length === 0) {
+      throw new Error(`audit source repository must be a non-empty string for ${source.id}`);
+    }
+    if (typeof source.revision !== "string" || !/^[0-9a-f]{40}$/.test(source.revision)) {
+      throw new Error(`audit source revision must be a 40-character lowercase hex commit ID for ${source.id}`);
+    }
+  }
+}
+
+function createGitSourceReader(record, sourceRoots) {
+  if (!Array.isArray(record.sources)) throw new Error("audit input must declare sources");
+  const declaredIds = new Set(record.sources.map((source) => source?.id));
+  for (const { id } of sourceRoots) {
+    if (!declaredIds.has(id)) throw new Error(`--source-root maps undeclared source ID ${id}`);
+  }
+
+  const rootsById = new Map();
+  for (const source of record.sources) {
+    const matches = sourceRoots.filter(({ id }) => id === source.id);
+    if (matches.length !== 1) {
+      throw new Error(`audit-fr-to-code requires exactly one --source-root mapping for ${source.id}`);
+    }
+    rootsById.set(source.id, matches[0].root);
+  }
+
+  for (const source of record.sources) {
+    verifyGitSource(source, rootsById.get(source.id));
+  }
+
+  return {
+    readFile(source, relativePath) {
+      const root = rootsById.get(source.id);
+      verifyRegularFileEntry(source, root, relativePath);
+      return runGit(source, root, ["show", "--end-of-options", `${source.revision}:${relativePath}`]);
+    },
+  };
+}
+
+function verifyGitSource(source, root) {
+  const origin = runGit(source, root, ["remote", "get-url", "origin"]);
+  if (origin.trim() !== source.repository) {
+    throw new Error(`origin URL does not match declared repository for ${source.id}`);
+  }
+  try {
+    runGit(source, root, ["cat-file", "-e", "--end-of-options", `${source.revision}^{commit}`]);
+  } catch {
+    throw new Error(`declared revision is absent from checkout for ${source.id}`);
+  }
+}
+
+function verifyRegularFileEntry(source, root, relativePath) {
+  const entry = runGit(source, root, [
+    "ls-tree",
+    "-z",
+    "--full-tree",
+    "--end-of-options",
+    source.revision,
+    "--",
+    relativePath,
+  ]);
+  const [mode, type, object, entryPath] = parseTreeEntry(entry, source, relativePath);
+  if ((mode !== "100644" && mode !== "100755") || type !== "blob" || !object) {
+    throw new Error(`pinned tree entry is not a regular file for ${source.id}:${relativePath}`);
+  }
+  if (entryPath !== relativePath) {
+    throw new Error(`pinned tree entry is missing for ${source.id}:${relativePath}`);
+  }
+}
+
+function parseTreeEntry(output, source, relativePath) {
+  const entries = output.split("\0").filter(Boolean);
+  if (entries.length !== 1) {
+    throw new Error(`pinned tree entry is missing for ${source.id}:${relativePath}`);
+  }
+  const tab = entries[0].indexOf("\t");
+  if (tab < 0) {
+    throw new Error(`could not inspect pinned tree entry for ${source.id}:${relativePath}`);
+  }
+  const fields = entries[0].slice(0, tab).split(" ");
+  const entryPath = entries[0].slice(tab + 1);
+  if (fields.length !== 3 || !entryPath)
+    throw new Error(`could not inspect pinned tree entry for ${source.id}:${relativePath}`);
+  return [...fields, entryPath];
+}
+
+function runGit(source, root, args) {
+  const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const target = args[0] === "show" ? ` ${source.id}:${args.at(-1).slice(args.at(-1).indexOf(":") + 1)}` : "";
+    throw new Error(`git ${args[0]} failed${target}: ${result.stderr.trim()}`);
+  }
+  return result.stdout;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    runFrToCodeAudit(process.argv.slice(2));
+  } catch (error) {
+    writeCliError(error, {
+      nextAction: "Run audit-fr-to-code --help, correct the input, and retry.",
+    });
+  }
+}

package/scripts/check-generated-docs.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildModelOverview } from "./generate-docs.mjs";
+import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
+
+const outputPath = path.join("generated", "docs", "model-overview.md");
+
+function staleMessage(root) {
+  return `${outputPath} is missing or stale; run ddduck generate --root ${root}`;
+}
+
+export function checkGeneratedDocs(rootPath) {
+  const root = path.resolve(rootPath);
+  const expected = buildModelOverview(root);
+  let actual;
+  try {
+    actual = readFileSync(path.join(root, outputPath), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") throw new Error(staleMessage(root));
+    throw error;
+  }
+  if (actual !== expected) throw new Error(staleMessage(root));
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const options = parseArgs(process.argv.slice(2));
+  try {
+    checkGeneratedDocs(resolveProductRoot({ explicitRoot: options.root }));
+    if (options.verbose) console.log("generated docs ok");
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+function parseArgs(args) {
+  const parsed = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--root") {
+      parsed.root = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === "--verbose") {
+      parsed.verbose = true;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return parsed;
+}

package/scripts/check-generated-graph-svg.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildModelGraph } from "./generate-graph.mjs";
+import { buildModelGraphSvg, svgOutputPath } from "./generate-graph-svg.mjs";
+import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
+
+function staleMessage(root) {
+  return `${svgOutputPath} is missing or stale; run ddduck generate --root ${root}`;
+}
+
+// Pin the canonical SVG byte-for-byte: rebuild it from the source model and
+// compare against the committed file. Deterministic because @hpcc-js/wasm is
+// version-pinned in the lockfile (the SVG embeds its Graphviz version).
+export async function checkGeneratedGraphSvg(rootPath) {
+  const root = path.resolve(rootPath);
+  const expected = await buildModelGraphSvg(buildModelGraph(root));
+  let actual;
+  try {
+    actual = readFileSync(path.join(root, svgOutputPath), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") throw new Error(staleMessage(root));
+    throw error;
+  }
+  if (actual !== expected) throw new Error(staleMessage(root));
+}
+
+function parseArgs(args) {
+  const parsed = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--root") {
+      parsed.root = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === "--verbose") {
+      parsed.verbose = true;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return parsed;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const options = parseArgs(process.argv.slice(2));
+  try {
+    await checkGeneratedGraphSvg(resolveProductRoot({ explicitRoot: options.root }));
+    if (options.verbose) console.log("generated graph svg ok");
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}

package/scripts/check-generated-graph.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildModelGraphOutputs, jsonOutputPath, ndjsonOutputPath } from "./generate-graph.mjs";
+import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
+
+function staleMessage(relativePath, root) {
+  return `${relativePath} is missing or stale; run ddduck generate --root ${root}`;
+}
+
+export function checkGeneratedGraph(rootPath) {
+  const root = path.resolve(rootPath);
+  const expected = buildModelGraphOutputs(root);
+  checkOutput(root, jsonOutputPath, expected.json);
+  checkOutput(root, ndjsonOutputPath, expected.ndjson);
+}
+
+function checkOutput(root, relativePath, expected) {
+  let actual;
+  try {
+    actual = readFileSync(path.join(root, relativePath), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(staleMessage(relativePath, root));
+    }
+    throw error;
+  }
+
+  if (actual !== expected) {
+    throw new Error(staleMessage(relativePath, root));
+  }
+}
+
+function parseArgs(args) {
+  const parsed = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--root") {
+      parsed.root = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === "--verbose") {
+      parsed.verbose = true;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return parsed;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const options = parseArgs(process.argv.slice(2));
+  try {
+    checkGeneratedGraph(resolveProductRoot({ explicitRoot: options.root }));
+    if (options.verbose) console.log("generated graph ok");
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}