Skip to content

armgit / Ix

Public Imported from GitHub
0

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

fix(ci): plugin contract check reads --remap\ as --remap (#894)

Ian Hockd7ae6234ec3e
diff --git a/ix-cli/scripts/check-plugin-contract.mjs b/ix-cli/scripts/check-plugin-contract.mjs
index f37e8418..606ab639 100644
--- a/ix-cli/scripts/check-plugin-contract.mjs
+++ b/ix-cli/scripts/check-plugin-contract.mjs
@@ -19,7 +19,7 @@
*/
import { execFileSync } from "node:child_process";
-import { mkdtempSync, readdirSync, readFileSync, statSync } from "node:fs";
+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";
@@ -96,10 +96,12 @@ function codeInvocations(text) {
}
/** Invocations in text: `ix …` code spans, and lines of fenced blocks starting with `ix `. */
-function textInvocations(text) {
+export 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) });
+ // 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) => {
@@ -148,8 +150,13 @@ 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. */
-function check(argv, surface) {
+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;
@@ -162,9 +169,11 @@ function check(argv, surface) {
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((a) => a.split("=")[0])
+ .map(flagName)
.filter((f) => !entry.flags.has(f) && !GLOBAL_FLAGS.has(f));
return bad.length ? `"${name}" has no ${bad.join(", ")}` : null;
}
@@ -217,4 +226,7 @@ function main(argv) {
return 0;
}
-process.exit(main(process.argv.slice(2)));
+// 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)));
diff --git a/ix-cli/src/cli/__tests__/check-plugin-contract.test.ts b/ix-cli/src/cli/__tests__/check-plugin-contract.test.ts
new file mode 100644
index 00000000..b3e4bc91
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/check-plugin-contract.test.ts
@@ -0,0 +1,81 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { describe, expect, it } from "vitest";
+
+/**
+ * The plugin contract check (ix-cli/scripts/check-plugin-contract.mjs) reads
+ * the CLI surface from a build, so these tests hand `check` a small surface of
+ * their own and pin only the parsing: which flag a plugin's text names.
+ */
+type Surface = Map<string, { flags: Set<string>; subcommands: Set<string> }>;
+type Invocation = { argv: string[]; line: number; snippet: string };
+
+// @ts-expect-error — no .d.mts: the local interface below is the type contract.
+const contract = (await import("../../../scripts/check-plugin-contract.mjs")) as unknown as {
+ textInvocations: (text: string) => Invocation[];
+ check: (argv: string[], surface: Surface) => string | null;
+};
+
+const surface: Surface = new Map([
+ ["map", { flags: new Set(["--remap", "--format"]), subcommands: new Set<string>() }],
+ ["docker", { flags: new Set<string>(), subcommands: new Set(["start"]) }],
+ ["docker start", { flags: new Set(["--port"]), subcommands: new Set<string>() }],
+]);
+
+/** The problems the checker reports for one source text. */
+function problems(text: string): (string | null)[] {
+ return contract.textInvocations(text).map((inv) => contract.check(inv.argv, surface));
+}
+
+describe("check-plugin-contract", () => {
+ it("reads a flag inside an escaped-backtick template literal (ix-openclaw / ix-opencode)", () => {
+ const openclaw = " : `Map is stale. Run \\`ix map --remap\\` to refresh it now._`;";
+ const opencode =
+ " return `_Map is out of date; run \\`ix map --remap\\` to refresh it now._`;";
+ expect(problems(openclaw)).toEqual([null]);
+ expect(problems(opencode)).toEqual([null]);
+ });
+
+ it.each([
+ "--remap\\",
+ "--remap`",
+ "--remap.",
+ "--remap,",
+ "--remap)",
+ '--remap"',
+ "--remap'",
+ "--remap=1",
+ ])("counts %s as --remap", (flag) => {
+ expect(contract.check(["map", flag], surface)).toBeNull();
+ });
+
+ it("still reports a misspelt flag, with or without trailing punctuation", () => {
+ expect(contract.check(["map", "--remapp"], surface)).toBe('"map" has no --remapp');
+ expect(contract.check(["map", "--remapp."], surface)).toBe('"map" has no --remapp');
+ expect(problems("Then run `ix map --remapp` to refresh.")).toEqual(['"map" has no --remapp']);
+ });
+
+ it("reads a flag at the end of a sentence in a code span", () => {
+ expect(problems("Run `ix map --format json --remap.` when stale.")).toEqual([null]);
+ });
+
+ it("reports a flag the CLI lacks under the full name the plugin wrote", () => {
+ expect(contract.check(["map", "--re_map"], surface)).toBe('"map" has no --re_map');
+ expect(contract.check(["map", "--remap_x."], surface)).toBe('"map" has no --remap_x');
+ });
+
+ it("reads a command span closed by an escaped backtick", () => {
+ expect(problems("`Run \\`ix map\\` first.`")).toEqual([null]);
+ expect(problems("`Run \\`ix mapp\\` first.`")).toEqual(['unknown command "mapp"']);
+ });
+
+ it("still skips prose whose first word ends in punctuation", () => {
+ const prose = [
+ "throw new Error(`\\`ix failed: ${msg}\\``);",
+ "Reason: `ix unavailable.`",
+ "Saw `ix exited, code 1` in the log.",
+ ].join("\n");
+ expect(problems(prose)).toEqual([null, null, null]);
+ expect(contract.check(["docker", "start.", "--remap"], surface)).toBe('"docker" has no --remap');
+ });
+});