@jqntn/agentdoctor 0.1.0

package/src/parse.js

@@ -0,0 +1,318 @@
+/**
+ * Tolerant JSON parsing that records the source position of every value.
+ *
+ * Findings are only actionable if they point at a line, so the whole rule
+ * engine is built on top of position-aware parses rather than JSON.parse.
+ */
+
+const WHITESPACE = new Set([' ', '\t', '\n', '\r']);
+
+class JsonSyntaxError extends Error {
+  constructor(message, line, column) {
+    super(`${message} (line ${line}, column ${column})`);
+    this.name = 'JsonSyntaxError';
+    this.line = line;
+    this.column = column;
+  }
+}
+
+/**
+ * @param {string} text
+ * @returns {{ value: unknown, positions: Map<string, {line:number, column:number}> }}
+ */
+export function parseJsonWithPositions(text) {
+  const positions = new Map();
+  let i = 0;
+  let line = 1;
+  let lineStart = 0;
+
+  const column = () => i - lineStart + 1;
+  const here = () => ({ line, column: column() });
+
+  const fail = (msg) => {
+    throw new JsonSyntaxError(msg, line, column());
+  };
+
+  function advance(n = 1) {
+    for (let k = 0; k < n; k += 1) {
+      if (text[i] === '\n') {
+        line += 1;
+        lineStart = i + 1;
+      }
+      i += 1;
+    }
+  }
+
+  function skipWhitespace() {
+    while (i < text.length) {
+      const ch = text[i];
+      if (WHITESPACE.has(ch)) {
+        advance();
+        continue;
+      }
+      // Comments are invalid JSON but common in hand-edited config; skip them
+      // so a stray comment yields real findings instead of one parse error.
+      if (ch === '/' && text[i + 1] === '/') {
+        while (i < text.length && text[i] !== '\n') advance();
+        continue;
+      }
+      if (ch === '/' && text[i + 1] === '*') {
+        advance(2);
+        while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) advance();
+        advance(2);
+        continue;
+      }
+      return;
+    }
+  }
+
+  function parseString() {
+    if (text[i] !== '"') fail('Expected a string');
+    advance();
+    let out = '';
+    while (i < text.length && text[i] !== '"') {
+      if (text[i] === '\\') {
+        advance();
+        const esc = text[i];
+        if (esc === undefined) fail('Unterminated escape sequence');
+        if (esc === 'u') {
+          const hex = text.slice(i + 1, i + 5);
+          if (!/^[0-9a-fA-F]{4}$/.test(hex)) fail('Invalid unicode escape');
+          out += String.fromCharCode(parseInt(hex, 16));
+          advance(5);
+          continue;
+        }
+        const simple = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' };
+        if (!(esc in simple)) fail('Invalid escape character \\' + esc);
+        out += simple[esc];
+        advance();
+        continue;
+      }
+      out += text[i];
+      advance();
+    }
+    if (text[i] !== '"') fail('Unterminated string');
+    advance();
+    return out;
+  }
+
+  function parseNumber() {
+    const start = i;
+    if (text[i] === '-') advance();
+    while (i < text.length && /[0-9]/.test(text[i])) advance();
+    if (text[i] === '.') {
+      advance();
+      while (i < text.length && /[0-9]/.test(text[i])) advance();
+    }
+    if (text[i] === 'e' || text[i] === 'E') {
+      advance();
+      if (text[i] === '+' || text[i] === '-') advance();
+      while (i < text.length && /[0-9]/.test(text[i])) advance();
+    }
+    const raw = text.slice(start, i);
+    const num = Number(raw);
+    if (raw === '' || !Number.isFinite(num)) fail('Invalid number "' + raw + '"');
+    return num;
+  }
+
+  function parseLiteral() {
+    for (const [word, value] of [['true', true], ['false', false], ['null', null]]) {
+      if (text.startsWith(word, i)) {
+        advance(word.length);
+        return value;
+      }
+    }
+    return fail('Unexpected token "' + (text[i] ?? 'EOF') + '"');
+  }
+
+  function parseValue(path) {
+    skipWhitespace();
+    positions.set(path, here());
+    const ch = text[i];
+    if (ch === '{') return parseObject(path);
+    if (ch === '[') return parseArray(path);
+    if (ch === '"') return parseString();
+    if (ch === '-' || (ch >= '0' && ch <= '9')) return parseNumber();
+    return parseLiteral();
+  }
+
+  function parseObject(path) {
+    advance(); // {
+    const out = {};
+    skipWhitespace();
+    if (text[i] === '}') {
+      advance();
+      return out;
+    }
+    for (;;) {
+      skipWhitespace();
+      const keyPos = here();
+      const key = parseString();
+      const childPath = path ? path + '.' + key : key;
+      positions.set(childPath + ' key', keyPos);
+      skipWhitespace();
+      if (text[i] !== ':') fail('Expected ":" after key "' + key + '"');
+      advance();
+      out[key] = parseValue(childPath);
+      skipWhitespace();
+      if (text[i] === ',') {
+        advance();
+        skipWhitespace();
+        if (text[i] === '}') { advance(); return out; } // tolerate trailing comma
+        continue;
+      }
+      if (text[i] === '}') {
+        advance();
+        return out;
+      }
+      fail('Expected "," or "}" in object');
+    }
+  }
+
+  function parseArray(path) {
+    advance(); // [
+    const out = [];
+    skipWhitespace();
+    if (text[i] === ']') {
+      advance();
+      return out;
+    }
+    for (;;) {
+      out.push(parseValue(path + '[' + out.length + ']'));
+      skipWhitespace();
+      if (text[i] === ',') {
+        advance();
+        skipWhitespace();
+        if (text[i] === ']') { advance(); return out; } // tolerate trailing comma
+        continue;
+      }
+      if (text[i] === ']') {
+        advance();
+        return out;
+      }
+      fail('Expected "," or "]" in array');
+    }
+  }
+
+  skipWhitespace();
+  if (i >= text.length) throw new JsonSyntaxError('File is empty', 1, 1);
+  const value = parseValue('');
+  skipWhitespace();
+  if (i < text.length) fail('Unexpected trailing content after top-level value');
+  return { value, positions };
+}
+
+/**
+ * Splits YAML-ish frontmatter off a markdown file. Agent and skill definitions
+ * carry their config in frontmatter, so this is the entry point for both.
+ *
+ * @param {string} text
+ * @returns {{ frontmatter: Record<string, unknown>|null, frontmatterLines: number, body: string, raw: string|null }}
+ */
+export function parseFrontmatter(text) {
+  const normalized = text.replace(/^\uFEFF/, '');
+  if (!/^---\r?\n/.test(normalized)) {
+    return { frontmatter: null, frontmatterLines: 0, body: normalized, raw: null };
+  }
+  const lines = normalized.split(/\r?\n/);
+  let end = -1;
+  for (let n = 1; n < lines.length; n += 1) {
+    if (lines[n].trim() === '---') {
+      end = n;
+      break;
+    }
+  }
+  if (end === -1) {
+    return { frontmatter: null, frontmatterLines: 0, body: normalized, raw: null };
+  }
+  const raw = lines.slice(1, end);
+  return {
+    frontmatter: parseSimpleYaml(raw),
+    frontmatterLines: end + 1,
+    body: lines.slice(end + 1).join('\n'),
+    raw: raw.join('\n'),
+  };
+}
+
+/**
+ * Deliberately small YAML subset: scalars, inline lists, dash lists and one
+ * level of nesting. That covers every documented agent/skill frontmatter field
+ * without taking on a YAML dependency in a security tool.
+ */
+export function parseSimpleYaml(lines) {
+  const root = {};
+  const lineOf = {};
+  let currentKey = null;
+  let listTarget = null;
+  let nested = null;
+  let nestedIndent = 0;
+
+  lines.forEach((rawLine, index) => {
+    const line = rawLine.replace(/\s+$/, '');
+    if (!line.trim() || line.trim().startsWith('#')) return;
+    const indent = line.length - line.trimStart().length;
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('- ')) {
+      const item = stripQuotes(trimmed.slice(2).trim());
+      if (nested && listTarget && nested[listTarget] !== undefined) {
+        if (!Array.isArray(nested[listTarget])) nested[listTarget] = [];
+        nested[listTarget].push(item);
+      } else if (currentKey) {
+        if (!Array.isArray(root[currentKey])) root[currentKey] = [];
+        root[currentKey].push(item);
+      }
+      return;
+    }
+
+    const match = /^([A-Za-z0-9_.-]+)\s*:\s*(.*)$/.exec(trimmed);
+    if (!match) return;
+    const key = match[1];
+    const rest = match[2];
+
+    if (indent > 0 && nested && indent >= nestedIndent) {
+      nested[key] = rest === '' ? {} : coerceScalar(rest);
+      listTarget = rest === '' ? key : null;
+      return;
+    }
+
+    lineOf[key] = index + 2; // +1 for the opening ---, +1 for 1-based lines
+    if (rest === '') {
+      root[key] = {};
+      nested = root[key];
+      nestedIndent = indent + 1;
+      currentKey = key;
+      listTarget = null;
+      return;
+    }
+    root[key] = coerceScalar(rest);
+    nested = null;
+    currentKey = key;
+    listTarget = null;
+  });
+
+  Object.defineProperty(root, '__lines', { value: lineOf, enumerable: false });
+  return root;
+}
+
+function stripQuotes(value) {
+  if (value.length >= 2 && ((value[0] === '"' && value.at(-1) === '"') || (value[0] === "'" && value.at(-1) === "'"))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function coerceScalar(rest) {
+  const value = stripQuotes(rest.trim());
+  if (value.startsWith('[') && value.endsWith(']')) {
+    const inner = value.slice(1, -1).trim();
+    if (!inner) return [];
+    return inner.split(',').map((part) => stripQuotes(part.trim()));
+  }
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value !== '' && !Number.isNaN(Number(value)) && /^-?[0-9.]+$/.test(value)) return Number(value);
+  return value;
+}
+
+export { JsonSyntaxError };

package/src/report/json.js

@@ -0,0 +1,36 @@
+import { computeGrade } from '../grade.js';
+
+/** Machine-readable report. Stable shape - treat additions as the only change. */
+export function renderJson(input) {
+  return JSON.stringify({
+    version: 1,
+    tool: 'agentdoctor',
+    toolVersion: input.version,
+    root: input.workspace.root,
+    scannedFiles: input.workspace.files.map((f) => ({
+      path: f.display, kind: f.kind, scope: f.scope, bytes: f.bytes,
+    })),
+    skippedFiles: input.workspace.skipped ?? [],
+    rulesRun: input.ran,
+    suppressed: input.suppressed,
+    grade: computeGrade(input.findings),
+    summary: {
+      error: input.findings.filter((f) => f.severity === 'error').length,
+      warning: input.findings.filter((f) => f.severity === 'warning').length,
+      info: input.findings.filter((f) => f.severity === 'info').length,
+    },
+    findings: input.findings.map((f) => ({
+      ruleId: f.ruleId,
+      severity: f.severity,
+      category: f.category,
+      message: f.message,
+      help: f.help ?? null,
+      file: f.display,
+      absolutePath: f.file,
+      line: f.line,
+      column: f.column ?? null,
+      configPath: f.configPath ?? null,
+      snippet: f.snippet ?? null,
+    })),
+  }, null, 2);
+}

package/src/report/sarif.js

@@ -0,0 +1,68 @@
+import { relative, isAbsolute } from 'node:path';
+import { allRules } from '../rules/index.js';
+import { REPO_URL } from '../links.js';
+
+const SARIF_LEVEL = { error: 'error', warning: 'warning', info: 'note' };
+
+/**
+ * SARIF 2.1.0 output, so findings surface as annotations in GitHub code
+ * scanning and any other SARIF-aware CI without extra glue.
+ */
+export function renderSarif(input) {
+  const usedRuleIds = [...new Set(input.findings.map((f) => f.ruleId))];
+  const ruleIndex = new Map();
+  const rules = usedRuleIds.map((id, index) => {
+    ruleIndex.set(id, index);
+    const rule = allRules.find((r) => r.id === id);
+    return {
+      id,
+      name: id.replace(/[^A-Za-z0-9]/g, '_'),
+      shortDescription: { text: rule?.title ?? id },
+      fullDescription: { text: rule?.help ?? rule?.title ?? id },
+      help: { text: rule?.help ?? '' },
+      defaultConfiguration: { level: SARIF_LEVEL[rule?.severity ?? 'warning'] ?? 'warning' },
+      properties: { category: rule?.category ?? 'other', tags: [rule?.category ?? 'other', 'agentdoctor'] },
+    };
+  });
+
+  return JSON.stringify({
+    $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'agentdoctor',
+          version: input.version,
+          informationUri: REPO_URL,
+          rules,
+        },
+      },
+      results: input.findings.map((finding) => ({
+        ruleId: finding.ruleId,
+        ruleIndex: ruleIndex.get(finding.ruleId),
+        level: SARIF_LEVEL[finding.severity] ?? 'warning',
+        message: { text: finding.help ? `${finding.message} ${finding.help}` : finding.message },
+        locations: [{
+          physicalLocation: {
+            artifactLocation: { uri: toUri(finding.file, input.workspace.root) },
+            region: {
+              startLine: Math.max(1, finding.line),
+              ...(finding.column ? { startColumn: finding.column } : {}),
+            },
+          },
+        }],
+        partialFingerprints: {
+          agentdoctorFingerprint: `${finding.ruleId}:${finding.display}:${finding.configPath ?? finding.line}`,
+        },
+      })),
+    }],
+  }, null, 2);
+}
+
+function toUri(absolutePath, root) {
+  if (!isAbsolute(absolutePath)) return absolutePath;
+  const rel = relative(root, absolutePath);
+  // Paths outside the repo (user-scope config) have no meaningful CI location;
+  // keep a short suffix rather than leaking an absolute home directory.
+  return rel.startsWith('..') ? absolutePath.split('/').slice(-3).join('/') : rel;
+}

