@jqntn/agentdoctor 0.1.0

package/src/discover.js

@@ -0,0 +1,235 @@
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, relative, basename, sep } from 'node:path';
+import { parseJsonWithPositions, parseFrontmatter, JsonSyntaxError } from './parse.js';
+
+/** Directories that never contain agent config worth linting. */
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.hg', '.svn', 'dist', 'build', 'out', 'target',
+  'vendor', '.next', '.nuxt', '.venv', 'venv', '__pycache__', '.cache',
+  'coverage', '.turbo', '.gradle', 'Pods', '.terraform',
+]);
+
+/**
+ * Files that may hold live credentials. agentdoctor never opens these — it can
+ * report on their permissions via stat(), but the contents stay unread so the
+ * tool can be run safely in CI and on shared machines.
+ */
+const NEVER_READ = new Set(['.credentials.json', 'credentials.json', '.netrc', 'id_rsa', 'id_ed25519']);
+
+const MAX_WALK_DEPTH = 6;
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+
+/**
+ * @typedef {Object} ConfigFile
+ * @property {string} path            absolute path
+ * @property {string} display         path shown to the user
+ * @property {'settings'|'mcp'|'memory'|'agent'|'skill'|'command'|'hook'|'keybindings'} kind
+ * @property {'project'|'local'|'user'|'enterprise'} scope
+ * @property {string} text
+ * @property {unknown} [data]
+ * @property {Map<string,{line:number,column:number}>} [positions]
+ * @property {Record<string,unknown>|null} [frontmatter]
+ * @property {number} [frontmatterLines]
+ * @property {string} [body]
+ * @property {{message:string,line:number,column:number}} [parseError]
+ * @property {number} bytes
+ * @property {number} mode
+ * @property {number} gid
+ * @property {number} uid
+ */
+
+/**
+ * Collects every agent-configuration file in scope for a run.
+ *
+ * @param {string} root project root to scan
+ * @param {{ includeUserScope?: boolean, home?: string }} [options]
+ * @returns {{ root: string, files: ConfigFile[], gitignore: string|null, isGitRepo: boolean, skipped: string[] }}
+ */
+export function discover(root, options = {}) {
+  const includeUserScope = options.includeUserScope !== false;
+  const home = options.home ?? homedir();
+  /** @type {ConfigFile[]} */
+  const files = [];
+  const skipped = [];
+
+  const add = (path, kind, scope) => {
+    if (!existsSync(path)) return;
+    let stats;
+    try {
+      stats = statSync(path);
+    } catch {
+      return;
+    }
+    if (!stats.isFile()) return;
+    if (NEVER_READ.has(basename(path))) {
+      skipped.push(path);
+      return;
+    }
+    if (stats.size > MAX_FILE_BYTES) {
+      skipped.push(path);
+      return;
+    }
+    if (files.some((f) => f.path === path)) return;
+
+    let text;
+    try {
+      text = readFileSync(path, 'utf8');
+    } catch (error) {
+      skipped.push(path);
+      return;
+    }
+
+    /** @type {ConfigFile} */
+    const file = {
+      path,
+      display: displayPath(path, root, home),
+      kind,
+      scope,
+      text,
+      bytes: stats.size,
+      mode: stats.mode,
+      gid: stats.gid,
+      uid: stats.uid,
+    };
+
+    if (kind === 'settings' || kind === 'mcp' || kind === 'keybindings') {
+      try {
+        const parsed = parseJsonWithPositions(text);
+        file.data = parsed.value;
+        file.positions = parsed.positions;
+      } catch (error) {
+        if (error instanceof JsonSyntaxError) {
+          file.parseError = { message: error.message, line: error.line, column: error.column };
+        } else {
+          file.parseError = { message: String(error.message ?? error), line: 1, column: 1 };
+        }
+      }
+    } else if (kind === 'agent' || kind === 'skill' || kind === 'command') {
+      const fm = parseFrontmatter(text);
+      file.frontmatter = fm.frontmatter;
+      file.frontmatterLines = fm.frontmatterLines;
+      file.body = fm.body;
+    }
+
+    files.push(file);
+  };
+
+  // --- project scope -------------------------------------------------------
+  add(join(root, '.claude', 'settings.json'), 'settings', 'project');
+  add(join(root, '.claude', 'settings.local.json'), 'settings', 'local');
+  add(join(root, '.mcp.json'), 'mcp', 'project');
+  add(join(root, '.claude', 'keybindings.json'), 'keybindings', 'project');
+  addDirectory(join(root, '.claude', 'agents'), 'agent', 'project', add, '.md');
+  addDirectory(join(root, '.claude', 'commands'), 'command', 'project', add, '.md');
+  addSkills(join(root, '.claude', 'skills'), 'project', add);
+  addDirectory(join(root, '.claude', 'hooks'), 'hook', 'project', add, null);
+
+  for (const memory of findMemoryFiles(root)) {
+    add(memory, 'memory', memory.includes('.local.md') ? 'local' : 'project');
+  }
+
+  // --- user scope ----------------------------------------------------------
+  if (includeUserScope) {
+    const userClaude = join(home, '.claude');
+    add(join(userClaude, 'settings.json'), 'settings', 'user');
+    add(join(userClaude, 'keybindings.json'), 'keybindings', 'user');
+    add(join(userClaude, 'CLAUDE.md'), 'memory', 'user');
+    addDirectory(join(userClaude, 'agents'), 'agent', 'user', add, '.md');
+    addDirectory(join(userClaude, 'commands'), 'command', 'user', add, '.md');
+    addSkills(join(userClaude, 'skills'), 'user', add);
+    addDirectory(join(userClaude, 'hooks'), 'hook', 'user', add, null);
+    // Credential file is intentionally recorded as skipped, never read.
+    const cred = join(userClaude, '.credentials.json');
+    if (existsSync(cred)) skipped.push(cred);
+  }
+
+  let gitignore = null;
+  const gitignorePath = join(root, '.gitignore');
+  if (existsSync(gitignorePath)) {
+    try {
+      gitignore = readFileSync(gitignorePath, 'utf8');
+    } catch {
+      gitignore = null;
+    }
+  }
+
+  return {
+    root,
+    files,
+    gitignore,
+    isGitRepo: existsSync(join(root, '.git')),
+    skipped,
+  };
+}
+
+function addDirectory(dir, kind, scope, add, extension) {
+  if (!existsSync(dir)) return;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      // Namespaced subdirectories are supported for agents and commands.
+      if (kind === 'agent' || kind === 'command') {
+        addDirectory(join(dir, entry.name), kind, scope, add, extension);
+      }
+      continue;
+    }
+    if (extension && !entry.name.endsWith(extension)) continue;
+    add(join(dir, entry.name), kind, scope);
+  }
+}
+
+function addSkills(dir, scope, add) {
+  if (!existsSync(dir)) return;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    add(join(dir, entry.name, 'SKILL.md'), 'skill', scope);
+  }
+}
+
+/** Walks the project for CLAUDE.md files, which can live at any depth. */
+function findMemoryFiles(root, depth = 0) {
+  const found = [];
+  if (depth > MAX_WALK_DEPTH) return found;
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      if (entry.name.startsWith('.') && entry.name !== '.claude') continue;
+      found.push(...findMemoryFiles(join(root, entry.name), depth + 1));
+      continue;
+    }
+    if (entry.name === 'CLAUDE.md' || entry.name === 'CLAUDE.local.md' || entry.name === 'AGENTS.md') {
+      found.push(join(root, entry.name));
+    }
+  }
+  return found;
+}
+
+function displayPath(path, root, home) {
+  // Always forward slashes: display paths end up in JSON, in SARIF (whose
+  // artifact URIs must be URI-form) and in baseline fingerprints, so a
+  // baseline written on Windows has to match one written on Linux.
+  const toPosix = (value) => value.split(sep).join('/');
+  if (path.startsWith(root + sep)) return toPosix(relative(root, path));
+  if (path.startsWith(home + sep)) return `~/${toPosix(relative(home, path))}`;
+  return toPosix(path);
+}
+
+export { NEVER_READ, SKIP_DIRS };

