claudecode-linter 0.1.0

package/dist/linters/agent-md.js

@@ -0,0 +1,92 @@
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+import { parseFrontmatter } from "../utils/frontmatter.js";
+const RULES = [
+    { id: "agent-md/valid-frontmatter", 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/model-required", defaultSeverity: "error" },
+    { id: "agent-md/model-valid", defaultSeverity: "warning" },
+    { id: "agent-md/color-required", defaultSeverity: "error" },
+    { id: "agent-md/color-valid", defaultSeverity: "warning" },
+    { id: "agent-md/system-prompt-present", defaultSeverity: "error" },
+    { id: "agent-md/system-prompt-length", defaultSeverity: "warning" },
+    { id: "agent-md/system-prompt-second-person", defaultSeverity: "info" },
+];
+const VALID_MODELS = new Set(["inherit", "sonnet", "opus", "haiku"]);
+const VALID_COLORS = new Set(["blue", "cyan", "green", "yellow", "magenta", "red"]);
+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 agentMdLinter = {
+    artifactType: "agent-md",
+    lint(filePath, content, config) {
+        const diagnostics = [];
+        const push = (d) => { if (d)
+            diagnostics.push(d); };
+        const fm = parseFrontmatter(content);
+        if (!fm.valid) {
+            push(diag(config, filePath, "agent-md/valid-frontmatter", "error", fm.error ?? "Invalid frontmatter"));
+            return diagnostics;
+        }
+        // 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"));
+        }
+        else {
+            const name = fm.data.name;
+            if (!/^[a-z][a-z0-9-]*[a-z0-9]$/.test(name) || name.length < 3 || name.length > 50) {
+                push(diag(config, filePath, "agent-md/name-format", "error", `"name" must be 3-50 chars, lowercase alphanumeric + hyphens (got "${name}")`));
+            }
+        }
+        // description
+        if (!("description" in fm.data) || typeof fm.data.description !== "string") {
+            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"));
+            }
+        }
+        // model
+        if (!("model" in fm.data) || typeof fm.data.model !== "string") {
+            push(diag(config, filePath, "agent-md/model-required", "error", "\"model\" is required in frontmatter"));
+        }
+        else if (!VALID_MODELS.has(fm.data.model)) {
+            push(diag(config, filePath, "agent-md/model-valid", "warning", `"model" must be one of: ${[...VALID_MODELS].join(", ")} (got "${fm.data.model}")`));
+        }
+        // color
+        if (!("color" in fm.data) || typeof fm.data.color !== "string") {
+            push(diag(config, filePath, "agent-md/color-required", "error", "\"color\" is required in frontmatter"));
+        }
+        else if (!VALID_COLORS.has(fm.data.color)) {
+            push(diag(config, filePath, "agent-md/color-valid", "warning", `"color" must be one of: ${[...VALID_COLORS].join(", ")} (got "${fm.data.color}")`));
+        }
+        // system prompt (body)
+        const body = fm.body.trim();
+        if (!body) {
+            push(diag(config, filePath, "agent-md/system-prompt-present", "error", "Agent must have a system prompt (body after frontmatter)"));
+        }
+        else {
+            if (body.length < 20) {
+                push(diag(config, filePath, "agent-md/system-prompt-length", "warning", `System prompt is very short (${body.length} chars, recommended >= 20)`, fm.bodyStartLine));
+            }
+            if (!/\byou\b/i.test(body)) {
+                push(diag(config, filePath, "agent-md/system-prompt-second-person", "info", "System prompt should use second person (\"You are...\", \"You will...\")", fm.bodyStartLine));
+            }
+        }
+        return diagnostics;
+    },
+};
+export { RULES as AGENT_MD_RULES };
+//# sourceMappingURL=agent-md.js.map

package/dist/linters/agent-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-md.js","sourceRoot":"","sources":["../../src/linters/agent-md.ts"],"names":[],"mappings":"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"}

package/dist/linters/claude-md.d.ts

