@praneeth_54/agentdoctor 0.2.0-beta → 0.3.0-beta

package/dist/core/rules/security/env-file-exposure.js

@@ -1,3 +1,4 @@
+import { isSampleOrTestPath } from "../path-kind.js";
 const TEMPLATE_BASENAMES = new Set([".env.example", ".env.sample", ".env.template", ".env.dist"]);
 const BACKUP_BASENAMES = new Set([".env_backup", ".env_old", ".env_local"]);
 /**
@@ -10,11 +11,18 @@ export function classifyEnvBasename(base) {
         return null;
     }
     const lower = normalized.toLowerCase();
+    if (BACKUP_BASENAMES.has(lower)) {
+        return "backup";
+    }
     if (TEMPLATE_BASENAMES.has(lower)) {
         return "template";
     }
-    if (BACKUP_BASENAMES.has(lower)) {
-        return "backup";
+    // .env.local.example, .env.testing.example, .env.example.local, etc.
+    if (/\.(?:example|sample|template)(?:\.|$)/i.test(normalized)) {
+        return "template";
+    }
+    if (/\.env(?:\.[A-Za-z0-9_-]+)*\.(?:example|sample|template)$/i.test(normalized)) {
+        return "template";
     }
     if (lower === ".env") {
         return "runtime";
@@ -93,19 +101,11 @@ export const envFileExposureRule = {
             if (!kind) {
                 continue;
             }
+            if (isSampleOrTestPath(file.relativePath)) {
+                continue;
+            }
+            // Templates document variable names; they are not agent-readiness findings.
             if (kind === "template") {
-                findings.push({
-                    ruleId: "security/env-file-exposure",
-                    category: "security",
-                    severity: "info",
-                    title: "Environment template file present",
-                    message: `Environment template file detected at ${file.relativePath}`,
-                    whyItMatters: "Template env files are usually placeholders, but they can still document secret names. Filename classification only — contents were not inspected.",
-                    recommendation: "Keep templates free of real credentials. Prefer documenting variable names without values.",
-                    affectedAgents: [],
-                    evidence: { path: file.relativePath, detail: "template" },
-                    fixability: "review",
-                });
                 continue;
             }
             if (!agentsPresent) {

package/dist/core/rules/security/private-key-file.js

@@ -1,3 +1,4 @@
+import { isSampleOrTestPath } from "../path-kind.js";
 const PRIVATE_KEY_PATTERNS = [
     { test: (b) => /^id_rsa$/i.test(b), label: "SSH private key" },
     { test: (b) => /^id_ed25519$/i.test(b), label: "SSH private key" },
@@ -40,6 +41,9 @@ export const privateKeyFileRule = {
         const findings = [];
         const affected = context.agents.filter((a) => a.detected || a.configured).map((a) => a.id);
         for (const file of context.discovery.files) {
+            if (isSampleOrTestPath(file.relativePath)) {
+                continue;
+            }
             const base = file.relativePath.split("/").pop() ?? file.relativePath;
             const label = classify(base);
             if (!label) {

package/dist/core/verify/compare.d.ts

@@ -0,0 +1,29 @@
+import type { Finding, FindingEvidence, Severity } from "../../types/index.js";
+/** Stable subset of a finding for verify reports. */
+export interface VerifyFindingRef {
+    id: string;
+    ruleId: string;
+    severity: Severity;
+    title: string;
+    message: string;
+    evidence?: FindingEvidence;
+}
+export interface FindingCompareResult {
+    fixed: VerifyFindingRef[];
+    remaining: VerifyFindingRef[];
+    new: VerifyFindingRef[];
+    unchanged: VerifyFindingRef[];
+    summary: {
+        fixed: number;
+        remaining: number;
+        new: number;
+        unchanged: number;
+        before: number;
+        after: number;
+    };
+}
+export declare function toVerifyFindingRef(finding: Finding): VerifyFindingRef;
+/**
+ * Deterministic finding set comparison keyed by stable `Finding.id`.
+ */
+export declare function compareFindings(before: readonly Finding[], after: readonly Finding[]): FindingCompareResult;

package/dist/core/verify/compare.js

