@praneeth_54/agentdoctor 0.1.0-beta

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

@@ -0,0 +1,87 @@
+const ENV_BASENAME = /^\.env(\..+)?$/i;
+function isEnvFile(relativePath) {
+    const base = relativePath.split("/").pop() ?? relativePath;
+    return ENV_BASENAME.test(base);
+}
+function agentsWithoutClearExclusion(context, relativePath) {
+    const affected = [];
+    for (const agent of context.agents) {
+        if (!agent.detected && !agent.configured) {
+            continue;
+        }
+        if (agent.id === "cursor") {
+            if (!context.ignore.isExcludedForCursor(relativePath)) {
+                affected.push("cursor");
+            }
+            continue;
+        }
+        if (agent.id === "claude-code") {
+            affected.push("claude-code");
+            continue;
+        }
+        if (agent.id === "codex") {
+            affected.push("codex");
+        }
+    }
+    return affected;
+}
+async function claudeDeniesRead(context, relativePath) {
+    const settingsFiles = context.agents
+        .find((a) => a.id === "claude-code")
+        ?.configFiles.filter((f) => f.kind === "claude-settings" || f.kind === "claude-settings-local") ?? [];
+    for (const file of settingsFiles) {
+        const cached = await context.textCache.read(file.relativePath);
+        if (!cached.text)
+            continue;
+        const patterns = [
+            `Read(./${relativePath})`,
+            `Read(${relativePath})`,
+            `Read(/**/${relativePath.split("/").pop()})`,
+        ];
+        if (patterns.some((p) => cached.text.includes(p))) {
+            return true;
+        }
+        if (/"deny"\s*:\s*\[[^\]]*"Read"\s*[,\]]/.test(cached.text)) {
+            return true;
+        }
+    }
+    return false;
+}
+export const envFileExposureRule = {
+    id: "security/env-file-exposure",
+    title: "Sensitive environment file may enter agent context",
+    description: "Detects repository .env files when configured AI agents may be able to access them.",
+    category: "security",
+    severity: "critical",
+    fixability: "review",
+    rationale: "Environment files often contain credentials. If an AI coding agent can read them, secrets may enter model context.",
+    recommendation: "Exclude the file from AI agent context (for example .cursorignore / Claude Code Read deny rules) and ensure it is not committed.",
+    async check(context) {
+        const findings = [];
+        const candidates = context.discovery.files.filter((f) => isEnvFile(f.relativePath));
+        for (const file of candidates) {
+            let affected = agentsWithoutClearExclusion(context, file.relativePath);
+            if (affected.includes("claude-code")) {
+                if (await claudeDeniesRead(context, file.relativePath)) {
+                    affected = affected.filter((a) => a !== "claude-code");
+                }
+            }
+            if (affected.length === 0) {
+                continue;
+            }
+            findings.push({
+                ruleId: "security/env-file-exposure",
+                category: "security",
+                severity: "critical",
+                title: "Sensitive environment file may enter agent context",
+                message: `Sensitive environment file detected and no relevant exclusion was found for: ${file.relativePath}`,
+                whyItMatters: "Environment files frequently hold API keys and credentials. If readable by an AI coding agent, those values may be included in prompts or logs.",
+                recommendation: "Add an agent-specific exclusion (for example .cursorignore or a Claude Code Read deny rule), keep the file out of version control, and rotate any credentials that may have been exposed.",
+                affectedAgents: affected,
+                evidence: { path: file.relativePath },
+                fixability: "review",
+            });
+        }
+        return findings;
+    },
+};

package/dist/core/rules/security/mcp-broad-filesystem.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from "../types.js";
+export declare const mcpBroadFilesystemRule: RuleDefinition;

package/dist/core/rules/security/mcp-broad-filesystem.js

