Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

ci(parity): gate registered flags against the flag reference (#576) (#584)

Alot1zedd3e1b13368
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 71fbe0f7..46e39b71 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -319,10 +319,40 @@ jobs:
# One stable required-status-check context. Branch protection requires only
# this job, so the matrix can be reshaped without orphaning required checks.
# Fails if any upstream job failed OR was skipped/cancelled.
+ # ── Flag-reference parity gate (#576) ───────────────────────────────────
+ # The flag reference (skills/ix/references/flags.md, #578) must stay in step
+ # with the *registered* commander tree: a registered flag without a doc row,
+ # or a doc row for a flag the CLI no longer registers, fails this job with
+ # the flag named. It reads the built CLI (dist/), never a regex over source —
+ # the same surface dump-cli-surface.mjs inventories. Inactive (green) while
+ # flags.md is absent, so it activates exactly when the reference ships and is
+ # strict from then on.
+ doc-parity:
+ name: Flag-reference parity
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+ with:
+ node-version: "22"
+ cache: "npm"
+ cache-dependency-path: ix-cli/package-lock.json
+ - name: Install (ix-cli)
+ working-directory: ix-cli
+ run: npm ci --silent
+ - name: Build (the gate reads dist/, what ships)
+ working-directory: ix-cli
+ run: npm run build
+ - name: Registered flags vs flag reference
+ working-directory: ix-cli
+ run: node scripts/check-doc-parity.mjs
+
ci-success:
name: CI Passed
if: always()
- needs: [static, test, e2e, api-parity]
+ needs: [static, test, e2e, api-parity, doc-parity]
runs-on: ubuntu-latest
steps:
- name: Verify all required jobs succeeded
@@ -331,7 +361,9 @@ jobs:
echo "test=${{ needs.test.result }}"
echo "e2e=${{ needs.e2e.result }}"
echo "api-parity=${{ needs.api-parity.result }}"
+ echo "doc-parity=${{ needs.doc-parity.result }}"
[ "${{ needs.static.result }}" = "success" ] \
&& [ "${{ needs.test.result }}" = "success" ] \
&& [ "${{ needs.e2e.result }}" = "success" ] \
- && [ "${{ needs.api-parity.result }}" = "success" ]
+ && [ "${{ needs.api-parity.result }}" = "success" ] \
+ && [ "${{ needs.doc-parity.result }}" = "success" ]
diff --git a/ix-cli/scripts/check-doc-parity.mjs b/ix-cli/scripts/check-doc-parity.mjs
new file mode 100644
index 00000000..b027da0c
--- /dev/null
+++ b/ix-cli/scripts/check-doc-parity.mjs
@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * Docs parity gate for the OSS CLI surface — part 2 of #576.
+ *
+ * The RFC asked for a committed check so a registered command or flag cannot
+ * merge without a doc mention. #578 shipped the inventory half
+ * (scripts/dump-cli-surface.mjs + skills/ix/references/flags.md); this is the
+ * compare half, wired into CI by .github/workflows/ci.yml.
+ *
+ * It reads the *registered commander tree* from dist/ (never a regex over
+ * source), walks the same command/flag shape dump-cli-surface.mjs prints, and
+ * compares both directions against the flag reference:
+ *
+ * - a registered command with no doc section -> fail, named
+ * - a registered long flag with no doc row -> fail, named
+ * - a doc row for a flag the CLI no longer registers -> fail, named (stale)
+ * - a doc section for a command that is gone -> fail, named (stale)
+ *
+ * Both halves of #576 matter. Gating flags alone leaves every flagless command
+ * unreachable, and 14 of the 54 registered here have no long flag at all.
+ *
+ * Inactive while skills/ix/references/flags.md is absent: with zero coverage
+ * the check would only report the whole command surface, so it exits 0 with a
+ * notice and activates the moment the reference file exists. That keeps CI
+ * green before #578 merges and strict from then on.
+ *
+ * node scripts/check-doc-parity.mjs # default doc path, from repo root
+ * node scripts/check-doc-parity.mjs --doc P # explicit doc path (testing)
+ *
+ * Exit 0 = parity; 1 = gaps listed on stdout.
+ */
+import { Command } from "commander";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(here, "..", "..");
+const ossPath = join(here, "..", "dist", "cli", "register", "oss.js");
+const flagsDocDefault = join(repoRoot, "skills", "ix", "references", "flags.md");
+
+/**
+ * Read `--name <value>` / `--name=<value>` from argv. A flag with no value —
+ * last argument, or followed by another flag — is a usage error, not a crash:
+ * `existsSync(undefined)` would throw a TypeError instead of telling the
+ * caller what to fix.
+ */
+const argValue = (name, fallback) => {
+ const eq = process.argv.find((a) => a.startsWith(`${name}=`));
+ if (eq !== undefined) return eq.slice(name.length + 1);
+ const i = process.argv.indexOf(name);
+ if (i < 0) return fallback;
+ const v = process.argv[i + 1];
+ if (v === undefined || v.startsWith("--")) {
+ process.stderr.write(`error: option '${name} <value>' argument missing\n`);
+ process.exit(1);
+ }
+ return v;
+};
+
+const flagsDoc = argValue("--doc", flagsDocDefault);
+
+if (!existsSync(flagsDoc)) {
+ console.log(
+ `check-doc-parity: no flag reference at ${flagsDoc} — ` +
+ "gate inactive until the reference ships (#576, #578)",
+ );
+ process.exit(0);
+}
+
+let registerOssCommands;
+try {
+ ({ registerOssCommands } = await import(pathToFileURL(ossPath).href));
+} catch (err) {
+ process.stderr.write(
+ `cannot load ${ossPath}\nRun 'npm run build' in ix-cli first.\n${err}\n`,
+ );
+ process.exit(1);
+}
+
+const program = new Command();
+program.name("ix");
+registerOssCommands(program);
+
+// Registered surface: every command name (rooted at `ix`, matching the doc's
+// `### \`ix <cmd>\`` section headers), plus the long flags per command for the
+// flag-bearing ones. A command with no flags still has a legitimate doc
+// section, so section staleness is checked against all names.
+const allCommands = new Set();
+const registered = new Map();
+function walk(cmd, parentPath) {
+ const name = parentPath ? `${parentPath} ${cmd.name()}` : `ix ${cmd.name()}`;
+ allCommands.add(name);
+ const longs = new Set();
+ for (const o of cmd.options ?? []) {
+ if (!o.long) continue;
+ // Commander auto-registers `-h, --help` on every command; the flag
+ // reference deliberately carries no help rows.
+ if (o.long === "--help") continue;
+ longs.add(o.long);
+ }
+ if (longs.size > 0) registered.set(name, longs);
+ for (const sub of cmd.commands ?? []) walk(sub, name);
+}
+for (const cmd of program.commands) walk(cmd, "");
+
+// Documented surface: per command section in flags.md, the backticked
+// `--flag` tokens in its table rows. Section headers look like
+// `### \`ix callees <symbol>\`` or `#### \`ix config show\`` — strip any
+// `<arg>` / `[arg]` tokens from the command name.
+const docLines = readFileSync(flagsDoc, "utf8").split(/\r?\n/);
+const documented = new Map();
+let current = null;
+for (const line of docLines) {
+ const head = line.match(/^(#{2,4}) `([^`]+)`\s*$/);
+ if (head) {
+ if (head[2].startsWith("ix ")) {
+ const parts = head[2]
+ .split(/\s+/)
+ .filter((t) => !/^[<[].*[>\]]$/.test(t));
+ current = parts.join(" ");
+ if (!documented.has(current)) documented.set(current, new Set());
+ continue;
+ }
+ current = null;
+ continue;
+ }
+ if (!current) continue;
+ for (const m of line.matchAll(/`(--[\w-]+)`/g)) {
+ documented.get(current).add(m[1]);
+ }
+}
+
+const missingSections = []; // registered command with no doc section
+const missing = []; // registered flag with no doc row
+const stale = []; // doc row or section with no registered counterpart
+
+// #576 asks that a registered command *or* flag cannot merge without a doc
+// mention. Gating flags alone leaves the flagless commands unreachable: 14 of
+// the 54 registered here (`ix init`, the four `ix docker` subcommands, the
+// `ix config` family, `ix view stop|status`, `ix savings reset`, `ix mcp`,
+// `ix help`) carry no long flag at all, so nothing about them was ever
+// compared and a new one could merge with no section.
+//
+// Nothing is excluded. `--help` is skipped above because commander registers
+// it on every command; there is no command-side equivalent — `ix help
+// [topic]` is a real Ix command with real behaviour (`ix help workflows`,
+// `ix help advanced`, and the collapsed-plural forwarding of Ix-pro#103/#108),
+// registered by registerWorkflowsHelpCommand, and it deserves a section like
+// any other.
+for (const cmd of [...allCommands].sort()) {
+ if (!documented.has(cmd)) missingSections.push(cmd);
+}
+
+for (const [cmd, flags] of registered) {
+ // A command with no section at all is reported once, as the section it
+ // needs. Listing each of its flags as a separate missing row would bury the
+ // one edit that fixes them.
+ if (!documented.has(cmd)) continue;
+ const known = documented.get(cmd);
+ for (const f of [...flags].sort()) {
+ if (!known.has(f)) missing.push(`${f} (on ${cmd})`);
+ }
+}
+for (const [cmd, flags] of documented) {
+ if (!allCommands.has(cmd)) {
+ stale.push(`section for ${cmd} has no registered command`);
+ continue;
+ }
+ const reg = registered.get(cmd);
+ if (!reg) continue; // command exists but registers no long flags
+ for (const f of [...flags].sort()) {
+ if (!reg.has(f)) stale.push(`${f} (under ${cmd})`);
+ }
+}
+
+const totalFlags = [...registered.values()].reduce((n, s) => n + s.size, 0);
+if (missingSections.length === 0 && missing.length === 0 && stale.length === 0) {
+ console.log(
+ `check-doc-parity: ${allCommands.size} commands, ${totalFlags} flags — ` +
+ `parity with ${flagsDoc}`,
+ );
+ process.exit(0);
+}
+
+for (const c of missingSections) console.log(`missing doc section: ${c}`);
+for (const f of missing) console.log(`missing doc row: ${f}`);
+for (const f of stale) console.log(`stale doc row: ${f}`);
+console.log(
+ `check-doc-parity: ${missingSections.length} undocumented command(s), ` +
+ `${missing.length} missing flag row(s), ${stale.length} stale — fix ${flagsDoc}`,
+);
+process.exit(1);