@@ -0,0 +1,56 @@
+export function toVerifyFindingRef(finding) {
+    const ref = {
+        id: finding.id,
+        ruleId: finding.ruleId,
+        severity: finding.severity,
+        title: finding.title,
+        message: finding.message,
+    };
+    if (finding.evidence !== undefined) {
+        ref.evidence = { ...finding.evidence };
+    }
+    return ref;
+}
+function sortRefs(refs) {
+    return [...refs].sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Deterministic finding set comparison keyed by stable `Finding.id`.
+ */
+export function compareFindings(before, after) {
+    const beforeById = new Map(before.map((f) => [f.id, f]));
+    const afterById = new Map(after.map((f) => [f.id, f]));
+    const fixed = [];
+    const remaining = [];
+    const newly = [];
+    for (const [id, finding] of beforeById) {
+        if (!afterById.has(id)) {
+            fixed.push(toVerifyFindingRef(finding));
+        }
+        else {
+            remaining.push(toVerifyFindingRef(afterById.get(id)));
+        }
+    }
+    for (const [id, finding] of afterById) {
+        if (!beforeById.has(id)) {
+            newly.push(toVerifyFindingRef(finding));
+        }
+    }
+    const fixedSorted = sortRefs(fixed);
+    const remainingSorted = sortRefs(remaining);
+    const newSorted = sortRefs(newly);
+    return {
+        fixed: fixedSorted,
+        remaining: remainingSorted,
+        new: newSorted,
+        unchanged: remainingSorted,
+        summary: {
+            fixed: fixedSorted.length,
+            remaining: remainingSorted.length,
+            new: newSorted.length,
+            unchanged: remainingSorted.length,
+            before: before.length,
+            after: after.length,
+        },
+    };
+}

package/dist/core/verify/load-baseline.d.ts

@@ -0,0 +1,15 @@
+import type { Finding } from "../../types/index.js";
+declare const DEFAULT_BASELINE_NAMES: readonly ["agentdoctor-report.json", ".agentdoctor-baseline.json"];
+export interface LoadedBaseline {
+    path: string;
+    findings: Finding[];
+}
+/**
+ * Load findings from a prior `scan --json` report (or a bare `{ findings: [...] }` file).
+ */
+export declare function loadBaselineFindings(baselinePath: string): Promise<LoadedBaseline>;
+/**
+ * Resolve baseline path: explicit flag, else first default filename that exists under root.
+ */
+export declare function resolveBaselinePath(root: string, explicitBaseline?: string): Promise<string | undefined>;
+export { DEFAULT_BASELINE_NAMES };

package/dist/core/verify/load-baseline.js

@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_BASELINE_NAMES = ["agentdoctor-report.json", ".agentdoctor-baseline.json"];
+function isFindingLike(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const record = value;
+    return (typeof record.id === "string" &&
+        typeof record.ruleId === "string" &&
+        typeof record.severity === "string" &&
+        typeof record.title === "string" &&
+        typeof record.message === "string");
+}
+/**
+ * Load findings from a prior `scan --json` report (or a bare `{ findings: [...] }` file).
+ */
+export async function loadBaselineFindings(baselinePath) {
+    const absolute = path.resolve(baselinePath);
+    let raw;
+    try {
+        raw = await fs.readFile(absolute, "utf8");
+    }
+    catch {
+        throw new Error(`baseline not found or unreadable: ${absolute}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`baseline is not valid JSON: ${absolute}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`baseline JSON must be an object: ${absolute}`);
+    }
+    const findingsUnknown = parsed.findings;
+    if (!Array.isArray(findingsUnknown)) {
+        throw new Error(`baseline JSON must include a findings array: ${absolute}`);
+    }
+    const findings = [];
+    for (const item of findingsUnknown) {
+        if (!isFindingLike(item)) {
+            throw new Error(`baseline contains an invalid finding entry: ${absolute}`);
+        }
+        findings.push(item);
+    }
+    return { path: absolute, findings };
+}
+/**
+ * Resolve baseline path: explicit flag, else first default filename that exists under root.
+ */
+export async function resolveBaselinePath(root, explicitBaseline) {
+    if (explicitBaseline) {
+        return path.isAbsolute(explicitBaseline)
+            ? explicitBaseline
+            : path.resolve(root, explicitBaseline);
+    }
+    for (const name of DEFAULT_BASELINE_NAMES) {
+        const candidate = path.join(root, name);
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch {
+            // try next
+        }
+    }
+    return undefined;
+}
+export { DEFAULT_BASELINE_NAMES };

package/dist/core/verify/verify.d.ts

@@ -0,0 +1,26 @@
+import type { Scores, ScanResult } from "../../types/index.js";
+import { type FindingCompareResult } from "./compare.js";
+export interface VerifyOptions {
+    cwd?: string;
+    /** Path to a prior scan JSON report. Defaults to agentdoctor-report.json if present. */
+    baselinePath?: string;
+    verbose?: boolean;
+}
+export interface VerifyResult extends FindingCompareResult {
+    version: string;
+    repositoryRoot: string;
+    baselinePath: string;
+    after: ScanResult;
+    scores: Scores | null;
+    scoringAvailable: boolean;
+    timing: {
+        totalMs: number;
+        scanMs: number;
+        compareMs: number;
+    };
+}
+/**
+ * Re-scan the repository and compare against a prior scan JSON baseline.
+ * Reuses the public `scan()` pipeline — no duplicated rule engine.
+ */
+export declare function verify(options?: VerifyOptions): Promise<VerifyResult>;

package/dist/core/verify/verify.js

@@ -0,0 +1,40 @@
+import { PACKAGE_VERSION } from "../../constants.js";
+import { scan } from "../scanner/scan.js";
+import { compareFindings } from "./compare.js";
+import { loadBaselineFindings, resolveBaselinePath } from "./load-baseline.js";
+/**
+ * Re-scan the repository and compare against a prior scan JSON baseline.
+ * Reuses the public `scan()` pipeline — no duplicated rule engine.
+ */
+export async function verify(options = {}) {
+    const totalStarted = performance.now();
+    const cwd = options.cwd ?? process.cwd();
+    const resolvedBaseline = await resolveBaselinePath(cwd, options.baselinePath);
+    if (!resolvedBaseline) {
+        throw new Error("No verify baseline found. Run `agentdoctor scan --json > agentdoctor-report.json`, apply fixes, then re-run verify.");
+    }
+    const baseline = await loadBaselineFindings(resolvedBaseline);
+    const scanStarted = performance.now();
+    const after = await scan({
+        cwd,
+        verbose: options.verbose ?? false,
+    });
+    const scanMs = Math.round(performance.now() - scanStarted);
+    const compareStarted = performance.now();
+    const compared = compareFindings(baseline.findings, after.findings);
+    const compareMs = Math.round(performance.now() - compareStarted);
+    return {
+        version: PACKAGE_VERSION,
+        repositoryRoot: after.repository.root,
+        baselinePath: baseline.path,
+        ...compared,
+        after,
+        scores: after.scores,
+        scoringAvailable: after.scoringAvailable,
+        timing: {
+            totalMs: Math.round(performance.now() - totalStarted),
+            scanMs,
+            compareMs,
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,8 +1,16 @@
 export { scan } from "./core/scanner/scan.js";
+export { verify } from "./core/verify/verify.js";
+export { compareFindings } from "./core/verify/compare.js";
 export { PACKAGE_VERSION } from "./constants.js";
 export type { ScanOptions, ScanResult, RepositoryInfo, Finding, FindingsSummary, Scores, AgentPresence, AgentDetectionResult, AgentSecurityAnalysisMode, CliOptions, ExitCode, } from "./types/index.js";
+export type { VerifyResult, VerifyOptions } from "./core/verify/verify.js";
+export type { VerifyFindingRef, FindingCompareResult } from "./core/verify/compare.js";
 export { EXIT_CODES } from "./types/index.js";
 export { agentRegistry } from "./agents/registry.js";
 export { detectAgents } from "./agents/detect-agents.js";
 export { ruleRegistry, getRuleById } from "./core/rules/registry.js";
 export { runRules } from "./core/rules/run-rules.js";
+export { buildFixPlan } from "./core/fix/plan.js";
+export { applyFixPlan } from "./core/fix/apply.js";
+export { runFix } from "./core/fix/run.js";
+export type { FixPlan, FixAction, FixApplyResult } from "./core/fix/types.js";

package/dist/index.js

@@ -1,7 +1,12 @@
 export { scan } from "./core/scanner/scan.js";
+export { verify } from "./core/verify/verify.js";
+export { compareFindings } from "./core/verify/compare.js";
 export { PACKAGE_VERSION } from "./constants.js";
 export { EXIT_CODES } from "./types/index.js";
 export { agentRegistry } from "./agents/registry.js";
 export { detectAgents } from "./agents/detect-agents.js";
 export { ruleRegistry, getRuleById } from "./core/rules/registry.js";
 export { runRules } from "./core/rules/run-rules.js";
+export { buildFixPlan } from "./core/fix/plan.js";
+export { applyFixPlan } from "./core/fix/apply.js";
+export { runFix } from "./core/fix/run.js";

package/dist/reporters/terminal/report.js

@@ -159,7 +159,13 @@ export function renderTerminalReport(result, options = {}) {
     lines.push(`  ${result.summary.warning} warning`);
     lines.push(`  ${result.summary.info} info`);
     lines.push("");
-    lines.push(colors.dim("Scoring: not included in this release"));
+    if (result.scoringAvailable && result.scores) {
+        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("");
     if (verbose) {
         lines.push(colors.dim("Timing"));

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,2 @@
+import type { VerifyResult } from "../../core/verify/verify.js";
+export declare function renderVerifyTerminalReport(result: VerifyResult, verbose?: boolean): string;

package/dist/reporters/verify/terminal.js

@@ -0,0 +1,45 @@
+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("");
+    return `${lines.join("\n")}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praneeth_54/agentdoctor",
-  "version": "0.2.0-beta",
+  "version": "0.3.0-beta",
   "description": "Audit AI coding agent configuration in a repository — local, deterministic, no API key.",
   "type": "module",
   "bin": {