@@ -0,0 +1,8 @@
+import type { Linter, Severity } from "../types.js";
+interface RuleDef {
+    id: string;
+    defaultSeverity: Severity;
+}
+declare const RULES: RuleDef[];
+export declare const claudeMdLinter: Linter;
+export { RULES as CLAUDE_MD_RULES };

package/dist/linters/claude-md.js

@@ -0,0 +1,109 @@
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+const RULES = [
+    { id: "claude-md/not-empty", defaultSeverity: "warning" },
+    { id: "claude-md/starts-with-heading", defaultSeverity: "info" },
+    { id: "claude-md/has-sections", defaultSeverity: "warning" },
+    { id: "claude-md/user-level-concise", defaultSeverity: "info" },
+    { id: "claude-md/project-has-overview", defaultSeverity: "info" },
+    { id: "claude-md/no-secrets", defaultSeverity: "error" },
+    { id: "claude-md/file-length", defaultSeverity: "warning" },
+    { id: "claude-md/no-absolute-paths", defaultSeverity: "info" },
+    { id: "claude-md/no-todo-markers", defaultSeverity: "info" },
+    { id: "claude-md/no-trailing-whitespace", defaultSeverity: "info" },
+];
+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 claudeMdLinter = {
+    artifactType: "claude-md",
+    lint(filePath, content, config, scope) {
+        const diagnostics = [];
+        const push = (d) => { if (d)
+            diagnostics.push(d); };
+        const lines = content.split("\n");
+        // empty file
+        if (!content.trim()) {
+            push(diag(config, filePath, "claude-md/not-empty", "warning", "CLAUDE.md is empty"));
+            return diagnostics;
+        }
+        // should start with a heading
+        const firstNonEmpty = lines.findIndex((l) => l.trim() !== "");
+        if (firstNonEmpty >= 0 && !lines[firstNonEmpty].startsWith("#")) {
+            push(diag(config, filePath, "claude-md/starts-with-heading", "info", "CLAUDE.md should start with a heading", firstNonEmpty + 1));
+        }
+        // check for H2 sections (structure)
+        const h2Count = lines.filter((l) => /^## /.test(l)).length;
+        if (h2Count === 0) {
+            push(diag(config, filePath, "claude-md/has-sections", "warning", "CLAUDE.md should have H2 (##) sections for organization"));
+        }
+        // Scope-aware: user-level should be concise global rules, project-level should describe the project
+        if (scope === "user" && lines.length > 100) {
+            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));
+            if (!hasProjectOverview && h2Count > 0) {
+                push(diag(config, filePath, "claude-md/project-has-overview", "info", "Project CLAUDE.md should include a project overview section"));
+            }
+        }
+        // detect potential secrets
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            // API keys, tokens, passwords in plain text
+            const secretMatch = /(?:api[_-]?key|token|password|secret)\s*[:=]\s*["']?[A-Za-z0-9_\-/.]{20,}/i.exec(line);
+            if (secretMatch) {
+                push(diag(config, filePath, "claude-md/no-secrets", "error", "Possible secret or token detected — do not store credentials in CLAUDE.md", i + 1, secretMatch.index + 1));
+            }
+        }
+        // large file warning
+        if (lines.length > 500) {
+            push(diag(config, filePath, "claude-md/file-length", "warning", `CLAUDE.md is ${lines.length} lines — consider splitting into focused sections or separate files`));
+        }
+        // check for broken markdown links to local files
+        const linkRe = /\[([^\]]*)\]\(([^)]+)\)/g;
+        for (let i = 0; i < lines.length; i++) {
+            let match;
+            while ((match = linkRe.exec(lines[i])) !== null) {
+                const target = match[2];
+                // skip URLs and anchors
+                if (target.startsWith("http://") || target.startsWith("https://") || target.startsWith("#")) {
+                    continue;
+                }
+                // warn about absolute paths
+                if (target.startsWith("/")) {
+                    push(diag(config, filePath, "claude-md/no-absolute-paths", "info", `Link uses absolute path "${target}" — prefer relative paths`, i + 1, match.index + 1));
+                }
+            }
+        }
+        // check for TODO/FIXME markers left in instructions
+        for (let i = 0; i < lines.length; i++) {
+            const todoMatch = /\b(TODO|FIXME|HACK|XXX)\b/.exec(lines[i]);
+            if (todoMatch) {
+                push(diag(config, filePath, "claude-md/no-todo-markers", "info", `Found ${todoMatch[0]} marker — resolve before finalizing`, i + 1, todoMatch.index + 1));
+            }
+        }
+        // trailing whitespace (formatting)
+        let trailingCount = 0;
+        for (let i = 0; i < lines.length; i++) {
+            if (/[ \t]+$/.test(lines[i])) {
+                trailingCount++;
+            }
+        }
+        if (trailingCount > 0) {
+            push(diag(config, filePath, "claude-md/no-trailing-whitespace", "info", `${trailingCount} line${trailingCount !== 1 ? "s" : ""} with trailing whitespace`));
+        }
+        return diagnostics;
+    },
+};
+export { RULES as CLAUDE_MD_RULES };
+//# sourceMappingURL=claude-md.js.map

