@praneeth_54/agentdoctor 0.1.0-beta

package/dist/agents/types.d.ts

@@ -0,0 +1,52 @@
+import type { AgentId, DiscoveredFile, DiscoveryResult } from "../types/index.js";
+export type AgentConfigStatus = "absent" | "detected" | "configured" | "misconfigured";
+export type AgentConfigFileKind = "cursor-rule-mdc" | "cursor-rule-ignored-md" | "cursor-legacy-cursorrules" | "agents-md" | "agents-override-md" | "claude-md" | "claude-local-md" | "claude-rule-md" | "claude-settings" | "claude-settings-local" | "codex-config" | "other";
+export type AgentConfigScope = "root" | "nested" | "legacy";
+export interface AgentConfigFile {
+    relativePath: string;
+    kind: AgentConfigFileKind;
+    sizeBytes: number;
+    empty: boolean;
+    readable: boolean;
+    legacy: boolean;
+    scope: AgentConfigScope;
+    /** Present when the file exists but could not be parsed (e.g. invalid JSON). */
+    parseError?: string;
+}
+export interface AgentDiagnostic {
+    code: string;
+    severity: "info" | "warning" | "error";
+    message: string;
+    file?: string;
+}
+export interface AgentDetectionResult {
+    id: AgentId;
+    displayName: string;
+    /** Any repository evidence that this agent is in use or configured. */
+    detected: boolean;
+    /** At least one non-empty, usable project instruction/config file. */
+    configured: boolean;
+    status: AgentConfigStatus;
+    /** Short human summary, e.g. "2 project rules". */
+    summary: string;
+    configFiles: AgentConfigFile[];
+    /** Convenience list derived from configFiles. */
+    configPaths: string[];
+    diagnostics: AgentDiagnostic[];
+    metadata: Record<string, unknown>;
+}
+export interface AgentDetectionContext {
+    root: string;
+    discovery: DiscoveryResult;
+    maxFileSizeBytes: number;
+}
+export interface AgentAdapter {
+    id: AgentId;
+    displayName: string;
+    detect(context: AgentDetectionContext): Promise<AgentDetectionResult>;
+}
+/** Map discovered files by relative path for O(1) lookups. */
+export declare function indexDiscoveredFiles(files: DiscoveredFile[]): Map<string, DiscoveredFile>;
+export declare function basenameOf(relativePath: string): string;
+export declare function dirnameOf(relativePath: string): string;
+export declare function isRootLevel(relativePath: string): boolean;

package/dist/agents/types.js

@@ -0,0 +1,15 @@
+/** Map discovered files by relative path for O(1) lookups. */
+export function indexDiscoveredFiles(files) {
+    return new Map(files.map((file) => [file.relativePath, file]));
+}
+export function basenameOf(relativePath) {
+    const parts = relativePath.split("/");
+    return parts[parts.length - 1] ?? relativePath;
+}
+export function dirnameOf(relativePath) {
+    const idx = relativePath.lastIndexOf("/");
+    return idx === -1 ? "" : relativePath.slice(0, idx);
+}
+export function isRootLevel(relativePath) {
+    return !relativePath.includes("/");
+}

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

@@ -0,0 +1,5 @@
+import { type ExitCode } from "../../types/index.js";
+/**
+ * Self-check for the AgentDoctor installation (environment health).
+ */
+export declare function runDoctorCommand(): Promise<ExitCode>;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,22 @@
+import { PACKAGE_VERSION } from "../../constants.js";
+import { EXIT_CODES } from "../../types/index.js";
+import { colors, symbolOk } from "../../utils/colors.js";
+/**
+ * Self-check for the AgentDoctor installation (environment health).
+ */
+export async function runDoctorCommand() {
+    const lines = [];
+    lines.push("");
+    lines.push(colors.bold("AgentDoctor doctor"));
+    lines.push("");
+    lines.push(`  ${symbolOk()} AgentDoctor v${PACKAGE_VERSION}`);
+    lines.push(`  ${symbolOk()} Node.js ${process.version}`);
+    lines.push(`  ${symbolOk()} Platform ${process.platform}-${process.arch}`);
+    lines.push(`  ${symbolOk()} Core scan API available`);
+    lines.push("");
+    lines.push(colors.dim("Environment looks ready."));
+    lines.push(colors.dim("Readiness scoring and automatic fixes are not available yet."));
+    lines.push("");
+    process.stdout.write(lines.join("\n"));
+    return EXIT_CODES.SUCCESS;
+}

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

@@ -0,0 +1,5 @@
+import { type ExitCode } from "../../types/index.js";
+/**
+ * Explain a rule by stable ID.
+ */
+export declare function runExplainCommand(ruleId: string | undefined): Promise<ExitCode>;

package/dist/cli/commands/explain.js

