claudecode-linter 2.1.138 → 2.1.139

package/.claudecode-lint.defaults.yaml

@@ -9,6 +9,7 @@
 rules:
   # ── plugin.json ──────────────────────────────────────────
   plugin-json/valid-json: error
+  plugin-json/schema-valid: error
   plugin-json/name-required: error
   plugin-json/name-kebab-case: error
   plugin-json/name-length: error
@@ -110,3 +111,27 @@ rules:
   claude-md/no-absolute-paths: info
   claude-md/no-todo-markers: info
   claude-md/no-trailing-whitespace: info
+
+  # ── .lsp.json ────────────────────────────────────────────
+  # Standalone LSP config files at plugin root. Most common bug:
+  # wrapping content under a top-level "lspServers" key, which only
+  # belongs inline in plugin.json. Claude Code parses with
+  # E.record(E.string(), <per-server>).safeParse — wrapped files
+  # validate as a single (invalid) server entry at session start.
+  lsp-json/valid-json: error
+  lsp-json/no-lsp-servers-wrapper: error
+  lsp-json/schema-valid: error
+
+  # ── monitors/monitors.json ───────────────────────────────
+  # Array of monitor entries. Names must be unique within a plugin
+  # (Claude Code refines this; not expressible in JSON Schema).
+  monitors-json/valid-json: error
+  monitors-json/schema-valid: error
+  monitors-json/unique-names: error
+
+  # ── Misplaced files ──────────────────────────────────────
+  # Reserved artifact basenames (plugin.json, hooks.json,
+  # marketplace.json, SKILL.md) found at non-canonical paths inside
+  # a plugin tree. Claude Code silently ignores them — easy to make,
+  # hard to debug.
+  misplaced-file/canonical-location: warning

package/README.md

@@ -7,7 +7,7 @@
 
 Standalone linter for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugins and configuration files.
 
-Validates `plugin.json`, `SKILL.md`, agent/command markdown, `hooks.json`, `mcp.json`, `settings.json`, and `CLAUDE.md` files with 90 rules across 8 artifact types.
+Validates `plugin.json`, `SKILL.md`, agent/command markdown, `hooks.json`, `mcp.json`, `settings.json`, `CLAUDE.md`, `.lsp.json`, and `monitors/monitors.json` files. plugin.json/lsp.json/monitors.json are checked against JSON Schemas auto-extracted from Claude Code's runtime Zod validators — failures the linter reports are the same failures Claude Code would raise at session start.
 
 ![demo](assets/demo.gif)
 
@@ -111,7 +111,7 @@ No issues found.
 
 | Type | Files | Rules |
 |------|-------|-------|
-| plugin-json | `.claude-plugin/plugin.json` | 12 |
+| plugin-json | `.claude-plugin/plugin.json` | 13 |
 | skill-md | `skills/*/SKILL.md` | 11 |
 | agent-md | `agents/*.md` | 13 |
 | command-md | `commands/*.md` | 5 |
@@ -119,6 +119,24 @@ No issues found.
 | settings-json | `.claude-plugin/settings.json` | 14 |
 | mcp-json | `.claude-plugin/mcp.json` | 16 |
 | claude-md | `CLAUDE.md` | 10 |
+| lsp-json | `.lsp.json` | 3 |
+| monitors-json | `monitors/monitors.json` | 3 |
+
+## Schema-derived rules
+
+`plugin-json/schema-valid`, `lsp-json/schema-valid`, and `monitors-json/schema-valid` validate against JSON Schemas that are *auto-extracted from Claude Code's cli.js bundle* — same Zod schemas that the runtime calls `.safeParse(content)` on. This catches:
+
+- **Missing required fields** (e.g., LSP server without `extensionToLanguage`)
+- **Wrong field types** (e.g., `name: 42` instead of a string)
+- **Invalid enum values** (e.g., `transport: "websocket"` when only `stdio`/`socket` are accepted)
+- **Nested-shape violations** in discriminated unions (e.g., `mcpServers.x.type: "telegraph"` when only `stdio`/`sse`/`http`/... are accepted)
+- **Unknown fields** in strict objects (e.g., `filetypes`/`rootPatterns` inside an LSP server config — common confusion with editor-LSP shapes from other ecosystems)
+
+The schemas live at `contracts/{plugin,lsp,monitors}.schema.json` and are regenerated by `npm run extract-contracts` on every Claude Code release.
+
+`lsp-json/no-lsp-servers-wrapper` catches a specific authoring mistake: putting your `.lsp.json` content under a top-level `lspServers` key. That wrapper belongs **inline in plugin.json** only — the dedicated file is a flat map of server-name → config.
+
+`monitors-json/unique-names` enforces Claude Code's "monitor names must be unique within a plugin" check (a `refine()` predicate that JSON Schema can't express natively).
 
 ## Configuration
 

