@x6txy/ctxscope 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.2.0 - 2026-06-21
+
+### Added
+
+- Added `ctxscope init` to create `ctxscope.config.json`.
+- Added configurable `maxTokens`, `maxFileTokens`, `ignore`, and rule severities.
+- Added diagnostics model with `off`, `warn`, and `error` severities.
+- Added `ctxscope doctor` for lint-style context checks.
+- Added `ctxscope doctor --ci` with exit code `1` on error diagnostics.
+- Added `ctxscope doctor --json` with stable automation output.
+- Added `CTX101` for conflicting package manager instructions.
+- Added `CTX102` for package scripts referenced in context but missing from `package.json`.
+- Added `CTX105` for total context budget violations.
+
+### Changed
+
+- `CTX001` now respects `maxFileTokens` from config.
+- Human output now uses diagnostic wording for mixed warnings and errors.
+
 ## 0.1.0 - 2026-06-21
 
 Published as `@x6txy/ctxscope` on npm. The installed binary is still `ctxscope`.

package/README.md

@@ -2,7 +2,7 @@
 
 Inspect and lint coding-agent context files.
 
-`ctxscope` helps you see the instructions your coding agents may read before they start working: `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, OpenCode skills, Cursor rules, and GitHub Copilot instructions.
+`ctxscope` helps you see and lint the instructions your coding agents may read before they start working: `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, OpenCode skills, Cursor rules, and GitHub Copilot instructions.
 
 It answers the first questions every agent-heavy repo eventually has:
 
@@ -10,6 +10,7 @@ It answers the first questions every agent-heavy repo eventually has:
 - How much context do they add?
 - Which agent is each file probably for?
 - Which files are suspiciously large, empty, duplicated, or stale?
+- Which context problems should fail CI?
 
 ## Install
 
@@ -31,9 +32,13 @@ ctxscope scan
 ```bash
 ctxscope --help
 ctxscope --version
+ctxscope init
 ctxscope scan [path]
 ctxscope scan --agent <all|codex|opencode|claude|generic>
 ctxscope scan --json
+ctxscope doctor [path]
+ctxscope doctor --ci
+ctxscope doctor --json
 ```
 
 Examples:
@@ -43,6 +48,8 @@ ctxscope scan
 ctxscope scan apps/web
 ctxscope scan --agent codex
 ctxscope scan --agent opencode --json
+ctxscope init
+ctxscope doctor --ci
 ```
 
 ## Output
@@ -86,7 +93,7 @@ Ignored directories:
 
 ## Warning Codes
 
-`ctxscope scan` reports objective hygiene warnings only.
+`ctxscope scan` reports objective hygiene diagnostics. `ctxscope doctor` adds CI-ready error rules.
 
 | Code | Meaning |
 | --- | --- |
@@ -96,6 +103,85 @@ Ignored directories:
 | `CTX004` | Empty context file |
 | `CTX005` | TODO, FIXME, or obsolete marker |
 | `CTX006` | Repeated paragraph |
+| `CTX101` | Conflicting package manager instructions |
+| `CTX102` | Missing package script referenced by context |
+| `CTX105` | Total context budget exceeded |
+
+## Doctor
+
+Use `doctor` when you want lint-style checks and CI exit codes:
+
+```bash
+ctxscope doctor
+ctxscope doctor --ci
+ctxscope doctor --json
+```
+
+`--ci` exits with code `1` when any diagnostic has severity `error`.
+
+Example output:
+
+```text
+ctxscope doctor
+
+Agent   all
+Target  /repo
+Status  fail
+
+Summary
+  4 files, ~9,200 tokens, 2 errors, 1 warnings
+
+Errors (2)
+ERROR CTX101  AGENTS.md
+  conflicting package managers: npm, pnpm
+
+ERROR CTX102  AGENTS.md
+  references missing package script: test:e2e
+```
+
+## Config
+
+Create a default config:
+
+```bash
+ctxscope init
+```
+
+This writes `ctxscope.config.json`:
+
+```json
+{
+  "maxTokens": 8000,
+  "maxFileTokens": 2500,
+  "ignore": ["node_modules", "dist", ".git"],
+  "rules": {
+    "CTX001": "warn",
+    "CTX002": "warn",
+    "CTX003": "warn",
+    "CTX004": "warn",
+    "CTX005": "warn",
+    "CTX006": "warn",
+    "CTX101": "error",
+    "CTX102": "error",
+    "CTX105": "error"
+  }
+}
+```
+
+Rule severities can be:
+
+- `off`
+- `warn`
+- `error`
+
+## CI
+
+GitHub Actions example:
+
+```yaml
+- name: Check agent context
+  run: npx @x6txy/ctxscope doctor --ci
+```
 
 ## JSON Output
 
@@ -103,6 +189,7 @@ Use `--json` for automation:
 
 ```bash
 ctxscope scan --json
