Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
ci(plugins): check every plugin's ix invocations against the CLI's surface
KageBinary9f856193e176
diff --git a/.github/workflows/plugin-contract.yml b/.github/workflows/plugin-contract.ymlnew file mode 100644index 00000000..f50bfb06--- /dev/null+++ b/.github/workflows/plugin-contract.yml@@ -0,0 +1,57 @@+# Plugin contract: every `ix …` invocation in the six editor plugins must name+# a command this CLI registers, with long flags that command accepts+# (ix-cli/scripts/check-plugin-contract.mjs). A flag renamed or removed here+# otherwise breaks a plugin silently, and a plugin that starts calling a flag+# the CLI never had is caught by the nightly run.+#+# Advisory for now: not part of CI Passed. The extraction from prompt text is+# heuristic, so it runs on its own until the ignore list has settled.+name: Plugin contract++on:+ pull_request:+ branches: [main]+ paths:+ - "ix-cli/src/cli/**"+ - "ix-cli/scripts/check-plugin-contract.mjs"+ - "ix-cli/scripts/plugin-contract-ignore.json"+ - ".github/workflows/plugin-contract.yml"+ schedule:+ - cron: "17 6 * * *"+ workflow_dispatch:++permissions:+ contents: read++concurrency:+ group: plugin-contract-${{ github.ref }}+ cancel-in-progress: true++jobs:+ contract:+ name: Plugin contract (advisory)+ 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+ core-ingestion/package-lock.json+ - name: Cache core-ingestion native deps+ uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0+ with:+ path: core-ingestion/node_modules+ key: core-ingestion-v2-${{ runner.os }}-node22-${{ hashFiles('core-ingestion/package-lock.json') }}+ - name: Install & build+ working-directory: ix-cli+ run: |+ npm ci --silent+ npm run build+ - name: Check every plugin's ix invocations (plugins' main)+ working-directory: ix-cli+ run: node scripts/check-plugin-contract.mjs --clonediff --git a/ix-cli/scripts/check-plugin-contract.mjs b/ix-cli/scripts/check-plugin-contract.mjsnew file mode 100644index 00000000..f37e8418--- /dev/null+++ b/ix-cli/scripts/check-plugin-contract.mjs@@ -0,0 +1,220 @@+#!/usr/bin/env node+// Copyright 2026 Ix Infrastructure Inc.++/**+ * Plugin contract check: every `ix …` invocation in the editor plugins must+ * name a command this CLI registers, with long flags that command accepts.+ *+ * The plugins call the CLI from code (argv arrays handed to runIx / safeRun /+ * run_ix_json) and tell agents to call it from prompt and skill text. Both+ * break silently when a flag is renamed or removed here: nothing in this repo+ * ever looked at them.+ *+ * node scripts/check-plugin-contract.mjs <plugins-dir> # one checkout per plugin under it+ * node scripts/check-plugin-contract.mjs --clone # shallow-clone the six plugins' main first+ *+ * Needs a build (`npm run build`): the surface comes from scripts/dump-cli-surface.mjs.+ * Exit 1 when an invocation names an unknown command or flag. Known false+ * positives go in scripts/plugin-contract-ignore.json.+ */++import { execFileSync } from "node:child_process";+import { mkdtempSync, readdirSync, readFileSync, statSync } from "node:fs";+import { tmpdir } from "node:os";+import { dirname, extname, join, relative } from "node:path";+import { fileURLToPath } from "node:url";++/* global process, console */++const here = dirname(fileURLToPath(import.meta.url));+const PLUGINS = [+ "ix-claude-plugin", "ix-codex-plugin", "ix-cursor-plugin",+ "ix-gemini-plugin", "ix-openclaw-plugin", "ix-opencode-plugin",+];+/** Ix Pro commands: registered by @ix/pro, not by this build. */+const PRO_COMMANDS = new Set([+ "plan", "plans", "task", "tasks", "workflow", "workflows", "decide", "decisions",+ "goal", "goals", "truth", "bug", "bugs", "briefing",+]);+/** Accepted by every command (commander adds --help; --version is the root's). */+const GLOBAL_FLAGS = new Set(["--help", "--version"]);+const CODE_EXT = new Set([".ts", ".mts", ".cts", ".js", ".mjs", ".cjs", ".py"]);+const TEXT_EXT = new Set([".md", ".json", ".toml", ".yaml", ".yml", ".txt", ".mdc"]);+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", "__pycache__", ".venv"]);+/** History, not instructions: changelogs and dated plans and test logs quote old invocations on purpose. */+const HISTORICAL = /(^|\/)(CHANGELOG[^/]*|[^/]*_PLAN\.md|[^/]*_LOG\.md)$/i;++function loadSurface() {+ const out = execFileSync(process.execPath, [join(here, "dump-cli-surface.mjs")], { encoding: "utf8" });+ const commands = new Map();+ for (const entry of JSON.parse(out)) {+ // "ix callers", "ix docker start": keyed without the leading "ix".+ commands.set(entry.command.replace(/^ix ?/, ""), {+ flags: new Set(entry.options.map((o) => o.long).filter(Boolean)),+ subcommands: new Set(entry.subcommands ?? []),+ });+ }+ return commands;+}++function loadIgnores() {+ try {+ return JSON.parse(readFileSync(join(here, "plugin-contract-ignore.json"), "utf8")).ignore ?? [];+ } catch {+ return [];+ }+}++function* walk(dir) {+ for (const name of readdirSync(dir)) {+ if (SKIP_DIRS.has(name)) continue;+ const path = join(dir, name);+ const st = statSync(path);+ if (st.isDirectory()) yield* walk(path);+ else if (st.size < 1_000_000) yield path;+ }+}++const STRING = /"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|`((?:[^`\\$]|\\.)*)`/g;++/** Invocations in code: argv arrays handed to something that runs ix. */+function codeInvocations(text) {+ const found = [];+ const call = /([A-Za-z_][\w.]*)\(\s*\[([^\]]*)\]/g;+ for (const m of text.matchAll(call)) {+ const fn = m[1];+ const items = [...m[2].matchAll(STRING)].map((s) => s[1] ?? s[2] ?? s[3]);+ const startsWithIx = items[0] === "ix";+ if (!startsWithIx && !/ix|safeRun|run_?ix/i.test(fn)) continue;+ const argv = startsWithIx ? items.slice(1) : items;+ if (argv.length === 0) continue;+ // `[...args, "--format", "llm"]` and `["--version"]` carry no command of their own.+ if (/^\s*\.\.\./.test(m[2]) || argv[0].startsWith("-")) continue;+ found.push({ argv, line: lineOf(text, m.index), snippet: m[0].slice(0, 100) });+ }+ return found;+}++/** Invocations in text: `ix …` code spans, and lines of fenced blocks starting with `ix `. */+function textInvocations(text) {+ const found = [];+ for (const m of text.matchAll(/`(ix\s+[a-z][^`\n]*)`/g)) {+ found.push({ argv: tokens(m[1]), line: lineOf(text, m.index), snippet: m[1].slice(0, 100) });+ }+ let inFence = false;+ text.split("\n").forEach((raw, i) => {+ if (/^\s*```/.test(raw)) { inFence = !inFence; return; }+ const line = raw.trim();+ if (inFence && /^ix\s+[a-z]/.test(line)) found.push({ argv: tokens(line), line: i + 1, snippet: line.slice(0, 100) });+ });+ return found;+}++/**+ * Invocations in a JSON file's string values. Agent definitions keep their+ * prompts as JSON strings, where a fenced block's newlines are `\n` escapes:+ * scanned as raw text, those blocks are invisible.+ */+function jsonInvocations(text) {+ let data;+ try {+ data = JSON.parse(text);+ } catch {+ return textInvocations(text);+ }+ const found = [];+ const visit = (value, path) => {+ if (typeof value === "string") {+ for (const inv of textInvocations(value)) found.push({ ...inv, line: `${path}:${inv.line}` });+ } else if (value && typeof value === "object") {+ for (const [key, child] of Object.entries(value)) visit(child, path ? `${path}.${key}` : key);+ }+ };+ visit(data, "");+ return found;+}++/** Split `ix cmd arg --flag x | other` into argv, stopping at shell operators. */+function tokens(command) {+ const out = [];+ for (const t of command.replace(/^ix\s+/, "").split(/\s+/)) {+ if (["|", "&&", "||", ";", ">", "2>&1"].includes(t) || t.startsWith("#")) break;+ out.push(t);+ }+ return out;+}++function lineOf(text, index) {+ return text.slice(0, index).split("\n").length;+}++/** What is wrong with one invocation, or null. */+function check(argv, surface) {+ const cmd = argv[0];+ if (!/^[a-z][a-z-]*$/.test(cmd)) return null; // a placeholder or a variable+ if (PRO_COMMANDS.has(cmd)) return null;+ const top = surface.get(cmd);+ if (!top) return `unknown command "${cmd}"`;+ let entry = top;+ let name = cmd;+ const sub = argv[1];+ if (sub && top.subcommands.has(sub) && surface.has(`${cmd} ${sub}`)) {+ entry = surface.get(`${cmd} ${sub}`);+ name = `${cmd} ${sub}`;+ }+ const bad = argv+ .filter((a) => /^--[a-z][a-z0-9-]*/.test(a))+ .map((a) => a.split("=")[0])+ .filter((f) => !entry.flags.has(f) && !GLOBAL_FLAGS.has(f));+ return bad.length ? `"${name}" has no ${bad.join(", ")}` : null;+}++function main(argv) {+ let dir = argv.find((a) => !a.startsWith("--"));+ if (argv.includes("--clone")) {+ dir = mkdtempSync(join(tmpdir(), "ix-plugins-"));+ for (const repo of PLUGINS) {+ execFileSync("git", ["clone", "-q", "--depth", "1", `https://github.com/ix-infrastructure/${repo}`, join(dir, repo)], { stdio: "inherit" });+ }+ }+ if (!dir) {+ console.error("usage: node scripts/check-plugin-contract.mjs <plugins-dir> | --clone");+ return 2;+ }+ const surface = loadSurface();+ const ignores = loadIgnores();+ const problems = [];+ let checked = 0;+ for (const repo of PLUGINS) {+ const root = join(dir, repo);+ try { statSync(root); } catch { console.error(`missing ${root}`); return 2; }+ for (const file of walk(root)) {+ const ext = extname(file);+ if (!CODE_EXT.has(ext) && !TEXT_EXT.has(ext)) continue;+ if (HISTORICAL.test(file)) continue;+ const text = readFileSync(file, "utf8");+ if (!text.includes("ix")) continue;+ const invocations = [+ ...(CODE_EXT.has(ext) ? codeInvocations(text) : []),+ ...(ext === ".json" ? jsonInvocations(text) : textInvocations(text)),+ ];+ for (const inv of invocations) {+ checked++;+ const problem = check(inv.argv, surface);+ if (!problem) continue;+ const where = `${repo}/${relative(root, file)}:${inv.line}`;+ if (ignores.some((ig) => where.startsWith(ig.where) && (!ig.match || inv.snippet.includes(ig.match)))) continue;+ problems.push(`${where} ${problem}\n ${inv.snippet}`);+ }+ }+ }+ console.log(`checked ${checked} ix invocations in ${PLUGINS.length} plugins`);+ if (problems.length) {+ console.error(`\n${problems.length} invocation(s) use a command or flag this CLI does not have:\n\n${problems.join("\n")}`);+ console.error(`\nA false positive (prompt prose, a placeholder) goes in scripts/plugin-contract-ignore.json.`);+ return 1;+ }+ return 0;+}++process.exit(main(process.argv.slice(2)));diff --git a/ix-cli/scripts/plugin-contract-ignore.json b/ix-cli/scripts/plugin-contract-ignore.jsonnew file mode 100644index 00000000..c4cc72c6--- /dev/null+++ b/ix-cli/scripts/plugin-contract-ignore.json@@ -0,0 +1,44 @@+{+ "ignore": [+ {+ "where": "ix-codex-plugin/tests/test_auto_map.py",+ "match": "locate --limit",+ "why": "asserts the old `ix locate --limit` form is no longer emitted"+ },+ {+ "where": "ix-codex-plugin/tests/test_ix_argv_resolution.py",+ "match": "\"git\"",+ "why": "argv resolution test with a non-ix command"+ },+ {+ "where": "ix-openclaw-plugin/tests/cli-argv.test.mjs",+ "match": "--limit",+ "why": "asserts runIx is never called with `locate --limit`"+ },+ {+ "where": "ix-openclaw-plugin/tests/cli-argv.test.mjs",+ "match": "--path",+ "why": "asserts runIx is never called with `smells --path`"+ },+ {+ "where": "ix-cursor-plugin/mcp/lib/parser.ts",+ "match": "ix output is not valid JSON",+ "why": "error message prose"+ },+ {+ "where": "ix-opencode-plugin/TOOL_CONTRACT.md",+ "match": "ix unavailable",+ "why": "prose"+ },+ {+ "where": "ix-opencode-plugin/runtime/cli.ts",+ "match": "ix exited",+ "why": "error message prose"+ },+ {+ "where": "ix-opencode-plugin/tests/tools.test.ts",+ "match": "ix unavailable",+ "why": "prose in an expected message"+ }+ ]+}