package/src/engine.js

@@ -0,0 +1,218 @@
+import { createHash } from 'node:crypto';
+import { allRules } from './rules/index.js';
+import { ISSUES_URL } from './links.js';
+
+export const SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
+
+/**
+ * @typedef {Object} Finding
+ * @property {string} ruleId
+ * @property {'error'|'warning'|'info'} severity
+ * @property {string} category
+ * @property {string} message
+ * @property {string} [help]
+ * @property {string} file        absolute path
+ * @property {string} display     path shown to the user
+ * @property {number} line
+ * @property {number} [column]
+ * @property {string} [configPath]
+ * @property {string} [snippet]
+ */
+
+/**
+ * Runs every enabled rule over a discovered workspace.
+ *
+ * @param {import('./discover.js').discover extends (...a:any)=>infer R ? R : never} workspace
+ * @param {{ rules?: any[], disabled?: Set<string>|string[], minSeverity?: string,
+ *           severityOverrides?: Record<string,string>,
+ *           baseline?: Set<string> }} [options]
+ * @returns {{ findings: Finding[], ran: string[], suppressed: number }}
+ */
+export function lint(workspace, options = {}) {
+  const rules = options.rules ?? allRules;
+  const disabled = normalizeSet(options.disabled);
+  const severityOverrides = options.severityOverrides ?? {};
+  const baseline = options.baseline ?? new Set();
+
+  /** @type {Finding[]} */
+  const findings = [];
+  const ran = [];
+  let suppressed = 0;
+
+  const inlineDisables = collectInlineDisables(workspace);
+
+  for (const rule of rules) {
+    if (disabled.has(rule.id) || disabled.has(rule.category)) continue;
+    ran.push(rule.id);
+
+    const report = (finding) => {
+      const file = finding.file ?? {};
+      const severity = severityOverrides[rule.id] ?? finding.severity ?? rule.severity;
+      const entry = {
+        ruleId: rule.id,
+        severity,
+        category: rule.category,
+        message: finding.message,
+        help: finding.help ?? rule.help,
+        file: file.path ?? finding.absolutePath ?? workspace.root,
+        display: file.display ?? finding.display ?? '.',
+        line: finding.line ?? 1,
+        column: finding.column,
+        configPath: finding.configPath,
+        snippet: finding.snippet,
+      };
+
+      if (isInlineDisabled(inlineDisables, entry)) {
+        suppressed += 1;
+        return;
+      }
+      if (baseline.has(fingerprint(entry))) {
+        suppressed += 1;
+        return;
+      }
+      findings.push(entry);
+    };
+
+    try {
+      rule.check({ workspace, report, files: workspace.files, helpers });
+    } catch (error) {
+      findings.push({
+        ruleId: 'internal/rule-crashed',
+        severity: 'warning',
+        category: 'internal',
+        message: `Rule "${rule.id}" failed to run: ${error.message}`,
+        help: `This is a bug in agentdoctor. Please report it with the config that triggered it: ${ISSUES_URL}`,
+        file: workspace.root,
+        display: '.',
+        line: 1,
+      });
+    }
+  }
+
+  const minSeverity = options.minSeverity ?? 'info';
+  const cutoff = SEVERITY_ORDER[minSeverity] ?? 2;
+  const filtered = findings.filter((f) => (SEVERITY_ORDER[f.severity] ?? 2) <= cutoff);
+
+  filtered.sort((a, b) => {
+    const bySeverity = (SEVERITY_ORDER[a.severity] ?? 3) - (SEVERITY_ORDER[b.severity] ?? 3);
+    if (bySeverity !== 0) return bySeverity;
+    if (a.display !== b.display) return a.display.localeCompare(b.display);
+    if (a.line !== b.line) return a.line - b.line;
+    return a.ruleId.localeCompare(b.ruleId);
+  });
+
+  return { findings: filtered, ran, suppressed };
+}
+
+/**
+ * Stable identity for a finding, used by baselines and suppression.
+ *
+ * Anchored to the config path where one exists, and otherwise to a hash of the
+ * finding's own content. Line numbers are deliberately not part of the identity:
+ * a baseline that breaks because someone inserted a line further up the file is
+ * a baseline people stop trusting.
+ */
+export function fingerprint(finding) {
+  return `${finding.ruleId}::${finding.display}::${anchorOf(finding)}`;
+}
+
+/**
+ * Anchors are chosen most-stable first:
+ *
+ *  1. the offending value itself, when the rule captured one. Permission rules
+ *     live in arrays, so `permissions.allow[0]` changes meaning the moment
+ *     anyone inserts a rule above it — the rule text does not.
+ *  2. the config path, for structural findings that have no single value
+ *     (an empty deny list, a missing required key).
+ *  3. the message, for findings about a whole file.
+ *
+ * Line numbers are never used: an unrelated edit further up the file must not
+ * invalidate an accepted baseline.
+ */
+function anchorOf(finding) {
+  if (finding.snippet) return hash(finding.snippet);
+  if (finding.configPath) return finding.configPath;
+  return hash(finding.message ?? '');
+}
+
+const hash = (material) => createHash('sha1').update(String(material)).digest('hex').slice(0, 12);
+
+/** Helpers handed to every rule so rule code stays declarative. */
+export const helpers = {
+  /** Resolves the source position of a config path within a file. */
+  at(file, configPath) {
+    const positions = file.positions;
+    if (!positions) return { line: 1, column: 1 };
+    return positions.get(configPath) ?? positions.get(`${configPath} key`) ?? { line: 1, column: 1 };
+  },
+
+  /** Frontmatter key line number, for markdown-backed config. */
+  atFrontmatter(file, key) {
+    const lines = file.frontmatter?.__lines;
+    if (lines && lines[key]) return { line: lines[key], column: 1 };
+    return { line: 1, column: 1 };
+  },
+
+  byKind(files, ...kinds) {
+    const wanted = new Set(kinds);
+    return files.filter((f) => wanted.has(f.kind));
+  },
+
+  /** Reads a value out of parsed settings by dotted path. */
+  get(data, path) {
+    return path.split('.').reduce((acc, key) => (acc == null ? undefined : acc[key]), data);
+  },
+
+  /**
+   * Splits a permission rule into tool and argument matcher.
+   * "Bash(npm run *)" -> { tool: 'Bash', argument: 'npm run *' }
+   */
+  parsePermission(rule) {
+    if (typeof rule !== 'string') return { tool: null, argument: null, raw: rule };
+    const match = /^([A-Za-z_][A-Za-z0-9_-]*)\s*\((.*)\)\s*$/s.exec(rule.trim());
+    if (!match) return { tool: rule.trim(), argument: null, raw: rule };
+    return { tool: match[1], argument: match[2], raw: rule };
+  },
+
+  /**
+   * Rough token estimate. Deliberately conservative and dependency-free: the
+   * goal is an order-of-magnitude signal about context cost, not exact billing.
+   */
+  estimateTokens(text) {
+    if (!text) return 0;
+    const words = text.split(/\s+/).filter(Boolean).length;
+    const chars = text.length;
+    return Math.round(Math.max(chars / 4, words * 1.3));
+  },
+};
+
+function normalizeSet(value) {
+  if (!value) return new Set();
+  return value instanceof Set ? value : new Set(value);
+}
+
+/**
+ * Supports `agentdoctor-disable <rule-id>` comments in markdown and JSON
+ * config, scoped to the whole file.
+ */
+function collectInlineDisables(workspace) {
+  const map = new Map();
+  for (const file of workspace.files) {
+    const ids = new Set();
+    const pattern = /agentdoctor-disable(?:-file)?\s+([A-Za-z0-9/_,\s-]+)/g;
+    let match;
+    while ((match = pattern.exec(file.text)) !== null) {
+      for (const id of match[1].split(/[,\s]+/)) {
+        if (id) ids.add(id.trim());
+      }
+    }
+    if (ids.size) map.set(file.path, ids);
+  }
+  return map;
+}
+
+function isInlineDisabled(map, finding) {
+  const ids = map.get(finding.file);
+  if (!ids) return false;
+  return ids.has(finding.ruleId) || ids.has(finding.category) || ids.has('all');
+}