+ctxscope doctor --json
 ```
 
 Shape:
@@ -120,8 +207,8 @@ Shape:
 ## Limitations
 
 - Token counts are estimates: `ceil(character_count / 4)`.
-- v0.1 is discovery-based, not real session tracing.
-- Semantic conflicts are not detected yet. For example, `npm` vs `pnpm` policy conflicts are planned for a future `doctor` command.
+- v0.2 is discovery-based, not real session tracing.
+- Semantic checks are intentionally conservative. They inspect explicit commands and context text, not model behavior.
 - `diff` and `trace` are future commands.
 
 ## License

package/dist/cli.js

@@ -1,92 +1,109 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 
-// src/output.ts
-var colorEnabled = process.env.NO_COLOR === void 0 && (process.stdout.isTTY || process.env.FORCE_COLOR !== void 0);
-var colors = {
-  bold: (value) => color("\x1B[1m", value),
-  cyan: (value) => color("\x1B[36m", value),
-  dim: (value) => color("\x1B[2m", value),
-  green: (value) => color("\x1B[32m", value),
-  yellow: (value) => color("\x1B[33m", value)
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+var CONFIG_FILE_NAME = "ctxscope.config.json";
+var DEFAULT_CONFIG = {
+  maxTokens: 8e3,
+  maxFileTokens: 2500,
+  ignore: ["node_modules", "dist", ".git"],
+  rules: {
+    CTX001: "warn",
+    CTX002: "warn",
+    CTX003: "warn",
+    CTX004: "warn",
+    CTX005: "warn",
+    CTX006: "warn",
+    CTX101: "error",
+    CTX102: "error",
+    CTX105: "error"
+  }
 };
-function formatHumanScanResult(result) {
-  const sections = [
-    colors.bold(colors.cyan("ctxscope scan")),
-    formatMeta(result),
-    formatFiles(result),
-    formatSummary(result),
-    formatWarnings(result)
-  ];
-  return sections.filter(Boolean).join("\n\n");
-}
-function formatJsonScanResult(result) {
-  return JSON.stringify({
-    agent: result.agent,
-    target: result.target,
-    files: result.files,
-    totalTokens: result.totalTokens,
-    warnings: result.warnings
-  }, null, 2);
-}
-function formatWarning(warning) {
-  return `${colors.yellow(warning.severity.toUpperCase())} ${colors.yellow(warning.code)}  ${warning.path}
-  ${colors.dim(warning.message)}`;
-}
-function formatMeta(result) {
-  return [
-    `${colors.dim("Agent")}   ${result.agent}`,
-    `${colors.dim("Target")}  ${result.target}`
-  ].join("\n");
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+function loadConfig(cwd = process.cwd()) {
+  const configPath = resolve(cwd, CONFIG_FILE_NAME);
+  if (!existsSync(configPath)) {
+    return structuredClone(DEFAULT_CONFIG);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "unknown parse error";
+    throw new ConfigError(`${CONFIG_FILE_NAME} is not valid JSON: ${message}`);
+  }
+  return normalizeConfig(parsed);
 }
-function formatFiles(result) {
-  if (result.files.length === 0) {
-    return `${colors.bold("Files")} ${colors.dim("(0)")}
-  No context files found.`;
+function normalizeConfig(value) {
+  if (!isObject(value)) {
+    throw new ConfigError(`${CONFIG_FILE_NAME} must contain a JSON object`);
   }
-  const pathWidth = Math.max("Path".length, ...result.files.map((file) => file.path.length));
-  const tokenWidth = Math.max("Tokens".length, ...result.files.map((file) => formatTokenCell(file.tokens, file.skippedBinary).length));
-  const header = [
-    colors.dim("Path".padEnd(pathWidth)),
-    colors.dim("Tokens".padStart(tokenWidth)),
-    colors.dim("Agents")
-  ].join("  ");
-  const rows = result.files.map((file) => [
-    file.path.padEnd(pathWidth),
-    formatTokenCell(file.tokens, file.skippedBinary).padStart(tokenWidth),
-    file.agents.join(", ")
-  ].join("  "));
-  return `${colors.bold("Files")} ${colors.dim(`(${result.files.length})`)}
-${header}
-${rows.join("\n")}`;
+  return {
+    maxTokens: readPositiveNumber(value, "maxTokens", DEFAULT_CONFIG.maxTokens),
+    maxFileTokens: readPositiveNumber(value, "maxFileTokens", DEFAULT_CONFIG.maxFileTokens),
+    ignore: readStringArray(value, "ignore", DEFAULT_CONFIG.ignore),
+    rules: {
+      ...DEFAULT_CONFIG.rules,
+      ...readRules(value)
+    }
+  };
 }
-function formatSummary(result) {
-  const warningLabel = result.warnings.length === 0 ? colors.green("0 warnings") : colors.yellow(`${result.warnings.length} warnings`);
-  return `${colors.bold("Summary")}
-  ${formatNumber(result.files.length)} files, ~${formatNumber(result.totalTokens)} tokens, ${warningLabel}`;
+function readPositiveNumber(value, key, fallback) {
+  const field = value[key];
+  if (field === void 0) {
+    return fallback;
+  }
+  if (typeof field !== "number" || !Number.isFinite(field) || field <= 0) {
+    throw new ConfigError(`${CONFIG_FILE_NAME}.${key} must be a positive number`);
+  }
+  return field;
 }
-function formatWarnings(result) {
-  if (result.warnings.length === 0) {
-    return "";
+function readStringArray(value, key, fallback) {
+  const field = value[key];
+  if (field === void 0) {
+    return [...fallback];
   }
-  return `${colors.bold("Warnings")} ${colors.dim(`(${result.warnings.length})`)}
-${result.warnings.map(formatWarning).join("\n")}`;
+  if (!Array.isArray(field) || field.some((item) => typeof item !== "string" || item.length === 0)) {
+    throw new ConfigError(`${CONFIG_FILE_NAME}.${key} must be an array of non-empty strings`);
+  }
+  return [...field];
 }
-function formatTokenCell(tokens, skippedBinary) {
-  return skippedBinary ? "binary" : `~${formatNumber(tokens)}`;
+function readRules(value) {
+  const field = value.rules;
+  if (field === void 0) {
+    return {};
+  }
+  if (!isObject(field)) {
+    throw new ConfigError(`${CONFIG_FILE_NAME}.rules must be an object`);
+  }
+  const rules = {};
+  for (const [code, severity] of Object.entries(field)) {
+    if (!isRuleSeverity(severity)) {
+      throw new ConfigError(`${CONFIG_FILE_NAME}.rules.${code} must be one of: off, warn, error`);
+    }
+    rules[code] = severity;
+  }
+  return rules;
 }
-function formatNumber(value) {
-  return String(value).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function color(code, value) {
-  return colorEnabled ? `${code}${value}\x1B[0m` : value;
+function isRuleSeverity(value) {
+  return value === "off" || value === "warn" || value === "error";
 }
 
 // src/scan.ts
 import { statSync as statSync2 } from "fs";
-import { dirname as dirname2, relative as relative2, resolve as resolve3 } from "path";
+import { dirname as dirname2, relative as relative2, resolve as resolve4 } from "path";
 
 // src/agents.ts
 var AGENT_ORDER = ["codex", "opencode", "claude", "generic"];
@@ -138,10 +155,10 @@ function basename(path) {
 
 // src/files.ts
 import { readdirSync, statSync } from "fs";
-import { relative, resolve } from "path";
+import { relative, resolve as resolve2 } from "path";
 var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([".git", "dist", "node_modules"]);
 function listFiles(targetPath) {
-  const absoluteTarget = resolve(targetPath);
+  const absoluteTarget = resolve2(targetPath);
   const stat = statSync(absoluteTarget);
   if (stat.isFile()) {
     return [absoluteTarget];
@@ -156,7 +173,7 @@ function listFiles(targetPath) {
 function walk(directory, files) {
   const entries = readdirSync(directory, { withFileTypes: true });
   for (const entry of entries) {
-    const absolutePath = resolve(directory, entry.name);
+    const absolutePath = resolve2(directory, entry.name);
     if (entry.isDirectory()) {
       if (!IGNORED_DIRECTORIES.has(entry.name)) {
         walk(absolutePath, files);
@@ -170,9 +187,9 @@ function walk(directory, files) {
 }
 
 // src/token.ts
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync2 } from "fs";
 function estimateFileTokens(path) {
-  const buffer = readFileSync(path);
+  const buffer = readFileSync2(path);
   if (looksBinary(buffer)) {
     return { tokens: 0, skipped: true };
   }
@@ -205,65 +222,83 @@ function looksBinary(buffer) {
 }
 
 // src/warnings.ts
-import { existsSync, readFileSync as readFileSync2 } from "fs";
-import { dirname, resolve as resolve2 } from "path";
-var OVERSIZED_TOKEN_LIMIT = 2500;
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import { dirname, resolve as resolve3 } from "path";
+
+// src/diagnostics.ts
+function createDiagnostic(input, config) {
+  const severity = config.rules[input.code] ?? input.defaultSeverity;
+  if (severity === "off") {
+    return null;
+  }
+  return {
+    code: input.code,
+    severity,
+    path: input.path,
+    message: input.message
+  };
+}
+function sortDiagnostics(diagnostics) {
+  return diagnostics.sort((a, b) => {
+    const pathComparison = a.path.localeCompare(b.path);
+    return pathComparison === 0 ? a.code.localeCompare(b.code) : pathComparison;
+  });
+}
+
+// src/warnings.ts
 var MARKER_PATTERN = /\b(TODO|FIXME|OBSOLETE)\b/i;
 var MARKDOWN_LINK_PATTERN = /(?<!!)\[[^\]\n]+\]\(([^)]+)\)/g;
-function collectWarnings(files) {
-  const warnings = [];
+function collectDiagnostics(files, config) {
+  const diagnostics = [];
   const headings = /* @__PURE__ */ new Map();
   for (const input of files) {
-    warnings.push(...collectFileWarnings(input));
+    diagnostics.push(...collectFileDiagnostics(input, config));
     collectHeadings(input, headings);
   }
-  warnings.push(...collectDuplicateHeadingWarnings(headings));
-  return warnings.sort((a, b) => {
-    const pathComparison = a.path.localeCompare(b.path);
-    return pathComparison === 0 ? a.code.localeCompare(b.code) : pathComparison;
-  });
+  diagnostics.push(...collectDuplicateHeadingDiagnostics(headings, config));
+  return sortDiagnostics(diagnostics);
 }
-function collectFileWarnings(input) {
-  const warnings = [];
+function collectFileDiagnostics(input, config) {
+  const diagnostics = [];
   const { file } = input;
   if (file.skippedBinary) {
-    return warnings;
+    return diagnostics;
   }
-  const content = readFileSync2(input.absolutePath, "utf8");
-  if (file.tokens > OVERSIZED_TOKEN_LIMIT) {
-    warnings.push({
+  const content = readFileSync3(input.absolutePath, "utf8");
+  if (file.tokens > config.maxFileTokens) {
+    pushDiagnostic(diagnostics, createDiagnostic({
       code: "CTX001",
-      severity: "warn",
+      defaultSeverity: "warn",
       path: file.path,
-      message: `larger than ${OVERSIZED_TOKEN_LIMIT} estimated tokens`
-    });
+      message: `larger than ${config.maxFileTokens} estimated tokens`
+    }, config));
   }
   if (content.trim().length === 0) {
-    warnings.push({
+    pushDiagnostic(diagnostics, createDiagnostic({
       code: "CTX004",
-      severity: "warn",
+      defaultSeverity: "warn",
       path: file.path,
       message: "empty context file"
-    });
+    }, config));
   }
   if (MARKER_PATTERN.test(content)) {
-    warnings.push({
+    pushDiagnostic(diagnostics, createDiagnostic({
       code: "CTX005",
-      severity: "warn",
+      defaultSeverity: "warn",
       path: file.path,
       message: "contains TODO, FIXME, or obsolete markers"
-    });
+    }, config));
   }
-  warnings.push(...collectStaleLinkWarnings(input.absolutePath, file.path, content));
-  warnings.push(...collectRepeatedParagraphWarnings(file.path, content));
-  return warnings;
+  diagnostics.push(...collectStaleLinkDiagnostics(input.absolutePath, file.path, content, config));
+  diagnostics.push(...collectRepeatedParagraphDiagnostics(file.path, content, config));
+  return diagnostics;
 }
 function collectHeadings(input, headings) {
   var _a;
   if (input.file.skippedBinary) {
     return;
   }
-  const content = readFileSync2(input.absolutePath, "utf8");
+  const content = readFileSync3(input.absolutePath, "utf8");
   for (const line of content.split(/\r?\n/)) {
     const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
     if (!match) {
@@ -278,27 +313,27 @@ function collectHeadings(input, headings) {
     headings.set(heading, paths);
   }
 }
-function collectDuplicateHeadingWarnings(headings) {
-  const warnings = [];
+function collectDuplicateHeadingDiagnostics(headings, config) {
+  const diagnostics = [];
   for (const [heading, paths] of headings.entries()) {
     const uniquePaths = [...new Set(paths)];
     if (uniquePaths.length < 2) {
       continue;
     }
     for (const path of uniquePaths) {
-      warnings.push({
+      pushDiagnostic(diagnostics, createDiagnostic({
         code: "CTX002",
-        severity: "warn",
+        defaultSeverity: "warn",
         path,
         message: `heading "${heading}" appears in ${uniquePaths.length} context files`
-      });
+      }, config));
     }
   }
-  return warnings;
+  return diagnostics;
 }
-function collectStaleLinkWarnings(absolutePath, displayPath, content) {
+function collectStaleLinkDiagnostics(absolutePath, displayPath, content, config) {
   var _a, _b;
-  const warnings = [];
+  const diagnostics = [];
   const directory = dirname(absolutePath);
   for (const match of content.matchAll(MARKDOWN_LINK_PATTERN)) {
     const href = (_a = match[1]) == null ? void 0 : _a.trim();
@@ -306,28 +341,29 @@ function collectStaleLinkWarnings(absolutePath, displayPath, content) {
       continue;
     }
     const pathOnly = ((_b = href.split("#")[0]) == null ? void 0 : _b.split("?")[0]) ?? "";
-    if (!pathOnly || !existsSync(resolve2(directory, pathOnly))) {
-      warnings.push({
+    if (!pathOnly || !existsSync2(resolve3(directory, pathOnly))) {
+      pushDiagnostic(diagnostics, createDiagnostic({
         code: "CTX003",
-        severity: "warn",
+        defaultSeverity: "warn",
         path: displayPath,
         message: `links to missing file: ${href}`
-      });
+      }, config));
     }
   }
-  return warnings;
+  return diagnostics;
 }
-function collectRepeatedParagraphWarnings(displayPath, content) {
+function collectRepeatedParagraphDiagnostics(displayPath, content, config) {
   const paragraphs = content.split(/\n\s*\n/).map((paragraph) => paragraph.trim().replace(/\s+/g, " ")).filter((paragraph) => paragraph.length >= 40);
   const seen = /* @__PURE__ */ new Set();
   for (const paragraph of paragraphs) {
     if (seen.has(paragraph)) {
-      return [{
+      const diagnostic = createDiagnostic({
         code: "CTX006",
-        severity: "warn",
+        defaultSeverity: "warn",
         path: displayPath,
         message: "contains a repeated paragraph"
-      }];
+      }, config);
+      return diagnostic ? [diagnostic] : [];
     }
     seen.add(paragraph);
   }
@@ -336,9 +372,14 @@ function collectRepeatedParagraphWarnings(displayPath, content) {
 function shouldSkipLink(href) {
   return href.startsWith("http://") || href.startsWith("https://") || href.startsWith("mailto:") || href.startsWith("#");
 }
+function pushDiagnostic(diagnostics, diagnostic) {
+  if (diagnostic) {
+    diagnostics.push(diagnostic);
+  }
+}
 
 // src/scan.ts
-function scanContext(target, agent) {
+function scanContext(target, agent, config = DEFAULT_CONFIG) {
   const root = getScanRoot(target);
   const absoluteFiles = listFiles(target);
   const discoveredFiles = absoluteFiles.map((absolutePath) => {
@@ -365,11 +406,11 @@ function scanContext(target, agent) {
     target,
     files: discoveredFiles,
     totalTokens: discoveredFiles.reduce((total, file) => total + file.tokens, 0),
-    warnings: collectWarnings(warningInputs)
+    warnings: collectDiagnostics(warningInputs, config)
   };
 }
 function getScanRoot(target) {
-  const absoluteTarget = resolve3(target);
+  const absoluteTarget = resolve4(target);
   const stat = statSync2(absoluteTarget);
   return stat.isDirectory() ? absoluteTarget : dirname2(absoluteTarget);
 }
@@ -378,6 +419,324 @@ function normalizeRelativePath(path) {
   return normalized === "" ? "." : normalized;
 }
 
+// src/rules/budget.ts
+function collectBudgetDiagnostics(scan, config) {
+  if (scan.totalTokens <= config.maxTokens) {
+    return [];
+  }
+  const diagnostic = createDiagnostic({
+    code: "CTX105",
+    defaultSeverity: "error",
+    path: scan.target,
+    message: `total context is ~${scan.totalTokens} tokens, budget is ${config.maxTokens}`
+  }, config);
+  return diagnostic ? [diagnostic] : [];
+}
+
+// src/rules/package-manager.ts
+import { readFileSync as readFileSync4, statSync as statSync3 } from "fs";
+import { dirname as dirname3, resolve as resolve5 } from "path";
+var PACKAGE_MANAGER_PATTERNS = [
+  ["npm", /\bnpm\s+(?:run\s+)?[a-z0-9:_-]+\b/i],
+  ["pnpm", /\bpnpm\s+(?:run\s+)?[a-z0-9:_-]+\b/i],
+  ["yarn", /\byarn\s+(?:run\s+)?[a-z0-9:_-]+\b/i],
+  ["bun", /\bbun\s+(?:run\s+)?[a-z0-9:_-]+\b/i]
+];
+function collectPackageManagerDiagnostics(target, files, config) {
+  const root = getScanRoot2(target);
+  const mentions = files.flatMap((file) => collectPackageManagerMentions(root, file));
+  const managers = [...new Set(mentions.map((mention) => mention.manager))].sort();
+  if (managers.length < 2) {
+    return [];
+  }
+  const involvedPaths = [...new Set(mentions.map((mention) => mention.path))].sort();
+  const diagnostics = involvedPaths.map((path) => createDiagnostic({
+    code: "CTX101",
+    defaultSeverity: "error",
+    path,
+    message: `conflicting package managers: ${managers.join(", ")}`
+  }, config)).filter((diagnostic) => diagnostic !== null);
+  return sortDiagnostics(diagnostics);
+}
+function collectPackageManagerMentions(root, file) {
+  if (file.skippedBinary) {
+    return [];
+  }
+  const absolutePath = resolve5(root, file.path);
+  const content = readFileSync4(absolutePath, "utf8");
+  const mentions = [];
+  for (const [manager, pattern] of PACKAGE_MANAGER_PATTERNS) {
+    if (pattern.test(content)) {
+      mentions.push({ manager, path: file.path });
+    }
+  }
+  return mentions;
+}
+function getScanRoot2(target) {
+  const absoluteTarget = resolve5(target);
+  const stat = statSync3(absoluteTarget);
+  return stat.isDirectory() ? absoluteTarget : dirname3(absoluteTarget);
+}
+
+// src/rules/package-scripts.ts
+import { existsSync as existsSync3, readFileSync as readFileSync5, statSync as statSync4 } from "fs";
+import { dirname as dirname4, resolve as resolve6 } from "path";
+var SCRIPT_PATTERNS = [
+  /\bnpm\s+run\s+([a-z0-9:_-]+)\b/gi,
+  /\bpnpm\s+(?!run\b|install\b|add\b|remove\b|exec\b|dlx\b|create\b|init\b)([a-z0-9:_-]+)\b/gi,
+  /\byarn\s+(?!run\b|install\b|add\b|remove\b|exec\b|dlx\b|create\b|init\b)([a-z0-9:_-]+)\b/gi,
+  /\bbun\s+run\s+([a-z0-9:_-]+)\b/gi
+];
+function collectPackageScriptDiagnostics(target, files, config) {
+  const root = getScanRoot3(target);
+  const scripts = readPackageScripts(root);
+  if (!scripts) {
+    return [];
+  }
+  const mentions = files.flatMap((file) => collectScriptMentions(root, file));
+  const seen = /* @__PURE__ */ new Set();
+  const diagnostics = [];
+  for (const mention of mentions) {
+    if (scripts.has(mention.script)) {
+      continue;
+    }
+    const key = `${mention.path}:${mention.script}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    const diagnostic = createDiagnostic({
+      code: "CTX102",
+      defaultSeverity: "error",
+      path: mention.path,
+      message: `references missing package script: ${mention.script}`
+    }, config);
+    if (diagnostic) {
+      diagnostics.push(diagnostic);
+    }
+  }
+  return sortDiagnostics(diagnostics);
+}
+function collectScriptMentions(root, file) {
+  if (file.skippedBinary) {
+    return [];
+  }
+  const absolutePath = resolve6(root, file.path);
+  const content = readFileSync5(absolutePath, "utf8");
+  const mentions = [];
+  for (const pattern of SCRIPT_PATTERNS) {
+    pattern.lastIndex = 0;
+    for (const match of content.matchAll(pattern)) {
+      const script = match[1];
+      if (script) {
+        mentions.push({ path: file.path, script });
+      }
+    }
+  }
+  return mentions;
+}
+function readPackageScripts(root) {
+  const packageJsonPath = resolve6(root, "package.json");
+  if (!existsSync3(packageJsonPath)) {
+    return null;
+  }
+  const parsed = JSON.parse(readFileSync5(packageJsonPath, "utf8"));
+  return new Set(Object.entries(parsed.scripts ?? {}).filter(([, value]) => typeof value === "string").map(([script]) => script));
+}
+function getScanRoot3(target) {
+  const absoluteTarget = resolve6(target);
+  const stat = statSync4(absoluteTarget);
+  return stat.isDirectory() ? absoluteTarget : dirname4(absoluteTarget);
+}
+
+// src/doctor.ts
+function runDoctor(target, agent, config) {
+  const scan = scanContext(target, agent, config);
+  const diagnostics = sortDiagnostics([
+    ...scan.warnings,
+    ...collectBudgetDiagnostics(scan, config),
+    ...collectPackageManagerDiagnostics(target, scan.files, config),
+    ...collectPackageScriptDiagnostics(target, scan.files, config)
+  ]);
+  const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
+  const warnings = diagnostics.filter((diagnostic) => diagnostic.severity === "warn").length;
+  return {
+    agent: scan.agent,
+    target: scan.target,
+    status: errors > 0 ? "fail" : "pass",
+    summary: {
+      files: scan.files.length,
+      totalTokens: scan.totalTokens,
+      warnings,
+      errors
+    },
+    files: scan.files,
+    diagnostics
+  };
+}
+
+// src/init.ts
+import { existsSync as existsSync4, writeFileSync } from "fs";
+import { resolve as resolve7 } from "path";
+var InitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InitError";
+  }
+};
+function initConfig(cwd = process.cwd()) {
+  const path = resolve7(cwd, CONFIG_FILE_NAME);
+  if (existsSync4(path)) {
+    throw new InitError(`${CONFIG_FILE_NAME} already exists`);
+  }
+  writeFileSync(path, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}
+`, "utf8");
+  return { path };
+}
+
+// src/output.ts
+var colorEnabled = process.env.NO_COLOR === void 0 && (process.stdout.isTTY || process.env.FORCE_COLOR !== void 0);
+var colors = {
+  bold: (value) => color("\x1B[1m", value),
+  cyan: (value) => color("\x1B[36m", value),
+  dim: (value) => color("\x1B[2m", value),
+  green: (value) => color("\x1B[32m", value),
+  red: (value) => color("\x1B[31m", value),
+  yellow: (value) => color("\x1B[33m", value)
+};
+function formatHumanScanResult(result) {
+  const sections = [
+    colors.bold(colors.cyan("ctxscope scan")),
+    formatMeta(result),
+    formatFiles(result),
+    formatSummary(result),
+    formatWarnings(result)
+  ];
+  return sections.filter(Boolean).join("\n\n");
+}
+function formatJsonScanResult(result) {
+  return JSON.stringify({
+    agent: result.agent,
+    target: result.target,
+    files: result.files,
+    totalTokens: result.totalTokens,
+    warnings: result.warnings
+  }, null, 2);
+}
+function formatHumanDoctorResult(result) {
+  const sections = [
+    colors.bold(colors.cyan("ctxscope doctor")),
+    formatDoctorMeta(result),
+    formatDoctorSummary(result),
+    formatDoctorDiagnostics(result)
+  ];
+  return sections.filter(Boolean).join("\n\n");
+}
+function formatJsonDoctorResult(result) {
+  return JSON.stringify({
+    agent: result.agent,
+    target: result.target,
+    status: result.status,
+    summary: result.summary,
+    files: result.files,
+    diagnostics: result.diagnostics
+  }, null, 2);
+}
+function formatWarning(warning) {
+  const severity = colorSeverity(warning);
+  const code = warning.severity === "error" ? colors.red(warning.code) : colors.yellow(warning.code);
+  return `${severity} ${code}  ${warning.path}
+  ${colors.dim(warning.message)}`;
+}
+function colorSeverity(diagnostic) {
+  return diagnostic.severity === "error" ? colors.red(diagnostic.severity.toUpperCase()) : colors.yellow(diagnostic.severity.toUpperCase());
+}
+function formatMeta(result) {
+  return [
+    `${colors.dim("Agent")}   ${result.agent}`,
+    `${colors.dim("Target")}  ${result.target}`
+  ].join("\n");
+}
+function formatFiles(result) {
+  if (result.files.length === 0) {
+    return `${colors.bold("Files")} ${colors.dim("(0)")}
+  No context files found.`;
+  }
+  const pathWidth = Math.max("Path".length, ...result.files.map((file) => file.path.length));
+  const tokenWidth = Math.max("Tokens".length, ...result.files.map((file) => formatTokenCell(file.tokens, file.skippedBinary).length));
+  const header = [
+    colors.dim("Path".padEnd(pathWidth)),
+    colors.dim("Tokens".padStart(tokenWidth)),
+    colors.dim("Agents")
+  ].join("  ");
+  const rows = result.files.map((file) => [
+    file.path.padEnd(pathWidth),
+    formatTokenCell(file.tokens, file.skippedBinary).padStart(tokenWidth),
+    file.agents.join(", ")
+  ].join("  "));
+  return `${colors.bold("Files")} ${colors.dim(`(${result.files.length})`)}
+${header}
+${rows.join("\n")}`;
+}
+function formatSummary(result) {
+  const errors = result.warnings.filter((warning) => warning.severity === "error").length;
+  const warnings = result.warnings.filter((warning) => warning.severity === "warn").length;
+  const diagnosticLabel = result.warnings.length === 0 ? colors.green("0 diagnostics") : [
+    errors > 0 ? colors.red(`${errors} errors`) : null,
+    warnings > 0 ? colors.yellow(`${warnings} warnings`) : null
+  ].filter(Boolean).join(", ");
+  return `${colors.bold("Summary")}
+  ${formatNumber(result.files.length)} files, ~${formatNumber(result.totalTokens)} tokens, ${diagnosticLabel}`;
+}
+function formatWarnings(result) {
+  if (result.warnings.length === 0) {
+    return "";
+  }
+  return `${colors.bold("Diagnostics")} ${colors.dim(`(${result.warnings.length})`)}
+${result.warnings.map(formatWarning).join("\n")}`;
+}
+function formatDoctorMeta(result) {
+  return [
+    `${colors.dim("Agent")}   ${result.agent}`,
+    `${colors.dim("Target")}  ${result.target}`,
+    `${colors.dim("Status")}  ${result.status === "pass" ? colors.green("pass") : colors.red("fail")}`
+  ].join("\n");
+}
+function formatDoctorSummary(result) {
+  const diagnosticLabel = result.diagnostics.length === 0 ? colors.green("0 diagnostics") : [
+    result.summary.errors > 0 ? colors.red(`${result.summary.errors} errors`) : null,
+    result.summary.warnings > 0 ? colors.yellow(`${result.summary.warnings} warnings`) : null
+  ].filter(Boolean).join(", ");
+  return `${colors.bold("Summary")}
+  ${formatNumber(result.summary.files)} files, ~${formatNumber(result.summary.totalTokens)} tokens, ${diagnosticLabel}`;
+}
+function formatDoctorDiagnostics(result) {
+  if (result.diagnostics.length === 0) {
+    return "";
+  }
+  const errors = result.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+  const warnings = result.diagnostics.filter((diagnostic) => diagnostic.severity === "warn");
+  const sections = [];
+  if (errors.length > 0) {
+    sections.push(`${colors.bold("Errors")} ${colors.dim(`(${errors.length})`)}
+${errors.map(formatWarning).join("\n")}`);
+  }
+  if (warnings.length > 0) {
+    sections.push(`${colors.bold("Warnings")} ${colors.dim(`(${warnings.length})`)}
+${warnings.map(formatWarning).join("\n")}`);
+  }
+  return sections.join("\n\n");
+}
+function formatTokenCell(tokens, skippedBinary) {
+  return skippedBinary ? "binary" : `~${formatNumber(tokens)}`;
+}
+function formatNumber(value) {
+  return String(value).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function color(code, value) {
+  return colorEnabled ? `${code}${value}\x1B[0m` : value;
+}
+
 // src/types.ts
 var SUPPORTED_AGENTS = ["all", "codex", "opencode", "claude", "generic"];
 
@@ -385,7 +744,7 @@ var SUPPORTED_AGENTS = ["all", "codex", "opencode", "claude", "generic"];
 function getVersion() {
   try {
     const packageJson = JSON.parse(
-      readFileSync3(new URL("../package.json", import.meta.url), "utf8")
+      readFileSync6(new URL("../package.json", import.meta.url), "utf8")
     );
     return packageJson.version ?? "0.0.0";
   } catch {
@@ -400,15 +759,20 @@ Inspect and lint coding-agent context files.
 Usage:
   ctxscope --help
   ctxscope --version
+  ctxscope init
   ctxscope scan [path] [--agent <agent>] [--json]
+  ctxscope doctor [path] [--agent <agent>] [--json] [--ci]
 
 Commands:
+  init                 Create ctxscope.config.json.
   scan                 Discover coding-agent context files for a path.
+  doctor               Lint coding-agent context files.
 
 Options:
   --agent <agent>      Agent profile: all, codex, opencode, claude, generic.
                        Default: all.
   --json               Print machine-readable JSON.
+  --ci                 Exit 1 when doctor finds errors.
   -h, --help           Show this help message.
   -v, --version        Show the package version.
 `);
@@ -464,14 +828,73 @@ function parseScanOptions(args) {
   }
   return options;
 }
