claudecode-linter 2.1.138-patch.1 → 2.1.138-patch.2

package/dist/discovery.js

@@ -173,6 +173,19 @@ function discoverInDirectory(dir) {
     for (const f of hooks) {
         artifacts.push({ filePath: f, artifactType: "hooks-json" });
     }
+    // .lsp.json (flat record at plugin root; Claude Code reads from <plugin>/.lsp.json)
+    const lspDot = join(dir, ".lsp.json");
+    if (existsSync(lspDot)) {
+        artifacts.push({ filePath: lspDot, artifactType: "lsp-json" });
+    }
+    // monitors/monitors.json
+    const monitors = globSync("monitors/monitors.json", {
+        cwd: dir,
+        absolute: true,
+    });
+    for (const f of monitors) {
+        artifacts.push({ filePath: f, artifactType: "monitors-json" });
+    }
     // Claude config files — settings
     for (const name of ["settings.json", "settings.local.json"]) {
         // Direct in dir (handles both ~/.claude/settings.json and project root)
@@ -283,6 +296,10 @@ function classifyFile(filePath) {
         return "skill-md";
     if (name === "hooks.json" && parent === "hooks")
         return "hooks-json";
+    if (name === ".lsp.json")
+        return "lsp-json";
+    if (name === "monitors.json" && parent === "monitors")
+        return "monitors-json";
     if (name.endsWith(".md") && parent === "agents")
         return "agent-md";
     if (name.endsWith(".md") && parent === "commands")

package/dist/index.js

@@ -16,6 +16,8 @@ import { hooksJsonLinter } from "./linters/hooks-json.js";
 import { settingsJsonLinter } from "./linters/settings-json.js";
 import { mcpJsonLinter } from "./linters/mcp-json.js";
 import { claudeMdLinter } from "./linters/claude-md.js";
+import { lspJsonLinter } from "./linters/lsp-json.js";
+import { monitorsJsonLinter } from "./linters/monitors-json.js";
 import { misplacedFileLinter, MISPLACED_FILE_RULES, } from "./linters/misplaced-file.js";
 import { pluginJsonFixer } from "./fixers/plugin-json.js";
 import { frontmatterFixer } from "./fixers/frontmatter.js";
@@ -31,6 +33,8 @@ import { HOOKS_JSON_RULES } from "./linters/hooks-json.js";
 import { SETTINGS_JSON_RULES } from "./linters/settings-json.js";
 import { MCP_JSON_RULES } from "./linters/mcp-json.js";
 import { CLAUDE_MD_RULES } from "./linters/claude-md.js";
+import { LSP_JSON_RULES } from "./linters/lsp-json.js";
+import { MONITORS_JSON_RULES } from "./linters/monitors-json.js";
 const LINTERS = {
     "plugin-json": pluginJsonLinter,
     "skill-md": skillMdLinter,
@@ -40,6 +44,8 @@ const LINTERS = {
     "settings-json": settingsJsonLinter,
     "mcp-json": mcpJsonLinter,
     "claude-md": claudeMdLinter,
+    "lsp-json": lspJsonLinter,
+    "monitors-json": monitorsJsonLinter,
     "misplaced-file": misplacedFileLinter,
 };
 const FIXERS = {
@@ -61,6 +67,8 @@ const ALL_RULES = [
     ...SETTINGS_JSON_RULES,
     ...MCP_JSON_RULES,
     ...CLAUDE_MD_RULES,
+    ...LSP_JSON_RULES,
+    ...MONITORS_JSON_RULES,
     ...MISPLACED_FILE_RULES,
 ];
 function simpleDiff(oldContent, newContent, filePath) {

package/dist/linters/lsp-json.js

@@ -0,0 +1,94 @@
+/**
+ * Lints standalone `.lsp.json` files (a flat map of server-name → LSP server
+ * config). Validates against the schema auto-extracted from Claude Code's
+ * runtime parser `E.record(E.string(), RSH()).safeParse(content)` — see
+ * scripts/extract-plugin-schema.ts → buildLspSchema().
+ *
+ * The most common mistake (observed in cluster plugin 0.29.0 → 0.30.3) is
+ * wrapping the contents under a top-level `lspServers` key. That wrapper only
+ * belongs inside plugin.json; a dedicated `.lsp.json` file must be flat.
+ * lsp-json/no-lsp-servers-wrapper catches this with a friendlier message
+ * than the generic "missing required field command" Ajv would otherwise emit.
+ */
+import { formatAjvError, loadLspSchema, summarizeErrors, } from "../plugin-schema.js";
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+const RULES = [
+    { id: "lsp-json/valid-json", defaultSeverity: "error" },
+    { id: "lsp-json/no-lsp-servers-wrapper", defaultSeverity: "error" },
+    { id: "lsp-json/schema-valid", defaultSeverity: "error" },
+];
+function diag(config, filePath, ruleId, defaultSeverity, message, line, column) {
+    if (!isRuleEnabled(config, ruleId))
+        return null;
+    return {
+        rule: ruleId,
+        severity: getRuleSeverity(config, ruleId, defaultSeverity),
+        message,
+        file: filePath,
+        line,
+        column,
+    };
+}
+function findKeyPosition(content, key) {
+    const re = new RegExp(`"${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"\\s*:`);
+    const match = re.exec(content);
+    if (!match)
+        return undefined;
+    const before = content.slice(0, match.index);
+    const line = before.split("\n").length;
+    const lastNl = before.lastIndexOf("\n");
+    const column = match.index - lastNl;
+    return { line, column };
+}
+export const lspJsonLinter = {
+    artifactType: "lsp-json",
+    lint(filePath, content, config) {
+        const diagnostics = [];
+        const push = (d) => {
+            if (d)
+                diagnostics.push(d);
+        };
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (e) {
+            push(diag(config, filePath, "lsp-json/valid-json", "error", `Invalid JSON: ${e.message}`));
+            return diagnostics;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            push(diag(config, filePath, "lsp-json/valid-json", "error", ".lsp.json must be a JSON object (map of server-name → config)"));
+            return diagnostics;
+        }
+        const obj = parsed;
+        // Special-case the cluster-plugin bug: wrapping content under "lspServers".
+        // That key is only valid inline in plugin.json. The dedicated file uses a
+        // flat map, so an "lspServers" wrapper is silently mis-validated by Claude
+        // Code at session start (each server entry fails RSH validation since it
+        // looks like one server config with sub-server keys).
+        if ("lspServers" in obj) {
+            const p = findKeyPosition(content, "lspServers");
+            push(diag(config, filePath, "lsp-json/no-lsp-servers-wrapper", "error", '.lsp.json must not have a top-level "lspServers" key — the file is itself the map of server-name → config. The "lspServers" wrapper only belongs in plugin.json under the lspServers field.', p?.line, p?.column));
+        }
+        // Schema validation — defers to the extracted Zod-equivalent JSON Schema.
+        if (isRuleEnabled(config, "lsp-json/schema-valid")) {
+            const ctx = loadLspSchema();
+            if (ctx) {
+                const ok = ctx.validate(parsed);
+                if (!ok && ctx.validate.errors) {
+                    const filtered = summarizeErrors(ctx.validate.errors);
+                    for (const err of filtered) {
+                        const firstSeg = err.instancePath
+                            .split("/")
+                            .filter(Boolean)[0];
+                        const p = firstSeg ? findKeyPosition(content, firstSeg) : undefined;
+                        push(diag(config, filePath, "lsp-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
+        return diagnostics;
+    },
+};
+export { RULES as LSP_JSON_RULES };
+//# sourceMappingURL=lsp-json.js.map

package/dist/linters/monitors-json.js

@@ -0,0 +1,85 @@
+/**
+ * Lints standalone `monitors/monitors.json` files (an array of monitor
+ * entries). Validates against the schema auto-extracted from Claude Code's
+ * runtime parser `vC8().parse(content)` — see scripts/extract-plugin-schema.ts
+ * → buildMonitorsSchema().
+ *
+ * monitors-json/unique-names mirrors Claude Code's refine() check that
+ * `Monitor names must be unique within a plugin`. JSON Schema can't express
+ * that constraint natively so we enforce it here.
+ */
+import { formatAjvError, loadMonitorsSchema, summarizeErrors, } from "../plugin-schema.js";
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+const RULES = [
+    { id: "monitors-json/valid-json", defaultSeverity: "error" },
+    { id: "monitors-json/schema-valid", defaultSeverity: "error" },
+    { id: "monitors-json/unique-names", defaultSeverity: "error" },
+];
+function diag(config, filePath, ruleId, defaultSeverity, message, line, column) {
+    if (!isRuleEnabled(config, ruleId))
+        return null;
+    return {
+        rule: ruleId,
+        severity: getRuleSeverity(config, ruleId, defaultSeverity),
+        message,
+        file: filePath,
+        line,
+        column,
+    };
+}
+export const monitorsJsonLinter = {
+    artifactType: "monitors-json",
+    lint(filePath, content, config) {
+        const diagnostics = [];
+        const push = (d) => {
+            if (d)
+                diagnostics.push(d);
+        };
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (e) {
+            push(diag(config, filePath, "monitors-json/valid-json", "error", `Invalid JSON: ${e.message}`));
+            return diagnostics;
+        }
+        if (!Array.isArray(parsed)) {
+            push(diag(config, filePath, "monitors-json/valid-json", "error", "monitors.json must be a JSON array of monitor entries"));
+            return diagnostics;
+        }
+        // Schema validation
+        if (isRuleEnabled(config, "monitors-json/schema-valid")) {
+            const ctx = loadMonitorsSchema();
+            if (ctx) {
+                const ok = ctx.validate(parsed);
+                if (!ok && ctx.validate.errors) {
+                    const filtered = summarizeErrors(ctx.validate.errors);
+                    for (const err of filtered) {
+                        push(diag(config, filePath, "monitors-json/schema-valid", "error", formatAjvError(err)));
+                    }
+                }
+            }
+        }
+        // Unique-name refinement — Claude Code's refine() check.
+        if (isRuleEnabled(config, "monitors-json/unique-names")) {
+            const seen = new Set();
+            const duplicates = new Set();
+            for (const entry of parsed) {
+                if (entry &&
+                    typeof entry === "object" &&
+                    typeof entry.name === "string") {
+                    const name = entry.name;
+                    if (seen.has(name))
+                        duplicates.add(name);
+                    seen.add(name);
+                }
+            }
+            for (const dup of duplicates) {
+                push(diag(config, filePath, "monitors-json/unique-names", "error", `Monitor name "${dup}" is duplicated. Monitor names must be unique within a plugin.`));
+            }
+        }
+        return diagnostics;
+    },
+};
+export { RULES as MONITORS_JSON_RULES };
+//# sourceMappingURL=monitors-json.js.map

package/dist/linters/plugin-json.js

@@ -1,5 +1,6 @@
 import semver from "semver";
 import { PLUGIN_JSON_FIELDS } from "../contracts.js";
+import { formatAjvError, loadPluginSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { isKebabCase } from "../utils/kebab-case.js";
 const SPDX_COMMON = new Set([
@@ -9,6 +10,7 @@ const SPDX_COMMON = new Set([
 ]);
 const RULES = [
     { id: "plugin-json/valid-json", defaultSeverity: "error" },
+    { id: "plugin-json/schema-valid", defaultSeverity: "error" },
     { id: "plugin-json/name-required", defaultSeverity: "error" },
     { id: "plugin-json/name-kebab-case", defaultSeverity: "error" },
     { id: "plugin-json/name-length", defaultSeverity: "error" },
@@ -64,6 +66,27 @@ export const pluginJsonLinter = {
             push(diag(config, filePath, "plugin-json/valid-json", "error", "plugin.json must be a JSON object"));
             return diagnostics;
         }
+        // schema-valid — defer to extracted JSON Schema for type/enum/nested checks
+        // that the per-field rules below don't cover. Existing rules (name-required,
+        // version-semver, …) handle the common cases with friendlier messages, so
+        // most users will see schema-valid fire only on deeper structural issues
+        // (MCP transport unions, userConfig shape, etc.). Skipped silently if the
+        // schema bundle isn't shipped with this install.
+        if (isRuleEnabled(config, "plugin-json/schema-valid")) {
+            const ctx = loadPluginSchema();
+            if (ctx) {
+                const ok = ctx.validate(parsed);
+                if (!ok && ctx.validate.errors) {
+                    const filtered = summarizeErrors(ctx.validate.errors);
+                    for (const err of filtered) {
+                        // First path segment maps to a top-level field we can highlight.
+                        const firstSeg = err.instancePath.split("/").filter(Boolean)[0];
+                        const p = firstSeg ? pos(firstSeg) : undefined;
+                        push(diag(config, filePath, "plugin-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
         // name
         if (!("name" in parsed) || typeof parsed.name !== "string" || parsed.name === "") {
             push(diag(config, filePath, "plugin-json/name-required", "error", "\"name\" field is required and must be a non-empty string"));
@@ -142,11 +165,17 @@ export const pluginJsonLinter = {
                 }
             }
         }
-        // unknown fields
-        for (const key of Object.keys(parsed)) {
-            if (!PLUGIN_JSON_FIELDS.has(key)) {
-                const p = pos(key);
-                push(diag(config, filePath, "plugin-json/no-unknown-fields", "info", `Unknown field "${key}" (known: ${[...PLUGIN_JSON_FIELDS].join(", ")})`, p?.line, p?.column));
+        // unknown fields — prefer the schema's property set (full + nested-aware)
+        // when available; fall back to the contract-extracted PLUGIN_JSON_FIELDS
+        // for installs that didn't ship the schema bundle.
+        {
+            const ctx = loadPluginSchema();
+            const known = ctx?.knownFields ?? PLUGIN_JSON_FIELDS;
+            for (const key of Object.keys(parsed)) {
+                if (!known.has(key)) {
+                    const p = pos(key);
+                    push(diag(config, filePath, "plugin-json/no-unknown-fields", "info", `Unknown field "${key}" (known: ${[...known].sort().join(", ")})`, p?.line, p?.column));
+                }
             }
         }
         // license

package/dist/plugin-schema.js

@@ -0,0 +1,222 @@
+/**
+ * Lazy loader for the auto-extracted plugin.json JSON Schema. The schema lives
+ * at `contracts/plugin.schema.json` (extracted from Claude Code's cli.js by
+ * `scripts/extract-plugin-schema.ts`).
+ *
+ * Resolution: from dist/plugin-schema.js (compiled), step up two directories to
+ * reach the package root where `contracts/` lives. Falls back to the package
+ * resolver if the file is being run from an alternate layout (e.g. monorepo).
+ */
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Ajv2020 } from "ajv/dist/2020.js";
+// biome-ignore lint/style/useImportType: runtime import; types only.
+import * as addFormatsNs from "ajv-formats";
+// ajv-formats ships as CJS with a default function export. Under Node16
+// ESM resolution we have to reach in for `.default`.
+const addFormats = addFormatsNs.default;
+let cached = null;
+const compiledCache = new Map();
+let ajvShared = null;
+function getAjv() {
+    if (ajvShared)
+        return ajvShared;
+    ajvShared = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajvShared);
+    return ajvShared;
+}
+function loadCompiledSchema(fileName) {
+    if (compiledCache.has(fileName))
+        return compiledCache.get(fileName) ?? null;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "..", "contracts", fileName),
+        resolve(here, "..", "..", "contracts", fileName),
+    ];
+    let raw = null;
+    for (const p of candidates) {
+        try {
+            raw = readFileSync(p, "utf8");
+            break;
+        }
+        catch {
+            // try next
+        }
+    }
+    if (!raw) {
+        compiledCache.set(fileName, null);
+        return null;
+    }
+    const wrapped = JSON.parse(raw);
+    const compiled = {
+        validate: getAjv().compile(wrapped.schema),
+        extractedFromVersion: wrapped.extractedFromClaudeCodeVersion,
+    };
+    compiledCache.set(fileName, compiled);
+    return compiled;
+}
+export function loadLspSchema() {
+    return loadCompiledSchema("lsp.schema.json");
+}
+export function loadMonitorsSchema() {
+    return loadCompiledSchema("monitors.schema.json");
+}
+export function loadPluginSchema() {
+    if (cached)
+        return cached;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "..", "contracts", "plugin.schema.json"),
+        resolve(here, "..", "..", "contracts", "plugin.schema.json"),
+    ];
+    let raw = null;
+    for (const p of candidates) {
+        try {
+            raw = readFileSync(p, "utf8");
+            break;
+        }
+        catch {
+            // try next
+        }
+    }
+    if (!raw)
+        return null;
+    const wrapped = JSON.parse(raw);
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const validate = ajv.compile(wrapped.schema);
+    const knownFields = new Set(Object.keys(wrapped.schema.properties ?? {}));
+    cached = {
+        validate,
+        extractedFromVersion: wrapped.extractedFromClaudeCodeVersion,
+        knownFields,
+    };
+    return cached;
+}
+/**
+ * Reduce Ajv's anyOf/oneOf branch enumeration to the "closest match" branch.
+ *
+ * When a value fails an anyOf with N branches, Ajv emits errors for every
+ * branch — that's faithful but noisy (14 lines for one malformed MCP server).
+ * We use schemaPath to group child errors by branch index and keep only the
+ * branch with the fewest errors (the most-likely-intended shape).
+ *
+ * Nested unions are handled by processing outer unions first: their kept
+ * branch's inner anyOf and inner children survive into the second pass, where
+ * the inner union is itself summarized.
+ */
+export function summarizeErrors(errors) {
+    if (errors.length === 0)
+        return errors;
+    // Sort unions outermost-first (shorter schemaPath = closer to root).
+    const unions = errors
+        .filter((e) => e.keyword === "anyOf" || e.keyword === "oneOf")
+        .sort((a, b) => a.schemaPath.length - b.schemaPath.length);
+    const dropped = new Set();
+    for (const union of unions) {
+        // Children of this union have schemaPath starting with `<unionPath>/<N>/`.
+        // AJV emits schemaPath like "#/properties/mcpServers/anyOf" for the union
+        // summary and "#/properties/mcpServers/anyOf/2/required" for branch 2's
+        // child errors.
+        const prefix = `${union.schemaPath}/`;
+        const children = errors.filter((e) => e !== union && e.schemaPath.startsWith(prefix) && !dropped.has(e));
+        if (children.length === 0)
+            continue;
+        // Group by branch index (the segment right after the prefix).
+        const byBranch = new Map();
+        for (const c of children) {
+            const branchIdx = c.schemaPath.slice(prefix.length).split("/", 1)[0];
+            const arr = byBranch.get(branchIdx) ?? [];
+            arr.push(c);
+            byBranch.set(branchIdx, arr);
+        }
+        // Pick the branch the user got the furthest into. We measure "furthest"
+        // as the depth of each branch's *shallowest* error: a branch that failed
+        // only deep inside means we matched the outer shape (e.g. value is an
+        // object, but a nested transport type is wrong) — strong signal of intent.
+        // Counting errors flatly would mislead since nested anyOfs fan out.
+        let bestBranch = null;
+        let bestDepth = -1;
+        for (const [branch, errs] of byBranch) {
+            let minDepth = Infinity;
+            for (const e of errs) {
+                const depth = e.schemaPath
+                    .slice(prefix.length + branch.length + 1)
+                    .split("/").length;
+                if (depth < minDepth)
+                    minDepth = depth;
+            }
+            if (minDepth > bestDepth) {
+                bestDepth = minDepth;
+                bestBranch = branch;
+            }
+        }
+        // Drop every child of this union that isn't in the best branch.
+        for (const [branch, errs] of byBranch) {
+            if (branch === bestBranch)
+                continue;
+            for (const e of errs)
+                dropped.add(e);
+        }
+        // The anyOf/oneOf parent error itself ("does not match any allowed shape")
+        // is redundant once we've kept a branch-specific child error that points
+        // to the actual problem. Drop it unless its best branch had nothing left.
+        const survivingKept = bestBranch !== null
+            ? (byBranch.get(bestBranch) ?? []).filter((e) => !dropped.has(e))
+            : [];
+        if (survivingKept.length > 0)
+            dropped.add(union);
+    }
+    // Final pass: drop the rejected branches and dedupe identical errors.
+    const seen = new Set();
+    const out = [];
+    for (const e of errors) {
+        if (dropped.has(e))
+            continue;
+        const sig = `${e.instancePath}|${e.keyword}|${JSON.stringify(e.params)}`;
+        if (seen.has(sig))
+            continue;
+        seen.add(sig);
+        out.push(e);
+    }
+    return out;
+}
+/** Format an Ajv error as a human-readable single-line message. */
+export function formatAjvError(error) {
+    const where = error.instancePath || "(root)";
+    const params = error.params;
+    switch (error.keyword) {
+        case "required":
+            return `${where}: missing required field "${params.missingProperty}"`;
+        case "type":
+            return `${where}: must be ${params.type}`;
+        case "enum": {
+            const allowed = params.allowedValues ?? [];
+            return `${where}: must be one of [${allowed
+                .map((v) => JSON.stringify(v))
+                .join(", ")}]`;
+        }
+        case "const":
+            return `${where}: must equal ${JSON.stringify(params.allowedValue)}`;
+        case "additionalProperties":
+            return `${where}: unknown property "${params.additionalProperty}"`;
+        case "anyOf":
+            return `${where}: does not match any allowed shape`;
+        case "oneOf":
+            return `${where}: does not match exactly one allowed shape`;
+        case "pattern":
+            return `${where}: does not match pattern ${params.pattern}`;
+        case "minLength":
+            return `${where}: must be at least ${params.limit} characters`;
+        case "maxLength":
+            return `${where}: must be at most ${params.limit} characters`;
+        case "minItems":
+            return `${where}: must have at least ${params.limit} items`;
+        case "maxItems":
+            return `${where}: must have at most ${params.limit} items`;
+        default:
+            return `${where}: ${error.message ?? error.keyword}`;
+    }
+}
+//# sourceMappingURL=plugin-schema.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claudecode-linter",
-	"version": "2.1.138-patch.1",
+	"version": "2.1.138-patch.2",
 	"description": "Standalone linter for Claude Code plugins and configuration files",
 	"type": "module",
 	"bin": {
@@ -17,11 +17,15 @@
 		"deps:update": "ncu -u",
 		"knip": "knip --exclude types",
 		"check-deps": "tsx scripts/check-deps.ts",
-		"extract-contracts": "tsx scripts/extract-contracts.ts",
+		"extract-contracts": "tsx scripts/extract-contracts.ts && tsx scripts/extract-plugin-schema.ts",
+		"extract-plugin-schema": "tsx scripts/extract-plugin-schema.ts",
 		"generate-contracts": "tsx scripts/generate-contracts.ts"
 	},
 	"files": [
 		"dist/**/*.js",
+		"contracts/plugin.schema.json",
+		"contracts/lsp.schema.json",
+		"contracts/monitors.schema.json",
 		".claudecode-lint.defaults.yaml",
 		"README.md"
 	],
@@ -45,6 +49,8 @@
 		"node": ">=18"
 	},
 	"dependencies": {
+		"ajv": "^8.20.0",
+		"ajv-formats": "^3.0.1",
 		"minimatch": "^10.2.4",
 		"picocolors": "^1.1.1",
 		"prettier": "^3.8.1",