claudecode-linter 2.1.150 → 2.1.153

package/dist/linters/settings-json.js

@@ -1,11 +1,14 @@
-import { basename } from "node:path";
-import { SETTINGS_USER_FIELDS, SETTINGS_PROJECT_FIELDS, TOOLS, PERMISSIONS_FIELDS, PERMISSION_MODES, SANDBOX_FIELDS, SANDBOX_NETWORK_FIELDS, SANDBOX_FILESYSTEM_FIELDS, } from "../contracts.js";
+import { basename, dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { SETTINGS_USER_FIELDS, TOOLS, PERMISSIONS_FIELDS, PERMISSION_MODES, SANDBOX_FIELDS, SANDBOX_NETWORK_FIELDS, SANDBOX_FILESYSTEM_FIELDS, } from "../contracts.js";
 import { formatAjvError, loadSettingsSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 const RULES = [
     { id: "settings-json/valid-json", defaultSeverity: "error" },
     { id: "settings-json/schema-valid", defaultSeverity: "error" },
-    { id: "settings-json/scope-file-name", defaultSeverity: "error" },
+    // settings-json/scope-file-name removed in gitea#4 — .claude/settings.json
+    // is a valid project-shared settings source. See misplaced-file/* for
+    // wrong-path warnings.
     { id: "settings-json/scope-field", defaultSeverity: "warning" },
     { id: "settings-json/no-unknown-fields", defaultSeverity: "warning" },
     { id: "settings-json/permissions-object", defaultSeverity: "error" },
@@ -28,6 +31,7 @@ const RULES = [
     { id: "settings-json/plugins-boolean", defaultSeverity: "warning" },
     { id: "settings-json/plugins-format", defaultSeverity: "warning" },
     { id: "settings-json/skip-prompt-boolean", defaultSeverity: "error" },
+    { id: "settings-json/disable-project-mcpjson-shadow", defaultSeverity: "warning" },
 ];
 // Expected type for each known sandbox sub-key, and for the nested
 // network/filesystem objects. Mirrors Claude Code's Zod schema.
@@ -242,22 +246,47 @@ export const settingsJsonLinter = {
                 }
             }
         }
-        // Scope-aware: settings.json (non-local) should only be at user level
-        if (!isLocal && scope && scope !== "user") {
-            push(diag(config, filePath, "settings-json/scope-file-name", "error", `"settings.json" should only exist at user level (~/.claude/). Use "settings.local.json" for project-level settings`));
-        }
-        // Determine which fields are valid for this scope
-        const knownFields = (scope === "user" || !scope) ? SETTINGS_USER_FIELDS : SETTINGS_PROJECT_FIELDS;
-        // unknown/misplaced top-level fields
+        // gitea#4: `.claude/settings.json` is a first-class project settings source
+        // (`projectSettings`, committed/shared) distinct from `.claude/settings.local.json`
+        // (`localSettings`, gitignored). Claude Code's bundle defines both:
+        //   `case "projectSettings": return Rk.join(".claude","settings.json")`
+        //   `case "localSettings":   return "project, gitignored"`
+        // The rule no longer fires for plain project-level settings.json; the
+        // `misplaced-file/canonical-location` rule covers files at the wrong path.
+        // Determine which fields are valid for this scope. gitea#2: the legacy
+        // SETTINGS_PROJECT_FIELDS whitelist is too narrow — Claude Code accepts
+        // most user-level fields at project scope too. We now treat all known
+        // user fields as valid at project scope, except a small denylist of
+        // genuinely user-only fields (auth helpers, plugin enablement, dangerous
+        // mode), which still warn via `settings-json/scope-field`.
+        const knownFields = SETTINGS_USER_FIELDS;
+        // Fields that genuinely only take effect at user scope. Project-scope
+        // versions are silently ignored by Claude Code. Source: bundle inspection
+        // (auth helpers run from user creds; enabledPlugins / skip-permission
+        // flags can't be enabled by a checked-in repo for security reasons).
+        const USER_ONLY_FIELDS = new Set([
+            "apiKeyHelper",
+            "awsAuthRefresh",
+            "awsCredentialExport",
+            "gcpAuthRefresh",
+            "proxyAuthHelper",
+            "policyHelper",
+            "enabledPlugins",
+            "skipDangerousModePermissionPrompt",
+            "forceLoginMethod",
+            "forceLoginOrgUUID",
+        ]);
+        // unknown / misplaced top-level fields
         for (const key of Object.keys(parsed)) {
             if (!knownFields.has(key)) {
                 const p = findKeyPosition(content, key);
-                if (SETTINGS_USER_FIELDS.has(key) && scope && scope !== "user") {
-                    push(diag(config, filePath, "settings-json/scope-field", "warning", `"${key}" is a user-level field — it has no effect in project-level settings.local.json`, p?.line, p?.column));
-                }
-                else if (!SETTINGS_USER_FIELDS.has(key)) {
-                    push(diag(config, filePath, "settings-json/no-unknown-fields", "warning", `Unknown top-level field "${key}"`, p?.line, p?.column));
-                }
+                push(diag(config, filePath, "settings-json/no-unknown-fields", "warning", `Unknown top-level field "${key}"`, p?.line, p?.column));
+                continue;
+            }
+            // gitea#2: only the genuinely user-only denylist warns at project scope.
+            if (USER_ONLY_FIELDS.has(key) && scope && scope !== "user") {
+                const p = findKeyPosition(content, key);
+                push(diag(config, filePath, "settings-json/scope-field", "warning", `"${key}" only takes effect at user level (~/.claude/settings.json); it is ignored in project settings`, p?.line, p?.column));
             }
         }
         // Validate the sub-keys of a nested object against a known-field set and a
@@ -444,6 +473,50 @@ export const settingsJsonLinter = {
                 }
             }
         }