package/src/report/terminal.js

@@ -0,0 +1,135 @@
+import { SEVERITY_ORDER } from '../engine.js';
+import { computeGrade } from '../grade.js';
+
+/**
+ * Control Sequence Introducer, built from a char code so this source file
+ * stays pure ASCII and survives copy-paste through any pipeline.
+ */
+const CSI = String.fromCharCode(27) + '[';
+
+/** ANSI helpers that no-op when colour is unwanted. */
+export function makeStyle(enabled) {
+  const wrap = (open, close) => (text) => (enabled ? `${CSI}${open}m${text}${CSI}${close}m` : String(text));
+  return {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    red: wrap(31, 39),
+    yellow: wrap(33, 39),
+    blue: wrap(34, 39),
+    cyan: wrap(36, 39),
+    green: wrap(32, 39),
+    magenta: wrap(35, 39),
+    underline: wrap(4, 24),
+  };
+}
+
+export function shouldUseColor(stream = process.stdout, env = process.env) {
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return false;
+  if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '0') return true;
+  if (env.CI && !env.GITHUB_ACTIONS) return false;
+  return Boolean(stream.isTTY);
+}
+
+const SEVERITY_LABEL = {
+  error: (s) => s.red('error'),
+  warning: (s) => s.yellow('warn '),
+  info: (s) => s.blue('info '),
+};
+
+/**
+ * Renders a human-readable report.
+ *
+ * @param {{ findings: any[], workspace: any, ran: string[], suppressed: number,
+ *           elapsedMs: number, color?: boolean }} input
+ * @returns {string}
+ */
+export function renderTerminal(input) {
+  const s = makeStyle(input.color !== false);
+  const { findings, workspace } = input;
+  const out = [];
+
+  const counts = { error: 0, warning: 0, info: 0 };
+  for (const finding of findings) counts[finding.severity] = (counts[finding.severity] ?? 0) + 1;
+
+  const fileWord = workspace.files.length === 1 ? 'config file' : 'config files';
+  out.push('');
+  out.push(`${s.bold('agentdoctor')} ${s.dim(`scanned ${workspace.files.length} ${fileWord} in ${workspace.root}`)}`);
+  out.push('');
+
+  if (findings.length === 0) {
+    out.push(`  ${s.green('OK')}  No problems found.`);
+    out.push('');
+    out.push(summaryLine(s, counts, input));
+    return out.join('\n');
+  }
+
+  // Group by file so the reader fixes one file at a time.
+  const byFile = new Map();
+  for (const finding of findings) {
+    if (!byFile.has(finding.display)) byFile.set(finding.display, []);
+    byFile.get(finding.display).push(finding);
+  }
+
+  const indent = ' '.repeat(17);
+  for (const [display, group] of byFile) {
+    out.push(s.underline(s.bold(display)));
+    group.sort((a, b) => (SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]) || (a.line - b.line));
+    for (const finding of group) {
+      const raw = `${finding.line}${finding.column ? `:${finding.column}` : ''}`;
+      const location = s.dim(raw) + ' '.repeat(Math.max(1, 8 - raw.length));
+      const label = (SEVERITY_LABEL[finding.severity] ?? SEVERITY_LABEL.info)(s);
+      out.push(`  ${location}${label}  ${finding.message}`);
+      if (finding.snippet) out.push(`${indent}${s.dim('|')} ${s.cyan(finding.snippet)}`);
+      if (finding.help) {
+        for (const line of wrapText(finding.help, 76)) out.push(`${indent}${s.dim(line)}`);
+      }
+      out.push(`${indent}${s.dim(s.magenta(finding.ruleId))}`);
+      out.push('');
+    }
+  }
+
+  out.push(summaryLine(s, counts, input));
+  return out.join('\n');
+}
+
+/** Soft-wraps help text so long guidance stays readable in a narrow terminal. */
+function wrapText(text, width) {
+  const words = String(text).split(/\s+/);
+  const lines = [];
+  let current = '';
+  for (const word of words) {
+    if (current === '') {
+      current = word;
+    } else if (current.length + 1 + word.length > width) {
+      lines.push(current);
+      current = word;
+    } else {
+      current += ` ${word}`;
+    }
+  }
+  if (current) lines.push(current);
+  return lines.map((line, index) => (index === 0 ? `-> ${line}` : `   ${line}`));
+}
+
+function summaryLine(s, counts, input) {
+  const lines = [];
+  const parts = [];
+  if (counts.error) parts.push(s.red(`${counts.error} error${counts.error === 1 ? '' : 's'}`));
+  if (counts.warning) parts.push(s.yellow(`${counts.warning} warning${counts.warning === 1 ? '' : 's'}`));
+  if (counts.info) parts.push(s.blue(`${counts.info} info`));
+  const summary = parts.length ? parts.join(', ') : s.green('clean');
+  const grade = computeGrade(input.findings);
+  const gradeColor = grade.startsWith('A') ? s.green : (grade === 'B' || grade === 'C' ? s.yellow : s.red);
+  lines.push(`${s.bold('Summary')}  ${s.bold(gradeColor(`Grade ${grade}`))}  ${summary}  ${s.dim(`- ${input.ran.length} rules in ${input.elapsedMs}ms`)}`);
+
+  if (input.suppressed > 0) {
+    const word = input.suppressed === 1 ? 'finding' : 'findings';
+    lines.push(s.dim(`         ${input.suppressed} ${word} suppressed by baseline or inline comment`));
+  }
+  const skipped = input.workspace.skipped ?? [];
+  if (skipped.length > 0) {
+    lines.push(s.dim(`         ${skipped.length} file(s) skipped - credential files are never read`));
+  }
+  lines.push(s.dim(`         Share the grade: agentdoctor --share  -  gate it in CI: agentdoctor --init-ci`));
+  return lines.join('\n');
+}