package/contracts/lsp.schema.json

@@ -0,0 +1,82 @@
+{
+	"extractedFromClaudeCodeVersion": "2.1.138",
+	"extractedAt": "2026-05-11T08:02:42.911Z",
+	"schema": {
+		"$schema": "https://json-schema.org/draft/2020-12/schema",
+		"title": "Claude Code .lsp.json",
+		"type": "object",
+		"additionalProperties": {
+			"type": "object",
+			"properties": {
+				"command": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Command to execute the LSP server (e.g., \"typescript-language-server\")"
+				},
+				"args": {
+					"type": "array",
+					"items": {
+						"type": "string",
+						"minLength": 1
+					},
+					"description": "Command-line arguments to pass to the server"
+				},
+				"extensionToLanguage": {
+					"type": "object",
+					"additionalProperties": {
+						"type": "string",
+						"minLength": 1
+					},
+					"description": "Mapping from file extension to LSP language ID. File extensions and languages are derived from this mapping."
+				},
+				"transport": {
+					"enum": [
+						"stdio",
+						"socket"
+					],
+					"default": "stdio",
+					"description": "Communication transport mechanism"
+				},
+				"env": {
+					"type": "object",
+					"additionalProperties": {
+						"type": "string"
+					},
+					"description": "Environment variables to set when starting the server"
+				},
+				"initializationOptions": {
+					"description": "Initialization options passed to the server during initialization"
+				},
+				"settings": {
+					"description": "Settings passed to the server via workspace/didChangeConfiguration"
+				},
+				"workspaceFolder": {
+					"type": "string",
+					"description": "Workspace folder path to use for the server"
+				},
+				"startupTimeout": {
+					"type": "number",
+					"description": "Maximum time to wait for server startup (milliseconds)"
+				},
+				"shutdownTimeout": {
+					"type": "number",
+					"description": "Maximum time to wait for graceful shutdown (milliseconds)"
+				},
+				"restartOnCrash": {
+					"type": "boolean",
+					"description": "Whether to restart the server if it crashes"
+				},
+				"maxRestarts": {
+					"type": "number",
+					"description": "Maximum number of restart attempts before giving up"
+				}
+			},
+			"required": [
+				"command",
+				"extensionToLanguage"
+			],
+			"additionalProperties": false
+		},
+		"description": "Flat map of server-name → LSP server config. The top-level keys are server names; their values match the per-server schema. This file is loaded by Claude Code when present at the plugin root."
+	}
+}

package/contracts/monitors.schema.json

@@ -0,0 +1,48 @@
+{
+	"extractedFromClaudeCodeVersion": "2.1.138",
+	"extractedAt": "2026-05-11T08:02:42.913Z",
+	"schema": {
+		"$schema": "https://json-schema.org/draft/2020-12/schema",
+		"title": "Claude Code monitors.json",
+		"type": "array",
+		"items": {
+			"type": "object",
+			"properties": {
+				"name": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Identifier for this monitor, unique within the plugin. Used to dedupe so re-arming (plugin reload, repeat skill invoke) does not spawn duplicates."
+				},
+				"command": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Shell command to run as a persistent background monitor. Each stdout line is delivered to the model as a <task_notification> event; the process runs for the session lifetime. ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${user_config.*}, and ${ENV_VAR} are substituted. Runs in the session cwd \\u2014 prefix with `cd \"${CLAUDE_PLUGIN_ROOT}\" && ` if the script needs its own directory."
+				},
+				"description": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Short human-readable description of what is being monitored (shown in task panel and notification summary)."
+				},
+				"when": {
+					"anyOf": [
+						{
+							"const": "always"
+						},
+						{
+							"type": "string"
+						}
+					],
+					"default": "always",
+					"description": "Arm trigger. \"always\" arms at session start and on plugin reload. \"on-skill-invoke:<skill>\" arms the first time that skill is dispatched (via Skill tool or slash command)."
+				}
+			},
+			"required": [
+				"name",
+				"command",
+				"description"
+			],
+			"additionalProperties": false
+		},
+		"description": "Array of monitor entries. Each monitor's `name` must be unique within the plugin (Claude Code enforces this with a refine() check that is not expressible in JSON Schema; the monitors-json linter does it separately)."
+	}
+}