+        // gitea#8: when this settings.json sits at <plugin-root>/.claude/settings.json
+        // and the plugin also ships a <plugin-root>/.mcp.json, Claude Code loads the
+        // plugin's MCP servers twice when launched from the plugin dir (once as the
+        // plugin, once as project-scope .mcp.json) and dedupes — triggering /doctor
+        // "skipped" warnings. The committed suppression is to list each server name
+        // in this file's `disabledMcpjsonServers`.
+        if (isRuleEnabled(config, "settings-json/disable-project-mcpjson-shadow") &&
+            basename(filePath) === "settings.json" &&
+            basename(dirname(filePath)) === ".claude") {
+            const pluginRoot = dirname(dirname(filePath));
+            const pluginJson = join(pluginRoot, ".claude-plugin", "plugin.json");
+            const mcpJson = join(pluginRoot, ".mcp.json");
+            if (existsSync(pluginJson) && existsSync(mcpJson)) {
+                let mcpServerNames = [];
+                try {
+                    const mcp = JSON.parse(readFileSync(mcpJson, "utf-8"));
+                    if (isPlainObject(mcp.mcpServers)) {
+                        mcpServerNames = Object.keys(mcp.mcpServers);
+                    }
+                }
+                catch { /* ignore — broken .mcp.json is the mcp-json linter's job */ }
+                // settings.local.json with the same disable also satisfies the rule.
+                let disabled = Array.isArray(parsed.disabledMcpjsonServers)
+                    ? parsed.disabledMcpjsonServers
+                    : [];
+                const localPath = join(dirname(filePath), "settings.local.json");
+                if (existsSync(localPath)) {
+                    try {
+                        const local = JSON.parse(readFileSync(localPath, "utf-8"));
+                        if (Array.isArray(local.disabledMcpjsonServers)) {
+                            disabled = disabled.concat(local.disabledMcpjsonServers);
+                        }
+                    }
+                    catch { /* ignore */ }
+                }
+                const disabledSet = new Set(disabled.filter((x) => typeof x === "string"));
+                const dp = findKeyPosition(content, "disabledMcpjsonServers");
+                for (const name of mcpServerNames) {
+                    if (!disabledSet.has(name)) {
+                        push(diag(config, filePath, "settings-json/disable-project-mcpjson-shadow", "warning", `Server "${name}" is declared in .mcp.json but not in .claude/settings.json#disabledMcpjsonServers — when Claude Code is launched from this plugin directory, the MCP server is loaded twice (plugin + project-level), triggering /doctor "skipped" warnings`, dp?.line, dp?.column));
+                    }
+                }
+            }
+        }
         // skipDangerousModePermissionPrompt — user-level only
         if ("skipDangerousModePermissionPrompt" in parsed) {
             if (typeof parsed.skipDangerousModePermissionPrompt !== "boolean") {

package/dist/linters/skill-md.js

@@ -52,7 +52,13 @@ function hasTriggerSignal(desc) {
     // ("Trigger on …", "Trigger when/whenever/if …", "Triggers: …", "TRIGGER
     // when:") — not when "trigger" merely appears as a noun (e.g. the phrase
     // "no trigger phrases").
-    const triggerPhrases = /\btrigger(s)?\b\s*(on|when|whenever|if|upon|for)\b|\btriggers?\s*:|\buse (this skill |it )?(when|whenever|for|to|on|if)\b|\bshould be used (when|whenever|for|to|if)\b|\b(applies|invoke|reach for|call this|run this|use this) (when|whenever|if|to|for)\b|\bwhen (the user|you|asked|working|debugging|diagnosing|investigating|reviewing|writing|building|creating|editing|setting up|deploying|the task|a request|a question|you need|there|something|anything)\b|\bwhen [a-z]+ing\b|\bfor (debugging|diagnosing|tasks|requests|questions|when|any)\b/i;
+    // gitea#5: widened to accept more applicability phrasings observed in the
+    // wild — "Loaded automatically when …", "when a turn touches …",
+    // "applies to …", "for memory operations", "Memory protocol for the X
+    // MCP" (a noun-opener that names the domain). The runtime makes
+    // `description` optional, so this rule is advisory; aim for low false
+    // positive rate rather than complete coverage.
+    const triggerPhrases = /\btrigger(s)?\b\s*(on|when|whenever|if|upon|for)\b|\btriggers?\s*:|\buse (this skill |it )?(when|whenever|for|to|on|if)\b|\bshould be used (when|whenever|for|to|if)\b|\b(applies|invoke|reach for|call this|run this|use this|loaded|loads|reaches for|fires) (when|whenever|if|to|for|automatically|on)\b|\bwhen (the user|you|asked|working|debugging|diagnosing|investigating|reviewing|writing|building|creating|editing|setting up|deploying|the task|a request|a question|a message|a turn|the turn|the session|the conversation|the model|you need|there|something|anything)\b|\bwhen [a-z]+ing\b|\bfor (debugging|diagnosing|tasks|requests|questions|when|any|memory|recall|search|saves?|the )\b|\bprotocol for\b|\barchivist for\b|\bhandler for\b|\bauto(matic|-?)\s+(save|load|invocation)\b/i;
     if (triggerPhrases.test(d))
         return true;
     // First "sentence-ish" chunk — used to detect imperative / gerund openers.

package/dist/plugin-schema.js

@@ -25,36 +25,87 @@ function getAjv() {
     addFormats(ajvShared);
     return ajvShared;
 }
-function loadCompiledSchema(fileName) {
-    if (compiledCache.has(fileName))
-        return compiledCache.get(fileName) ?? null;
+function tryReadFile(relPath) {
     const candidates = [
-        ...assetCandidates(import.meta.url, ["..", "contracts", fileName]),
-        ...assetCandidates(import.meta.url, ["..", "..", "contracts", fileName]),
+        ...assetCandidates(import.meta.url, ["..", ...relPath]),
+        ...assetCandidates(import.meta.url, ["..", "..", ...relPath]),
     ];
-    let raw = null;
     for (const p of candidates) {
         try {
-            raw = readFileSync(p, "utf8");
-            break;
+            return readFileSync(p, "utf8");
         }
         catch {
             // try next
         }
     }
+    return null;
+}
+/**
+ * Compile a schema document, handling both wrapper shapes:
+ *   - extracted (`{ extractedFromClaudeCodeVersion, schema: {...} }`)
+ *   - bare JSON Schema (the schemastore.org files, no envelope)
+ */
+function compileSchemaDoc(raw, sourceLabel) {
+    const parsed = JSON.parse(raw);
+    let schema;
+    let version;
+    if ("extractedFromClaudeCodeVersion" in parsed &&
+        typeof parsed.extractedFromClaudeCodeVersion === "string" &&
+        "schema" in parsed &&
+        typeof parsed.schema === "object" &&
+        parsed.schema !== null) {
+        schema = parsed.schema;
+        version = parsed.extractedFromClaudeCodeVersion;
+    }
+    else {
+        // Bare schemastore document. Strip `$id` (Ajv registers it globally
+        // and trips `$id already exists` on a second compile) and any
+        // `$schema` meta-pointer Ajv2020 can't resolve (draft-07 etc.).
+        const { $id: _id, $schema: _meta, ...rest } = parsed;
+        void _id;
+        void _meta;
+        schema = rest;
+        version = sourceLabel;
+    }
+    const propSrc = schema.properties ?? {};
+    return {
+        validate: getAjv().compile(schema),
+        extractedFromVersion: version,
+        knownFields: new Set(Object.keys(propSrc)),
+    };
+}
+function loadCompiledSchema(fileName) {
+    if (compiledCache.has(fileName))
+        return compiledCache.get(fileName) ?? null;
+    const raw = tryReadFile(["contracts", fileName]);
     if (!raw) {
         compiledCache.set(fileName, null);
         return null;
     }
-    const wrapped = JSON.parse(raw);
-    const compiled = {
-        validate: getAjv().compile(wrapped.schema),
-        extractedFromVersion: wrapped.extractedFromClaudeCodeVersion,
-        knownFields: new Set(Object.keys(wrapped.schema.properties ?? {})),
-    };
+    const compiled = compileSchemaDoc(raw, fileName);
     compiledCache.set(fileName, compiled);
     return compiled;
 }
+/**
+ * Load a schemastore.org-curated schema from `contracts/schemastore/`.
+ * Schemastore is preferred for top-level artifact validation because it's
+ * Anthropic's own published source of truth and stays stable across Claude
+ * Code minifier rotations. The Zod-extracted schemas (`loadCompiledSchema`)
+ * remain authoritative for sub-shapes schemastore doesn't enumerate.
+ */
+function loadSchemastoreSchema(fileName) {
+    const cacheKey = `schemastore/${fileName}`;
+    if (compiledCache.has(cacheKey))
+        return compiledCache.get(cacheKey) ?? null;
+    const raw = tryReadFile(["contracts", "schemastore", fileName]);
+    if (!raw) {
+        compiledCache.set(cacheKey, null);
+        return null;
+    }
+    const compiled = compileSchemaDoc(raw, `schemastore:${fileName}`);
+    compiledCache.set(cacheKey, compiled);
+    return compiled;
+}
 export function loadLspSchema() {
     return loadCompiledSchema("lsp.schema.json");
 }
@@ -62,8 +113,24 @@ export function loadMonitorsSchema() {
     return loadCompiledSchema("monitors.schema.json");
 }
 export function loadSettingsSchema() {
+    // gitea#6: prefer the Zod-extracted schema (runtime truth, e.g.
+    // `disableAutoMode` is `boolean` in 2.1.150) over schemastore (which
+    // still lists it as a string literal — out of date). Schemastore is
+    // only used for artifacts with no Zod source (marketplace, keybindings).
     return loadCompiledSchema("settings.schema.json");
 }
+/**
+ * Marketplace and keybindings schemas come exclusively from schemastore —
+ * there is no Zod source for them in the Claude Code bundle. Returns null
+ * if the user's install was shipped without the schemastore bundle (rare;
+ * the package.json includes them in `files`).
+ */
+export function loadMarketplaceSchema() {
+    return loadSchemastoreSchema("marketplace.schema.json");
+}
+export function loadKeybindingsSchema() {
+    return loadSchemastoreSchema("keybindings.schema.json");
+}
 export function loadMcpJsonSchema() {
     return loadCompiledSchema("mcp.schema.json");
 }
@@ -82,36 +149,17 @@ export function loadCommandFrontmatterSchema() {
 export function loadPluginSchema() {
     if (cached)
         return cached;
-    const candidates = [
-        ...assetCandidates(import.meta.url, ["..", "contracts", "plugin.schema.json"]),
-        ...assetCandidates(import.meta.url, [
-            "..",
-            "..",
-            "contracts",
-            "plugin.schema.json",
-        ]),
-    ];
-    let raw = null;
-    for (const p of candidates) {
-        try {
-            raw = readFileSync(p, "utf8");
-            break;
-        }
-        catch {
-            // try next
-        }
-    }
+    // gitea#6: prefer the Zod-extracted plugin.schema.json (runtime truth);
+    // schemastore copy stays committed at `contracts/schemastore/` for
+    // reference and for the marketplace/keybindings artifacts only.
+    const raw = tryReadFile(["contracts", "plugin.schema.json"]);
     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 ?? {}));
+    const compiled = compileSchemaDoc(raw, "plugin.schema.json");
     cached = {
-        validate,
-        extractedFromVersion: wrapped.extractedFromClaudeCodeVersion,
-        knownFields,
+        validate: compiled.validate,
+        extractedFromVersion: compiled.extractedFromVersion,
+        knownFields: compiled.knownFields,
     };
     return cached;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claudecode-linter",
-	"version": "2.1.150",
+	"version": "2.1.153",
 	"description": "Standalone linter for Claude Code plugins and configuration files",
 	"type": "module",
 	"bin": {
@@ -17,8 +17,9 @@
 		"deps:update": "ncu -u",
 		"knip": "knip --exclude types",
 		"check-deps": "tsx scripts/check-deps.ts",
-		"extract-contracts": "tsx scripts/extract-contracts.ts && tsx scripts/extract-plugin-schema.ts",
+		"extract-contracts": "tsx scripts/extract-contracts.ts && tsx scripts/extract-plugin-schema.ts && tsx scripts/fetch-schemastore.ts",
 		"extract-plugin-schema": "tsx scripts/extract-plugin-schema.ts",
+		"fetch-schemastore": "tsx scripts/fetch-schemastore.ts",
 		"generate-contracts": "tsx scripts/generate-contracts.ts"
 	},
 	"files": [
@@ -32,6 +33,7 @@
 		"contracts/command-frontmatter.schema.json",
 		"contracts/mcp.schema.json",
 		"contracts/hooks.schema.json",
+		"contracts/schemastore/*.json",
 		".claudecode-lint.defaults.yaml",
 		"README.md"
 	],