@praneeth_54/agentdoctor 0.2.0-beta → 1.0.0

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,9 +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("");
-    lines.push(colors.dim("Scoring: not included in this release"));
+    if (result.scoringAvailable && result.scores) {
+        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/json.d.ts

@@ -0,0 +1,5 @@
+import type { VerifyResult } from "../../core/verify/verify.js";
+/**
+ * Machine-readable verify report.
+ */
+export declare function renderVerifyJsonReport(result: VerifyResult): string;

package/dist/reporters/verify/json.js

@@ -0,0 +1,51 @@
+import { sanitizeForOutput } from "../../utils/path.js";
+/**
+ * Machine-readable verify report.
+ */
+export function renderVerifyJsonReport(result) {
+    const payload = {
+        version: result.version,
+        baselinePath: sanitizeForOutput(result.baselinePath),
+        repositoryRoot: sanitizeForOutput(result.repositoryRoot),
+        fixed: result.fixed.map((f) => ({
+            ...f,
+            message: sanitizeForOutput(f.message),
+            title: sanitizeForOutput(f.title),
+            ...(f.evidence?.path !== undefined
+                ? { evidence: { ...f.evidence, path: sanitizeForOutput(f.evidence.path) } }
+                : f.evidence !== undefined
+                    ? { evidence: f.evidence }
+                    : {}),
+        })),
+        remaining: result.remaining.map((f) => ({
+            ...f,
+            message: sanitizeForOutput(f.message),
+            title: sanitizeForOutput(f.title),
+            ...(f.evidence?.path !== undefined
+                ? { evidence: { ...f.evidence, path: sanitizeForOutput(f.evidence.path) } }
+                : f.evidence !== undefined
+                    ? { evidence: f.evidence }
+                    : {}),
+        })),
+        new: result.new.map((f) => ({
+            ...f,
+            message: sanitizeForOutput(f.message),
+            title: sanitizeForOutput(f.title),
+            ...(f.evidence?.path !== undefined
+                ? { evidence: { ...f.evidence, path: sanitizeForOutput(f.evidence.path) } }
+                : f.evidence !== undefined
+                    ? { evidence: f.evidence }
+                    : {}),
+        })),
+        unchanged: result.unchanged.map((f) => ({
+            id: f.id,
+            ruleId: f.ruleId,
+            severity: f.severity,
+        })),
+        summary: result.summary,
+        scoringAvailable: result.scoringAvailable,
+        scores: result.scores,
+        timing: result.timing,
+    };
+    return `${JSON.stringify(payload, null, 2)}\n`;
+}

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

@@ -0,0 +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

@@ -0,0 +1,71 @@
+import { PACKAGE_VERSION } from "../../constants.js";
+import { colors, symbolFail, symbolOk, symbolWarn } from "../../utils/colors.js";
+import { sanitizeForOutput } from "../../utils/path.js";
+function renderBucket(title, symbol, color, items, limit) {
+    const lines = [];
+    lines.push(color(`${symbol} ${title} (${items.length})`));
+    if (items.length === 0) {
+        lines.push(colors.dim("  (none)"));
+        lines.push("");
+        return lines;
+    }
+    const shown = items.slice(0, limit);
+    for (const item of shown) {
+        const path = item.evidence?.path ? ` — ${sanitizeForOutput(item.evidence.path)}` : "";
+        lines.push(`  ${sanitizeForOutput(item.ruleId)}${path}`);
+        lines.push(colors.dim(`    ${sanitizeForOutput(item.title)}`));
+    }
+    if (items.length > limit) {
+        lines.push(colors.dim(`  … and ${items.length - limit} more`));
+    }
+    lines.push("");
+    return lines;
+}
+export function renderVerifyTerminalReport(result, verbose = false) {
+    const lines = [];
+    const limit = verbose ? 50 : 12;
+    lines.push("");
+    lines.push(colors.bold(`AgentDoctor verify v${PACKAGE_VERSION}`));
+    lines.push(colors.dim(`Baseline: ${sanitizeForOutput(result.baselinePath)}`));
+    lines.push("");
+    lines.push(...renderBucket("Fixed", symbolOk(), colors.green, result.fixed, limit));
+    lines.push(...renderBucket("Remaining", symbolWarn(), colors.yellow, result.remaining, limit));
+    lines.push(...renderBucket("New", symbolFail(), colors.red, result.new, limit));
+    lines.push(colors.bold("Summary"));
+    lines.push(`  Fixed ${result.summary.fixed} · Remaining ${result.summary.remaining} · New ${result.summary.new} · Unchanged ${result.summary.unchanged}`);
+    lines.push(colors.dim(`  Before ${result.summary.before} → After ${result.summary.after} findings`));
+    if (result.scores) {
+        lines.push(colors.dim(`  Score ${result.scores.overall}/100`));
+    }
+    if (verbose) {
+        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.2.0-beta",
+  "version": "1.0.0",
   "description": "Audit AI coding agent configuration in a repository — local, deterministic, no API key.",
   "type": "module",
   "bin": {
@@ -33,7 +33,14 @@
     "format:check": "prettier --check .",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:understanding": "vitest run --config vitest.understanding.config.ts",
+    "validate:understanding": "tsx validation/software-understanding/runner/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",
     "prepare": "node scripts/ensure-cli-bin.mjs",
     "prepublishOnly": "npm run verify"
   },
@@ -77,5 +84,8 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.50.0",
     "vitest": "^3.2.4"
+  },
+  "overrides": {
+    "js-yaml": "4.3.1"
   }
 }