package/src/grade.js

@@ -0,0 +1,39 @@
+/**
+ * The health grade: one glanceable letter for a whole config audit.
+ *
+ * The formula is deliberately simple enough to state in a sentence, because a
+ * grade nobody can explain is a grade nobody trusts:
+ *
+ *   A+  zero findings
+ *   A   info only
+ *   B   no errors, 1-2 warnings
+ *   C   no errors, 3+ warnings
+ *   D   1-2 errors
+ *   F   3+ errors
+ *
+ * Grades are computed from the post-filter finding set, so a baseline or
+ * suppression that hides a finding also lifts the grade - the grade describes
+ * what is actionable today, not history.
+ */
+export function computeGrade(findings) {
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const warnings = findings.filter((f) => f.severity === 'warning').length;
+  if (errors >= 3) return 'F';
+  if (errors >= 1) return 'D';
+  if (warnings >= 3) return 'C';
+  if (warnings >= 1) return 'B';
+  if (findings.length > 0) return 'A';
+  return 'A+';
+}
+
+/** Badge color per grade, used by --badge and the share card. */
+export const GRADE_COLORS = {
+  'A+': '34D399', A: '34D399', B: 'A3E635', C: 'FBBF24', D: 'FB923C', F: 'F87171',
+};
+
+export function gradeSummary(findings) {
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const warnings = findings.filter((f) => f.severity === 'warning').length;
+  const info = findings.filter((f) => f.severity === 'info').length;
+  return { grade: computeGrade(findings), errors, warnings, info };
+}