package/dist/linters/claude-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-md.js","sourceRoot":"","sources":["../../src/linters/claude-md.ts"],"names":[],"mappings":"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"}

package/dist/linters/command-md.d.ts

@@ -0,0 +1,8 @@
+import type { Linter, Severity } from "../types.js";
+interface RuleDef {
+    id: string;
+    defaultSeverity: Severity;
+}
+declare const RULES: RuleDef[];
+export declare const commandMdLinter: Linter;
+export { RULES as COMMAND_MD_RULES };

package/dist/linters/command-md.js

@@ -0,0 +1,61 @@
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+import { parseFrontmatter } from "../utils/frontmatter.js";
+const RULES = [
+    { id: "command-md/valid-frontmatter", defaultSeverity: "error" },
+    { id: "command-md/description-required", defaultSeverity: "error" },
+    { id: "command-md/allowed-tools-valid", defaultSeverity: "warning" },
+    { id: "command-md/body-present", defaultSeverity: "warning" },
+];
+const KNOWN_TOOLS = new Set([
+    "Read", "Write", "Edit", "Bash", "Glob", "Grep",
+    "WebFetch", "WebSearch", "Agent", "AskUserQuestion",
+    "NotebookEdit", "TodoWrite", "EnterPlanMode", "ExitPlanMode",
+]);
+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 commandMdLinter = {
+    artifactType: "command-md",
+    lint(filePath, content, config) {
+        const diagnostics = [];
+        const push = (d) => { if (d)
+            diagnostics.push(d); };
+        const fm = parseFrontmatter(content);
+        if (!fm.valid) {
+            push(diag(config, filePath, "command-md/valid-frontmatter", "error", fm.error ?? "Invalid frontmatter"));
+            return diagnostics;
+        }
+        // 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"));
+        }
+        // allowed-tools
+        if ("allowed-tools" in fm.data) {
+            const tools = fm.data["allowed-tools"];
+            if (Array.isArray(tools)) {
+                for (const t of tools) {
+                    if (typeof t === "string" && !KNOWN_TOOLS.has(t)) {
+                        push(diag(config, filePath, "command-md/allowed-tools-valid", "warning", `Unknown tool "${t}" in allowed-tools`));
+                    }
+                }
+            }
+        }
+        // body
+        const body = fm.body.trim();
+        if (!body) {
+            push(diag(config, filePath, "command-md/body-present", "warning", "Command should have a body with instructions"));
+        }
+        return diagnostics;
+    },
+};
+export { RULES as COMMAND_MD_RULES };
+//# sourceMappingURL=command-md.js.map

package/dist/linters/command-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-md.js","sourceRoot":"","sources":["../../src/linters/command-md.ts"],"names":[],"mappings":"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"}

package/dist/linters/hooks-json.d.ts

@@ -0,0 +1,8 @@
+import type { Linter, Severity } from "../types.js";
+interface RuleDef {
+    id: string;
+    defaultSeverity: Severity;
+}
+declare const RULES: RuleDef[];
+export declare const hooksJsonLinter: Linter;
+export { RULES as HOOKS_JSON_RULES };

