claudecode-linter 2.1.144 → 2.1.148-patch.2

package/dist/linters/agent-md.js

@@ -1,8 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { AGENT_FRONTMATTER, AGENT_MODELS, AGENT_COLORS, TOOLS, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
+import { AGENT_MODELS, AGENT_COLORS, TOOLS, PERMISSION_MODES, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
+import { invalidEffortReason } from "../utils/effort.js";
+import { formatAjvError, loadAgentFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
+import { artifactLabel, classifyUnknownFrontmatterKey, } from "../utils/frontmatter-keys.js";
 function findPluginRoot(agentFilePath) {
     let dir = dirname(agentFilePath);
     for (let i = 0; i < 10; i++) {
@@ -56,12 +59,16 @@ function parseToolsField(v) {
 }
 const RULES = [
     { id: "agent-md/valid-frontmatter", defaultSeverity: "error" },
+    { id: "agent-md/schema-valid", defaultSeverity: "error" },
     { id: "agent-md/name-required", defaultSeverity: "error" },
     { id: "agent-md/name-format", defaultSeverity: "error" },
     { id: "agent-md/description-required", defaultSeverity: "error" },
-    { id: "agent-md/description-examples", defaultSeverity: "warning" },
+    { id: "agent-md/description-routing-guidance", defaultSeverity: "warning" },
     { id: "agent-md/model-required", defaultSeverity: "error" },
     { id: "agent-md/model-valid", defaultSeverity: "warning" },
+    { id: "agent-md/permission-mode-valid", defaultSeverity: "warning" },
+    { id: "agent-md/effort-valid", defaultSeverity: "warning" },
+    { id: "agent-md/max-turns-valid", defaultSeverity: "warning" },
     { id: "agent-md/color-required", defaultSeverity: "warning" },
     { id: "agent-md/color-valid", defaultSeverity: "warning" },
     { id: "agent-md/system-prompt-present", defaultSeverity: "error" },
@@ -97,6 +104,26 @@ export const agentMdLinter = {
             push(diag(config, filePath, "agent-md/valid-frontmatter", "error", fm.error ?? "Invalid frontmatter"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's agent frontmatter Zod validator.
+        // The hand-written rules below add Claude-Code-specific advice with
+        // friendlier messages (model-valid / color-valid re-check fields the
+        // schema also covers — that minimal double-reporting is acceptable).
+        // The extracted schema is intentionally permissive about unknown
+        // frontmatter keys (Claude Code still loads the agent), so those are
+        // NOT reported here — agent-md/no-unknown-frontmatter handles them.
+        // Skipped silently if the schema bundle isn't shipped with this install.
+        if (isRuleEnabled(config, "agent-md/schema-valid")) {
+            const compiled = loadAgentFrontmatterSchema();
+            if (compiled) {
+                const ok = compiled.validate(fm.data);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        push(diag(config, filePath, "agent-md/schema-valid", "error", formatAjvError(err)));
+                    }
+                }
+            }
+        }
         // name
         if (!("name" in fm.data) || typeof fm.data.name !== "string") {
             push(diag(config, filePath, "agent-md/name-required", "error", '"name" is required in frontmatter'));
@@ -115,8 +142,16 @@ export const agentMdLinter = {
             push(diag(config, filePath, "agent-md/description-required", "error", '"description" is required in frontmatter'));
         }
         else {
-            if (!/<example>/i.test(fm.data.description)) {
-                push(diag(config, filePath, "agent-md/description-examples", "warning", "Description should include <example> blocks for triggering"));
+            // An agent description must convey *when to route to it*. Three
+            // forms satisfy that: <example> blocks (the upstream few-shot
+            // convention), an explicit routing-triggers block, or prose that
+            // states the triggers. Warn only when the description does none.
+            const desc = fm.data.description;
+            const hasExamples = /<example>/i.test(desc);
+            const hasRoutingTriggers = /ROUTING TRIGGERS/i.test(desc);
+            const hasTriggerProse = /\b(use (it |this )?(for|when|to)\b|use this (agent|skill)|trigger(s|ed)? (on|by|when)|when the user|for any (task|request|work)|invoke (this|when))/i.test(desc);
+            if (!hasExamples && !hasRoutingTriggers && !hasTriggerProse) {
+                push(diag(config, filePath, "agent-md/description-routing-guidance", "warning", "Description should convey when to route to this agent — via <example> blocks, a routing-triggers block (<!-- BEGIN ROUTING TRIGGERS -->…<!-- END ROUTING TRIGGERS -->), or prose stating the triggers"));
             }
         }
         // model
@@ -127,6 +162,30 @@ export const agentMdLinter = {
             !fm.data.model.startsWith("claude-")) {
             push(diag(config, filePath, "agent-md/model-valid", "warning", `"model" must be one of: ${[...AGENT_MODELS].join(", ")} or a versioned claude-* model ID (got "${fm.data.model}")`));
         }
+        // permissionMode — typed as a permissive scalar by the Zod schema;
+        // at runtime only the PERMISSION_MODES values take effect.
+        if ("permissionMode" in fm.data) {
+            const pm = fm.data.permissionMode;
+            if (typeof pm !== "string" || !PERMISSION_MODES.has(pm)) {
+                push(diag(config, filePath, "agent-md/permission-mode-valid", "warning", `"permissionMode" must be one of: ${[...PERMISSION_MODES].join(", ")} (got ${JSON.stringify(pm)})`));
+            }
+        }
+        // effort — Zod types it as a permissive scalar; the field's describe()
+        // string restricts it to a named level or an integer.
+        if ("effort" in fm.data) {
+            const reason = invalidEffortReason(fm.data.effort);
+            if (reason) {
+                push(diag(config, filePath, "agent-md/effort-valid", "warning", reason));
+            }
+        }
+        // maxTurns — Zod accepts a string / float; only a positive integer
+        // is a meaningful turn budget.
+        if ("maxTurns" in fm.data) {
+            const mt = fm.data.maxTurns;
+            if (typeof mt !== "number" || !Number.isInteger(mt) || mt <= 0) {
+                push(diag(config, filePath, "agent-md/max-turns-valid", "warning", `"maxTurns" must be a positive integer (got ${JSON.stringify(mt)})`));
+            }
+        }
         // color
         if (!("color" in fm.data) || typeof fm.data.color !== "string") {
             push(diag(config, filePath, "agent-md/color-required", "warning", '"color" is required in frontmatter'));
@@ -134,11 +193,15 @@ export const agentMdLinter = {
         else if (!AGENT_COLORS.has(fm.data.color)) {
             push(diag(config, filePath, "agent-md/color-valid", "warning", `"color" must be one of: ${[...AGENT_COLORS].join(", ")} (got "${fm.data.color}")`));
         }
-        // unknown frontmatter fields
-        const knownFields = new Set([...AGENT_FRONTMATTER, "name", "color"]);
+        // Frontmatter keys: only flag cross-artifact misplacement. A key valid
+        // for a *different* markdown artifact (e.g. a skill-only key on an
+        // agent) gets an info; a key valid for no artifact stays silent.
+        // "name"/"color" are agent-valid but absent from the contract set.
+        const extraKnown = new Set(["name", "color"]);
         for (const key of Object.keys(fm.data)) {
-            if (!knownFields.has(key)) {
-                push(diag(config, filePath, "agent-md/no-unknown-frontmatter", "info", `Unknown frontmatter field "${key}"`));
+            const cls = classifyUnknownFrontmatterKey(key, "agent", extraKnown);
+            if (cls?.kind === "owned-by-other" && cls.owner) {
+                push(diag(config, filePath, "agent-md/no-unknown-frontmatter", "info", `"${key}" is ${artifactLabel(cls.owner)} frontmatter — Claude Code ignores it on an agent`));
             }
         }
         // system prompt (body)

package/dist/linters/claude-md.js

@@ -50,10 +50,22 @@ export const claudeMdLinter = {
             push(diag(config, filePath, "claude-md/user-level-concise", "info", `User-level CLAUDE.md is ${lines.length} lines — keep global rules concise, put project-specific content in project CLAUDE.md files`));
         }
         if (scope === "project") {
-            // Project CLAUDE.md should have a project description
-            const hasProjectOverview = lines.some((l) => /^#+ .*(overview|project|about|description|what this is|introduction|summary)/i.test(l));
+            // Project CLAUDE.md should describe the project. This is satisfied by
+            // either an explicit overview-style heading OR descriptive prose near
+            // the top — a CLAUDE.md that opens with a title followed by a sentence
+            // of project description does not need a literal "Overview" heading.
+            const hasOverviewHeading = lines.some((l) => /^#+ .*(overview|project|about|description|what this is|introduction|summary)/i.test(l));
+            // Descriptive opening prose: a non-heading, non-list, non-blank line
+            // of reasonable length appearing before the first H2 section.
+            const firstH2 = lines.findIndex((l) => /^## /.test(l));
+            const preambleEnd = firstH2 >= 0 ? firstH2 : lines.length;
+            const hasOpeningProse = lines.slice(0, preambleEnd).some((l) => {
+                const t = l.trim();
+                return t.length >= 25 && !t.startsWith("#") && !/^[-*>|]/.test(t);
+            });
+            const hasProjectOverview = hasOverviewHeading || hasOpeningProse;
             if (!hasProjectOverview && h2Count > 0) {
-                push(diag(config, filePath, "claude-md/project-has-overview", "info", "Project CLAUDE.md should include a project overview section"));
+                push(diag(config, filePath, "claude-md/project-has-overview", "info", "Project CLAUDE.md should include a project overview — an \"Overview\" section or descriptive opening prose"));
             }
         }
         // detect potential secrets

package/dist/linters/command-md.js

@@ -1,9 +1,17 @@
-import { COMMAND_FRONTMATTER, TOOLS } from "../contracts.js";
+import { AGENT_MODELS, TOOLS } from "../contracts.js";
+import { formatAjvError, loadCommandFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
+import { invalidEffortReason } from "../utils/effort.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
+import { artifactLabel, classifyUnknownFrontmatterKey, } from "../utils/frontmatter-keys.js";
 const RULES = [
     { id: "command-md/valid-frontmatter", defaultSeverity: "error" },
+    { id: "command-md/schema-valid", defaultSeverity: "error" },
     { id: "command-md/description-required", defaultSeverity: "error" },
+    { id: "command-md/name-format", defaultSeverity: "warning" },
+    { id: "command-md/model-valid", defaultSeverity: "warning" },
+    { id: "command-md/effort-valid", defaultSeverity: "warning" },
+    { id: "command-md/frontmatter-field-type", defaultSeverity: "warning" },
     { id: "command-md/allowed-tools-valid", defaultSeverity: "warning" },
     { id: "command-md/body-present", defaultSeverity: "warning" },
     { id: "command-md/no-unknown-frontmatter", defaultSeverity: "info" },
@@ -31,10 +39,60 @@ export const commandMdLinter = {
             push(diag(config, filePath, "command-md/valid-frontmatter", "error", fm.error ?? "Invalid frontmatter"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's command frontmatter Zod validator.
+        // The hand-written rules below add Claude-Code-specific advice (known
+        // tool names, body presence). The extracted schema is intentionally
+        // permissive about unknown frontmatter keys (Claude Code still loads the
+        // command), so those are NOT reported here — command-md/no-unknown-
+        // frontmatter handles them. Skipped silently if the schema bundle isn't
+        // shipped with this install.
+        if (isRuleEnabled(config, "command-md/schema-valid")) {
+            const compiled = loadCommandFrontmatterSchema();
+            if (compiled) {
+                const ok = compiled.validate(fm.data);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        push(diag(config, filePath, "command-md/schema-valid", "error", formatAjvError(err)));
+                    }
+                }
+            }
+        }
         // description
         if (!("description" in fm.data) || typeof fm.data.description !== "string") {
             push(diag(config, filePath, "command-md/description-required", "error", "\"description\" is required in frontmatter"));
         }
+        // name — optional display-name override. Zod types it as a permissive
+        // scalar; if present it must be a non-empty string.
+        if ("name" in fm.data) {
+            const name = fm.data.name;
+            if (typeof name !== "string" || name.trim() === "") {
+                push(diag(config, filePath, "command-md/name-format", "warning", `"name" must be a non-empty string (got ${JSON.stringify(name)})`));
+            }
+        }
+        // model — Zod types it as a permissive scalar; accept a named alias or a
+        // versioned claude-* model id. Mirrors agent-md/model-valid.
+        if ("model" in fm.data && typeof fm.data.model === "string") {
+            const model = fm.data.model;
+            if (!AGENT_MODELS.has(model) && !model.startsWith("claude-")) {
+                push(diag(config, filePath, "command-md/model-valid", "warning", `"model" must be one of: ${[...AGENT_MODELS].join(", ")} or a versioned claude-* model ID (got "${model}")`));
+            }
+        }
+        // effort — Zod types it as a permissive scalar; the field's describe()
+        // string restricts it to a named level or an integer.
+        if ("effort" in fm.data) {
+            const reason = invalidEffortReason(fm.data.effort);
+            if (reason) {
+                push(diag(config, filePath, "command-md/effort-valid", "warning", reason));
+            }
+        }
+        // boolean fields — the Zod schema accepts the string "true"; only a real
+        // boolean behaves as expected.
+        for (const field of ["disable-model-invocation", "user-invocable"]) {
+            if (field in fm.data && typeof fm.data[field] !== "boolean") {
+                push(diag(config, filePath, "command-md/frontmatter-field-type", "warning", `"${field}" must be a boolean (got ${JSON.stringify(fm.data[field])})`));
+            }
+        }
         // allowed-tools
         if ("allowed-tools" in fm.data) {
             const tools = fm.data["allowed-tools"];
@@ -46,11 +104,15 @@ export const commandMdLinter = {
                 }
             }
         }
-        // unknown frontmatter fields
-        const knownFields = new Set([...COMMAND_FRONTMATTER, "allowed-tools", "argument-hint"]);
+        // Frontmatter keys: only flag cross-artifact misplacement. A key valid
+        // for a *different* markdown artifact gets an info; a key valid for no
+        // artifact stays silent. The hyphenated "allowed-tools"/"argument-hint"
+        // are command-valid aliases of the camelCase contract keys.
+        const extraKnown = new Set(["allowed-tools", "argument-hint"]);
         for (const key of Object.keys(fm.data)) {
-            if (!knownFields.has(key)) {
-                push(diag(config, filePath, "command-md/no-unknown-frontmatter", "info", `Unknown frontmatter field "${key}"`));
+            const cls = classifyUnknownFrontmatterKey(key, "command", extraKnown);
+            if (cls?.kind === "owned-by-other" && cls.owner) {
+                push(diag(config, filePath, "command-md/no-unknown-frontmatter", "info", `"${key}" is ${artifactLabel(cls.owner)} frontmatter — Claude Code ignores it on a command`));
             }
         }
         // body

package/dist/linters/hooks-json.js

@@ -1,7 +1,9 @@
 import { HOOK_EVENTS, HOOK_TYPES, PROMPT_EVENTS } from "../contracts.js";
+import { formatAjvError, loadHooksJsonSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 const RULES = [
     { id: "hooks-json/valid-json", defaultSeverity: "error" },
+    { id: "hooks-json/schema-valid", defaultSeverity: "error" },
     { id: "hooks-json/root-hooks-key", defaultSeverity: "error" },
     { id: "hooks-json/valid-event-names", defaultSeverity: "error" },
     { id: "hooks-json/hook-type-required", defaultSeverity: "error" },
@@ -52,6 +54,28 @@ export const hooksJsonLinter = {
             push(diag(config, filePath, "hooks-json/valid-json", "error", "hooks.json must be a JSON object"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's hooks-config Zod validator (the
+        // hook-event → matcher-array map, each matcher holding a discriminated
+        // union of hook definitions). The hand-written rules below add
+        // Claude-Code-specific advice the schema can't express (hardcoded-path
+        // warnings, prompt-event-support hints, …). The extracted schema is
+        // intentionally permissive about unknown hook fields (Claude Code's hook
+        // objects are not .strict()). Skipped silently if the schema bundle isn't
+        // shipped with this install.
+        if (isRuleEnabled(config, "hooks-json/schema-valid")) {
+            const compiled = loadHooksJsonSchema();
+            if (compiled) {
+                const ok = compiled.validate(parsed);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        const firstSeg = err.instancePath.split("/").filter(Boolean)[0];
+                        const p = firstSeg ? findKeyPosition(content, firstSeg) : undefined;
+                        push(diag(config, filePath, "hooks-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
         const root = parsed;
         // root "hooks" key
         if (!("hooks" in root) || typeof root.hooks !== "object" || root.hooks === null) {

package/dist/linters/mcp-json.js

@@ -1,10 +1,16 @@
 import { basename } from "node:path";
 import { MCP_SERVER_FIELDS } from "../contracts.js";
+import { formatAjvError, loadMcpJsonSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { isKebabCase } from "../utils/kebab-case.js";
+// Valid `type` values for a URL-based HTTP MCP server. Claude Code v2.1.146
+// accepts both — its HTTP transport schema is
+// `enum(["http","streamable-http"]).transform(()=>"http")`.
+const HTTP_TRANSPORT_TYPES = new Set(["http", "streamable-http"]);
 const RULES = [
     { id: "mcp-json/scope-file-name", defaultSeverity: "warning" },
     { id: "mcp-json/valid-json", defaultSeverity: "error" },
+    { id: "mcp-json/schema-valid", defaultSeverity: "error" },
     { id: "mcp-json/servers-required", defaultSeverity: "error" },
     { id: "mcp-json/servers-object", defaultSeverity: "error" },
     { id: "mcp-json/server-name-kebab", defaultSeverity: "info" },
@@ -69,6 +75,28 @@ export const mcpJsonLinter = {
             push(diag(config, filePath, "mcp-json/valid-json", "error", "mcp.json must be a JSON object"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's .mcp.json Zod validator (the
+        // `mcpServers` record of discriminated transport configs). The hand-written
+        // rules below add Claude-Code-specific advice the schema can't express
+        // (kebab-case names, ${CLAUDE_PLUGIN_ROOT} hints, …). The extracted schema
+        // is intentionally permissive about unknown server fields (Claude Code's
+        // server union is not .strict()), so those are NOT reported here —
+        // mcp-json/no-unknown-server-fields handles them. Skipped silently if the
+        // schema bundle isn't shipped with this install.
+        if (isRuleEnabled(config, "mcp-json/schema-valid")) {
+            const compiled = loadMcpJsonSchema();
+            if (compiled) {
+                const ok = compiled.validate(parsed);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        const firstSeg = err.instancePath.split("/").filter(Boolean)[0];
+                        const p = firstSeg ? findKeyPosition(content, firstSeg) : undefined;
+                        push(diag(config, filePath, "mcp-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
         // mcpServers required
         if (!("mcpServers" in parsed)) {
             push(diag(config, filePath, "mcp-json/servers-required", "error", "\"mcpServers\" field is required"));
@@ -109,8 +137,11 @@ export const mcpJsonLinter = {
                 catch {
                     push(diag(config, filePath, "mcp-json/url-valid", "error", `Server "${name}" has invalid URL: "${url}"`, sp?.line, sp?.column));
                 }
-                if ("type" in server && server.type !== "http") {
-                    push(diag(config, filePath, "mcp-json/type-matches-transport", "warning", `Server "${name}" has URL but type is "${server.type}" (expected "http")`, sp?.line, sp?.column));
+                // A URL-based HTTP server may declare "http" or "streamable-http".
+                // Claude Code v2.1.146 treats them identically — its HTTP transport
+                // schema is `enum(["http","streamable-http"]).transform(()=>"http")`.
+                if ("type" in server && !HTTP_TRANSPORT_TYPES.has(server.type)) {
+                    push(diag(config, filePath, "mcp-json/type-matches-transport", "warning", `Server "${name}" has URL but type is "${server.type}" (expected one of ${[...HTTP_TRANSPORT_TYPES].join(", ")})`, sp?.line, sp?.column));
                 }
             }
             // stdio server checks