calllint 0.3.0-rc.1 → 0.4.0

package/README.md

@@ -60,6 +60,7 @@ will do, it says so and never silently upgrades to `SAFE`.
 ## More
 
 - SARIF 2.1.0 for GitHub Code Scanning: `calllint scan <config> --sarif`
+- Editor / agent-host diagnostics JSON (`calllint.diagnostics.v0`): `calllint diagnostics <config> --json`
 - Self-contained HTML report: `calllint scan <config> --html > report.html`
 - Drift / rug-pull detection: `calllint baseline <config>` then `calllint verify <config> --ci`
 - Policy-as-code: `calllint policy init`

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync4 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 
 // src/args.ts
 var EXIT = {
@@ -57,6 +57,7 @@ USAGE
 
 COMMANDS
   scan [target]      Scan an MCP config file, or npm:<pkg> / github:<owner/repo>
+  diagnostics [target]  Emit editor/agent-host diagnostics JSON (calllint.diagnostics.v0)
   baseline [target]  Record the approved risk surface as a baseline
   verify [target]    Compare a fresh scan against the baseline (drift / rug-pull)
   explain <server>   Explain the verdict for one server from the last scan
@@ -89,6 +90,7 @@ EXAMPLES
   calllint scan .cursor/mcp.json
   cat .cursor/mcp.json | calllint scan --stdin --json
   calllint scan ./mcp.json --ci --no-emoji
+  calllint diagnostics ./mcp.json --json
   calllint scan npm:mcp-weather@1.0.0
   calllint scan github:owner/repo --online
   calllint baseline ./mcp.json
@@ -100,7 +102,7 @@ function helpCommand() {
 }
 
 // src/commands/scan.ts
-import { join as join3 } from "node:path";
+import { join as join4, resolve } from "node:path";
 
 // ../../packages/policy/src/defaultPolicy.ts
 function defaultPolicy() {
@@ -267,7 +269,8 @@ function resolveScanOptions(opts) {
     policy: opts?.policy ?? defaultPolicy(),
     now: opts?.now ?? 0,
     generatedAt: opts?.generatedAt ?? "1970-01-01T00:00:00.000Z",
-    extraFindings: opts?.extraFindings ?? {}
+    extraFindings: opts?.extraFindings ?? {},
+    surfaces: opts?.surfaces ?? []
   };
 }
 
@@ -534,6 +537,56 @@ function looksLikeBroadPath(arg) {
   if (/^[A-Za-z]:\\Users\\[^\\]+\\?$/.test(arg)) return true;
   return false;
 }
+function looksLikeHostPath(s) {
+  if (!s) return false;
+  return s.startsWith("/") || // POSIX absolute (incl. /Users, /home, /etc, ...)
+  s.startsWith("~") || // home
+  s.startsWith(".") || // workspace-relative (handled as not-broad by isWorkspaceScoped/below)
+  /^[A-Za-z]:[\\/]/.test(s) || // Windows drive, C:\ or C:/
+  s.startsWith("$") || // $HOME / ${HOME}
+  s.startsWith("%");
+}
+function extractDockerHostPaths(args) {
+  const hosts = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--mount" || arg.startsWith("--mount=")) {
+      const csv = arg === "--mount" ? args[i + 1] ?? "" : arg.slice("--mount=".length);
+      if (arg === "--mount") i += 1;
+      const fields = /* @__PURE__ */ new Map();
+      for (const part of csv.split(",")) {
+        const eq = part.indexOf("=");
+        if (eq === -1) continue;
+        fields.set(part.slice(0, eq).trim(), part.slice(eq + 1).trim());
+      }
+      const type = fields.get("type") ?? "volume";
+      if (type !== "bind") continue;
+      const src = fields.get("source") ?? fields.get("src");
+      if (src && looksLikeHostPath(src)) hosts.push(src);
+      continue;
+    }
+    let spec;
+    if (arg === "-v" || arg === "--volume") {
+      spec = args[i + 1];
+      i += 1;
+    } else if (arg.startsWith("-v=")) {
+      spec = arg.slice("-v=".length);
+    } else if (arg.startsWith("--volume=")) {
+      spec = arg.slice("--volume=".length);
+    }
+    if (spec === void 0) continue;
+    const host = dockerVolumeHostSide(spec);
+    if (host && looksLikeHostPath(host)) hosts.push(host);
+  }
+  return hosts;
+}
+function dockerVolumeHostSide(spec) {
+  const winDrive = /^[A-Za-z]:[\\/]/.test(spec);
+  const searchFrom = winDrive ? 2 : 0;
+  const sep = spec.indexOf(":", searchFrom);
+  if (sep === -1) return void 0;
+  return spec.slice(0, sep);
+}
 function detectBroadFilesystemPath(ctx) {
   const { server } = ctx;
   const evidence = [];
@@ -547,6 +600,18 @@ function detectBroadFilesystemPath(ctx) {
       });
     }
   }