package/dist/linters/hooks-json.js

@@ -0,0 +1,123 @@
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+const RULES = [
+    { id: "hooks-json/valid-json", 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" },
+    { id: "hooks-json/command-has-command", defaultSeverity: "error" },
+    { id: "hooks-json/no-hardcoded-paths", defaultSeverity: "warning" },
+    { id: "hooks-json/prompt-has-prompt", defaultSeverity: "error" },
+    { id: "hooks-json/prompt-event-support", defaultSeverity: "warning" },
+    { id: "hooks-json/timeout-range", defaultSeverity: "warning" },
+];
+const VALID_EVENTS = new Set([
+    "PreToolUse", "PostToolUse", "UserPromptSubmit",
+    "Stop", "SubagentStop", "SessionStart", "SessionEnd",
+    "PreCompact", "Notification",
+]);
+const PROMPT_EVENTS = new Set([
+    "Stop", "SubagentStop", "UserPromptSubmit", "PreToolUse",
+]);
+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 };
+}
+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 hooksJsonLinter = {
+    artifactType: "hooks-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, "hooks-json/valid-json", "error", `Invalid JSON: ${e.message}`));
+            return diagnostics;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            push(diag(config, filePath, "hooks-json/valid-json", "error", "hooks.json must be a JSON object"));
+            return diagnostics;
+        }
+        const root = parsed;
+        // root "hooks" key
+        if (!("hooks" in root) || typeof root.hooks !== "object" || root.hooks === null) {
+            push(diag(config, filePath, "hooks-json/root-hooks-key", "error", "Root must have a \"hooks\" key containing event definitions"));
+            return diagnostics;
+        }
+        const hooks = root.hooks;
+        for (const [eventName, matchers] of Object.entries(hooks)) {
+            const ep = findKeyPosition(content, eventName);
+            // valid event name
+            if (!VALID_EVENTS.has(eventName)) {
+                push(diag(config, filePath, "hooks-json/valid-event-names", "error", `Invalid event name "${eventName}" (valid: ${[...VALID_EVENTS].join(", ")})`, ep?.line, ep?.column));
+                continue;
+            }
+            if (!Array.isArray(matchers))
+                continue;
+            for (const matcher of matchers) {
+                if (typeof matcher !== "object" || matcher === null)
+                    continue;
+                const m = matcher;
+                const hookList = m.hooks;
+                if (!Array.isArray(hookList))
+                    continue;
+                for (const hook of hookList) {
+                    if (typeof hook !== "object" || hook === null)
+                        continue;
+                    const h = hook;
+                    // type required
+                    if (!("type" in h) || (h.type !== "command" && h.type !== "prompt")) {
+                        push(diag(config, filePath, "hooks-json/hook-type-required", "error", `Hook in ${eventName} must have "type" set to "command" or "prompt"`, ep?.line, ep?.column));
+                        continue;
+                    }
+                    if (h.type === "command") {
+                        if (!("command" in h) || typeof h.command !== "string") {
+                            push(diag(config, filePath, "hooks-json/command-has-command", "error", `Command hook in ${eventName} must have a "command" field`, ep?.line, ep?.column));
+                        }
+                        else if (/^\//.test(h.command) && !h.command.includes("${CLAUDE_PLUGIN_ROOT}")) {
+                            push(diag(config, filePath, "hooks-json/no-hardcoded-paths", "warning", `Hook command uses absolute path — use \${CLAUDE_PLUGIN_ROOT} instead`, ep?.line, ep?.column));
+                        }
+                    }
+                    if (h.type === "prompt") {
+                        if (!("prompt" in h) || typeof h.prompt !== "string") {
+                            push(diag(config, filePath, "hooks-json/prompt-has-prompt", "error", `Prompt hook in ${eventName} must have a "prompt" field`, ep?.line, ep?.column));
+                        }
+                        if (!PROMPT_EVENTS.has(eventName)) {
+                            push(diag(config, filePath, "hooks-json/prompt-event-support", "warning", `Prompt hooks work best on ${[...PROMPT_EVENTS].join(", ")} (used on ${eventName})`, ep?.line, ep?.column));
+                        }
+                    }
+                    // timeout
+                    if ("timeout" in h && typeof h.timeout === "number") {
+                        if (h.timeout < 5 || h.timeout > 600) {
+                            push(diag(config, filePath, "hooks-json/timeout-range", "warning", `Hook timeout ${h.timeout}s is outside recommended range (5-600s)`, ep?.line, ep?.column));
+                        }
+                    }
+                }
+            }
+        }
+        return diagnostics;
+    },
+};
+export { RULES as HOOKS_JSON_RULES };
+//# sourceMappingURL=hooks-json.js.map