@@ -0,0 +1,42 @@
+import { classifyFilesystemScope } from "../../mcp/parse.js";
+export const mcpBroadFilesystemRule = {
+    id: "security/mcp-broad-filesystem",
+    title: "MCP filesystem server has broad or out-of-repo scope",
+    description: "Detects MCP filesystem-related path arguments that point at / , home, or paths outside the repository.",
+    category: "security",
+    severity: "critical",
+    fixability: "review",
+    rationale: "An MCP filesystem server scoped to the entire machine can expose secrets far beyond the project.",
+    recommendation: "Limit filesystem MCP servers to the repository root (or a specific subdirectory) and avoid / , ~, and $HOME scopes.",
+    async check(context) {
+        const findings = [];
+        for (const server of context.mcpServers) {
+            if (server.parseError) {
+                continue;
+            }
+            const scopes = server.filesystemScopes ?? [];
+            for (const scope of scopes) {
+                const classification = classifyFilesystemScope(scope, context.root);
+                if (classification !== "broad" && classification !== "outside") {
+                    continue;
+                }
+                findings.push({
+                    ruleId: "security/mcp-broad-filesystem",
+                    category: "security",
+                    severity: "critical",
+                    title: "MCP filesystem server has broad or out-of-repo scope",
+                    message: `MCP server "${server.name}" configures filesystem scope "${scope}" (${classification})`,
+                    whyItMatters: "Broad filesystem MCP scopes can let an agent read files outside the project, including credentials and unrelated personal data.",
+                    recommendation: "Point the filesystem server at the repository directory only. Do not use /, ~, or $HOME.",
+                    affectedAgents: [server.sourceAgent],
+                    evidence: {
+                        path: server.sourcePath,
+                        detail: `server=${server.name}; scope=${scope}`,
+                    },
+                    fixability: "review",
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/core/rules/security/private-key-file.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from "../types.js";
+export declare const privateKeyFileRule: RuleDefinition;

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

@@ -0,0 +1,60 @@
+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" },
+    { test: (b) => /^id_ecdsa$/i.test(b), label: "SSH private key" },
+    {
+        test: (b) => /\.pem$/i.test(b) && !/cert|certificate|public|ca-bundle/i.test(b),
+        label: "PEM private key",
+    },
+    { test: (b) => /\.p12$/i.test(b), label: "PKCS#12 credential bundle" },
+    { test: (b) => /\.pfx$/i.test(b), label: "PKCS#12 credential bundle" },
+    { test: (b) => /^credentials\.json$/i.test(b), label: "credentials file" },
+    { test: (b) => /service-account.*\.json$/i.test(b), label: "service account key" },
+    {
+        test: (b) => /\.key$/i.test(b) && !/public|pub/i.test(b),
+        label: "private key file",
+    },
+];
+function classify(base) {
+    for (const pattern of PRIVATE_KEY_PATTERNS) {
+        if (pattern.test(base)) {
+            return pattern.label;
+        }
+    }
+    return null;
+}
+export const privateKeyFileRule = {
+    id: "security/private-key-file",
+    title: "Private key or credential file present in repository",
+    description: "Detects high-confidence private key / credential filenames inside the repository tree.",
+    category: "security",
+    severity: "critical",
+    fixability: "manual",
+    rationale: "Private keys and service-account credentials in a repository are high-risk if accessible to agents or collaborators.",
+    recommendation: "Remove the credential from the repository, rotate it, and store secrets in a secret manager or local-only location excluded from agents.",
+    async check(context) {
+        const findings = [];
+        const affected = context.agents.filter((a) => a.detected || a.configured).map((a) => a.id);
+        const agents = affected.length > 0 ? affected : ["cursor", "claude-code", "codex"];
+        for (const file of context.discovery.files) {
+            const base = file.relativePath.split("/").pop() ?? file.relativePath;
+            const label = classify(base);
+            if (!label) {
+                continue;
+            }
+            findings.push({
+                ruleId: "security/private-key-file",
+                category: "security",
+                severity: "critical",
+                title: "Private key or credential file present in repository",
+                message: `Possible ${label} detected at ${file.relativePath}`,
+                whyItMatters: "Credential material in the working tree can be read by AI coding agents and may leak into model context or logs. Filename heuristics only — contents were not inspected.",
+                recommendation: "Remove the file from the repository, rotate the credential, add ignore rules, and never commit replacements.",
+                affectedAgents: [...agents],
+                evidence: { path: file.relativePath, detail: label },
+                fixability: "manual",
+            });
+        }
+        return findings;
+    },
+};

package/dist/core/rules/text-cache.d.ts

@@ -0,0 +1,19 @@
+export interface CachedText {
+    relativePath: string;
+    text: string | null;
+    sizeBytes: number;
+    empty: boolean;
+    binary: boolean;
+    error?: string;
+}
+/**
+ * Bounded UTF-8 text reader with per-path caching.
+ * Skips binaries and oversized files without throwing.
+ */
+export declare class TextCache {
+    private readonly root;
+    private readonly maxBytes;
+    private readonly cache;
+    constructor(root: string, maxBytes: number);
+    read(relativePath: string): Promise<CachedText>;
+}

package/dist/core/rules/text-cache.js

@@ -0,0 +1,112 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isPathInsideRoot, toPosixRelative } from "../../utils/path.js";
+/**
+ * Bounded UTF-8 text reader with per-path caching.
+ * Skips binaries and oversized files without throwing.
+ */
+export class TextCache {
+    root;
+    maxBytes;
+    cache = new Map();
+    constructor(root, maxBytes) {
+        this.root = root;
+        this.maxBytes = maxBytes;
+    }
+    async read(relativePath) {
+        const existing = this.cache.get(relativePath);
+        if (existing) {
+            return existing;
+        }
+        const absolute = path.resolve(this.root, relativePath);
+        if (!isPathInsideRoot(this.root, absolute)) {
+            const blocked = {
+                relativePath,
+                text: null,
+                sizeBytes: 0,
+                empty: true,
+                binary: false,
+                error: "Path escapes repository root",
+            };
+            this.cache.set(relativePath, blocked);
+            return blocked;
+        }
+        try {
+            const stat = await fs.stat(absolute);
+            if (!stat.isFile()) {
+                const result = {
+                    relativePath: toPosixRelative(this.root, absolute),
+                    text: null,
+                    sizeBytes: 0,
+                    empty: true,
+                    binary: false,
+                    error: "Not a regular file",
+                };
+                this.cache.set(relativePath, result);
+                return result;
+            }
+            const sizeBytes = Number(stat.size);
+            if (sizeBytes > this.maxBytes) {
+                const result = {
+                    relativePath,
+                    text: null,
+                    sizeBytes,
+                    empty: false,
+                    binary: false,
+                    error: "File exceeds max read size",
+                };
+                this.cache.set(relativePath, result);
+                return result;
+            }
+            const buffer = await fs.readFile(absolute);
+            if (looksBinary(buffer)) {
+                const result = {
+                    relativePath,
+                    text: null,
+                    sizeBytes,
+                    empty: sizeBytes === 0,
+                    binary: true,
+                    error: "Binary file skipped",
+                };
+                this.cache.set(relativePath, result);
+                return result;
+            }
+            const text = buffer.toString("utf8");
+            const result = {
+                relativePath,
+                text,
+                sizeBytes,
+                empty: text.trim().length === 0,
+                binary: false,
+            };
+            this.cache.set(relativePath, result);
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unable to read file";
+            const result = {
+                relativePath,
+                text: null,
+                sizeBytes: 0,
+                empty: true,
+                binary: false,
+                error: message,
+            };
+            this.cache.set(relativePath, result);
+            return result;
+        }
+    }
+}
+function looksBinary(buffer) {
+    const sample = buffer.subarray(0, Math.min(buffer.length, 8000));
+    if (sample.includes(0)) {
+        return true;
+    }
+    let suspicious = 0;
+    for (const byte of sample) {
+        if (byte < 7 || (byte > 13 && byte < 32)) {
+            suspicious += 1;
+        }
+    }
+    return suspicious / Math.max(sample.length, 1) > 0.3;
+}

package/dist/core/rules/thresholds.d.ts

@@ -0,0 +1,13 @@
+/** Shared deterministic thresholds for context/instruction rules. */
+export declare const THRESHOLDS: {
+    /** Instruction file size (bytes) — info */
+    readonly instructionInfoBytes: number;
+    /** Instruction file size (bytes) — warning */
+    readonly instructionWarningBytes: number;
+    /** Log / dump file size that may pollute context */
+    readonly largeLogBytes: number;
+    /** Unusually large lockfile (info only) */
+    readonly largeLockfileBytes: number;
+    /** Minimum content length before duplicate detection applies */
+    readonly duplicateMinChars: 80;
+};

package/dist/core/rules/thresholds.js

@@ -0,0 +1,13 @@
+/** Shared deterministic thresholds for context/instruction rules. */
+export const THRESHOLDS = {
+    /** Instruction file size (bytes) — info */
+    instructionInfoBytes: 16 * 1024,
+    /** Instruction file size (bytes) — warning */
+    instructionWarningBytes: 32 * 1024,
+    /** Log / dump file size that may pollute context */
+    largeLogBytes: 256 * 1024,
+    /** Unusually large lockfile (info only) */
+    largeLockfileBytes: 2 * 1024 * 1024,
+    /** Minimum content length before duplicate detection applies */
+    duplicateMinChars: 80,
+};

package/dist/core/rules/types.d.ts

@@ -0,0 +1,57 @@
+import type { AgentDetectionResult } from "../../agents/types.js";
+import type { AgentId, DiscoveryResult, DiscoveredFile, Finding, RepositoryInfo, RuleCategory, Severity } from "../../types/index.js";
+import type { McpServerConfig } from "../mcp/types.js";
+import type { IgnoreIndex } from "./ignore.js";
+import type { TextCache } from "./text-cache.js";
+export type Fixability = "safe" | "review" | "manual" | "none";
+export interface RuleDefinition {
+    id: string;
+    title: string;
+    description: string;
+    category: RuleCategory;
+    severity: Severity;
+    /** Agents this rule typically concerns; findings may narrow further. */
+    affectedAgents?: AgentId[];
+    fixability: Fixability;
+    rationale: string;
+    recommendation: string;
+    check(context: RuleContext): Promise<FindingDraft[]>;
+}
+/**
+ * Draft finding produced by a rule before ID assignment / deduplication.
+ */
+export interface FindingDraft {
+    ruleId: string;
+    category: RuleCategory;
+    severity: Severity;
+    title: string;
+    message: string;
+    whyItMatters: string;
+    recommendation?: string;
+    affectedAgents: AgentId[];
+    evidence?: {
+        path?: string;
+        line?: number;
+        detail?: string;
+    };
+    fixability: Fixability;
+}
+export interface RuleContext {
+    root: string;
+    repository: RepositoryInfo;
+    discovery: DiscoveryResult;
+    agents: AgentDetectionResult[];
+    ignore: IgnoreIndex;
+    mcpServers: McpServerConfig[];
+    textCache: TextCache;
+    maxFileSizeBytes: number;
+    /** Instruction/config files discovered by agent adapters (unique relative paths). */
+    instructionFiles: DiscoveredFile[];
+}
+export interface FindingsSummary {
+    critical: number;
+    warning: number;
+    info: number;
+    total: number;
+}
+export declare function finalizeFinding(draft: FindingDraft): Finding;

package/dist/core/rules/types.js

@@ -0,0 +1,23 @@
+export function finalizeFinding(draft) {
+    const pathKey = draft.evidence?.path?.replace(/\\/g, "/") ?? "repo";
+    const detailKey = draft.evidence?.detail?.replace(/\\/g, "/") ?? "";
+    const id = detailKey.length > 0 ? `${draft.ruleId}:${pathKey}:${detailKey}` : `${draft.ruleId}:${pathKey}`;
+    const finding = {
+        id,
+        ruleId: draft.ruleId,
+        category: draft.category,
+        severity: draft.severity,
+        title: draft.title,
+        message: draft.message,
+        whyItMatters: draft.whyItMatters,
+        affectedAgents: [...new Set(draft.affectedAgents)].sort(),
+        fixability: draft.fixability,
+    };
+    if (draft.recommendation !== undefined) {
+        finding.recommendation = draft.recommendation;
+    }
+    if (draft.evidence !== undefined) {
+        finding.evidence = { ...draft.evidence };
+    }
+    return finding;
+}

package/dist/core/scanner/scan.d.ts

@@ -0,0 +1,7 @@
+import type { ScanOptions, ScanResult } from "../../types/index.js";
+/**
+ * Public scan entry point.
+ * Pipeline: discovery → project detection → agent adapters → rule engine → findings.
+ * Readiness scoring is reserved for a later release (`scores` remains null for now).
+ */
+export declare function scan(options?: ScanOptions): Promise<ScanResult>;

package/dist/core/scanner/scan.js

@@ -0,0 +1,70 @@
+import { detectAgents } from "../../agents/detect-agents.js";
+import { PACKAGE_VERSION, DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
+import { sanitizeTerminalText } from "../../security/redaction.js";
+import { buildRuleContext } from "../rules/build-context.js";
+import { runRules } from "../rules/run-rules.js";
+/**
+ * Public scan entry point.
+ * Pipeline: discovery → project detection → agent adapters → rule engine → findings.
+ * Readiness scoring is reserved for a later release (`scores` remains null for now).
+ */
+export async function scan(options = {}) {
+    const totalStarted = performance.now();
+    const cwd = options.cwd ?? process.cwd();
+    const maxFileSizeBytes = options.maxFileSizeBytes ?? DEFAULT_MAX_FILE_SIZE_BYTES;
+    const detectionStarted = performance.now();
+    const { repository, discovery, diagnostics } = await detectProject(cwd, maxFileSizeBytes);
+    const detectionMs = Math.round(performance.now() - detectionStarted);
+    const { agents, elapsedMs: agentsMs } = await detectAgents({
+        root: repository.root,
+        discovery,
+        maxFileSizeBytes,
+    });
+    const ruleContext = await buildRuleContext({
+        root: repository.root,
+        repository,
+        discovery,
+        agents,
+        maxFileSizeBytes,
+    });
+    const { findings, summary, elapsedMs: rulesMs, ruleErrors, } = await runRules({
+        context: ruleContext,
+        ...(options.includeRules !== undefined ? { includeRules: options.includeRules } : {}),
+        ...(options.excludeRules !== undefined ? { excludeRules: options.excludeRules } : {}),
+    });
+    const warnings = [...diagnostics];
+    for (const agent of agents) {
+        for (const diagnostic of agent.diagnostics) {
+            if (diagnostic.severity === "info") {
+                continue;
+            }
+            const location = diagnostic.file ? ` (${sanitizeTerminalText(diagnostic.file)})` : "";
+            warnings.push(`${sanitizeTerminalText(diagnostic.message)}${location}`);
+        }
+    }
+    for (const error of ruleErrors) {
+        warnings.push(sanitizeTerminalText(error));
+    }
+    return {
+        version: PACKAGE_VERSION,
+        repository,
+        agents,
+        findings,
+        summary,
+        scores: null,
+        scoringAvailable: false,
+        timing: {
+            discoveryMs: discovery.elapsedMs,
+            detectionMs,
+            agentsMs,
+            rulesMs,
+            scoringMs: 0,
+            totalMs: Math.round(performance.now() - totalStarted),
+        },
+        diagnostics: {
+            warnings,
+            errors: [],
+        },
+    };
+}

package/dist/core/scoring/placeholder.d.ts

@@ -0,0 +1,7 @@
+import type { Scores } from "../../types/index.js";
+/**
+ * Internal scoring stub retained for upcoming readiness scores.
+ * Production scans currently return `scores: null`.
+ * A clean undetected-agent repo stays below 100 by design.
+ */
+export declare function computePlaceholderScores(filesScanned: number): Scores;

package/dist/core/scoring/placeholder.js

@@ -0,0 +1,29 @@
+/**
+ * Internal scoring stub retained for upcoming readiness scores.
+ * Production scans currently return `scores: null`.
+ * A clean undetected-agent repo stays below 100 by design.
+ */
+export function computePlaceholderScores(filesScanned) {
+    const base = 72;
+    const fileBonus = Math.min(8, Math.floor(filesScanned / 25));
+    const overall = clamp(base + fileBonus);
+    return {
+        overall,
+        categories: {
+            security: clamp(overall + 4),
+            context: clamp(overall - 6),
+            instructions: clamp(overall - 10),
+            mcp: clamp(overall - 8),
+            compatibility: clamp(overall - 4),
+            performance: clamp(overall),
+        },
+        agents: {
+            cursor: clamp(overall - 5),
+            "claude-code": clamp(overall - 8),
+            codex: clamp(overall - 6),
+        },
+    };
+}
+function clamp(value) {
+    return Math.max(0, Math.min(100, Math.round(value)));
+}

package/dist/detectors/framework.d.ts

@@ -0,0 +1,17 @@
+import type { FrameworkId } from "../types/index.js";
+export interface FrameworkDetectionInput {
+    relativePaths: string[];
+    packageJsonDependencies?: Record<string, string>;
+    composerJsonRequire?: Record<string, string>;
+    pubspecName?: string;
+}
+export interface FrameworkDetectionResult {
+    frameworks: FrameworkId[];
+    primaryFramework: FrameworkId;
+}
+/**
+ * Detect frameworks from config markers and dependency names.
+ * Does not fail when nothing matches — returns unknown.
+ */
+export declare function detectFrameworks(input: FrameworkDetectionInput): FrameworkDetectionResult;
+export declare function formatFramework(framework: FrameworkId): string;