Skip to content

armgit / Ix

Public Imported from GitHub
0

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

9.1 KB
Raw Blame
#!/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, realpathSync, 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 `. */
export function textInvocations(text) {
  const found = [];
  for (const m of text.matchAll(/`(ix\s+[a-z][^`\n]*)`/g)) {
    // Inside a JS template literal the span is written \`ix …\`: the closing
    // backtick's escape is captured as the span's last character.
    found.push({ argv: tokens(m[1].replace(/\\+$/, "")), 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;
}

/** A flag's name without `=value` or the escape, quote or punctuation after it. */
function flagName(token) {
  return token.split("=")[0].replace(/[\\`'",.;:!?)\]}]+$/, "");
}

/** What is wrong with one invocation, or null. */
export 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}`;
  }
  // Only trailing punctuation is dropped, never a letter or `_`, so `--remapp`
  // and `--re_map` are reported under the name the plugin wrote.
  const bad = argv
    .filter((a) => /^--[a-z][a-z0-9-]*/.test(a))
    .map(flagName)
    .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;
}

// Run as a script, not when a test imports it. Real paths, so a symlinked
// invocation still runs the check rather than exiting 0 having checked nothing.
const isMain = process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
if (isMain) process.exit(main(process.argv.slice(2)));