@serfab/cadre-host 0.11.0 → 0.13.0

package/src/bin/__tests__/cli-reference.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Drift guard for the README's `## CLI reference` section.
+ *
+ * The section is hand-maintained prose, one `### ` heading per command, and
+ * nothing used to check it against the commander program in `../host.ts` — so
+ * the whole `cadre-host push` group shipped undocumented. This test compares
+ * the two in both directions.
+ *
+ * Scope is deliberately narrow: **presence of a heading only**. A heading's
+ * command path must name a real command, and every leaf command must have a
+ * heading. The flag list inside a heading is *not* validated — doing so would
+ * turn a wording tweak into a red build for no correctness gain.
+ *
+ * NOTE: a heading advertising a flag the CLI no longer accepts therefore slips
+ * through; if that drift is ever observed in practice, compare the bracketed
+ * tokens against `cmd.options` rather than widening the parse.
+ *
+ * NOTE: every `### ` heading inside the section must be a command reference —
+ * the malformed-heading assertion is a hard failure, not a skip. Explanatory
+ * prose belongs in the section preamble or under a different `## ` section.
+ *
+ * Importing `../host.js` is inert: its module scope only builds the commander
+ * tree and reads `package.json` for `.version()`. Nothing spawns, binds, or
+ * exits until an action fires, and `parseAsync()` is gated behind an
+ * entry-point check. The counter-guard for that gate is
+ * `src/__tests__/cli.smoke.test.ts`, which spawns `dist/bin/host.js --help` as
+ * a child process — run `yarn workspace @serfab/cadre-host build:server`
+ * before the suite so it checks the current source.
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { describe, it, expect } from 'vitest';
+import type { Command } from 'commander';
+
+import { program } from '../host.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(here, '..', '..', '..');
+const readmePath = resolve(packageRoot, 'README.md');
+const packageJsonPath = resolve(packageRoot, 'package.json');
+
+/** Commander's implicit `help [command]` is never documented in the README. */
+const IMPLICIT_HELP = 'help';
+
+interface CommandNode {
+  /** Space-joined path below `cadre-host`, e.g. `push fcm`, `nat ddns set`. */
+  path: string;
+  /** True when the command is a *visible leaf* — no subcommands, not hidden. */
+  requiresHeading: boolean;
+}
+
+/**
+ * Walk the commander tree, collecting every command's path.
+ *
+ * `visible` tracks whether the command is reachable in `--help` output:
+ * a `.hidden()` command (or anything under one) is *allowed* a README heading
+ * but never *required* to have one, so hiding a command doesn't force a doc
+ * edit in the same commit.
+ */
+function collectCommands(cmd: Command, prefix: string[] = [], visible = true): CommandNode[] {
+  const visibleChildren = new Set(cmd.createHelp().visibleCommands(cmd));
+  const out: CommandNode[] = [];
+  for (const child of cmd.commands) {
+    if (child.name() === IMPLICIT_HELP) continue;
+    const path = [...prefix, child.name()];
+    const childVisible = visible && visibleChildren.has(child);
+    const subcommands = child.commands.filter((c) => c.name() !== IMPLICIT_HELP);
+    out.push({ path: path.join(' '), requiresHeading: subcommands.length === 0 && childVisible });
+    out.push(...collectCommands(child, path, childVisible));
+  }
+  return out;
+}
+
+interface ReadmeHeading {
+  /** The raw `### ` line, for failure messages. */
+  line: string;
+  /** Space-joined command path below `cadre-host`, or null when unparseable. */
+  path: string | null;
+}
+
+/**
+ * Slice the README between `## CLI reference` and the next `## ` heading, and
+ * return every `### ` heading found there.
+ *
+ * Throws when the section is missing rather than returning an empty list — an
+ * absent or renamed section must fail loudly, not pass vacuously.
+ */
+function readCliReferenceHeadings(): ReadmeHeading[] {
+  // Split on /\r?\n/ — this repo is developed on Windows and a bare \n split
+  // leaves a \r glued to the end of every heading.
+  const lines = readFileSync(readmePath, 'utf8').split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === '## CLI reference');
+  if (start === -1) {
+    throw new Error(`No "## CLI reference" heading in ${readmePath} — was the section renamed or removed?`);
+  }
+  // The section ends at the next `## ` heading. Anchor on `^## ` rather than a
+  // literal title: the following heading contains backticks today.
+  const rest = lines.slice(start + 1);
+  const relativeEnd = rest.findIndex((l) => /^## /.test(l));
+  const section = relativeEnd === -1 ? rest : rest.slice(0, relativeEnd);
+
+  return section.filter((l) => l.startsWith('### ')).map((line) => ({ line, path: parseHeading(line) }));
+}
+
+/**
+ * Extract the command path from a heading of the shape
+ * ``### `cadre-host <path...> [flags]` ``.
+ *
+ * Returns null when the heading doesn't match — malformed headings are
+ * reported as a failure, never silently skipped, because silent skipping is
+ * exactly how the section rots.
+ */
+function parseHeading(line: string): string | null {
+  const code = /^###\s+`([^`]+)`\s*$/.exec(line)?.[1];
+  if (!code) return null;
+  const tokens = code.trim().split(/\s+/);
+  if (tokens[0] !== 'cadre-host') return null;
+  const path: string[] = [];
+  for (const token of tokens.slice(1)) {
+    if (token.startsWith('<') || token.startsWith('[') || token.startsWith('-')) break;
+    path.push(token);
+  }
+  return path.length > 0 ? path.join(' ') : null;
+}
+
+describe('README CLI reference matches the commander tree', () => {
+  const commands = collectCommands(program);
+  const headings = readCliReferenceHeadings();
+  const documented = new Set(headings.map((h) => h.path).filter((p): p is string => p !== null));
+
+  it('has a heading for every leaf command', () => {
+    const missing = commands
+      .filter((c) => c.requiresHeading && !documented.has(c.path))
+      .map((c) => `cadre-host ${c.path}`);
+    expect(
+      missing,
+      `Commands with no "### " heading under "## CLI reference" in ${readmePath}:\n  ${missing.join('\n  ')}`,
+    ).toEqual([]);
+  });
+
+  it('has no heading for a command that does not exist', () => {
+    const known = new Set(commands.map((c) => c.path));
+    const ghosts = [...documented].filter((p) => !known.has(p)).map((p) => `cadre-host ${p}`);
+    expect(
+      ghosts,
+      `Headings under "## CLI reference" in ${readmePath} naming commands the CLI does not accept:\n  ${ghosts.join('\n  ')}`,
+    ).toEqual([]);
+  });
+
+  it('has no malformed headings in the section', () => {
+    const malformed = headings.filter((h) => h.path === null).map((h) => h.line);
+    expect(
+      malformed,
+      'Headings under "## CLI reference" must have the shape "### `cadre-host <path...> [flags]`":\n  ' +
+        malformed.join('\n  '),
+    ).toEqual([]);
+  });
+});
+
+describe('CLI version', () => {
+  it('reports the version from package.json', () => {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { version: string };
+    expect(program.version()).toBe(pkg.version);
+  });
+});