@@ -0,0 +1,51 @@
+import { getRuleById } from "../../core/rules/registry.js";
+import { EXIT_CODES } from "../../types/index.js";
+import { colors } from "../../utils/colors.js";
+import { AGENT_DISPLAY_NAMES } from "../../constants.js";
+/**
+ * Explain a rule by stable ID.
+ */
+export async function runExplainCommand(ruleId) {
+    if (!ruleId || ruleId.trim() === "") {
+        console.error("Error: provide a rule id, e.g. agentdoctor explain security/env-file-exposure");
+        return EXIT_CODES.USAGE_ERROR;
+    }
+    const rule = getRuleById(ruleId.trim());
+    if (!rule) {
+        console.error(`Error: unknown rule id "${ruleId}"`);
+        console.error("Run agentdoctor explain with a documented rule from docs/rules.md");
+        return EXIT_CODES.USAGE_ERROR;
+    }
+    const agents = rule.affectedAgents?.map((id) => AGENT_DISPLAY_NAMES[id] ?? id).join(", ") ??
+        "Depends on finding evidence";
+    const lines = [];
+    lines.push("");
+    lines.push(colors.bold(`Explain: ${rule.id}`));
+    lines.push("");
+    lines.push(`  Title:        ${rule.title}`);
+    lines.push(`  Category:     ${rule.category}`);
+    lines.push(`  Severity:     ${rule.severity}`);
+    lines.push(`  Fixability:   ${rule.fixability}`);
+    lines.push(`  Agents:       ${agents}`);
+    lines.push("");
+    lines.push(colors.bold("What it detects"));
+    lines.push(`  ${rule.description}`);
+    lines.push("");
+    lines.push(colors.bold("Why it matters"));
+    lines.push(`  ${rule.rationale}`);
+    lines.push("");
+    lines.push(colors.bold("Recommended solution"));
+    lines.push(`  ${rule.recommendation}`);
+    lines.push("");
+    lines.push(colors.bold("Can AgentDoctor safely fix it?"));
+    lines.push(rule.fixability === "safe"
+        ? "  Potentially yes. Conservative auto-fix is planned but not applied today."
+        : rule.fixability === "review"
+            ? "  Only with review. Automatic fixes are not applied today."
+            : rule.fixability === "manual"
+                ? "  No automatic fix. Manual remediation required."
+                : "  No fix available.");
+    lines.push("");
+    process.stdout.write(lines.join("\n"));
+    return EXIT_CODES.SUCCESS;
+}

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

@@ -0,0 +1,8 @@
+import { type ExitCode } from "../../types/index.js";
+/**
+ * Safe automatic fixes are not implemented yet.
+ */
+export declare function runFixCommand(options: {
+    dryRun?: boolean;
+    yes?: boolean;
+}): Promise<ExitCode>;

package/dist/cli/commands/fix.js

@@ -0,0 +1,19 @@
+import { EXIT_CODES } from "../../types/index.js";
+import { colors } from "../../utils/colors.js";
+/**
+ * Safe automatic fixes are not implemented yet.
+ */
+export async function runFixCommand(options) {
+    const lines = [];
+    lines.push("");
+    lines.push(colors.bold("AgentDoctor fix"));
+    lines.push("");
+    if (options.dryRun) {
+        lines.push("  Dry-run mode requested.");
+    }
+    lines.push("  Fix mode is not implemented yet.");
+    lines.push("  No files were modified.");
+    lines.push("");
+    process.stdout.write(lines.join("\n"));
+    return EXIT_CODES.SUCCESS;
+}

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

@@ -0,0 +1,10 @@
+import { type ExitCode } from "../../types/index.js";
+export interface ScanCommandOptions {
+    targetPath?: string;
+    json?: boolean;
+    ci?: boolean;
+    verbose?: boolean;
+    minScore?: number;
+}
+export declare function runScanCommand(options: ScanCommandOptions): Promise<ExitCode>;
+export declare function resolveTargetArgument(pathArg: string | undefined, cwd?: string): string;