+function parseDoctorOptions(args) {
+  const options = {
+    agent: "all",
+    ci: false,
+    json: false,
+    target: "."
+  };
+  let targetSet = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === "--ci") {
+      options.ci = true;
+      continue;
+    }
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (arg === "--agent") {
+      options.agent = parseAgent(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--agent=")) {
+      options.agent = parseAgent(arg.slice("--agent=".length));
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      fail(`unknown option '${arg}'`);
+    }
+    if (targetSet) {
+      fail(`unexpected extra path '${arg}'`);
+    }
+    options.target = arg;
+    targetSet = true;
+  }
+  return options;
+}
 function runScan(options) {
-  const result = scanContext(options.target, options.agent);
+  const config = loadConfig();
+  const result = scanContext(options.target, options.agent, config);
   if (options.json) {
     console.log(formatJsonScanResult(result));
     return;
   }
   console.log(formatHumanScanResult(result));
 }
+function runDoctorCommand(options) {
+  const config = loadConfig();
+  const result = runDoctor(options.target, options.agent, config);
+  if (options.json) {
+    console.log(formatJsonDoctorResult(result));
+  } else {
+    console.log(formatHumanDoctorResult(result));
+  }
+  if (options.ci && result.status === "fail") {
+    process.exit(1);
+  }
+}
+function runInitCommand() {
+  const result = initConfig();
+  console.log(`Created ${result.path}`);
+}
 function main(argv) {
   const [command, ...args] = argv;
   if (!command || command === "--help" || command === "-h") {
@@ -483,7 +906,39 @@ function main(argv) {
     return;
   }
   if (command === "scan") {
-    runScan(parseScanOptions(args));
+    try {
+      runScan(parseScanOptions(args));
+    } catch (error) {
+      if (error instanceof ConfigError) {
+        fail(error.message);
+      }
+      throw error;
+    }
+    return;
+  }
+  if (command === "init") {
+    if (args.length > 0) {
+      fail(`init does not accept arguments: ${args.join(" ")}`);
+    }
+    try {
+      runInitCommand();
+    } catch (error) {
+      if (error instanceof InitError) {
+        fail(error.message);
+      }
+      throw error;
+    }
+    return;
+  }
+  if (command === "doctor") {
+    try {
+      runDoctorCommand(parseDoctorOptions(args));
+    } catch (error) {
+      if (error instanceof ConfigError) {
+        fail(error.message);
+      }
+      throw error;
+    }
     return;
   }
   fail(`unknown command '${command}'`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x6txy/ctxscope",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Inspect and lint coding-agent context files",
   "type": "module",
   "keywords": [