paperlint 2.0.0

package/eslint-rules/install-path-literals.harness.mjs

@@ -0,0 +1,121 @@
+/**
+ * `port/md-install-path` and `port/js-install-path` — both halves on real ESLint.
+ *
+ * 🔴 NO RATCHET HERE, AND THAT IS THE POINT (Erni, 2026-09-17). The first draft of this file
+ * froze the corpus at 76 findings and `lib/` at 2, so the debt could not grow. That reads like
+ * caution and is not: a ratchet does not say "correct", it says "at least not worse", and this
+ * repository's own rule calls it debt rather than a fix. Freezing a number the same day the
+ * rule is written turns "we will remove these paths" into "we have decided to keep them".
+ *
+ * So the rule reports and nothing freezes. The debt is an issue with an owner, not a constant
+ * in a test; the count lives in `docs/incidents.md` as a measurement with a date, where it can
+ * go stale honestly instead of looking maintained.
+ */ import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ESLint } from "eslint";
+import markdown from "@eslint/markdown";
+import { recordCheck } from "vigiles";
+import port, { PORT } from "./install-path-literals.mjs";
+
+// Resolved from THIS file, never from the caller's cwd — rule 6, and the mistake this very
+// class of bug is about.
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(HERE, "..");
+const FIX = join(ROOT, "fixtures", "install-path-literals");
+
+const RULE_MD = "port/md-install-path";
+const RULE_JS = "port/js-install-path";
+
+const mdLinter = new ESLint({
+  cwd: ROOT,
+  overrideConfigFile: true,
+  overrideConfig: [
+    {
+      files: ["**/*.md"],
+      plugins: { markdown, port },
+      language: "markdown/gfm",
+      languageOptions: { frontmatter: "yaml" },
+      rules: { [RULE_MD]: "error" },
+    },
+  ],
+});
+
+const jsLinter = new ESLint({
+  cwd: ROOT,
+  overrideConfigFile: true,
+  overrideConfig: [
+    { files: ["**/*.mjs"], plugins: { port }, rules: { [RULE_JS]: "error" } },
+  ],
+});
+
+const findings = async (linter, target, ruleId) => {
+  const res = await linter.lintFiles([target]);
+  return res.flatMap((r) => r.messages).filter((m) => m.ruleId === ruleId);
+};
+
+const cases = [];
+
+// ── 1. MARKDOWN FIRES. Three carriers in one fixture: the frontmatter value, the fenced
+//      command, and an inline mention. All three are how a real skill names a script.
+{
+  const m = await findings(mdLinter, join(FIX, "defect.md"), RULE_MD);
+  assert.ok(m.length >= 3, `expected at least three findings, got ${m.length}`);
+  assert.match(
+    m[0].message,
+    /INSTALLED/,
+    "the message must name what is wrong",
+  );
+  // Where the answer belongs — and it must be a file that EXISTS. Until #67 the message sent
+  // people to a module that was never in any commit, and a pattern match on the name was green.
+  assert.ok(m[0].message.includes(PORT), "and where the answer belongs");
+  assert.ok(
+    existsSync(join(ROOT, PORT)),
+    `the port ${PORT} must exist on disk`,
+  );
+  const prefixes = new Set(m.map((x) => x.message.match(/'([^']+)'/)?.[1]));
+  assert.ok(
+    prefixes.has(".claude/skills/"),
+    "the symlink channel must be named",
+  );
+  assert.ok(prefixes.has("node_modules/"), "the npm channel must be named");
+  cases.push("md fires on frontmatter, fenced command and inline mention");
+}
+
+// ── 2. MARKDOWN STAYS QUIET. Same skill written through the substitution, plus a
+//      repository-relative path that is identical in every channel.
+{
+  const m = await findings(mdLinter, join(FIX, "clean.md"), RULE_MD);
+  assert.equal(
+    m.length,
+    0,
+    `clean fixture must be silent, got ${JSON.stringify(m)}`,
+  );
+  cases.push("md quiet on a skill that uses the substitution");
+}
+
+// ── 3. JAVASCRIPT FIRES, in both literal forms. The template case is not decoration: a path
+//      assembled from a template is still a path, and reading only `Literal` would miss it.
+{
+  const m = await findings(jsLinter, join(FIX, "defect.fixture.mjs"), RULE_JS);
+  assert.equal(
+    m.length,
+    2,
+    `expected one plain and one template finding, got ${m.length}`,
+  );
+  cases.push("js fires on a plain literal AND on a template quasi");
+}
+
+// ── 4. JAVASCRIPT STAYS QUIET when the module asks the port.
+{
+  const m = await findings(jsLinter, join(FIX, "clean.fixture.mjs"), RULE_JS);
+  assert.equal(
+    m.length,
+    0,
+    `clean module must be silent, got ${JSON.stringify(m)}`,
+  );
+  cases.push("js quiet on a module that asks the port");
+}
+
+for (const c of cases) recordCheck(c);

package/eslint-rules/install-path-literals.mjs

@@ -0,0 +1,108 @@
+/**
+ * Rule 10's mechanical half: nothing outside the port may name a file by WHERE IT IS
+ * INSTALLED.
+ *
+ * The class this exists for has broken this repository five times, silently every time, and
+ * the detail is in `docs/incidents.md`. What matters for the code below is the shape of the
+ * defect: a path that is correct in one install channel and absent in another. There are
+ * three channels and each has its own give-away prefix — the consumer's skills directory
+ * (the symlink channel), the package directory npm creates, and the plugin cache. A literal
+ * naming any of them is a bet on the channel, made by a file that has no business knowing
+ * which channel it is in.
+ *
+ * WHY TWO RULES RATHER THAN ONE. The literals live in two different languages: markdown, in
+ * a skill's own prose and in its `allowed-tools` frontmatter, and JavaScript, in the modules
+ * this package ships. A single rule cannot visit both — ESLint hands a rule the AST of
+ * whatever language the file is, and the node types share nothing. So the detector is shared
+ * and the visitors are not.
+ *
+ * WHY NOT A GREP OVER THE FILE. In markdown the give-away sits inside a fenced block, inline
+ * code, or a YAML frontmatter value, and a text scan cannot tell those from a sentence that
+ * merely discusses the hazard — which is exactly what `CLAUDE.md` and `docs/incidents.md` do.
+ * The parser can: this rule sees nodes, and it is pointed only at skills.
+ */
+
+// Each entry is a prefix that only makes sense in ONE install channel.
+const CHANNEL_PREFIXES = [
+  ".claude/skills/", // the consumer symlinks the package's skills to here
+  "node_modules/", // npm's copy
+  ".claude/plugins/", // the plugin cache
+  "plugins/cache/", // the same cache, named from further up
+];
+
+/** The first channel prefix appearing in `s`, or null. Plain substring: a path IS a string. */
+function channelPrefixIn(s) {
+  if (typeof s !== "string") return null;
+  for (const p of CHANNEL_PREFIXES) if (s.includes(p)) return p;
+  return null;
+}
+
+// The port, named by its path INSIDE this package — the same in every channel, so naming it
+// is not the bet this rule forbids. One constant, because the advice below was once a file
+// that never existed (#67) and read fine for a week: the harness now requires it on disk.
+const PORT = "skills/paper-pipeline/scripts/consumer.mjs";
+
+const MESSAGES = {
+  installPath:
+    "This names a file by where it is INSTALLED ('{{prefix}}'), so it resolves in one " +
+    "delivery channel and does not exist in another. Rule 10: every answer to *where* comes " +
+    `from the port, ${PORT}. In a skill, use the substitution the harness performs ` +
+    "(CLAUDE_SKILL_DIR / CLAUDE_PLUGIN_ROOT); in a module, ask the port.",
+};
+
+/** Markdown: a skill's own prose, its fenced commands, and its YAML frontmatter. */
+const mdInstallPath = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "a skill must not name its scripts by an install-specific path — rule 10, the port owns where",
+    },
+    schema: [],
+    messages: MESSAGES,
+  },
+  create(context) {
+    const check = (node) => {
+      const prefix = channelPrefixIn(node.value);
+      if (prefix)
+        context.report({ node, messageId: "installPath", data: { prefix } });
+    };
+    // `yaml` is the frontmatter block, which is where `allowed-tools` lives; the other three
+    // are the ways a command can appear in the body.
+    return { yaml: check, code: check, inlineCode: check, text: check };
+  },
+};
+
+/** JavaScript: the modules this package ships. */
+const jsInstallPath = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "a shipped module must not carry an install-specific path literal — rule 10, the port owns where",
+    },
+    schema: [],
+    messages: MESSAGES,
+  },
+  create(context) {
+    const report = (node, prefix) =>
+      context.report({ node, messageId: "installPath", data: { prefix } });
+    return {
+      Literal(node) {
+        const prefix = channelPrefixIn(node.value);
+        if (prefix) report(node, prefix);
+      },
+      // A template literal's static parts are just as much a path as a plain string; its
+      // interpolations are not our business, which is why the quasis are read one by one.
+      TemplateElement(node) {
+        const prefix = channelPrefixIn(node.value?.cooked ?? node.value?.raw);
+        if (prefix) report(node, prefix);
+      },
+    };
+  },
+};
+
+export default {
+  rules: { "md-install-path": mdInstallPath, "js-install-path": jsInstallPath },
+};
+export { channelPrefixIn, CHANNEL_PREFIXES, PORT };