+  if ((server.command ?? "").toLowerCase() === "docker") {
+    for (const host of extractDockerHostPaths(server.args)) {
+      if (looksLikeBroadPath(host)) {
+        evidence.push({
+          type: "config",
+          path: server.sourceConfigPath,
+          key: "args",
+          value: host
+        });
+      }
+    }
+  }
   if (evidence.length === 0) return [];
   return [
     {
@@ -727,7 +792,7 @@ function detectUnknownRemote(ctx) {
   ];
 }
 
-// ../../packages/static-analyzer/src/detectors/promptPoisoning.ts
+// ../../packages/static-analyzer/src/promptScan.ts
 var POISON_PATTERNS = [
   "ignore previous instructions",
   "ignore all previous instructions",
@@ -749,23 +814,69 @@ var POISON_PATTERNS = [
   "override the system prompt",
   "you are now"
 ];
-function scanText(text, source) {
+function findPoisonPhrases(text) {
   if (!text) return [];
   const lower = text.toLowerCase();
   const hits = [];
   for (const pattern of POISON_PATTERNS) {
-    if (lower.includes(pattern)) {
-      hits.push({
-        pattern,
-        evidence: {
-          type: "tool-metadata",
-          path: source.path,
-          key: source.key,
-          snippet: pattern
-        }
-      });
+    if (lower.includes(pattern)) hits.push(pattern);
+  }
+  return hits;
+}
+var INVISIBLE_CODE_POINTS = [8203, 8204, 8205, 8288, 65279];
+var BIDI_RANGES = [
+  [8234, 8238],
+  [8294, 8297]
+];
+var TAG_RANGE = [917504, 917631];
+function hasInvisible(text) {
+  for (const ch of text) {
+    if (INVISIBLE_CODE_POINTS.includes(ch.codePointAt(0))) return true;
+  }
+  return false;
+}
+function inAnyRange(text, ranges) {
+  for (const ch of text) {
+    const cp = ch.codePointAt(0);
+    for (const [lo, hi] of ranges) {
+      if (cp >= lo && cp <= hi) return true;
     }
   }
+  return false;
+}
+function findHiddenContent(text) {
+  if (!text) return [];
+  const categories = [];
+  if (hasInvisible(text)) categories.push("zero-width or invisible characters");
+  if (inAnyRange(text, BIDI_RANGES)) {
+    categories.push("Unicode bidirectional override controls");
+  }
+  if (inAnyRange(text, [TAG_RANGE])) {
+    categories.push("invisible tag-character ASCII smuggling");
+  }
+  if (/<!--[\s\S]*?-->/.test(text)) categories.push("embedded HTML/XML comment");
+  return categories;
+}
+function poisonEvidence(pattern, source) {
+  return { type: source.type, path: source.path, key: source.key, snippet: pattern };
+}
+function hiddenEvidence(category, source) {
+  return { type: source.type, path: source.path, key: source.key, snippet: category };
+}
+
+// ../../packages/static-analyzer/src/detectors/promptPoisoning.ts
+function scanText(text, source) {
+  const hits = [];
+  for (const pattern of findPoisonPhrases(text)) {
+    hits.push({
+      pattern,
+      evidence: poisonEvidence(pattern, {
+        type: "tool-metadata",
+        path: source.path,
+        key: source.key
+      })
+    });
+  }
   return hits;
 }
 function detectPromptPoisoning(ctx) {
@@ -1009,6 +1120,93 @@ function detectFinancialAction(ctx) {
   return findings;
 }
 
+// ../../packages/static-analyzer/src/detectors/unverifiedLocalSource.ts
+function localSubject(args) {
+  for (const a of args) {
+    if (a === "-y" || a === "--yes" || a.startsWith("-")) continue;
+    return a;
+  }
+  return void 0;
+}
+function detectUnverifiedLocalSource(ctx) {
+  const { binding, server } = ctx;
+  if (!binding.sourceKnown) return [];
+  if (!binding.runtimeExecutable) return [];
+  if (binding.runtimeKind === "docker") return [];
+  if (binding.packageName) return [];
+  const command = binding.declaredCommand ?? server.command;
+  if (!command) return [];
+  const subject = localSubject(binding.declaredArgs);
+  const display = subject ? `${command} ${subject}` : command;
+  const evidence = [
+    {
+      type: "runtime-binding",
+      path: server.sourceConfigPath,
+      key: "command",
+      value: display
+    }
+  ];
+  return [
+    {
+      id: "exec.unverified-local-source",
+      title: "Runs an unverified local executable",
+      severity: "medium",
+      blocker: false,
+      symbol: "EXEC",
+      riskClass: "S2",
+      mode: "OBSERVED",
+      confidence: "medium",
+      detectionMethod: "runtime-binding",
+      evidence,
+      impact: "The runtime executes a local script or binary whose contents CallLint never inspects. It is not a recognized package or pinned image, so what actually runs cannot be verified from the config alone.",
+      fix: "Confirm you trust the local source, or run it from a pinned, recognized package (e.g. npx pkg@1.2.3 / a pinned docker image) so the runtime is independently verifiable.",
+      falsePositiveNote: "A developer running their own local server (e.g. node ./dist/server.js) is normal; this flags that the source is not independently verifiable, not that it is malicious."
+    }
+  ];
+}
+
+// ../../packages/static-analyzer/src/detectors/hiddenInstructions.ts
+function scanHidden(text, key, path) {
+  const out = [];
+  for (const category of findHiddenContent(text)) {
+    out.push(hiddenEvidence(category, { type: "tool-metadata", path, key }));
+  }
+  return out;
+}
+function detectHiddenInstructions(ctx) {
+  const { server } = ctx;
+  const evidence = [];
+  evidence.push(...scanHidden(server.instructions, "instructions", server.sourceConfigPath));
+  for (const tool of server.providedTools) {
+    const base = tool.name ? `tools.${tool.name}` : "tools";
+    evidence.push(...scanHidden(tool.name, `${base}.name`, server.sourceConfigPath));
+    evidence.push(
+      ...scanHidden(tool.description, `${base}.description`, server.sourceConfigPath)
+    );
+    evidence.push(
+      ...scanHidden(tool.inputSchemaText, `${base}.inputSchema`, server.sourceConfigPath)
+    );
+  }
+  if (evidence.length === 0) return [];
+  return [
+    {
+      id: "prompt.hidden-instructions",
+      title: "Hidden or obfuscated content in model-visible metadata",
+      severity: "medium",
+      blocker: false,
+      symbol: "PROMPT",
+      riskClass: "S2",
+      mode: "OBSERVED",
+      confidence: "medium",
+      detectionMethod: "tool-metadata",
+      evidence,
+      impact: "Invisible or obfuscated characters in tool metadata reach the model but not a human reader, so a model-directed instruction can hide from review while still steering autonomous tool use.",
+      fix: "Remove zero-width/bidirectional/tag characters and HTML comments from tool names, descriptions, schemas, and server instructions; keep model-visible text identical to what a human reviewer sees.",
+      falsePositiveNote: "Some hidden characters are benign (e.g. a BOM, or a bidi control in a legitimate right-to-left language sample, or an HTML comment in documentation). This flags that the model-visible text differs from the rendered text; review the surface in context."
+    }
+  ];
+}
+
 // ../../packages/static-analyzer/src/analyzeServerConfig.ts
 var DETECTORS = [
   detectBroadFilesystemPath,
@@ -1018,7 +1216,9 @@ var DETECTORS = [
   detectUnpinnedPackage,
   detectUnknownRemote,
   detectExternalMutation,
-  detectFinancialAction
+  detectFinancialAction,
+  detectUnverifiedLocalSource,
+  detectHiddenInstructions
 ];
 function analyzeServerConfig(server) {
   const binding = resolveRuntimeBinding(server);
@@ -1030,6 +1230,41 @@ function analyzeServerConfig(server) {
   return findings;
 }
 
+// ../../packages/static-analyzer/src/documentSurface.ts
+function analyzeDocumentSurfaces(surfaces) {
+  const evidence = [];
+  for (const surface of surfaces) {
+    for (const pattern of findPoisonPhrases(surface.text)) {
+      evidence.push(
+        poisonEvidence(pattern, { type: "source", path: surface.path, key: surface.kind })
+      );
+    }
+    for (const category of findHiddenContent(surface.text)) {
+      evidence.push(
+        hiddenEvidence(category, { type: "source", path: surface.path, key: surface.kind })
+      );
+    }
+  }
+  if (evidence.length === 0) return [];
+  return [
+    {
+      id: "prompt.surface-instructions",
+      title: "Model-directed or hidden content in a project document",
+      severity: "medium",
+      blocker: false,
+      symbol: "PROMPT",
+      riskClass: "S2",
+      mode: "OBSERVED",
+      confidence: "medium",
+      detectionMethod: "source-text",
+      evidence,
+      impact: "A project document (README / SKILL.md / AGENTS.md / package description) contains model-directed instructions or hidden/obfuscated content. An agent that reads project docs alongside the tool could be steered by text a human reviewer skims past.",
+      fix: "Remove model-directed instructions and hidden/obfuscated characters from project documents; keep their visible text equal to their intent.",
+      falsePositiveNote: "Documentation legitimately discusses prompts, tool ordering, or includes HTML comments and non-Latin scripts. This flags prompt-surface shape in project docs, not a proven injection; review the cited file in context."
+    }
+  ];
+}
+
 // ../../packages/risk-engine/src/computeRiskClass.ts
 function computeRiskClass(findings, binding) {
   const classes = findings.map((f) => f.riskClass);
@@ -1387,6 +1622,126 @@ function normalizeMcpServers(root, sourceConfigPath) {
 
 // ../../packages/config-parser/src/parseConfig.ts
 import { basename } from "node:path";
+
+// ../../packages/config-parser/src/positionIndex.ts
+function peek(c) {
+  return c.text[c.i] ?? "";
+}
+function advance(c) {
+  const ch = c.text[c.i] ?? "";
+  c.i++;
+  if (ch === "\n") {
+    c.line++;
+    c.col = 1;
+  } else {
+    c.col++;
+  }
+  return ch;
+}
+function skipWhitespace(c) {
+  while (c.i < c.text.length) {
+    const ch = peek(c);
+    if (ch === " " || ch === "	" || ch === "\n" || ch === "\r") advance(c);
+    else break;
+  }
+}
+function readString(c) {
+  advance(c);
+  let out = "";
+  while (c.i < c.text.length) {
+    const ch = advance(c);
+    if (ch === "\\") {
+      const esc2 = advance(c);
+      if (esc2 === "n") out += "\n";
+      else if (esc2 === "t") out += "	";
+      else if (esc2 === "r") out += "\r";
+      else if (esc2 === "u") {
+        let hex = "";
+        for (let k = 0; k < 4; k++) hex += advance(c);
+        const code = Number.parseInt(hex, 16);
+        out += Number.isNaN(code) ? "" : String.fromCharCode(code);
+      } else out += esc2;
+    } else if (ch === '"') {
+      break;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+function skipValue(c, index, pathPrefix) {
+  skipWhitespace(c);
+  const ch = peek(c);
+  if (ch === "{") {
+    scanObject(c, index, pathPrefix);
+  } else if (ch === "[") {
+    scanArray(c, index, pathPrefix);
+  } else if (ch === '"') {
+    readString(c);
+  } else {
+    while (c.i < c.text.length) {
+      const n = peek(c);
+      if (n === "," || n === "}" || n === "]" || n === " " || n === "	" || n === "\n" || n === "\r") break;
+      advance(c);
+    }
+  }
+}
+function scanArray(c, index, pathPrefix) {
+  advance(c);
+  for (; ; ) {
+    skipWhitespace(c);
+    const ch = peek(c);
+    if (ch === "]" || ch === "") {
+      if (ch === "]") advance(c);
+      return;
+    }
+    if (ch === ",") {
+      advance(c);
+      continue;
+    }
+    skipValue(c, index, pathPrefix);
+  }
+}
+function scanObject(c, index, pathPrefix) {
+  advance(c);
+  for (; ; ) {
+    skipWhitespace(c);
+    const ch = peek(c);
+    if (ch === "}" || ch === "") {
+      if (ch === "}") advance(c);
+      return;
+    }
+    if (ch === ",") {
+      advance(c);
+      continue;
+    }
+    if (ch !== '"') {
+      advance(c);
+      continue;
+    }
+    const keyLine = c.line;
+    const keyCol = c.col;
+    const key = readString(c);
+    const path = pathPrefix ? `${pathPrefix}.${key}` : key;
+    if (!(path in index)) index[path] = { line: keyLine, column: keyCol };
+    skipWhitespace(c);
+    if (peek(c) === ":") advance(c);
+    skipValue(c, index, path);
+  }
+}
+function buildPositionIndex(text) {
+  const index = {};
+  const c = { text, i: 0, line: 1, col: 1 };
+  try {
+    skipWhitespace(c);
+    if (peek(c) === "{") scanObject(c, index, "");
+    else if (peek(c) === "[") scanArray(c, index, "");
+  } catch {
+  }
+  return index;
+}
+
+// ../../packages/config-parser/src/parseConfig.ts
 function kindForPath(path) {
   const base = basename(path).toLowerCase();
   if (base.includes("settings")) return "claude-settings";
@@ -1399,10 +1754,84 @@ function parseConfigText(text, configPath = "<inline>") {
     configPath,
     kind: configPath === "<inline>" ? "inline" : kindForPath(configPath),
     servers: normalizeMcpServers(root, configPath),
-    root
+    root,
+    positions: buildPositionIndex(text)
+  };
+}
+
+// ../../packages/core/src/scanSurfaces.ts
+function scanDocumentSurfaces(surfaces, configPath, generatedAt) {
+  if (surfaces.length === 0) return void 0;
+  const findings = analyzeDocumentSurfaces(surfaces);
+  if (findings.length === 0) return void 0;
+  const truncated = surfaces.some((s) => s.truncated);
+  return {
+    schemaVersion: "calllint.report.v0",
+    reportKind: "single-target",
+    target: {
+      name: "project-docs",
+      kind: "project-docs",
+      configPath
+    },
+    verdict: "REVIEW",
+    publicVerdictLabel: VERDICT_PUBLIC_LABEL.REVIEW,
+    riskClass: "S2",
+    symbols: ["PROMPT"],
+    confidence: "medium",
+    reproducibility: {
+      level: "HIGH",
+      reasons: ["Static scan of local documents; deterministic given the same files."]
+    },
+    summary: "Project documents contain model-directed or hidden prompt-surface content; review the cited files.",
+    observed: findings,
+    inferred: [],
+    findings,
+    topFindings: findings,
+    policy: {
+      autonomousUse: "warn",
+      manualApproval: "recommended",
+      sandbox: "recommended"
+    },
+    fingerprints: {
+      configHash: "",
+      targetSpecHash: "",
+      riskSurfaceHash: ""
+    },
+    diagnostics: truncated ? [
+      {
+        level: "info",
+        code: "surface.truncated",
+        message: "One or more project documents exceeded the scan size cap and were truncated."
+      }
+    ] : [],
+    generatedAt
   };
 }
 
+// ../../packages/core/src/enrichPositions.ts
+function enrichEvidencePositions(reports, positions) {
+  if (Object.keys(positions).length === 0) return;
+  const prefixes = ["mcpServers", "servers", ""];
+  for (const report of reports) {
+    const server = report.target.name;
+    for (const finding of report.findings) {
+      for (const ev of finding.evidence) {
+        if (ev.line !== void 0) continue;
+        if (!ev.key) continue;
+        for (const prefix of prefixes) {
+          const path = prefix ? `${prefix}.${server}.${ev.key}` : `${server}.${ev.key}`;
+          const pos = positions[path];
+          if (pos) {
+            ev.line = pos.line;
+            ev.column = pos.column;
+            break;
+          }
+        }
+      }
+    }
+  }
+}
+
 // ../../packages/core/src/scanConfig.ts
 function aggregate(configPath, reports, generatedAt) {
   const counts = { SAFE: 0, REVIEW: 0, BLOCK: 0, UNKNOWN: 0 };
@@ -1421,10 +1850,13 @@ function aggregate(configPath, reports, generatedAt) {
   };
 }
 function scanParsed(parsed, opts) {
-  const { generatedAt } = resolveScanOptions(opts);
+  const { generatedAt, surfaces } = resolveScanOptions(opts);
   const reports = parsed.servers.map(
     (server) => scanServer({ server, targetKind: parsed.kind }, opts)
   );
+  enrichEvidencePositions(reports, parsed.positions);
+  const surfaceReport = scanDocumentSurfaces(surfaces, parsed.configPath, generatedAt);
+  if (surfaceReport) reports.push(surfaceReport);
   return aggregate(parsed.configPath, reports, generatedAt);
 }
 function scanConfigText(text, configPath, opts) {
@@ -1872,6 +2304,60 @@ function renderSarif(summary) {
   return JSON.stringify(sarif, null, 2);
 }
 
+// ../../packages/report-renderer/src/renderDiagnostics.ts
+function verdictContributionFor(f) {
+  if (f.blocker) return "blocker";
+  return f.mode === "INFERRED" ? "inferred" : "review";
+}
+function keyPathFor(f) {
+  const ev = f.evidence[0];
+  if (!ev) return null;
+  return ev.key ?? null;
+}
+function observedFor(f) {
+  const ev = f.evidence[0];
+  if (!ev) return null;
+  return ev.value ?? ev.snippet ?? null;
+}
+function entryFromFinding(f, report, configFile) {
+  const ev = f.evidence[0];
+  return {
+    ruleId: f.id,
+    title: f.title,
+    severity: f.severity,
+    server: report.target.name,
+    file: ev?.path ?? configFile,
+    keyPath: keyPathFor(f),
+    // Populated by the post-hoc position enrichment (config-parser position
+    // index → core), when the evidence's config key maps to a source location;
+    // null for evidence with no locatable source key (e.g. binding-derived).
+    line: ev?.line ?? null,
+    column: ev?.column ?? null,
+    observed: observedFor(f),
+    remediation: f.fix,
+    mode: f.mode,
+    confidence: f.confidence,
+    verdictContribution: verdictContributionFor(f)
+  };
+}
+function renderDiagnostics(summary) {
+  const diagnostics = [];
+  for (const report of summary.reports) {
+    for (const f of report.findings) {
+      diagnostics.push(entryFromFinding(f, report, summary.configPath));
+    }
+  }
+  const out = {
+    schemaVersion: "calllint.diagnostics.v0",
+    verdict: summary.verdict,
+    publicVerdictLabel: summary.publicVerdictLabel,
+    file: summary.configPath,
+    diagnostics,
+    generatedAt: summary.generatedAt
+  };
+  return JSON.stringify(out, null, 2);
+}
+
 // ../../packages/report-renderer/src/logoBase64.ts
 var LOGO_REPORT_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAYAAABXAvmHAAAACXBIWXMAAAPoAAAD6AG1e1JrAAAKdElEQVRo3u1aeXAT1xlf35cs2bJ8yJYtbGxjG+rgkJCjdaBMSYBAhstAhwSYZDJ105CGnBwNSUlKmibNJDR0GJrJQELb1C2kgQ6dtJwFAgFyTAB7tVpprdvyjW3Zkvb4+r2nAzVtZ/qHhO2ZLrOjZd/bx/f73u87Hwzz/+u/X8AwSeSezABSgJmVNikFJ7+m3PINnLq8NfbdpKAN+f1So8kTVAarNbfM9YWqpDB2bFJo36Iu32tP14EDb4umYh9510YpNYFBoHCp5JfTGTc5GA103vU9qbN5gWTHZ0tB1WYydhLnTDgQRKCTYeHZwurHhLRC4HVTZD/LKX7eqpiLqmQhTQfmgsofRUC8yDDJE0H2pFhacAVVzwtIGXNOsTxy6qwS7LRDwCLAyJlPFbNKL9sQBKub8sI3QY+jiwxp0W5o0Jq0Vb91JuUBX2CURk6eUZQxPwgzm8E64w6QfT4EcV7hdZWSMxnnaCvbWH2tLrxOctt4eiizvnYpn1NmcTLZ0Nl4t0hoIw8Ng+2ehWBKzgdTSj7Yvn0vSIPXwc/xSmfTd0Qy15xTKphLqlvGxR44pjqD05St4LJLT9iIsabrlK4nt0iKKIG/gwNhxl3A4m6YMouAyyqmQKwNs8HfzoIiy+B9drskZOgUG6MGNlt/ukNTtlJgjJkRWiZM8IjhsZqKSkd26ag7txycyx6Sxr6+KgNeA3v3AZdXAaaMQmBRONs9C8A+bwk+5wKXWQycphz697xHpsLYlQ7ZuWKd5FYZwJZTOnxFa6yPUCrhQepqwxwVarjdOWsukUUeu/g52Ocuhg4mh1KGRYpY62+HgLUTgjYHCA130HcsjpE5tuaFMPrZZUDUsvPO+fhOY/bMfzAnocGOGNpVhkmnQapyRjHL5PW65iwC0TeqWOtvQyHSwZxrAKHudvBu2gqixwsKoiO36O2G7mdeAKF+NnA4h8y11MwEyR9QXN8lwNU9jurZBqoc/DcSZtQR7VhLan9mYzLAu/WnstjTA3y+EThVKZiYPOh99ZeUIooogixJoRufydX72lu4E3k4twy9VRUEPV3g3fYyBroM6CyZ9mosTePOffQaq0xq/UY2u/SQBenAl9UqYm8fDOz+DQqeg9ovA1N6IQlW4L/aHgKBwtMbnwNo3GZdVWiOuhy/yYaBXXtA7OsHS9k0wDUVdAqHTGrDRlOO4ftxoVPsAi5V6YnBHAO4NBWSY/5SOSjYqMfh9bVgwgDFZeuRHuWU696Nz4Z34Yb2vU9uRqpkUZpxOaXApRcBX1ILAZaDINqK/d7lijvPKA2gUbtVZefiYtCxAFDIY47iGhj78usA0ajv9DmwVjZSo+VyysCcpUffrgdTqo6+l3B3ojaAWrZWN9ExKnxWCZiRRqbUArBMvQV8p85SkL4LlwLOiukITncm7gDY5PwTbkMDKIoieZ/ahtrMoO6SahS1b47eKGCKFoaP/h0i18jx0xgLtFR4c+xc/Jas0cFk4g5tQXc2JnVV34pz884lAID2hAcBoOeQnA+sQaqokMsGYDE1MKFGuQgQNaFRJvT94u0oAPJMYwHSw0xAkLn4DZusprGBjDnvXwXSyEgYgDb+ALhk7fGu8umE05Jr9cOotTSwNy+A7m0vI40QBBEQeW0mAiXlg/exp6MAPPhMhDRrKugcAp5NzYPuLTvAhq64A9Mq18p1IPl8CKApQQBStcc9BgQQDEquNY9AOw73hV2m728nwLVkDfCFU4FL09Ixx+LllP/kcixdDejf0QMVgLmwGsdWwcgnx0Ou9ZXX4RqORQFMRQApCQGgO+Ypa8AdCErOZWvBgh5E7OkNGaoSEpVE3uHDR6HvzXdg8Hd/jBrx4IcHoe+NXTD88VE6h16yEjLw7h7qyQgoaXRUclfeQmzoH3FLKyIg0IN87CmZBuLwsOR+5HEYOnQkJAcJWOQOBqNAIhf5+7+9wz90bjjQkWvooyPg2tAK4uCgRByFKa3gaNwARMK6Ob14X7fGCGJvr+h94nnwPPpEFIASFiTi+0mAE3v7QwCIlvv76Ts5Zh6N0MFQjPC0PgUejB3Brm7Jie4VM9j347kDtGrC7sIrXiwVx65cE/t/tZfy1nfsVEhoFGT0/EXoeW47OBauBB557Fr7aNQG3A8/DpYpjeBY1ALdOIfMVXAXqP0cO03X6seIPnrlmuQk9bOmfEes8uLSZbAXVa/txEg6+Ps/yaNnL1BD9az7AYjuLnAtexDQRsIZpwbHMsFxf0sUgHPFQ/guhXoelmSsGLnJN2JXN7jXt9K1fGc+xbUPSS70UILOuCZuvaTINrprmuo5JjtI0gQ0XgUbVmh800CovRWFyqL+ncN8KOTX1eBGcFE3ijbTQaqwPGM08NGUu3om5lR1YM4n1OxTvEgljCFjjsoZjXE34qstLel8Uv4XHqysJL9fdi1eTYXgsopionEJBUGEJVSJXCRWkDqAi43auZTrdA0X8UC4pnvGncAzmq/a2tpSEtKs6sw17PRgkPKdvyhdR9dI6MDjTtBELnKHE7rBd/dHAQwe+AO+09A0+l/SDnVo7lDbRzBy4RLSB8tTjWFn3Pj/TRo5jQ0zeSY74EHeYt6iWGuaaEJGEjMiUGyiNvrZ51EA/mtsKN3OihGegMFvrUhBspZ7XSuYmWy/raJuVkJKy2gxk1lyyIUC+M0WaeDd9yn/I9QgGiYFfGdTM8iBQDQOEJ9P0g5TeBdCFCqn3w7iGmMmXnJhEtiZrT+YsLIyohGLvr7ZwqhE16r1GJFkxd58HzVaCgK1TCjRu+O1G0Eu7OtJJCZj1F7wJt/Ysd0CkqQ4V64HsqZJX9Oc0MI+srCQa9jrRm0OHfmrGOgwoUBYTpKuQwYWKUVVtBt3oyKjDQsQnS7gS2swmSsM0U2Fu3ilHa4fPioS7pM1b1pXQjA2lAipOqvDUA+BLq98/YMPqUZNaOD9b+8JaZ9QCHtAhELkOdp2SSlAKqlg8L0DEPR2yzZcA9fi2yvq9DelBR9tnxfXLRYYteyYt4SoWOnZvpMGMOL/ScsksgOR9GH08lcYDzbS4qVn80ukpaLY5j2gWBm1xJfULEq49v9TfmTRVm4lkdOz4YeU6N4fb6ZpgQljQ9+bu6NeqP8dLPyx3CRjXeE6AYMbthixKNJWbhmXE5yoUedX/NqDgmCCR5Ob7md+QrVMAtfQwcMwgqUloRfpBXk3PgfhOUE3juPBx56EtVL+1xPItpaWFHSJBzwoEO5AkNLppZ+HmldV36IdOlJxEdqQMe/TRHgV8JryAyfnzCGJ4vidZEZAnGTmpPKaiv0ERJhOysDe/cCma7C8xP7PW9Swla7WTVTzGL0/uDyLnl6O/zEsEYBQABhI4jXGXU4U0HnfckkKBOThv3yCacKfMVzIsmvZWnSXGAfyp+wG3LUJdYYcFibUucazMIFRyY7GuxW/zS4FPF2S/ba5ikAMVjd1W8R+JuJhX1LEO+Hpy1ILo+l1ldaBGzsZPJPbz+qmrposJ5UhF1vaWMum6y5g5L0kGKfXT7bDbkonL54jcNWz1XFPj2/GRQz7xTDXYYIcqU7I/63yT1NyvbeodjVcAAAAAElFTkSuQmCC";
 
@@ -2066,6 +2552,55 @@ function resolveConfigInput(args, deps) {
   return { text: readFileSync3(resolved, "utf8"), configPath: resolved };
 }
 
+// src/commands/surfaces.ts
+import { existsSync as existsSync3, readFileSync as readFileSync4, statSync } from "node:fs";
+import { join as join3 } from "node:path";
+var SURFACE_SIZE_CAP = 256 * 1024;
+var SURFACE_FILES = [
+  { file: "README.md", kind: "readme" },
+  { file: "SKILL.md", kind: "skill" },
+  { file: "AGENTS.md", kind: "agents" }
+];
+function readCapped(path) {
+  try {
+    const st = statSync(path);
+    if (!st.isFile()) return void 0;
+    const raw = readFileSync4(path, "utf8");
+    if (raw.length > SURFACE_SIZE_CAP) {
+      return { text: raw.slice(0, SURFACE_SIZE_CAP), truncated: true };
+    }
+    return { text: raw, truncated: false };
+  } catch {
+    return void 0;
+  }
+}
+function readDocumentSurfaces(dir) {
+  const surfaces = [];
+  if (!existsSync3(dir)) return surfaces;
+  for (const { file, kind } of SURFACE_FILES) {
+    const got = readCapped(join3(dir, file));
+    if (got) surfaces.push({ path: file, kind, text: got.text, truncated: got.truncated });
+  }
+  const pkgPath = join3(dir, "package.json");
+  const pkgRaw = readCapped(pkgPath);
+  if (pkgRaw) {
+    try {
+      const pkg = JSON.parse(pkgRaw.text);
+      const description = pkg && typeof pkg === "object" && !Array.isArray(pkg) ? pkg.description : void 0;
+      if (typeof description === "string") {
+        surfaces.push({
+          path: "package.json",
+          kind: "package-description",
+          text: description,
+          truncated: pkgRaw.truncated
+        });
+      }
+    } catch {
+    }
+  }
+  return surfaces;
+}
+
 // src/commands/scan.ts
 function scanCommand(args, deps) {
   const policyPath = flagStr(args.flags, "policy");
@@ -2084,13 +2619,16 @@ function scanCommand(args, deps) {
     return { stdout: "", stderr: input.error, exitCode: input.exitCode };
   }
   const { text, configPath } = input;
+  const surfaceDir = flagStr(args.flags, "surface-dir");
+  const surfaces = surfaceDir ? readDocumentSurfaces(resolve(deps.cwd, surfaceDir)) : void 0;
   let summary;
   try {
     summary = scanConfigText(text, configPath, {
       policy,
       now: deps.now,
       generatedAt: deps.generatedAt,
-      extraFindings: deps.online?.extraFindings
+      extraFindings: deps.online?.extraFindings,
+      surfaces
     });
   } catch (err) {
     if (err instanceof ConfigParseError) {
@@ -2104,7 +2642,7 @@ function scanCommand(args, deps) {
   }
   if (deps.writeCacheFile !== false) {
     try {
-      writeCache(summary, join3(deps.cwd, ".calllint", "last-scan.json"));
+      writeCache(summary, join4(deps.cwd, ".calllint", "last-scan.json"));
     } catch {
     }
   }
@@ -2119,8 +2657,55 @@ function scanCommand(args, deps) {
   return { stdout, exitCode };
 }
 
+// src/commands/diagnostics.ts
+function diagnosticsCommand(args, deps) {
+  if (!flagBool(args.flags, "json")) {
+    return {
+      stdout: "",
+      stderr: "diagnostics v0 emits JSON only \u2014 pass --json (calllint.diagnostics.v0).",
+      exitCode: EXIT.USAGE
+    };
+  }
+  let policy;
+  try {
+    policy = loadPolicyOrDefault(flagStr(args.flags, "policy"));
+  } catch (err) {
+    return {
+      stdout: "",
+      stderr: err instanceof Error ? err.message : String(err),
+      exitCode: EXIT.ERROR
+    };
+  }
+  const input = deps.online?.inputOverride ?? resolveConfigInput(args, deps);
+  if (isInputError(input)) {
+    return { stdout: "", stderr: input.error, exitCode: input.exitCode };
+  }
+  const { text, configPath } = input;
+  let summary;
+  try {
+    summary = scanConfigText(text, configPath, {
+      policy,
+      now: deps.now,
+      generatedAt: deps.generatedAt,
+      extraFindings: deps.online?.extraFindings
+    });
+  } catch (err) {
+    if (err instanceof ConfigParseError) {
+      return {
+        stdout: "",
+        stderr: `Parse error in ${configPath}: ${err.message}`,
+        exitCode: EXIT.ERROR
+      };
+    }
+    throw err;
+  }
+  const stdout = renderDiagnostics(summary);
+  const exitCode = flagBool(args.flags, "ci") ? exitCodeFor(summary, policy) : EXIT.OK;
+  return { stdout, exitCode };
+}
+
 // src/commands/explain.ts
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 function explainCommand(args, deps) {
   const serverName = args.positionals[0];
   if (!serverName) {
@@ -2130,7 +2715,7 @@ function explainCommand(args, deps) {
       exitCode: EXIT.USAGE
     };
   }
-  const summary = readCache(join4(deps.cwd, ".calllint", "last-scan.json"));
+  const summary = readCache(join5(deps.cwd, ".calllint", "last-scan.json"));
   if (!summary) {
     return {
       stdout: "",
@@ -2152,13 +2737,13 @@ function explainCommand(args, deps) {
 }
 
 // src/commands/policy.ts
-import { existsSync as existsSync3, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join5 } from "node:path";
+import { existsSync as existsSync4, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join6 } from "node:path";
 function policyCommand(args, deps) {
   const sub = args.positionals[0];
   if (sub === "init") {
-    const path = join5(deps.cwd, "calllint.policy.json");
-    if (existsSync3(path) && !flagBool(args.flags, "force")) {
+    const path = join6(deps.cwd, "calllint.policy.json");
+    if (existsSync4(path) && !flagBool(args.flags, "force")) {
       return {
         stdout: "",
         stderr: `${path} already exists. Use --force to overwrite.`,
@@ -2188,7 +2773,7 @@ function policyCommand(args, deps) {
 }
 
 // src/commands/verify.ts
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 function loadPolicy(args) {
   try {
     return loadPolicyOrDefault(flagStr(args.flags, "policy"));
@@ -2197,7 +2782,7 @@ function loadPolicy(args) {
   }
 }
 function baselinePathFor(args, cwd) {
-  return flagStr(args.flags, "baseline") ?? join6(cwd, ".calllint", "baseline.json");
+  return flagStr(args.flags, "baseline") ?? join7(cwd, ".calllint", "baseline.json");
 }
 function baselineCommand(args, deps) {
   const policy = loadPolicy(args);
@@ -2285,6 +2870,14 @@ function run(argv, deps) {
         writeCacheFile: deps.writeCacheFile,
         online: deps.online
       });
+    case "diagnostics":
+      return diagnosticsCommand(args, {
+        cwd: deps.cwd,
+        readStdin: deps.readStdin,
+        now: deps.now,
+        generatedAt: deps.generatedAt,
+        online: deps.online
+      });
     case "baseline":
       return baselineCommand(args, {
         cwd: deps.cwd,
@@ -2548,7 +3141,7 @@ async function breathe(argv, deps = {}) {
 // src/index.ts
 function readStdin() {
   try {
-    return readFileSync4(0, "utf8");
+    return readFileSync5(0, "utf8");
   } catch {
     return "";
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "calllint",
-  "version": "0.3.0-rc.1",
+  "version": "0.4.0",
   "description": "Evidence-backed security verdicts for MCP servers and agent tools. Lint agent tool-call risk before tools run — SAFE / REVIEW / BLOCK / UNKNOWN, with evidence. Never executes the server it judges.",
   "keywords": [
     "mcp",