@praneeth_54/agentdoctor 0.2.0-beta → 1.0.0

package/dist/cli/commands/scan.js

@@ -1,10 +1,12 @@
 import path from "node:path";
+import { evaluateScanPolicy } from "../../core/policy/evaluate.js";
 import { scan } from "../../core/scanner/scan.js";
+import { emitGithubReports } from "../../reporters/github/emit.js";
 import { renderJsonReport } from "../../reporters/json/report.js";
 import { renderTerminalReport } from "../../reporters/terminal/report.js";
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
 import { isDirectory } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
 export async function runScanCommand(options) {
     const target = resolveRepoRoot(options.targetPath ?? process.cwd());
     if (!(await isDirectory(target))) {
@@ -24,13 +26,30 @@ export async function runScanCommand(options) {
                 verbose: options.verbose === true,
             }));
         }
-        if (options.minScore !== undefined && result.scores !== null) {
-            if (result.scores.overall < options.minScore) {
-                if (!options.json) {
-                    console.error(`\nCI check failed: overall score ${result.scores.overall} is below --min-score ${options.minScore}`);
+        const failOnSeverity = options.failOnSeverity ?? (options.ci === true ? "critical" : undefined);
+        const policy = {
+            ...(options.minScore !== undefined ? { minimumScore: options.minScore } : {}),
+            ...(failOnSeverity !== undefined ? { failOnSeverity } : {}),
+            ...(options.failOnRules && options.failOnRules.length > 0
+                ? { failOnRules: options.failOnRules }
+                : {}),
+        };
+        const violations = evaluateScanPolicy(result, policy);
+        await emitGithubReports({
+            mode: "scan",
+            findings: result.findings,
+            overallScore: result.scores?.overall ?? null,
+            violations,
+            summary: options.summary === true,
+            annotations: options.annotations === true,
+        });
+        if (violations.length > 0) {
+            if (!options.json) {
+                for (const violation of violations) {
+                    console.error(`\n${violation.message}`);
                 }
-                return EXIT_CODES.ISSUES_OR_THRESHOLD;
             }
+            return EXIT_CODES.ISSUES_OR_THRESHOLD;
         }
         return EXIT_CODES.SUCCESS;
     }

package/dist/cli/commands/verify.d.ts

@@ -0,0 +1,19 @@
+import { type PolicyOptions } from "../../core/policy/evaluate.js";
+import { type ExitCode } from "../../types/index.js";
+export interface VerifyCommandOptions {
+    targetPath?: string;
+    baselinePath?: string;
+    json?: boolean;
+    ci?: boolean;
+    verbose?: boolean;
+    minScore?: number;
+    failOnSeverity?: PolicyOptions["failOnSeverity"];
+    failOnRules?: string[];
+    failOnNew?: boolean;
+    summary?: boolean;
+    annotations?: boolean;
+}
+/**
+ * Verify: re-scan after Fix and compare against a prior scan JSON baseline.
+ */
+export declare function runVerifyCommand(options: VerifyCommandOptions): Promise<ExitCode>;

package/dist/cli/commands/verify.js

@@ -0,0 +1,70 @@
+import { evaluateVerifyPolicy } from "../../core/policy/evaluate.js";
+import { verify } from "../../core/verify/verify.js";
+import { emitGithubReports } from "../../reporters/github/emit.js";
+import { renderVerifyJsonReport } from "../../reporters/verify/json.js";
+import { renderVerifyTerminalReport } from "../../reporters/verify/terminal.js";
+import { EXIT_CODES } from "../../types/index.js";
+import { isDirectory } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+/**
+ * Verify: re-scan after Fix and compare against a prior scan JSON baseline.
+ */
+export async function runVerifyCommand(options) {
+    const target = resolveRepoRoot(options.targetPath ?? process.cwd());
+    if (!(await isDirectory(target))) {
+        console.error(`Error: not a directory: ${target}`);
+        return EXIT_CODES.USAGE_ERROR;
+    }
+    try {
+        const result = await verify({
+            cwd: target,
+            verbose: options.verbose ?? false,
+            ...(options.baselinePath !== undefined ? { baselinePath: options.baselinePath } : {}),
+        });
+        if (options.json) {
+            process.stdout.write(renderVerifyJsonReport(result));
+        }
+        else {
+            process.stdout.write(renderVerifyTerminalReport(result, options.verbose === true));
+        }
+        const failOnNew = options.failOnNew === true || options.ci === true;
+        const policy = {
+            ...(options.minScore !== undefined ? { minimumScore: options.minScore } : {}),
+            ...(options.failOnSeverity !== undefined ? { failOnSeverity: options.failOnSeverity } : {}),
+            ...(options.failOnRules && options.failOnRules.length > 0
+                ? { failOnRules: options.failOnRules }
+                : {}),
+            ...(failOnNew ? { failOnNew: true } : {}),
+        };
+        const violations = evaluateVerifyPolicy(result, policy);
+        await emitGithubReports({
+            mode: "verify",
+            findings: result.after.findings,
+            overallScore: result.scores?.overall ?? null,
+            violations,
+            verifySummary: result.summary,
+            summary: options.summary === true,
+            annotations: options.annotations === true,
+        });
+        if (violations.length > 0) {
+            if (!options.json) {
+                for (const violation of violations) {
+                    console.error(`\n${violation.message}`);
+                }
+            }
+            return EXIT_CODES.ISSUES_OR_THRESHOLD;
+        }
+        return EXIT_CODES.SUCCESS;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+        if (options.verbose && error instanceof Error && error.stack) {
+            console.error(error.stack);
+        }
+        if (message.includes("baseline") || message.includes("No verify baseline")) {
+            return EXIT_CODES.USAGE_ERROR;
+        }
+        return EXIT_CODES.INTERNAL_ERROR;
+    }
+}

package/dist/cli/program.js

@@ -1,14 +1,16 @@
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 import { PACKAGE_VERSION } from "../constants.js";
+import { parseFailOnRules, parseSeverityGate } from "../core/policy/evaluate.js";
+import { EXIT_CODES } from "../types/index.js";
 import { runDoctorCommand } from "./commands/doctor.js";
 import { runExplainCommand } from "./commands/explain.js";
 import { runFixCommand } from "./commands/fix.js";
 import { resolveTargetArgument, runScanCommand } from "./commands/scan.js";
-import { EXIT_CODES } from "../types/index.js";
+import { runVerifyCommand } from "./commands/verify.js";
 function parseMinScore(value) {
     const parsed = Number(value);
     if (!Number.isFinite(parsed) || parsed < 0 || parsed > 100) {
-        throw new Error("--min-score must be a number between 0 and 100");
+        throw new InvalidArgumentError("--min-score must be a number between 0 and 100");
     }
     return parsed;
 }
@@ -21,56 +23,118 @@ function readMinScore(options) {
     }
     return undefined;
 }
+function collectFailOnRules(value, previous) {
+    return [...previous, ...parseFailOnRules(value)];
+}
+function readFailOnSeverity(options) {
+    if (typeof options.failOnSeverity !== "string" || options.failOnSeverity.length === 0) {
+        return undefined;
+    }
+    return parseSeverityGate(options.failOnSeverity);
+}
+function readFailOnRules(options) {
+    if (Array.isArray(options.failOnRule)) {
+        return options.failOnRule.filter((item) => typeof item === "string");
+    }
+    if (typeof options.failOnRule === "string") {
+        return parseFailOnRules(options.failOnRule);
+    }
+    return [];
+}
+/**
+ * Scan flags are declared on both the root program and the `scan` subcommand
+ * so `--help` stays accurate. Commander stores overlapping flags on the parent
+ * when `scan` is invoked, so callers must read `optsWithGlobals()`.
+ */
+function addScanOptions(command) {
+    return command
+        .option("--json", "Emit machine-readable JSON (no decorative output)", false)
+        .option("--ci", "CI mode: exit 1 when any critical finding exists (override with --fail-on-severity)", false)
+        .option("--verbose", "Show timing and extra diagnostics", false)
+        .option("--min-score <number>", "Exit 1 when overall readiness score is below this (0-100)", parseMinScore)
+        .option("--fail-on-severity <level>", "Exit 1 when any finding has this severity or higher (critical|warning|info)", parseSeverityGate)
+        .option("--fail-on-rule <id>", "Exit 1 when a finding matches this rule id (repeatable or comma-separated)", collectFailOnRules, [])
+        .option("--summary", "Write a GitHub Actions step summary when GITHUB_STEP_SUMMARY is set", false)
+        .option("--annotations", "Emit GitHub Actions annotations for findings (stderr)", false);
+}
+async function runScanFromCli(pathArg, command) {
+    const options = command.optsWithGlobals();
+    const minScore = readMinScore(options);
+    const failOnSeverity = readFailOnSeverity(options);
+    const failOnRules = readFailOnRules(options);
+    const code = await runScanCommand({
+        targetPath: resolveTargetArgument(pathArg),
+        json: Boolean(options.json),
+        ci: Boolean(options.ci),
+        verbose: Boolean(options.verbose),
+        summary: Boolean(options.summary),
+        annotations: Boolean(options.annotations),
+        ...(minScore !== undefined ? { minScore } : {}),
+        ...(failOnSeverity !== undefined ? { failOnSeverity } : {}),
+        ...(failOnRules.length > 0 ? { failOnRules } : {}),
+    });
+    process.exitCode = code;
+}
 export function createProgram() {
     const program = new Command();
-    program
+    addScanOptions(program
         .name("agentdoctor")
         .description("Audit AI coding agent configuration in a repository (local, deterministic, no API key).")
         .version(PACKAGE_VERSION, "-V, --version", "Print AgentDoctor version")
-        .argument("[path]", "Repository path to scan (default: current directory)")
-        .option("--json", "Emit machine-readable JSON (no decorative output)", false)
-        .option("--ci", "CI mode (non-interactive; report-only unless --min-score is set)", false)
-        .option("--verbose", "Show timing and extra diagnostics", false)
-        .option("--min-score <number>", "Exit 1 when overall readiness score is below this (0-100)", parseMinScore)
+        .argument("[path]", "Repository path to scan (default: current directory)")).action(async (pathArg, _options, command) => {
+        await runScanFromCli(pathArg, command);
+    });
+    addScanOptions(program
+        .command("scan")
+        .description("Scan a repository for AI coding agent configuration issues (default command)")
+        .argument("[path]", "Repository path to scan")).action(async (pathArg, _options, command) => {
+        await runScanFromCli(pathArg, command);
+    });
+    program
+        .command("fix")
+        .description("Apply safe automatic fixes (Cursor .cursorignore, Claude Code Read deny, and Codex filesystem deny for safe context findings)")
+        .argument("[path]", "Repository path (default: current directory)")
+        .option("--dry-run", "Show proposed fixes without writing files", false)
+        .option("-y, --yes", "Skip confirmation prompts", false)
         .action(async (pathArg, options) => {
-        const minScore = readMinScore(options);
-        const code = await runScanCommand({
+        const code = await runFixCommand({
             targetPath: resolveTargetArgument(pathArg),
-            json: Boolean(options.json),
-            ci: Boolean(options.ci),
-            verbose: Boolean(options.verbose),
-            ...(minScore !== undefined ? { minScore } : {}),
+            dryRun: Boolean(options.dryRun),
+            yes: Boolean(options.yes),
         });
         process.exitCode = code;
     });
     program
-        .command("scan")
-        .description("Scan a repository for AI coding agent configuration issues (default command)")
-        .argument("[path]", "Repository path to scan")
+        .command("verify")
+        .description("Re-scan and compare against a prior scan JSON baseline (Scan → Fix → Verify)")
+        .argument("[path]", "Repository path (default: current directory)")
         .option("--json", "Emit machine-readable JSON", false)
-        .option("--ci", "CI mode (non-interactive; report-only unless --min-score is set)", false)
+        .option("--ci", "CI mode: exit 1 when new findings appear (also honors other policy flags)", false)
+        .option("--fail-on-new", "Exit 1 when new findings appear relative to the baseline", false)
         .option("--verbose", "Show timing and extra diagnostics", false)
+        .option("--baseline <file>", "Prior scan JSON report (default: agentdoctor-report.json or .agentdoctor-baseline.json)")
         .option("--min-score <number>", "Exit 1 when overall readiness score is below this (0-100)", parseMinScore)
-        .action(async (pathArg, options) => {
+        .option("--fail-on-severity <level>", "Exit 1 when any finding has this severity or higher (critical|warning|info)", parseSeverityGate)
+        .option("--fail-on-rule <id>", "Exit 1 when a finding matches this rule id (repeatable or comma-separated)", collectFailOnRules, [])
+        .option("--summary", "Write a GitHub Actions step summary when GITHUB_STEP_SUMMARY is set", false)
+        .option("--annotations", "Emit GitHub Actions annotations for findings (stderr)", false)
+        .action(async (pathArg, _options, command) => {
+        const options = command.optsWithGlobals();
         const minScore = readMinScore(options);
-        const code = await runScanCommand({
+        const failOnSeverity = readFailOnSeverity(options);
+        const failOnRules = readFailOnRules(options);
+        const code = await runVerifyCommand({
             targetPath: resolveTargetArgument(pathArg),
             json: Boolean(options.json),
             ci: Boolean(options.ci),
+            failOnNew: Boolean(options.failOnNew),
             verbose: Boolean(options.verbose),
+            summary: Boolean(options.summary),
+            annotations: Boolean(options.annotations),
+            ...(typeof options.baseline === "string" ? { baselinePath: options.baseline } : {}),
             ...(minScore !== undefined ? { minScore } : {}),
-        });
-        process.exitCode = code;
-    });
-    program
-        .command("fix")
-        .description("Apply safe automatic fixes (not implemented yet)")
-        .option("--dry-run", "Show proposed fixes without writing files", false)
-        .option("-y, --yes", "Skip confirmation prompts", false)
-        .action(async (options) => {
-        const code = await runFixCommand({
-            dryRun: Boolean(options.dryRun),
-            yes: Boolean(options.yes),
+            ...(failOnSeverity !== undefined ? { failOnSeverity } : {}),
+            ...(failOnRules.length > 0 ? { failOnRules } : {}),
         });
         process.exitCode = code;
     });

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const PACKAGE_VERSION = "0.2.0-beta";
+export declare const PACKAGE_VERSION = "1.0.0";
 export declare const DEFAULT_MAX_FILE_SIZE_BYTES: number;
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export declare const DEFAULT_IGNORE_DIRECTORIES: Set<string>;

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "0.2.0-beta";
+export const PACKAGE_VERSION = "1.0.0";
 export const DEFAULT_MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024; // 2 MiB
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export const DEFAULT_IGNORE_DIRECTORIES = new Set([

package/dist/core/fix/apply.d.ts

@@ -0,0 +1,14 @@
+import type { FixApplyResult, FixPlan } from "./types.js";
+import { previewClaudeSettingsActions, readClaudeSettings } from "./writers/claude-settings.js";
+import { previewCodexConfigActions, readCodexConfig } from "./writers/codex-config.js";
+import { previewCursorignoreActions, readCursorignore } from "./writers/cursorignore.js";
+/**
+ * Apply (or dry-run) a fix plan.
+ * Safe writers: `.cursorignore`, Claude settings deny, Codex config.toml deny.
+ */
+export declare function applyFixPlan(plan: FixPlan, options: {
+    dryRun: boolean;
+}): Promise<FixApplyResult>;
+export { previewCursorignoreActions, readCursorignore };
+export { previewClaudeSettingsActions, readClaudeSettings };
+export { previewCodexConfigActions, readCodexConfig };

package/dist/core/fix/apply.js

@@ -0,0 +1,47 @@
+import { previewClaudeSettingsActions, readClaudeSettings, writeClaudeSettings, } from "./writers/claude-settings.js";
+import { previewCodexConfigActions, readCodexConfig, writeCodexConfig, } from "./writers/codex-config.js";
+import { previewCursorignoreActions, readCursorignore, writeCursorignore, } from "./writers/cursorignore.js";
+/**
+ * Apply (or dry-run) a fix plan.
+ * Safe writers: `.cursorignore`, Claude settings deny, Codex config.toml deny.
+ */
+export async function applyFixPlan(plan, options) {
+    const cursorContent = await readCursorignore(plan.root);
+    const claudeContent = await readClaudeSettings(plan.root);
+    const codexContent = await readCodexConfig(plan.root);
+    const cursorPreview = previewCursorignoreActions(cursorContent, plan.actions);
+    const claudePreview = previewClaudeSettingsActions(claudeContent, plan.actions);
+    const codexPreview = previewCodexConfigActions(codexContent, plan.actions);
+    const writtenFiles = [];
+    const changedFiles = [];
+    if (cursorPreview) {
+        changedFiles.push(cursorPreview.targetRelativePath);
+        if (!options.dryRun) {
+            await writeCursorignore(plan.root, cursorPreview.after);
+            writtenFiles.push(cursorPreview.targetRelativePath);
+        }
+    }
+    if (claudePreview) {
+        changedFiles.push(claudePreview.targetRelativePath);
+        if (!options.dryRun) {
+            await writeClaudeSettings(plan.root, claudePreview.after);
+            writtenFiles.push(claudePreview.targetRelativePath);
+        }
+    }
+    if (codexPreview) {
+        changedFiles.push(codexPreview.targetRelativePath);
+        if (!options.dryRun) {
+            await writeCodexConfig(plan.root, codexPreview.after);
+            writtenFiles.push(codexPreview.targetRelativePath);
+        }
+    }
+    return {
+        plan,
+        dryRun: options.dryRun,
+        writtenFiles,
+        changedFiles,
+    };
+}
+export { previewCursorignoreActions, readCursorignore };
+export { previewClaudeSettingsActions, readClaudeSettings };
+export { previewCodexConfigActions, readCodexConfig };

package/dist/core/fix/patterns.d.ts

@@ -0,0 +1,7 @@
+import type { Finding } from "../../types/index.js";
+export declare function isSafeContextFixRule(ruleId: string): boolean;
+/**
+ * Build a gitignore-style pattern that excludes the finding evidence path.
+ * Directories (generated-directory) get a trailing slash.
+ */
+export declare function patternForFinding(finding: Finding): string | null;

package/dist/core/fix/patterns.js

@@ -0,0 +1,21 @@
+const SAFE_CONTEXT_RULES = new Set(["context/generated-directory", "context/large-log-file"]);
+export function isSafeContextFixRule(ruleId) {
+    return SAFE_CONTEXT_RULES.has(ruleId);
+}
+/**
+ * Build a gitignore-style pattern that excludes the finding evidence path.
+ * Directories (generated-directory) get a trailing slash.
+ */
+export function patternForFinding(finding) {
+    const evidencePath = finding.evidence?.path?.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (!evidencePath) {
+        return null;
+    }
+    if (finding.ruleId === "context/generated-directory") {
+        return evidencePath.endsWith("/") ? evidencePath : `${evidencePath}/`;
+    }
+    if (finding.ruleId === "context/large-log-file") {
+        return evidencePath;
+    }
+    return null;
+}

package/dist/core/fix/plan.d.ts

@@ -0,0 +1,9 @@
+import type { ScanResult } from "../../types/index.js";
+import type { FixPlan } from "./types.js";
+/**
+ * Build a fix plan from a scan result.
+ * Safe context exclusions: Cursor `.cursorignore`, Claude Code Read deny, Codex filesystem deny.
+ */
+export declare function buildFixPlan(result: ScanResult): Promise<FixPlan>;
+/** Patterns that would be newly appended given current file contents. */
+export declare function missingPatternsForCursorignore(currentContent: string | null, patterns: string[]): string[];