package/eslint-rules/install-path-literals.mutations.mjs

@@ -0,0 +1,62 @@
+/**
+ * Battery on the two `port/*-install-path` rules: four mutations, each removing one
+ * load-bearing property — the detection itself, the markdown carriers, the template form on
+ * the code side, and the ratchet.
+ *
+ * There is no fourth mutation here anymore — for the ratchet: the ratchet itself was removed.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { runMutations } from "../lib/mutation-driver.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..");
+const RULE = join(HERE, "install-path-literals.mjs");
+const HARNESS = join(HERE, "install-path-literals.harness.mjs");
+
+process.exit(
+  runMutations({
+    root: ROOT,
+    runner: "node",
+    cases: [
+      {
+        name: "the detector stops finding anything",
+        harness: HARNESS,
+        expect: "expected at least three findings",
+        disables:
+          "the check itself — an install-specific path passes silently in both languages",
+        edits: [
+          [
+            RULE,
+            "for (const p of CHANNEL_PREFIXES) if (s.includes(p)) return p;",
+            "void CHANNEL_PREFIXES;",
+          ],
+        ],
+      },
+      {
+        name: "markdown stops seeing frontmatter and code",
+        harness: HARNESS,
+        expect: "expected at least three findings",
+        disables:
+          "the carriers in a skill — only prose is left, while the command lives in a fence and in allowed-tools",
+        edits: [
+          [
+            RULE,
+            "return { yaml: check, code: check, inlineCode: check, text: check };",
+            "return { text: check };",
+          ],
+        ],
+      },
+      {
+        name: "code stops seeing the template string",
+        harness: HARNESS,
+        expect: "expected one plain and one template finding",
+        disables:
+          "the second literal form — a path assembled by a template stays a path",
+        edits: [
+          [RULE, "TemplateElement(node) {", "TemplateElement_disabled(node) {"],
+        ],
+      },
+    ],
+  }),
+);