vigiles 14.0.0 → 14.2.0

package/dist/cli.js

@@ -1535,7 +1535,7 @@ function computeRuleInventory(root, instructionFile) {
  * instruction files PLUS nested subdirectory-memory (`src/CLAUDE.md`,
  * `research/CLAUDE.md`, …), skipping fixture/demo/build/test dirs (`isFixturePath`)
  * so a repo's real memory is read without the test-fixture noise. `.claude/` rule
- * sources remain a future source. research/rule-compiler-multilang-design.md §0. */
+ * sources remain a future source. research/rule-enforcer-multilang-design.md §0. */
 function gatherInstructionFiles(root, instructionFile) {
     const raw = [];
     const collect = (rel) => {
@@ -1580,28 +1580,73 @@ function gatherInstructionFiles(root, instructionFile) {
  * sticky `audit.measure` consent as the other executing checks AND on own-repo
  * (never a stranger's toolchain). The textual routing is the foreign-safe default;
  * the catalog only ADDS enabled-state nudges and matches named-but-`/`-broken rules. */
+/** Does the repo actually USE Pylint — i.e. is there a real Pylint config to run
+ * against? A DEDICATED pylintrc file (`.pylintrc`, `pylintrc`, `.pylintrc.toml`,
+ * `pylintrc.toml`) is unambiguous. A SHARED file (`pyproject.toml`, `setup.cfg`,
+ * `tox.ini`) counts ONLY when it carries a Pylint section — otherwise a Ruff-only
+ * / packaging-only `pyproject.toml` would falsely make us spawn pylint and route
+ * docs as `reuse`/`enabled` against a linter the repo doesn't use. Mirrors
+ * Pylint's own config search order. */
+function hasPythonSurface(root) {
+    const dedicated = [
+        ".pylintrc",
+        "pylintrc",
+        ".pylintrc.toml",
+        "pylintrc.toml",
+    ];
+    if (dedicated.some((f) => (0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, f))))
+        return true;
+    // A pylint section: `[tool.pylint...]` (pyproject) or `[pylint...]` / `[MASTER]`
+    // / `[MESSAGES CONTROL]` (setup.cfg / tox.ini, incl. case variants).
+    const pylintSection = /(\[tool\.pylint)|(\[pylint)|(\[MASTER\])|(\[MESSAGES CONTROL\])/i;
+    for (const f of ["pyproject.toml", "setup.cfg", "tox.ini"]) {
+        const p = (0, node_path_1.resolve)(root, f);
+        if ((0, node_fs_1.existsSync)(p)) {
+            try {
+                if (pylintSection.test((0, node_fs_1.readFileSync)(p, "utf-8")))
+                    return true;
+            }
+            catch {
+                /* unreadable — treat as no pylint config */
+            }
+        }
+    }
+    return false;
+}
 function computeRuleRouting(root, instructionFile) {
     try {
         const files = gatherInstructionFiles(root, instructionFile);
         if (files.every((f) => !f.text.trim()))
             return undefined;
-        // Own-repo + consented → enumerate the live ESLint catalog. NOT gated on the
-        // agent harness: the catalog is a property of the repo's LINTER (its ESLint
-        // config on disk), not of Claude-Code-vs-Codex, so a Codex JS/TS repo gets the
-        // same catalog match + enabled-state (adapter-aware-lint-rules: never gate a
-        // harness-agnostic capability on CC). enumerateEslintCatalog returns null when
-        // no ESLint config resolves (e.g. a pure-Python repo) → undefined, so a non-JS
-        // repo simply falls back to the foreign-safe textual routing regardless.
+        // Own-repo + consented → enumerate the live rule catalog of whichever
+        // linter(s) the repo has: ESLint (JS/TS) and/or Pylint (Python), merged so a
+        // polyglot repo matches against both. NOT gated on the agent harness — a
+        // catalog is a property of the repo's LINTER (its config on disk), not of
+        // Claude-Code-vs-Codex (adapter-aware-lint-rules: never gate a harness-
+        // agnostic capability on CC). Each enumerate returns null when its linter
+        // doesn't apply, so a repo with neither falls back to the foreign-safe textual
+        // routing. Enumerating EXECUTES the linter (plugin code loads), hence own-repo
+        // + consent — same posture for both.
         const ownRepo = (0, node_path_1.resolve)(root) === (0, node_path_1.resolve)(process.cwd());
         const consented = (0, validate_js_1.loadConfig)().audit?.measure === true;
         const availableRules = ownRepo && consented
-            ? ((0, rule_catalog_js_1.enumerateEslintCatalog)(root) ?? undefined)
+            ? (0, rule_catalog_js_1.mergeCatalogs)((0, rule_catalog_js_1.enumerateEslintCatalog)(root), 
+            // Only spawn pylint when the repo actually has a Python surface —
+            // avoids a needless (and possibly noisy) pylint run on a pure-JS repo.
+            hasPythonSurface(root) ? (0, rule_catalog_js_1.enumeratePylintCatalog)(root) : null)
             : undefined;
         // Route each source SEPARATELY (each rule keeps its own file + line numbers),
         // then merge — so a CLAUDE.md rule and an AGENTS.md rule carry correct
         // provenance instead of line numbers offset by a concatenation.
         const routing = (0, rule_routing_js_1.mergeRoutings)(files.map((f) => (0, rule_routing_js_1.routeRules)(f.text, f.path, { availableRules })));
-        return routing.segmented > 0 ? routing : undefined;
+        // Keep the routing if it found ANY confident rule, possible rule, or skipped
+        // bullet — so the two-tier + skipped report surfaces even a doc with 0
+        // confident rules (all its bullets landed in possible/skipped).
+        return routing.segmented > 0 ||
+            routing.possible.length > 0 ||
+            routing.skipped.length > 0
+            ? routing
+            : undefined;
     }
     catch {
         return undefined;
@@ -1635,6 +1680,36 @@ function formatTriggerNudge(triggerableSkills) {
     return (`ℹ Do your ${String(n)} skill${n === 1 ? "" : "s"} actually fire? The deterministic read can't tell — ` +
         `run \`audit\` interactively to measure, or test with \`measureTriggerRate\` (vigiles/testing).`);
 }
+/** A terminal summary of the rule map: the CONFIDENT lane counts + the POSSIBLE
+ * (review) and SKIPPED tiers, with the honest caveat that detection is a
+ * heuristic filter. The full per-rule map + skipped list live in the HTML/JSON
+ * report; this is the "be clear about what was detected" headline. "" when there
+ * is nothing to show. */
+function formatRuleMapSummary(routing) {
+    if (!routing)
+        return "";
+    const { counts, possible, skipped } = routing;
+    const confident = counts.reuse +
+        counts.hook +
+        counts.unrouted +
+        counts.semantic +
+        counts.meta;
+    if (confident === 0 && possible.length === 0 && skipped.length === 0)
+        return "";
+    // Lane counts, rendered from the single-source LANE_META (glyph + label).
+    const lane = (c) => `${rule_routing_js_1.LANE_META[c].glyph} ${String(counts[c])} ${rule_routing_js_1.LANE_META[c].label}`;
+    const lines = [
+        "Rule map [experimental] — how your prose rules could be enforced (heuristic, precision-first; misses some rules):",
+        `  ${lane("reuse")} · ${lane("hook")} · ${lane("unrouted")} · ${lane("semantic")}` +
+            (counts.meta > 0 ? ` · ${lane("meta")}` : ""),
+    ];
+    if (possible.length > 0)
+        lines.push(`  ? ${String(possible.length)} possible — rule-ish, but below the confidence bar (review these)`);
+    if (skipped.length > 0)
+        lines.push(`  ⊘ ${String(skipped.length)} skipped — not treated as rules (setup steps, descriptions, index entries, no norm signal)`);
+    lines.push("  Detection is a best-effort filter — it won't catch every rule. Full map + skipped list in the report (or --json).");
+    return lines.join("\n");
+}
 function scaffoldSpec(args) {
     const targetFlag = args.find((a) => a.startsWith("--target="));
     const target = targetFlag ? targetFlag.split("=")[1] : "CLAUDE.md";
@@ -3905,7 +3980,7 @@ function printUsage(command) {
     console.log("  vigiles eject [file]           Un-manage a compiled file → plain hand-owned markdown (--keep-spec)");
     console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
     console.log("  vigiles audit [dir...]          Lighthouse for your harness — a LOCAL report: rings + what's broken + fixes (a deterministic read; 2+ dirs → leaderboard)");
-    console.log("                                 writes vigiles-report.html + vigiles-report.json (--no-html/--no-json) · --json for machine output. NOT a CI step — use `vigiles lint` in CI.");
+    console.log("                                 writes vigiles-report.html + .json (auto-gitignored; --out=<dir> · --no-html/--no-json · --no-open · --json for machine output). NOT a CI step — use `vigiles lint` in CI.");
     console.log("                                 the executing checks (run your hooks · live MCP · do skills fire?) run only interactively — `audit` asks once (remembered); automation uses the vigiles/testing API");
     console.log("                                 --serve opens a LIVE local report whose buttons create specs in one click (own repo only; loopback + token-guarded) · --no-serve to skip the prompt");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
@@ -4821,18 +4896,50 @@ async function runHookProgramCommand(file) {
         }
     }
 }
+/**
+ * Idempotently keep the generated report artifacts OUT of git — the tool that
+ * writes a build artifact keeps it ignored (the `next build` → `.next` pattern),
+ * so `vigiles audit` (which runs zero-config, without `init`) never leaves
+ * surprise untracked files in `git status`. Appends only the MISSING entries
+ * under a labelled block if a `.gitignore` exists; if none exists, prints a
+ * one-line nudge rather than creating one silently. Best-effort — a failure here
+ * never breaks the audit. `entries` are paths relative to the git root (cwd).
+ */
+function ensureReportGitignored(cwd, entries) {
+    if (entries.length === 0)
+        return;
+    const gi = (0, node_path_1.resolve)(cwd, ".gitignore");
+    try {
+        if (!(0, node_fs_1.existsSync)(gi)) {
+            console.log(`\nℹ tip: add ${entries.join(" + ")} to a .gitignore (generated report artifacts)`);
+            return;
+        }
+        const content = (0, node_fs_1.readFileSync)(gi, "utf-8");
+        const present = new Set(content.split("\n").map((l) => l.trim()));
+        const missing = entries.filter((e) => !present.has(e));
+        if (missing.length === 0)
+            return;
+        const sep = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+        (0, node_fs_1.writeFileSync)(gi, `${content}${sep}\n# vigiles audit report (generated)\n${missing.join("\n")}\n`);
+        console.log(`✓ Added ${missing.join(" + ")} to .gitignore`);
+    }
+    catch {
+        /* best-effort — a read-only or missing .gitignore never breaks the audit */
+    }
+}
 /**
  * Write the versioned JSON artifact (`vigiles-report.json`) — the upload/CI
  * boundary a hosted dashboard ingests. Stamps `meta.generatedAt` here (at write
  * time, not in the pure builder, so the HTML-embedded form stays deterministic).
  */
-function writeAuditJson(report) {
-    const jsonPath = (0, node_path_1.resolve)(process.cwd(), "vigiles-report.json");
+function writeAuditJson(report, outDir) {
+    const jsonPath = (0, node_path_1.resolve)(outDir, "vigiles-report.json");
     const stamped = {
         ...report,
         meta: { ...report.meta, generatedAt: new Date().toISOString() },
     };
     try {
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
         (0, node_fs_1.writeFileSync)(jsonPath, JSON.stringify(stamped, null, 2) + "\n");
         console.log("✓ Wrote vigiles-report.json — the upload/CI artifact");
     }
@@ -4864,12 +4971,16 @@ function openBestEffort(file) {
  * for a human at a TTY, open it best-effort. The shareable Lighthouse artifact;
  * never spawns a browser for an agent / CI run.
  */
-function writeAuditHtml(report) {
-    const htmlPath = (0, node_path_1.resolve)(process.cwd(), "vigiles-report.html");
+function writeAuditHtml(report, outDir, open) {
+    const htmlPath = (0, node_path_1.resolve)(outDir, "vigiles-report.html");
     try {
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
         (0, node_fs_1.writeFileSync)(htmlPath, (0, audit_html_js_1.renderAuditHtml)(report));
         console.log("\n✓ Wrote vigiles-report.html — open it for the full report");
-        if (process.stdout.isTTY)
+        // Great DX: pop the report open in the browser for a human at a TTY (the
+        // `lighthouse --view` behaviour). `--no-open` suppresses it; an agent / CI
+        // run (no TTY) never spawns a browser.
+        if (open && process.stdout.isTTY)
             openBestEffort(htmlPath);
     }
     catch (e) {
@@ -5309,26 +5420,30 @@ async function main() {
                 // Read the local flight recorder ONCE — feeds both the JSON report
                 // (structured summary, the product boundary) and the terminal render.
                 const ledgerRecords = (0, observe_js_1.readObservations)(root);
-                const auditReport = (0, audit_report_js_1.buildAuditReport)(report, {
+                // The report scaffold WITHOUT the rule map — the map's catalog
+                // enrichment (enabled-state / "documented but OFF") enumerates the repo's
+                // linter, which is gated on the SAME audit.measure consent as the
+                // executing checks. So the map is routed AFTER consent (resolved below)
+                // and folded into the report there, so a first-time "yes" enriches THIS
+                // run — not the next one.
+                const auditReportBase = (0, audit_report_js_1.buildAuditReport)(report, {
                     harness: adapter.name,
                     vigilesVersion: getVersion(),
                     adoptableSurfaces,
                     observations: (0, observe_js_1.summarizeObservations)(ledgerRecords),
                     rulesInventory: computeRuleInventory(root, adapter.layout.instructionFile),
-                    ruleRouting: computeRuleRouting(root, adapter.layout.instructionFile),
                 });
-                const sc = auditReport.score;
+                const sc = auditReportBase.score;
                 const plan = (0, optimize_js_1.optimize)(report);
+                // The deterministic READ leads: rings + report + fixes + nudges print
+                // BEFORE the consent prompt, so a plain `audit` shows its findings first.
+                // (JSON stays silent until the single blob below, after consent.)
                 if (!json) {
                     // The Lighthouse rings: per-category 0–100 + the weighted overall,
                     // shown before the detailed report so the headline signal leads.
                     console.log((0, audit_score_js_1.formatAuditScore)(sc));
                     console.log("");
-                }
-                console.log(json
-                    ? JSON.stringify(auditReport, null, 2)
-                    : (0, scan_js_1.formatScanReport)(report));
-                if (!json) {
+                    console.log((0, scan_js_1.formatScanReport)(report));
                     // Fold each finding's fix inline (replaces the former --fix-plan/--explain
                     // flags): the deterministic, free recommendation list under the report.
                     const fixes = (0, optimize_js_1.formatRecommendations)(plan);
@@ -5346,17 +5461,14 @@ async function main() {
                         .length);
                     if (fireNudge)
                         console.log("\n" + fireNudge);
-                    // The flight recorder: a compact summary of what the harness actually
-                    // DID in real sessions (hook/agent decisions), read off the local
-                    // agent-readable ledger. Empty (skipped) until something is recorded.
-                    const ledgerSummary = (0, observe_js_1.formatLedgerSummary)(ledgerRecords);
-                    if (ledgerSummary)
-                        console.log("\n" + ledgerSummary);
                 }
                 // ONE read-vs-run decision for the EXECUTING checks (live MCP + skill
-                // firing). A plain `audit` is a deterministic READ; these run only on
-                // consent — ASK once at a TTY (remembered); headless stays a read + a
-                // nudge (no execution flag — automation uses the vigiles/testing API).
+                // firing) AND the rule map's catalog enrichment (enumerating the repo's
+                // linter also executes it). A plain `audit` is a deterministic READ;
+                // these run only on consent — ASK once at a TTY (remembered); headless
+                // stays a read + a nudge (no execution flag — automation uses the
+                // vigiles/testing API). Resolved AFTER the report (so the read leads) but
+                // BEFORE the rule map is routed, so a first-time "yes" enriches THIS run.
                 // (The safety battery is NOT here — it needs cross-platform confinement
                 // that isn't shipped, so it lives in the vigiles/testing API.)
                 const isForeign = root !== process.cwd();
@@ -5368,6 +5480,30 @@ async function main() {
                         (0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, adapter.layout.instructionFile)),
                 };
                 const { execute, note: execNote } = await resolveExecution(surfaces, json, args, adapter.name);
+                // Consent is now settled (and remembered via .vigilesrc.json, which
+                // computeRuleRouting re-reads) — route the prose rules, enumerating the
+                // live catalog when consented + own-repo. Feeds the JSON report, the
+                // written artifacts, and the terminal rule-map summary.
+                const ruleRouting = computeRuleRouting(root, adapter.layout.instructionFile);
+                const auditReport = ruleRouting
+                    ? { ...auditReportBase, ruleRouting }
+                    : auditReportBase;
+                if (json) {
+                    console.log(JSON.stringify(auditReport, null, 2));
+                }
+                else {
+                    // The rule map — what audit detected in your instruction file and how
+                    // each rule could be enforced (confident / possible / skipped tiers).
+                    const ruleMap = formatRuleMapSummary(ruleRouting);
+                    if (ruleMap)
+                        console.log("\n" + ruleMap);
+                    // The flight recorder: a compact summary of what the harness actually
+                    // DID in real sessions (hook/agent decisions), read off the local
+                    // agent-readable ledger. Empty (skipped) until something is recorded.
+                    const ledgerSummary = (0, observe_js_1.formatLedgerSummary)(ledgerRecords);
+                    if (ledgerSummary)
+                        console.log("\n" + ledgerSummary);
+                }
                 // LIVE MCP tool resolution STARTS each declared MCP server — a server is
                 // exactly what connects to a real Postgres / authenticates a real API on
                 // boot. So it runs only under consent (`execute`) AND own-repo (never
@@ -5465,10 +5601,19 @@ async function main() {
                 const finalReport = adoptabilityResult
                     ? { ...auditReport, adoptability: adoptabilityResult }
                     : auditReport;
+                // Where the report artifacts land: cwd by default, or `--out=<dir>` (for
+                // CI upload / a custom location). The dir is created if missing.
+                const outFlag = args.find((a) => a.startsWith("--out="));
+                const outDir = outFlag
+                    ? (0, node_path_1.resolve)(process.cwd(), outFlag.slice("--out=".length))
+                    : process.cwd();
+                const openReport = !args.includes("--no-open");
+                const wroteReports = [];
                 // The versioned JSON artifact — the upload/CI boundary (a hosted dashboard
                 // ingests this). Written by default in the human path; --no-json to skip.
                 if (!json && !args.includes("--no-json")) {
-                    writeAuditJson(finalReport);
+                    writeAuditJson(finalReport, outDir);
+                    wroteReports.push("vigiles-report.json");
                 }
                 // The HTML report has two deliveries. STATIC (default): write the
                 // shareable file whose buttons copy the `init` command. LIVE (`--serve`,
@@ -5493,7 +5638,21 @@ async function main() {
                     await runAuditServe(finalReport, finalReport.adoptable, errMsg);
                 }
                 else if (!json && !args.includes("--no-html")) {
-                    writeAuditHtml(finalReport);
+                    writeAuditHtml(finalReport, outDir, openReport);
+                    wroteReports.push("vigiles-report.html");
+                }
+                // Keep the generated artifacts out of git so a zero-config `audit` leaves
+                // a clean `git status` (works without `init`). Entries are relative to the
+                // git root (cwd); a custom --out dir is ignored by its relative path.
+                // .gitignore patterns are POSIX-separated, so normalize away Windows
+                // backslashes (`relative()` yields `reports\x` on Windows, which would
+                // never match `reports/x`).
+                if (wroteReports.length > 0) {
+                    const rel = wroteReports.map((f) => {
+                        const r = (0, node_path_1.relative)(process.cwd(), (0, node_path_1.resolve)(outDir, f)) || f;
+                        return node_path_1.sep === "/" ? r : r.split(node_path_1.sep).join("/");
+                    });
+                    ensureReportGitignored(process.cwd(), rel);
                 }
             }
             break;

package/dist/core/rule-catalog.d.ts

@@ -8,7 +8,7 @@
  * / boundaries), of which ~140 are enabled — vs the old static map's ~23. That
  * makes an architecture norm enforceable too (`boundaries/dependencies` is in the
  * catalog), which a static map never captured. See
- * `research/rule-compiler-multilang-design.md` §0 (the spike this productizes).
+ * `research/rule-enforcer-multilang-design.md` §0 (the spike this productizes).
  *
  * SAFETY — this EXECUTES the linter. Loading ESLint resolves the repo's real
  * config (which can run plugin/config code), so `enumerateEslintCatalog` is an
@@ -21,16 +21,25 @@
  */
 /** One rule the repo's linter has available, with its enabled state. */
 export interface AvailableRule {
-    /** The rule id: `no-console`, `@typescript-eslint/no-explicit-any`, `boundaries/dependencies`. */
+    /** The rule id: `no-console`, `@typescript-eslint/no-explicit-any`, `boundaries/dependencies`.
+     * For Pylint this is the SYMBOLIC name (`missing-function-docstring`). */
     id: string;
-    /** The plugin prefix (`@typescript-eslint`, `boundaries`), or null for a core rule. */
+    /** The linter this rule belongs to. Carried PER-RULE (not only on the catalog)
+     * so a merged polyglot catalog keeps each rule's provenance — a routed reuse
+     * hit can then say `pylint:invalid-name` vs `eslint:no-console`. */
+    linter: "eslint" | "pylint";
+    /** The plugin prefix (`@typescript-eslint`, `boundaries`), or null for a core rule.
+     * Pylint's `--list-msgs` doesn't attribute a message to its plugin, so it's null there. */
     plugin: string | null;
+    /** An alternate id the rule is ALSO matchable by (Pylint's numeric code, e.g. `C0116`),
+     * so a doc naming either the symbol or the code resolves. Absent for ESLint. */
+    code?: string;
     /** Whether the rule is enabled (severity not 0/"off") in the resolved config. */
     enabled: boolean;
 }
 /** The full available-rule catalog for a repo's linter. */
 export interface RuleCatalog {
-    linter: "eslint";
+    linter: "eslint" | "pylint";
     /** Total rules available (core + every installed plugin). */
     available: number;
     /** How many of those are enabled in the resolved config. */
@@ -45,6 +54,30 @@ export interface RuleCatalog {
  * `discoverEslintRules` returning null when nothing is found).
  */
 export declare function parseEslintCatalog(raw: string): RuleCatalog | null;
+/**
+ * Parse pylint's `--list-msgs` (available) + `--list-msgs-enabled` (enabled)
+ * text listings into a typed {@link RuleCatalog}.
+ *
+ * The available set is every emittable message (`:name (CODE):` lines); enabled
+ * is the section-scoped subset. Each rule is matchable by BOTH its symbolic name
+ * (`id`) and its numeric code (`code`), since a doc may name either. Returns null
+ * when no message parses (pylint absent, or malformed output).
+ */
+export declare function parsePylintCatalog(listMsgs: string, listEnabled: string): RuleCatalog | null;
+/**
+ * Merge the catalogs of every linter a repo has into ONE catalog for routing.
+ *
+ * KEEPS EVERY entry — a polyglot repo genuinely has a rule in each linter, so an
+ * id shared across ESLint and Pylint (`no-else-return`) is two real rules and
+ * both are retained (never dropped by id, the bug that let a Python doc inherit
+ * ESLint's state). Collision handling belongs at the ROUTING lookup, not here: a
+ * bare id that resolves to two hits is combined conservatively there, while a
+ * numeric code (unique to its linter) keeps its own hit — see `buildCatalogLookup`
+ * in rule-routing.ts. So the merge is a plain concatenation; each rule carries its
+ * own `linter`/`enabled`/`code` provenance. Returns undefined when nothing was
+ * enumerated (so a non-JS-non-Python repo is byte-identical to before this existed).
+ */
+export declare function mergeCatalogs(...cats: (RuleCatalog | null | undefined)[]): RuleCatalog | undefined;
 /**
  * Enumerate the repo's available ESLint rules (core + every installed plugin).
  *
@@ -53,4 +86,16 @@ export declare function parseEslintCatalog(raw: string): RuleCatalog | null;
  * config applies, or the subprocess fails.
  */
 export declare function enumerateEslintCatalog(root: string): RuleCatalog | null;
+/**
+ * Enumerate the repo's available Pylint messages (core + every loaded plugin)
+ * and their enabled state, via `pylint --list-msgs` + `--list-msgs-enabled`.
+ *
+ * Run at the repo's cwd so its rcfile (`.pylintrc` / `pyproject.toml` /
+ * `setup.cfg`) and `load-plugins` apply — so the listing reflects the repo's
+ * REAL rule set, plugins included, with correct enabled state. Like the ESLint
+ * catalog this EXECUTES the linter (loading a pylint plugin imports its module),
+ * so it's an OWN-REPO / consented capability, NOT the foreign-safe default.
+ * Returns null when pylint isn't runnable or lists nothing.
+ */
+export declare function enumeratePylintCatalog(root: string): RuleCatalog | null;
 //# sourceMappingURL=rule-catalog.d.ts.map

package/dist/core/rule-catalog.js

@@ -9,7 +9,7 @@
  * / boundaries), of which ~140 are enabled — vs the old static map's ~23. That
  * makes an architecture norm enforceable too (`boundaries/dependencies` is in the
  * catalog), which a static map never captured. See
- * `research/rule-compiler-multilang-design.md` §0 (the spike this productizes).
+ * `research/rule-enforcer-multilang-design.md` §0 (the spike this productizes).
  *
  * SAFETY — this EXECUTES the linter. Loading ESLint resolves the repo's real
  * config (which can run plugin/config code), so `enumerateEslintCatalog` is an
@@ -22,7 +22,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseEslintCatalog = parseEslintCatalog;
+exports.parsePylintCatalog = parsePylintCatalog;
+exports.mergeCatalogs = mergeCatalogs;
 exports.enumerateEslintCatalog = enumerateEslintCatalog;
+exports.enumeratePylintCatalog = enumeratePylintCatalog;
 const node_path_1 = require("node:path");
 const node_child_process_1 = require("node:child_process");
 // ---------------------------------------------------------------------------
@@ -44,12 +47,22 @@ function parsePlugins(v) {
 function buildRules(core, plugins, enabledSet) {
     const rules = [];
     for (const id of core) {
-        rules.push({ id, plugin: null, enabled: enabledSet.has(id) });
+        rules.push({
+            id,
+            linter: "eslint",
+            plugin: null,
+            enabled: enabledSet.has(id),
+        });
     }
     for (const [prefix, pluginRules] of Object.entries(plugins)) {
         for (const rule of pluginRules) {
             const id = `${prefix}/${rule}`;
-            rules.push({ id, plugin: prefix, enabled: enabledSet.has(id) });
+            rules.push({
+                id,
+                linter: "eslint",
+                plugin: prefix,
+                enabled: enabledSet.has(id),
+            });
         }
     }
     return rules;
@@ -85,6 +98,108 @@ function parseEslintCatalog(raw) {
     return { linter: "eslint", available: rules.length, enabled, rules };
 }
 // ---------------------------------------------------------------------------
+// Pure parse: pylint's text listings → typed catalog (covered by the unit test)
+// ---------------------------------------------------------------------------
+// A message line in `pylint --list-msgs`: `:invalid-name (C0103): *...*`
+// (leading colon, no indent). In `--list-msgs-enabled`: `  invalid-name (C0103)`
+// (indented, no colon). One regex captures the `name (CODE)` core of both.
+const PYLINT_MSG_RE = /^\s*:?([a-z][a-z0-9-]*)\s+\(([A-Z]\d+)\)/;
+/** Collect the symbol names under the `Enabled messages:` header ONLY.
+ *
+ * `--list-msgs-enabled` also prints `Disabled messages:` and `Non-emittable
+ * messages:` sections with the SAME `name (CODE)` line shape, so a naive
+ * line-shape parse would mislabel disabled rules as enabled. Track the current
+ * section: a non-indented line ending in `:` is a header; only lines while the
+ * "enabled" header is active count. */
+function parseEnabledSymbols(listEnabled) {
+    const enabled = new Set();
+    let inEnabled = false;
+    for (const line of listEnabled.split("\n")) {
+        // A section header is a flush-left line ending in a colon (e.g.
+        // "Enabled messages:", "Disabled messages:"). Indented message lines never
+        // start at column 0, so this never eats a rule.
+        if (/^\S.*:\s*$/.test(line)) {
+            inEnabled = /^enabled messages:/i.test(line.trim());
+            continue;
+        }
+        if (!inEnabled)
+            continue;
+        const m = PYLINT_MSG_RE.exec(line);
+        if (m)
+            enabled.add(m[1]);
+    }
+    return enabled;
+}
+/**
+ * Parse pylint's `--list-msgs` (available) + `--list-msgs-enabled` (enabled)
+ * text listings into a typed {@link RuleCatalog}.
+ *
+ * The available set is every emittable message (`:name (CODE):` lines); enabled
+ * is the section-scoped subset. Each rule is matchable by BOTH its symbolic name
+ * (`id`) and its numeric code (`code`), since a doc may name either. Returns null
+ * when no message parses (pylint absent, or malformed output).
+ */
+function parsePylintCatalog(listMsgs, listEnabled) {
+    const enabledSet = parseEnabledSymbols(listEnabled);
+    const rules = [];
+    const seen = new Set();
+    for (const line of listMsgs.split("\n")) {
+        // Available lines carry a leading colon; skip anything else (headers, the
+        // wrapped description lines, blank lines).
+        if (!line.startsWith(":"))
+            continue;
+        const m = PYLINT_MSG_RE.exec(line);
+        if (!m)
+            continue;
+        const [, name, code] = m;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        rules.push({
+            id: name,
+            linter: "pylint",
+            plugin: null,
+            code,
+            enabled: enabledSet.has(name),
+        });
+    }
+    if (rules.length === 0)
+        return null;
+    const enabled = rules.reduce((n, r) => (r.enabled ? n + 1 : n), 0);
+    return { linter: "pylint", available: rules.length, enabled, rules };
+}
+// ---------------------------------------------------------------------------
+// Merge: a polyglot repo (JS + Python) yields two catalogs → one for routing
+// ---------------------------------------------------------------------------
+/**
+ * Merge the catalogs of every linter a repo has into ONE catalog for routing.
+ *
+ * KEEPS EVERY entry — a polyglot repo genuinely has a rule in each linter, so an
+ * id shared across ESLint and Pylint (`no-else-return`) is two real rules and
+ * both are retained (never dropped by id, the bug that let a Python doc inherit
+ * ESLint's state). Collision handling belongs at the ROUTING lookup, not here: a
+ * bare id that resolves to two hits is combined conservatively there, while a
+ * numeric code (unique to its linter) keeps its own hit — see `buildCatalogLookup`
+ * in rule-routing.ts. So the merge is a plain concatenation; each rule carries its
+ * own `linter`/`enabled`/`code` provenance. Returns undefined when nothing was
+ * enumerated (so a non-JS-non-Python repo is byte-identical to before this existed).
+ */
+function mergeCatalogs(...cats) {
+    const present = cats.filter((c) => c != null);
+    if (present.length === 0)
+        return undefined;
+    if (present.length === 1)
+        return present[0];
+    const rules = present.flatMap((c) => c.rules);
+    const enabled = rules.reduce((n, r) => (r.enabled ? n + 1 : n), 0);
+    return {
+        linter: present[0].linter,
+        available: rules.length,
+        enabled,
+        rules,
+    };
+}
+// ---------------------------------------------------------------------------
 // Real-IO seam: run ESLint in a child process at the repo's cwd
 // ---------------------------------------------------------------------------
 /* v8 ignore start -- spawns a `node -e` subprocess that LOADS ESLint in the
@@ -143,4 +258,37 @@ function enumerateEslintCatalog(root) {
     }
 }
 /* v8 ignore stop */
+// ---------------------------------------------------------------------------
+// Real-IO seam: run pylint in a child process at the repo's cwd
+// ---------------------------------------------------------------------------
+/* v8 ignore start -- spawns the repo's `pylint` twice (the executes-the-linter
+   seam); the pure text→typed parse is parsePylintCatalog, covered by the unit
+   test, and the gated integration test drives this real path when pylint is on
+   PATH. */
+/**
+ * Enumerate the repo's available Pylint messages (core + every loaded plugin)
+ * and their enabled state, via `pylint --list-msgs` + `--list-msgs-enabled`.
+ *
+ * Run at the repo's cwd so its rcfile (`.pylintrc` / `pyproject.toml` /
+ * `setup.cfg`) and `load-plugins` apply — so the listing reflects the repo's
+ * REAL rule set, plugins included, with correct enabled state. Like the ESLint
+ * catalog this EXECUTES the linter (loading a pylint plugin imports its module),
+ * so it's an OWN-REPO / consented capability, NOT the foreign-safe default.
+ * Returns null when pylint isn't runnable or lists nothing.
+ */
+function enumeratePylintCatalog(root) {
+    const run = (args) => (0, node_child_process_1.execSync)(`pylint ${args}`, {
+        encoding: "utf-8",
+        cwd: root,
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 15000,
+    });
+    try {
+        return parsePylintCatalog(run("--list-msgs"), run("--list-msgs-enabled"));
+    }
+    catch {
+        return null;
+    }
+}
+/* v8 ignore stop */
 //# sourceMappingURL=rule-catalog.js.map

package/dist/instruction-sources.d.ts

@@ -7,7 +7,7 @@
  * NOISE that would flood the preview. `isFixturePath` is the precision-first
  * discriminator (over-skip a legit `sample-service` before flooding with fixture
  * rules). Pure + unit-tested; the fs discovery/glue lives in cli.ts
- * (`gatherInstructionFiles`). See research/rule-compiler-multilang-design.md §0.
+ * (`gatherInstructionFiles`). See research/rule-enforcer-multilang-design.md §0.
  */
 /** One instruction file gathered from disk, with its canonical (symlink-resolved)
  * path so a mirror can be detected. */

package/dist/instruction-sources.js

@@ -8,7 +8,7 @@
  * NOISE that would flood the preview. `isFixturePath` is the precision-first
  * discriminator (over-skip a legit `sample-service` before flooding with fixture
  * rules). Pure + unit-tested; the fs discovery/glue lives in cli.ts
- * (`gatherInstructionFiles`). See research/rule-compiler-multilang-design.md §0.
+ * (`gatherInstructionFiles`). See research/rule-enforcer-multilang-design.md §0.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dedupeInstructionFiles = dedupeInstructionFiles;