@praneeth_54/agentdoctor 0.3.0-beta → 1.1.0

package/dist/reporters/github/annotations.js

@@ -0,0 +1,42 @@
+/**
+ * GitHub Actions workflow commands for file annotations.
+ * Emitted to stderr so `--json` stdout stays pure JSON.
+ *
+ * @see https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+ */
+export function renderGithubAnnotations(findings) {
+    const lines = [];
+    for (const finding of findings) {
+        lines.push(formatAnnotation(finding));
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+function formatAnnotation(finding) {
+    const level = annotationLevel(finding.severity);
+    const properties = [];
+    const file = finding.evidence?.path?.replace(/\\/g, "/");
+    if (file) {
+        properties.push(`file=${escapeProperty(file)}`);
+    }
+    if (finding.evidence?.line !== undefined && Number.isFinite(finding.evidence.line)) {
+        properties.push(`line=${finding.evidence.line}`);
+    }
+    properties.push(`title=${escapeProperty(`${finding.ruleId}: ${finding.title}`)}`);
+    const message = escapeMessage(`${finding.message} (${finding.ruleId})`);
+    const props = properties.length > 0 ? ` ${properties.join(",")}` : "";
+    return `::${level}${props}::${message}`;
+}
+function annotationLevel(severity) {
+    return severity === "critical" ? "error" : severity === "warning" ? "warning" : "notice";
+}
+function escapeProperty(value) {
+    return value
+        .replace(/%/g, "%25")
+        .replace(/\r/g, "%0D")
+        .replace(/\n/g, "%0A")
+        .replace(/:/g, "%3A")
+        .replace(/,/g, "%2C");
+}
+function escapeMessage(value) {
+    return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}

package/dist/reporters/github/emit.d.ts

@@ -0,0 +1,23 @@
+import type { PolicyViolation } from "../../core/policy/evaluate.js";
+import type { Finding } from "../../types/index.js";
+export interface GithubReportOptions {
+    summary?: boolean;
+    annotations?: boolean;
+}
+export declare function emitGithubReports(options: {
+    mode: "scan" | "verify";
+    findings: Finding[];
+    overallScore: number | null;
+    violations: PolicyViolation[];
+    verifySummary?: {
+        fixed: number;
+        remaining: number;
+        new: number;
+        unchanged: number;
+    };
+    summary?: boolean;
+    annotations?: boolean;
+    /** Override for tests */
+    stepSummaryPath?: string | null;
+    annotationsWrite?: (text: string) => void;
+}): Promise<void>;

package/dist/reporters/github/emit.js

@@ -0,0 +1,31 @@
+import fs from "node:fs/promises";
+import { renderGithubAnnotations } from "./annotations.js";
+import { renderGithubStepSummary } from "./summary.js";
+export async function emitGithubReports(options) {
+    if (options.annotations) {
+        const text = renderGithubAnnotations(options.findings);
+        if (text.length > 0) {
+            const write = options.annotationsWrite ?? ((chunk) => process.stderr.write(chunk));
+            write(text);
+        }
+    }
+    if (!options.summary) {
+        return;
+    }
+    const markdown = renderGithubStepSummary({
+        title: options.mode === "verify" ? "AgentDoctor Verify" : "AgentDoctor Scan",
+        overallScore: options.overallScore,
+        findings: options.findings,
+        violations: options.violations,
+        mode: options.mode,
+        ...(options.verifySummary ? { verifySummary: options.verifySummary } : {}),
+    });
+    const summaryPath = options.stepSummaryPath !== undefined
+        ? options.stepSummaryPath
+        : (process.env.GITHUB_STEP_SUMMARY ?? null);
+    if (summaryPath) {
+        await fs.appendFile(summaryPath, markdown, "utf8");
+        return;
+    }
+    process.stderr.write("Note: --summary set but GITHUB_STEP_SUMMARY is unset; skipping step summary write.\n");
+}

package/dist/reporters/github/summary.d.ts

@@ -0,0 +1,20 @@
+import type { Finding, ScanResult } from "../../types/index.js";
+import type { PolicyViolation } from "../../core/policy/evaluate.js";
+export interface GithubSummaryInput {
+    title: string;
+    overallScore: number | null;
+    findings: Finding[];
+    violations: PolicyViolation[];
+    mode: "scan" | "verify";
+    verifySummary?: {
+        fixed: number;
+        remaining: number;
+        new: number;
+        unchanged: number;
+    };
+}
+/**
+ * Markdown for `$GITHUB_STEP_SUMMARY`.
+ */
+export declare function renderGithubStepSummary(input: GithubSummaryInput): string;
+export declare function renderGithubStepSummaryForScan(result: ScanResult, violations: PolicyViolation[]): string;

package/dist/reporters/github/summary.js

@@ -0,0 +1,111 @@
+/**
+ * Markdown for `$GITHUB_STEP_SUMMARY`.
+ */
+export function renderGithubStepSummary(input) {
+    const lines = [];
+    lines.push(`# AgentDoctor ${input.mode === "verify" ? "Verify" : "Scan"}`);
+    lines.push("");
+    if (input.overallScore !== null) {
+        lines.push(`**Readiness:** ${input.overallScore}/100`);
+        lines.push("");
+    }
+    if (input.violations.length > 0) {
+        lines.push("## Policy violations");
+        lines.push("");
+        for (const violation of input.violations) {
+            lines.push(`- ${violation.message}`);
+        }
+        lines.push("");
+    }
+    else {
+        lines.push("Policy gates: **passed**");
+        lines.push("");
+    }
+    if (input.verifySummary) {
+        lines.push("## Verify delta");
+        lines.push("");
+        lines.push(`| Fixed | Remaining | New | Unchanged |`);
+        lines.push(`| ---: | ---: | ---: | ---: |`);
+        lines.push(`| ${input.verifySummary.fixed} | ${input.verifySummary.remaining} | ${input.verifySummary.new} | ${input.verifySummary.unchanged} |`);
+        lines.push("");
+    }
+    const critical = input.findings.filter((f) => f.severity === "critical").length;
+    const warning = input.findings.filter((f) => f.severity === "warning").length;
+    const info = input.findings.filter((f) => f.severity === "info").length;
+    lines.push("## Findings");
+    lines.push("");
+    lines.push(`| Severity | Count |`);
+    lines.push(`| --- | ---: |`);
+    lines.push(`| Critical | ${critical} |`);
+    lines.push(`| Warning | ${warning} |`);
+    lines.push(`| Info | ${info} |`);
+    lines.push(`| **Total** | **${input.findings.length}** |`);
+    lines.push("");
+    if (input.findings.length > 0) {
+        lines.push("### Top findings");
+        lines.push("");
+        const top = [...input.findings]
+            .sort((a, b) => severityOrder(b.severity) - severityOrder(a.severity))
+            .slice(0, 20);
+        for (const finding of top) {
+            const path = finding.evidence?.path ? ` \`${finding.evidence.path}\`` : "";
+            lines.push(`- **${finding.severity}** \`${finding.ruleId}\`${path} — ${finding.title}`);
+        }
+        lines.push("");
+    }
+    if (input.violations.length > 0) {
+        lines.push(...renderGithubNextSteps(input));
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Shortest path back to green when the Action failed a policy gate.
+ * Shown only on failure — success summaries stay quiet.
+ */
+function renderGithubNextSteps(input) {
+    const lines = [];
+    lines.push("## Next");
+    lines.push("");
+    lines.push("Policy gate failed. Shortest path back to green:");
+    lines.push("");
+    const hasSafe = input.findings.some((f) => f.fixability === "safe");
+    const topRule = [...input.findings].sort((a, b) => severityOrder(b.severity) - severityOrder(a.severity))[0]?.ruleId;
+    if (input.mode === "verify") {
+        lines.push("1. Reproduce locally: `npx @praneeth_54/agentdoctor verify`");
+        if (hasSafe) {
+            lines.push("2. Apply safe fixes: `npx @praneeth_54/agentdoctor fix -y`");
+            lines.push("3. Re-check: `npx @praneeth_54/agentdoctor verify`");
+        }
+        else {
+            lines.push(`2. Inspect a finding: \`npx @praneeth_54/agentdoctor explain ${topRule ?? "<rule-id>"}\``);
+            lines.push("3. Fix or baseline, then re-run this Action");
+        }
+    }
+    else {
+        lines.push("1. Reproduce locally: `npx @praneeth_54/agentdoctor scan --ci`");
+        if (hasSafe) {
+            lines.push("2. Apply safe fixes: `npx @praneeth_54/agentdoctor fix -y`");
+            lines.push("3. Confirm: `npx @praneeth_54/agentdoctor scan --ci`");
+        }
+        else {
+            lines.push(`2. Inspect a finding: \`npx @praneeth_54/agentdoctor explain ${topRule ?? "<rule-id>"}\``);
+            lines.push("3. Fix the gated findings, then re-run this Action");
+        }
+    }
+    lines.push("");
+    lines.push("Preview before applying: `npx @praneeth_54/agentdoctor fix --dry-run`");
+    lines.push("");
+    return lines;
+}
+export function renderGithubStepSummaryForScan(result, violations) {
+    return renderGithubStepSummary({
+        title: "AgentDoctor Scan",
+        overallScore: result.scores?.overall ?? null,
+        findings: result.findings,
+        violations,
+        mode: "scan",
+    });
+}
+function severityOrder(severity) {
+    return severity === "critical" ? 3 : severity === "warning" ? 2 : 1;
+}

package/dist/reporters/terminal/report.d.ts

@@ -2,6 +2,11 @@ import type { ScanResult } from "../../types/index.js";
 export interface TerminalReportOptions {
     verbose?: boolean;
 }
+/**
+ * Close the Scan → Fix → Verify loop on first run.
+ * Empty / agentless scans already print a Next line; findings used to dead-end.
+ */
+export declare function renderNextSteps(result: ScanResult): string[];
 /**
  * Terminal report: agents and actionable findings.
  */

package/dist/reporters/terminal/report.js

@@ -42,7 +42,12 @@ function renderFindingBlock(finding, verbose) {
         : finding.severity === "warning"
             ? symbolWarn()
             : symbolInfo();
-    lines.push(`  ${icon} ${sanitizeTerminalText(finding.title)}`);
+    const fixTag = finding.fixability === "safe"
+        ? colors.green("[safe]")
+        : finding.fixability === "review"
+            ? colors.yellow("[review]")
+            : colors.dim("[manual]");
+    lines.push(`  ${icon} ${fixTag} ${sanitizeTerminalText(finding.title)}`);
     if (finding.evidence?.path) {
         lines.push(colors.dim(`    ${sanitizeTerminalText(finding.evidence.path)}`));
     }
@@ -59,6 +64,50 @@ function renderFindingBlock(finding, verbose) {
     lines.push("");
     return lines;
 }
+function countByFixability(findings) {
+    let safe = 0;
+    let review = 0;
+    let manual = 0;
+    for (const finding of findings) {
+        if (finding.fixability === "safe") {
+            safe += 1;
+        }
+        else if (finding.fixability === "review") {
+            review += 1;
+        }
+        else {
+            manual += 1;
+        }
+    }
+    return { safe, review, manual };
+}
+/**
+ * Close the Scan → Fix → Verify loop on first run.
+ * Empty / agentless scans already print a Next line; findings used to dead-end.
+ */
+export function renderNextSteps(result) {
+    const lines = [];
+    const total = result.summary.total;
+    if (total === 0) {
+        return lines;
+    }
+    const { safe, review, manual } = countByFixability(result.findings);
+    const reviewLike = review + manual;
+    lines.push(colors.bold("Next"));
+    lines.push("");
+    if (safe > 0) {
+        lines.push(`  ${safe} finding(s) are auto-fixable. Preview: ${colors.bold("agentdoctor fix --dry-run")}`);
+        lines.push(`  Apply: ${colors.bold("agentdoctor fix -y")}`);
+    }
+    else if (reviewLike > 0) {
+        lines.push(`  ${reviewLike} finding(s) need review or manual action — ${colors.bold("agentdoctor fix")} will not change them automatically.`);
+        lines.push(colors.dim("  Inspect a rule: agentdoctor explain <rule-id>  (ids are in --json output)"));
+    }
+    lines.push(colors.dim("  Save a verify baseline: agentdoctor scan --json > agentdoctor-report.json"));
+    lines.push(colors.dim("  After changes: agentdoctor verify --baseline agentdoctor-report.json"));
+    lines.push("");
+    return lines;
+}
 /**
  * Terminal report: agents and actionable findings.
  */
@@ -115,7 +164,10 @@ export function renderTerminalReport(result, options = {}) {
     }
     if (total === 0) {
         if (limited) {
-            lines.push(`  ${symbolOk()} No agent-configuration findings`);
+            lines.push(`  ${symbolWarn()} Nothing to audit yet — no Cursor, Claude Code, or Codex config found`);
+            lines.push("");
+            lines.push(colors.dim("  Next: add project agent config (for example `.cursor/`, `CLAUDE.md` / `.claude/`, or `AGENTS.md`),"));
+            lines.push(colors.dim("  then re-run `agentdoctor` in this repository."));
         }
         else {
             lines.push(`  ${symbolOk()} No findings`);
@@ -149,7 +201,7 @@ export function renderTerminalReport(result, options = {}) {
             }
         }
         if (total > shown) {
-            lines.push(colors.dim(`  … and ${total - shown} more. Re-run with --verbose to see additional detail.`));
+            lines.push(colors.dim(`  … and ${total - shown} more. Re-run with --verbose for detail, or --json for the full list.`));
             lines.push("");
         }
     }
@@ -158,15 +210,26 @@ export function renderTerminalReport(result, options = {}) {
     lines.push(`  ${result.summary.critical} critical`);
     lines.push(`  ${result.summary.warning} warning`);
     lines.push(`  ${result.summary.info} info`);
+    if (total > 0) {
+        const { safe, review, manual } = countByFixability(result.findings);
+        lines.push(colors.dim(`  Fixability: ${safe} safe · ${review} review · ${manual} manual`));
+    }
     lines.push("");
     if (result.scoringAvailable && result.scores) {
-        lines.push(`  Readiness: ${result.scores.overall}/100`);
-        lines.push(colors.dim("  Category and agent scores: agentdoctor scan --json"));
+        if (limited) {
+            lines.push(`  Readiness: n/a — configure Cursor, Claude Code, or Codex before treating scores as agent readiness`);
+            lines.push(colors.dim(`  Numeric scores remain in JSON (overall ${result.scores.overall}/100) for repository-risk findings only`));
+        }
+        else {
+            lines.push(`  Readiness: ${result.scores.overall}/100`);
+            lines.push(colors.dim("  Category and agent scores: agentdoctor scan --json"));
+        }
     }
     else {
         lines.push(colors.dim("  Readiness scoring unavailable for this scan"));
     }
     lines.push("");
+    lines.push(...renderNextSteps(result));
     if (verbose) {
         lines.push(colors.dim("Timing"));
         lines.push(`  Discovery: ${result.timing.discoveryMs}ms`);

package/dist/reporters/verify/terminal.d.ts

@@ -1,2 +1,6 @@
 import type { VerifyResult } from "../../core/verify/verify.js";
 export declare function renderVerifyTerminalReport(result: VerifyResult, verbose?: boolean): string;
+/**
+ * Close the verify step: tell a first-time user what to do with Fixed / Remaining / New.
+ */
+export declare function renderVerifyNextSteps(result: VerifyResult): string[];

package/dist/reporters/verify/terminal.js

@@ -41,5 +41,31 @@ export function renderVerifyTerminalReport(result, verbose = false) {
         lines.push(colors.dim(`  Timing scan=${result.timing.scanMs}ms compare=${result.timing.compareMs}ms total=${result.timing.totalMs}ms`));
     }
     lines.push("");
+    lines.push(...renderVerifyNextSteps(result));
     return `${lines.join("\n")}\n`;
 }
+/**
+ * Close the verify step: tell a first-time user what to do with Fixed / Remaining / New.
+ */
+export function renderVerifyNextSteps(result) {
+    const lines = [];
+    const { fixed, remaining, new: newly } = result.summary;
+    lines.push(colors.bold("Next"));
+    if (remaining === 0 && newly === 0) {
+        lines.push(fixed > 0
+            ? "  All tracked findings cleared. Optional: gate CI with agentdoctor scan --ci"
+            : "  No regressions vs baseline. Optional: gate CI with agentdoctor scan --ci");
+    }
+    else {
+        if (newly > 0) {
+            lines.push(`  ${newly} new finding(s) appeared since the baseline — inspect: agentdoctor scan`);
+        }
+        if (remaining > 0) {
+            lines.push(`  ${remaining} finding(s) still open — auto-fixable ones: agentdoctor fix --dry-run`);
+            lines.push(colors.dim("  Review/manual leftovers: agentdoctor explain <rule-id>  (ids in scan --json)"));
+        }
+        lines.push(colors.dim("  After more fixes, re-check: agentdoctor verify --baseline agentdoctor-report.json"));
+    }
+    lines.push("");
+    return lines;
+}

package/dist/utils/fs.d.ts

@@ -15,3 +15,8 @@ export declare function listDirectorySafe(dirPath: string): Promise<{
     ok: false;
     error: string;
 }>;
+/**
+ * Write text via a same-directory temp file, then replace the target.
+ * On Windows, `rename` cannot overwrite an existing destination — remove first.
+ */
+export declare function atomicWriteTextFile(filePath: string, content: string): Promise<void>;

package/dist/utils/fs.js

@@ -61,3 +61,37 @@ export async function listDirectorySafe(dirPath) {
         return { ok: false, error: message };
     }
 }
+/**
+ * Write text via a same-directory temp file, then replace the target.
+ * On Windows, `rename` cannot overwrite an existing destination — remove first.
+ */
+export async function atomicWriteTextFile(filePath, content) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(filePath)}.agentdoctor.${process.pid}.${Date.now()}.tmp`);
+    await fs.writeFile(tmp, content, "utf8");
+    try {
+        await replaceFile(tmp, filePath);
+    }
+    catch (error) {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function replaceFile(tmpPath, targetPath) {
+    try {
+        await fs.rename(tmpPath, targetPath);
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : "";
+        // Windows (and some locked-file cases) cannot rename over an existing path.
+        if (process.platform === "win32" || code === "EEXIST" || code === "EPERM") {
+            await fs.rm(targetPath, { force: true });
+            await fs.rename(tmpPath, targetPath);
+            return;
+        }
+        throw error;
+    }
+}

package/dist/utils/path.d.ts

@@ -7,6 +7,11 @@ export declare function resolveRepoRoot(inputPath: string): string;
  * Produce a POSIX-style relative path for stable cross-platform reporting.
  */
 export declare function toPosixRelative(from: string, to: string): string;
+/**
+ * Normalize a repository-relative path to POSIX form without regex backtracking.
+ * Converts `\` to `/` and strips leading/trailing `/`.
+ */
+export declare function toRepoRelativePosix(relativePath: string): string;
 /**
  * Ensure a candidate path stays within a root (defense against traversal).
  */

package/dist/utils/path.js

@@ -16,6 +16,22 @@ export function resolveRepoRoot(inputPath) {
 export function toPosixRelative(from, to) {
     return path.relative(from, to).split(path.sep).join("/");
 }
+/**
+ * Normalize a repository-relative path to POSIX form without regex backtracking.
+ * Converts `\` to `/` and strips leading/trailing `/`.
+ */
+export function toRepoRelativePosix(relativePath) {
+    const value = relativePath.includes("\\") ? relativePath.split("\\").join("/") : relativePath;
+    let start = 0;
+    let end = value.length;
+    while (start < end && value.charCodeAt(start) === 47) {
+        start += 1;
+    }
+    while (end > start && value.charCodeAt(end - 1) === 47) {
+        end -= 1;
+    }
+    return start === 0 && end === value.length ? value : value.slice(start, end);
+}
 /**
  * Ensure a candidate path stays within a root (defense against traversal).
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praneeth_54/agentdoctor",
-  "version": "0.3.0-beta",
+  "version": "1.1.0",
   "description": "Audit AI coding agent configuration in a repository — local, deterministic, no API key.",
   "type": "module",
   "bin": {
@@ -33,7 +33,17 @@
     "format:check": "prettier --check .",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:understanding": "vitest run --config vitest.understanding.config.ts",
+    "test:mcp": "vitest run tests/unit/mcp",
+    "validate:understanding": "tsx validation/software-understanding/runner/run.ts",
+    "validate:mcp-agent": "tsx validation/mcp-agent/run.ts",
+    "validate:project-brain": "tsx validation/project-brain/run.ts",
+    "validate:project-brain:real-world": "tsx validation/project-brain/real-world-run.ts",
+    "benchmark:project-brain": "tsx validation/project-brain/benchmark.ts",
     "verify": "npm run typecheck && npm run lint && npm run format:check && npm test && npm run build",
+    "verify:understanding": "npm run typecheck && npm run test:understanding",
+    "verify:project-brain": "npm run typecheck && npm run test:understanding && npm run validate:project-brain && npm run benchmark:project-brain",
+    "verify:mcp": "npm run typecheck && npm run test:mcp",
     "prepare": "node scripts/ensure-cli-bin.mjs",
     "prepublishOnly": "npm run verify"
   },
@@ -65,6 +75,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^14.0.3",
     "picocolors": "^1.1.1"
   },
@@ -77,5 +88,8 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.50.0",
     "vitest": "^3.2.4"
+  },
+  "overrides": {
+    "js-yaml": "4.3.1"
   }
 }