package/dist/linters/hooks-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-json.js","sourceRoot":"","sources":["../../src/linters/hooks-json.ts"],"names":[],"mappings":"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"}

package/dist/linters/mcp-json.d.ts

@@ -0,0 +1,8 @@
+import type { Linter, Severity } from "../types.js";
+interface RuleDef {
+    id: string;
+    defaultSeverity: Severity;
+}
+declare const RULES: RuleDef[];
+export declare const mcpJsonLinter: Linter;
+export { RULES as MCP_JSON_RULES };

package/dist/linters/mcp-json.js

@@ -0,0 +1,160 @@
+import { basename } from "node:path";
+import { isRuleEnabled, getRuleSeverity } from "../types.js";
+import { isKebabCase } from "../utils/kebab-case.js";
+const RULES = [
+    { id: "mcp-json/scope-file-name", defaultSeverity: "warning" },
+    { id: "mcp-json/valid-json", defaultSeverity: "error" },
+    { id: "mcp-json/servers-required", defaultSeverity: "error" },
+    { id: "mcp-json/servers-object", defaultSeverity: "error" },
+    { id: "mcp-json/server-name-kebab", defaultSeverity: "info" },
+    { id: "mcp-json/server-object", defaultSeverity: "error" },
+    { id: "mcp-json/server-transport", defaultSeverity: "error" },
+    { id: "mcp-json/url-protocol", defaultSeverity: "warning" },
+    { id: "mcp-json/url-valid", defaultSeverity: "error" },
+    { id: "mcp-json/type-matches-transport", defaultSeverity: "warning" },
+    { id: "mcp-json/command-args-split", defaultSeverity: "info" },
+    { id: "mcp-json/args-array", defaultSeverity: "error" },
+    { id: "mcp-json/env-object", defaultSeverity: "error" },
+    { id: "mcp-json/env-string-values", defaultSeverity: "warning" },
+    { id: "mcp-json/no-unknown-server-fields", defaultSeverity: "info" },
+    { id: "mcp-json/no-unknown-root-fields", defaultSeverity: "info" },
+];
+const KNOWN_SERVER_FIELDS = new Set([
+    "type", "url", "command", "args", "env", "cwd",
+]);
+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 };
+}
+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 mcpJsonLinter = {
+    artifactType: "mcp-json",
+    lint(filePath, content, config, scope) {
+        const diagnostics = [];
+        const push = (d) => { if (d)
+            diagnostics.push(d); };
+        const fileName = basename(filePath);
+        // Scope-aware file naming: user level = mcp.json, project level = .mcp.json
+        if (scope === "user" && fileName === ".mcp.json") {
+            push(diag(config, filePath, "mcp-json/scope-file-name", "warning", "At user level (~/.claude/), use \"mcp.json\" instead of \".mcp.json\""));
+        }
+        if (scope === "project" && fileName === "mcp.json") {
+            push(diag(config, filePath, "mcp-json/scope-file-name", "warning", "At project level, use \".mcp.json\" (dot-prefixed) instead of \"mcp.json\""));
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (e) {
+            push(diag(config, filePath, "mcp-json/valid-json", "error", `Invalid JSON: ${e.message}`));
+            return diagnostics;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            push(diag(config, filePath, "mcp-json/valid-json", "error", "mcp.json must be a JSON object"));
+            return diagnostics;
+        }
+        // mcpServers required
+        if (!("mcpServers" in parsed)) {
+            push(diag(config, filePath, "mcp-json/servers-required", "error", "\"mcpServers\" field is required"));
+            return diagnostics;
+        }
+        const servers = parsed.mcpServers;
+        if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
+            push(diag(config, filePath, "mcp-json/servers-object", "error", "\"mcpServers\" must be an object"));
+            return diagnostics;
+        }
+        for (const [name, serverDef] of Object.entries(servers)) {
+            const sp = findKeyPosition(content, name);
+            // server name convention
+            if (!isKebabCase(name)) {
+                push(diag(config, filePath, "mcp-json/server-name-kebab", "info", `Server name "${name}" should be kebab-case`, sp?.line, sp?.column));
+            }
+            if (typeof serverDef !== "object" || serverDef === null || Array.isArray(serverDef)) {
+                push(diag(config, filePath, "mcp-json/server-object", "error", `Server "${name}" must be an object`, sp?.line, sp?.column));
+                continue;
+            }
+            const server = serverDef;
+            // Must have either type+url (http) or command (stdio)
+            const hasUrl = "url" in server && typeof server.url === "string";
+            const hasCommand = "command" in server && typeof server.command === "string";
+            if (!hasUrl && !hasCommand) {
+                push(diag(config, filePath, "mcp-json/server-transport", "error", `Server "${name}" must have either "url" (http) or "command" (stdio)`, sp?.line, sp?.column));
+                continue;
+            }
+            // http server checks
+            if (hasUrl) {
+                const url = server.url;
+                try {
+                    const parsed = new URL(url);
+                    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+                        push(diag(config, filePath, "mcp-json/url-protocol", "warning", `Server "${name}" URL uses "${parsed.protocol}" — expected http: or https:`, sp?.line, sp?.column));
+                    }
+                }
+                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));
+                }
+            }
+            // stdio server checks
+            if (hasCommand && !hasUrl) {
+                const cmd = server.command;
+                if (cmd.includes(" ") && !("args" in server)) {
+                    push(diag(config, filePath, "mcp-json/command-args-split", "info", `Server "${name}" command contains spaces — consider splitting into "command" and "args"`, sp?.line, sp?.column));
+                }
+            }
+            // args must be array
+            if ("args" in server && !Array.isArray(server.args)) {
+                push(diag(config, filePath, "mcp-json/args-array", "error", `Server "${name}" "args" must be an array`, sp?.line, sp?.column));
+            }
+            // env must be object of strings
+            if ("env" in server) {
+                if (typeof server.env !== "object" || server.env === null || Array.isArray(server.env)) {
+                    push(diag(config, filePath, "mcp-json/env-object", "error", `Server "${name}" "env" must be an object`, sp?.line, sp?.column));
+                }
+                else {
+                    for (const [k, v] of Object.entries(server.env)) {
+                        if (typeof v !== "string") {
+                            push(diag(config, filePath, "mcp-json/env-string-values", "warning", `Server "${name}" env.${k} should be a string`, sp?.line, sp?.column));
+                        }
+                    }
+                }
+            }
+            // unknown fields
+            for (const key of Object.keys(server)) {
+                if (!KNOWN_SERVER_FIELDS.has(key)) {
+                    push(diag(config, filePath, "mcp-json/no-unknown-server-fields", "info", `Server "${name}" has unknown field "${key}"`, sp?.line, sp?.column));
+                }
+            }
+        }
+        // unknown root fields
+        for (const key of Object.keys(parsed)) {
+            if (key !== "mcpServers") {
+                const p = findKeyPosition(content, key);
+                push(diag(config, filePath, "mcp-json/no-unknown-root-fields", "info", `Unknown root field "${key}" (expected only "mcpServers")`, p?.line, p?.column));
+            }
+        }
+        return diagnostics;
+    },
+};
+export { RULES as MCP_JSON_RULES };
+//# sourceMappingURL=mcp-json.js.map