claudecode-linter 2.1.138 → 2.1.140

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",
+	"version": "2.1.140",
 	"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,10 +49,12 @@
 		"node": ">=18"
 	},
 	"dependencies": {
-		"commander": "^14.0.3",
+		"ajv": "^8.20.0",
+		"ajv-formats": "^3.0.1",
 		"minimatch": "^10.2.4",
 		"picocolors": "^1.1.1",
 		"prettier": "^3.8.1",
+		"sade": "^1.8.1",
 		"semver": "^7.7.4",
 		"tinyglobby": "^0.2.15",
 		"yaml": "^2.8.3"