package/src/index.js

@@ -0,0 +1,42 @@
+import { discover } from './discover.js';
+import { lint, fingerprint, helpers } from './engine.js';
+import { allRules, CATEGORIES } from './rules/index.js';
+import { loadPolicy } from './rules/policy.js';
+
+export const VERSION = '0.1.0';
+
+/**
+ * One-call entry point: discover config, load any team policy, run every rule.
+ *
+ * @param {string} root
+ * @param {{ includeUserScope?: boolean, policyPath?: string,
+ *           disabled?: string[], minSeverity?: string, baseline?: Set<string>,
+ *           only?: string[], home?: string }} [options]
+ */
+export function run(root, options = {}) {
+  const started = process.hrtime.bigint();
+  const workspace = discover(root, {
+    includeUserScope: options.includeUserScope,
+    home: options.home,
+  });
+
+  workspace.policy = loadPolicy(root, options.policyPath);
+
+  let rules = allRules;
+  if (options.only && options.only.length > 0) {
+    const wanted = new Set(options.only);
+    rules = rules.filter((rule) => wanted.has(rule.category) || wanted.has(rule.id));
+  }
+
+  const result = lint(workspace, {
+    rules,
+    disabled: options.disabled,
+    minSeverity: options.minSeverity,
+    baseline: options.baseline,
+  });
+
+  const elapsedMs = Number((process.hrtime.bigint() - started) / 1_000_000n);
+  return { ...result, workspace, elapsedMs, version: VERSION };
+}
+
+export { discover, lint, fingerprint, helpers, allRules, CATEGORIES, loadPolicy };

package/src/links.js

@@ -0,0 +1,9 @@
+/**
+ * Every outbound URL the tool prints, in one place.
+ *
+ * These are placeholders until the repository and sales page exist. Set them
+ * once here before publishing; nothing else references a URL directly.
+ */
+export const REPO_URL = 'https://github.com/jqntn/agentdoctor';
+export const ISSUES_URL = 'https://github.com/jqntn/agentdoctor/issues';
+export const BADGE_BASE_URL = 'https://img.shields.io/badge';