package/dist/cli/commands/scan.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+import { scan } from "../../core/scanner/scan.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";
+export async function runScanCommand(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 scan({
+            cwd: target,
+            verbose: options.verbose ?? false,
+        });
+        if (options.json) {
+            process.stdout.write(renderJsonReport(result));
+        }
+        else {
+            process.stdout.write(renderTerminalReport(result, {
+                verbose: options.verbose === true,
+            }));
+        }
+        if (options.ci || options.minScore !== undefined) {
+            if (!result.scoringAvailable || result.scores === null) {
+                if (!options.json) {
+                    console.error("Note: readiness scoring is not available in this release; --min-score was ignored.");
+                }
+            }
+            else {
+                const threshold = options.minScore ?? 0;
+                if (result.scores.overall < threshold) {
+                    if (!options.json) {
+                        console.error(`\nCI check failed: overall score ${result.scores.overall} is below --min-score ${threshold}`);
+                    }
+                    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);
+        }
+        return EXIT_CODES.INTERNAL_ERROR;
+    }
+}
+export function resolveTargetArgument(pathArg, cwd = process.cwd()) {
+    if (!pathArg) {
+        return cwd;
+    }
+    return path.isAbsolute(pathArg) ? pathArg : path.resolve(cwd, pathArg);
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from "./program.js";
+await runCli(process.argv);

package/dist/cli/program.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createProgram(): Command;
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli/program.js

@@ -0,0 +1,124 @@
+import { Command } from "commander";
+import { PACKAGE_VERSION } from "../constants.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";
+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");
+    }
+    return parsed;
+}
+function readMinScore(options) {
+    if (typeof options.minScore === "number") {
+        return options.minScore;
+    }
+    if (typeof options.minScore === "string") {
+        return parseMinScore(options.minScore);
+    }
+    return undefined;
+}
+export function createProgram() {
+    const program = new Command();
+    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; --min-score is ignored until scoring ships)", false)
+        .option("--verbose", "Show timing and extra diagnostics", false)
+        .option("--min-score <number>", "Fail when overall score is below this (no-op until scoring ships)", parseMinScore)
+        .action(async (pathArg, options) => {
+        const minScore = readMinScore(options);
+        const code = await runScanCommand({
+            targetPath: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+            ci: Boolean(options.ci),
+            verbose: Boolean(options.verbose),
+            ...(minScore !== undefined ? { minScore } : {}),
+        });
+        process.exitCode = code;
+    });
+    program
+        .command("scan")
+        .description("Scan a repository for AI coding agent configuration issues (default command)")
+        .argument("[path]", "Repository path to scan")
+        .option("--json", "Emit machine-readable JSON", false)
+        .option("--ci", "CI mode (--min-score ignored until scoring ships)", false)
+        .option("--verbose", "Show timing and extra diagnostics", false)
+        .option("--min-score <number>", "Fail when overall score is below this (no-op until scoring ships)", parseMinScore)
+        .action(async (pathArg, options) => {
+        const minScore = readMinScore(options);
+        const code = await runScanCommand({
+            targetPath: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+            ci: Boolean(options.ci),
+            verbose: Boolean(options.verbose),
+            ...(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),
+        });
+        process.exitCode = code;
+    });
+    program
+        .command("explain")
+        .description("Explain a rule by id")
+        .argument("<rule>", "Rule id, e.g. security/env-file-exposure")
+        .action(async (rule) => {
+        const code = await runExplainCommand(rule);
+        process.exitCode = code;
+    });
+    program
+        .command("doctor")
+        .description("Check AgentDoctor installation health")
+        .action(async () => {
+        const code = await runDoctorCommand();
+        process.exitCode = code;
+    });
+    program.configureOutput({
+        outputError: (str, write) => write(str),
+    });
+    program.exitOverride();
+    return program;
+}
+export async function runCli(argv = process.argv) {
+    const program = createProgram();
+    try {
+        await program.parseAsync(argv);
+    }
+    catch (error) {
+        // Commander throws on --help / --version with exitOverride
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            (error.code === "commander.helpDisplayed" || error.code === "commander.version")) {
+            process.exitCode = EXIT_CODES.SUCCESS;
+            return;
+        }
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            typeof error.code === "string" &&
+            error.code.startsWith("commander.")) {
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+        process.exitCode = EXIT_CODES.INTERNAL_ERROR;
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const PACKAGE_VERSION = "0.1.0-beta";
+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>;
+export declare const AGENT_DISPLAY_NAMES: Record<"cursor" | "claude-code" | "codex", string>;

package/dist/constants.js

@@ -0,0 +1,38 @@
+export const PACKAGE_VERSION = "0.1.0-beta";
+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([
+    ".git",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    ".nuxt",
+    ".svelte-kit",
+    "coverage",
+    ".dart_tool",
+    "target",
+    ".turbo",
+    ".nx",
+    ".cache",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".gradle",
+    ".idea",
+    ".vscode",
+    "Pods",
+    "DerivedData",
+    ".parcel-cache",
+    ".yarn",
+    ".pnpm-store",
+]);
+export const AGENT_DISPLAY_NAMES = {
+    cursor: "Cursor",
+    "claude-code": "Claude Code",
+    codex: "Codex",
+};

package/dist/core/mcp/parse.d.ts

@@ -0,0 +1,7 @@
+import type { McpParseResult } from "./types.js";
+export declare function parseProjectMcpConfigs(root: string, maxFileSizeBytes: number): Promise<McpParseResult>;
+/**
+ * Classify whether a filesystem scope string is overly broad relative to the repo.
+ * Does not follow or read the path.
+ */
+export declare function classifyFilesystemScope(scope: string, root: string): "broad" | "outside" | "ok" | "unknown";