@praneeth_54/agentdoctor 0.2.0-beta → 0.3.0-beta

package/dist/core/fix/plan.js

@@ -0,0 +1,140 @@
+import path from "node:path";
+import { readTextFile } from "../../utils/fs.js";
+import { createIgnoreIndex, parseIgnoreFile, pathMatchesAny } from "../rules/ignore.js";
+import { isSafeContextFixRule, patternForFinding } from "./patterns.js";
+const DEFAULT_MAX_IGNORE_BYTES = 512 * 1024;
+function cursorConfigured(result) {
+    return result.agents.some((a) => a.id === "cursor" && (a.detected || a.configured));
+}
+async function loadCursorignorePatterns(root) {
+    const filePath = path.join(root, ".cursorignore");
+    const text = await readTextFile(filePath, DEFAULT_MAX_IGNORE_BYTES);
+    if (text === null) {
+        return [];
+    }
+    return parseIgnoreFile(text);
+}
+/**
+ * Build a fix plan from a scan result.
+ * Week 1: Cursor `.cursorignore` appends for safe context findings only.
+ */
+export async function buildFixPlan(result) {
+    const root = result.repository.root;
+    const skipped = [];
+    const actionsByKey = new Map();
+    const existingCursorPatterns = await loadCursorignorePatterns(root);
+    const cursorIndex = createIgnoreIndex({
+        gitignorePatterns: [],
+        cursorignorePatterns: existingCursorPatterns,
+    });
+    const hasCursor = cursorConfigured(result);
+    for (const finding of result.findings) {
+        if (finding.fixability !== "safe") {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: finding.fixability === "review"
+                    ? "Requires human review (not auto-fixed)"
+                    : finding.fixability === "manual"
+                        ? "Manual remediation required (not auto-fixed)"
+                        : "Not auto-fixable",
+            });
+            continue;
+        }
+        if (!isSafeContextFixRule(finding.ruleId)) {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: "No automated fixer for this safe rule yet",
+            });
+            continue;
+        }
+        const pattern = patternForFinding(finding);
+        const evidencePath = finding.evidence?.path?.replace(/\\/g, "/");
+        if (!pattern || !evidencePath) {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: "Finding has no usable evidence path",
+            });
+            continue;
+        }
+        const wantsCursor = finding.affectedAgents.includes("cursor");
+        if (wantsCursor && hasCursor) {
+            if (cursorIndex.matchesCursorignore(evidencePath) ||
+                cursorIndex.matchesCursorignore(pattern)) {
+                skipped.push({
+                    findingId: finding.id,
+                    ruleId: finding.ruleId,
+                    reason: "Already excluded by .cursorignore",
+                });
+            }
+            else {
+                mergeCursorAction(actionsByKey, finding, pattern, evidencePath);
+            }
+        }
+        else if (wantsCursor && !hasCursor) {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: "Cursor not detected; skipping .cursorignore fix",
+            });
+        }
+        for (const agent of finding.affectedAgents) {
+            if (agent === "cursor") {
+                continue;
+            }
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: `Fix writer for ${agent} not implemented yet`,
+            });
+        }
+    }
+    return {
+        root,
+        actions: [...actionsByKey.values()].sort((a, b) => a.id.localeCompare(b.id)),
+        skipped,
+    };
+}
+function mergeCursorAction(actionsByKey, finding, pattern, evidencePath) {
+    const key = `cursor:.cursorignore:${pattern}`;
+    const existing = actionsByKey.get(key);
+    if (existing) {
+        if (!existing.findingIds.includes(finding.id)) {
+            existing.findingIds.push(finding.id);
+        }
+        return;
+    }
+    actionsByKey.set(key, {
+        id: key,
+        kind: "append-ignore-pattern",
+        agent: "cursor",
+        targetRelativePath: ".cursorignore",
+        pattern,
+        evidencePath,
+        findingIds: [finding.id],
+        description: `Exclude ${evidencePath} from Cursor agent context via .cursorignore`,
+    });
+}
+/** Patterns that would be newly appended given current file contents. */
+export function missingPatternsForCursorignore(currentContent, patterns) {
+    const existing = currentContent === null ? [] : parseIgnoreFile(currentContent);
+    const missing = [];
+    for (const pattern of patterns) {
+        if (existing.includes(pattern)) {
+            continue;
+        }
+        if (pathMatchesAny(pattern.replace(/\/$/, ""), existing) &&
+            existing.some((p) => p === pattern)) {
+            continue;
+        }
+        // Also skip if an existing pattern already excludes this path
+        const evidenceGuess = pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+        if (pathMatchesAny(evidenceGuess, existing) || pathMatchesAny(pattern, existing)) {
+            continue;
+        }
+        missing.push(pattern);
+    }
+    return missing;
+}

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

@@ -0,0 +1,6 @@
+import type { FixApplyResult, FixPlan } from "./types.js";
+export declare function renderFixPlanTerminal(plan: FixPlan, options: {
+    dryRun: boolean;
+    cursorContent: string | null;
+    applyResult?: FixApplyResult;
+}): string;

package/dist/core/fix/render.js

@@ -0,0 +1,68 @@
+import { previewCursorignoreActions } from "./writers/cursorignore.js";
+export function renderFixPlanTerminal(plan, options) {
+    const lines = [];
+    lines.push("");
+    lines.push(options.dryRun ? "AgentDoctor fix (dry-run)" : "AgentDoctor fix");
+    lines.push("");
+    if (plan.actions.length === 0) {
+        lines.push("  No automatic fixes available for this scan.");
+        if (plan.skipped.length > 0) {
+            lines.push("");
+            lines.push(`  ${plan.skipped.length} finding(s) need manual or review action:`);
+            const reasons = summarizeSkipReasons(plan.skipped.map((s) => s.reason));
+            for (const [reason, count] of reasons) {
+                lines.push(`    - ${reason} (${count})`);
+            }
+            lines.push("");
+            lines.push("  Next: address remaining findings, then run `agentdoctor verify`.");
+        }
+        else {
+            lines.push("  Scan found nothing that Fix can change.");
+        }
+        lines.push("");
+        return lines.join("\n");
+    }
+    lines.push(`  Proposed actions: ${plan.actions.length}`);
+    for (const action of plan.actions) {
+        lines.push(`    • [${action.agent}] ${action.description}`);
+        lines.push(`      pattern: ${action.pattern}`);
+        lines.push(`      findings: ${action.findingIds.length}`);
+    }
+    const preview = previewCursorignoreActions(options.cursorContent, plan.actions);
+    if (preview) {
+        lines.push("");
+        lines.push("  File changes:");
+        lines.push(`    ${preview.targetRelativePath} (+${preview.patternsToAdd.length} pattern(s))`);
+        lines.push("");
+        for (const previewLine of preview.preview.split("\n")) {
+            lines.push(`  ${previewLine}`);
+        }
+    }
+    if (options.applyResult && !options.dryRun) {
+        lines.push("");
+        if (options.applyResult.writtenFiles.length > 0) {
+            lines.push(`  Wrote: ${options.applyResult.writtenFiles.join(", ")}`);
+        }
+        else {
+            lines.push("  No files written.");
+        }
+    }
+    else if (options.dryRun) {
+        lines.push("");
+        lines.push("  No files were modified (dry-run).");
+        lines.push("  Re-run without --dry-run to apply.");
+    }
+    if (plan.skipped.length > 0) {
+        lines.push("");
+        lines.push(`  Skipped: ${plan.skipped.length} finding(s) (writers pending or already fixed)`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function summarizeSkipReasons(reasons) {
+    const map = new Map();
+    for (const reason of reasons) {
+        map.set(reason, (map.get(reason) ?? 0) + 1);
+    }
+    return [...map.entries()].sort((a, b) => b[1] - a[1]);
+}

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

@@ -0,0 +1,15 @@
+import type { FixApplyResult, FixPlan } from "./types.js";
+export interface RunFixOptions {
+    cwd: string;
+    dryRun: boolean;
+    yes: boolean;
+}
+export interface RunFixResult {
+    plan: FixPlan;
+    applyResult: FixApplyResult;
+    cancelled: boolean;
+}
+/**
+ * Scan → plan → (confirm) → apply Safe Repository Mutation actions.
+ */
+export declare function runFix(options: RunFixOptions): Promise<RunFixResult>;

package/dist/core/fix/run.js

@@ -0,0 +1,54 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { scan } from "../scanner/scan.js";
+import { applyFixPlan, readCursorignore } from "./apply.js";
+import { buildFixPlan } from "./plan.js";
+import { renderFixPlanTerminal } from "./render.js";
+/**
+ * Scan → plan → (confirm) → apply Safe Repository Mutation actions.
+ */
+export async function runFix(options) {
+    const result = await scan({ cwd: options.cwd });
+    const plan = await buildFixPlan(result);
+    const cursorContent = await readCursorignore(plan.root);
+    if (plan.actions.length === 0 || options.dryRun) {
+        const applyResult = await applyFixPlan(plan, { dryRun: true });
+        return { plan, applyResult, cancelled: false };
+    }
+    if (!options.yes) {
+        const previewText = renderFixPlanTerminal(plan, {
+            dryRun: true,
+            cursorContent,
+        });
+        process.stdout.write(previewText);
+        const confirmed = await confirm("Apply these changes?");
+        if (!confirmed) {
+            return {
+                plan,
+                applyResult: {
+                    plan,
+                    dryRun: true,
+                    writtenFiles: [],
+                    changedFiles: [],
+                },
+                cancelled: true,
+            };
+        }
+    }
+    const applyResult = await applyFixPlan(plan, { dryRun: false });
+    return { plan, applyResult, cancelled: false };
+}
+async function confirm(question) {
+    if (!input.isTTY || !output.isTTY) {
+        process.stderr.write("Error: confirmation required but stdin is not a TTY. Re-run with --yes or --dry-run.\n");
+        return false;
+    }
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(`${question} [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { AgentId } from "../../types/index.js";
+export type FixKind = "append-ignore-pattern";
+/** Allowlisted relative paths fix may create or modify. */
+export declare const FIX_PATH_ALLOWLIST: readonly [".cursorignore"];
+export type FixAllowlistedPath = (typeof FIX_PATH_ALLOWLIST)[number];
+export interface FixAction {
+    id: string;
+    kind: FixKind;
+    agent: AgentId;
+    targetRelativePath: FixAllowlistedPath;
+    /** Ignore pattern to ensure is present (gitignore-style). */
+    pattern: string;
+    /** Evidence path this pattern is meant to exclude. */
+    evidencePath: string;
+    findingIds: string[];
+    description: string;
+}
+export interface SkippedFix {
+    findingId: string;
+    ruleId: string;
+    reason: string;
+}
+export interface FixPlan {
+    root: string;
+    actions: FixAction[];
+    skipped: SkippedFix[];
+}
+export interface FixApplyResult {
+    plan: FixPlan;
+    dryRun: boolean;
+    writtenFiles: string[];
+    /** Relative paths that would be / were written */
+    changedFiles: string[];
+}

package/dist/core/fix/types.js

@@ -0,0 +1,2 @@
+/** Allowlisted relative paths fix may create or modify. */
+export const FIX_PATH_ALLOWLIST = [".cursorignore"];

package/dist/core/fix/writers/cursorignore.d.ts

@@ -0,0 +1,13 @@
+import type { FixAction } from "../types.js";
+export interface CursorignoreWritePreview {
+    targetRelativePath: ".cursorignore";
+    patternsToAdd: string[];
+    before: string;
+    after: string;
+    /** Unified-diff-like preview (simplified). */
+    preview: string;
+}
+export declare function buildCursorignoreContent(currentContent: string | null, patternsToAdd: string[]): string;
+export declare function previewCursorignoreActions(currentContent: string | null, actions: FixAction[]): CursorignoreWritePreview | null;
+export declare function readCursorignore(root: string): Promise<string | null>;
+export declare function writeCursorignore(root: string, content: string): Promise<void>;

package/dist/core/fix/writers/cursorignore.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readTextFile } from "../../../utils/fs.js";
+import { missingPatternsForCursorignore } from "../plan.js";
+const MAX_BYTES = 512 * 1024;
+const BANNER = "# Added by AgentDoctor";
+export function buildCursorignoreContent(currentContent, patternsToAdd) {
+    if (patternsToAdd.length === 0) {
+        return currentContent ?? "";
+    }
+    const base = currentContent ?? "";
+    const trimmed = base.replace(/\s+$/, "");
+    const block = [BANNER, ...patternsToAdd].join("\n");
+    if (trimmed.length === 0) {
+        return `${block}\n`;
+    }
+    return `${trimmed}\n\n${block}\n`;
+}
+export function previewCursorignoreActions(currentContent, actions) {
+    const cursorActions = actions.filter((a) => a.agent === "cursor" && a.targetRelativePath === ".cursorignore");
+    if (cursorActions.length === 0) {
+        return null;
+    }
+    const requested = [...new Set(cursorActions.map((a) => a.pattern))];
+    const patternsToAdd = missingPatternsForCursorignore(currentContent, requested);
+    if (patternsToAdd.length === 0) {
+        return null;
+    }
+    const before = currentContent ?? "";
+    const after = buildCursorignoreContent(currentContent, patternsToAdd);
+    const preview = formatSimpleDiff(".cursorignore", before, after);
+    return {
+        targetRelativePath: ".cursorignore",
+        patternsToAdd,
+        before,
+        after,
+        preview,
+    };
+}
+export async function readCursorignore(root) {
+    return readTextFile(path.join(root, ".cursorignore"), MAX_BYTES);
+}
+export async function writeCursorignore(root, content) {
+    const target = path.join(root, ".cursorignore");
+    const dir = path.dirname(target);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.cursorignore.agentdoctor.${process.pid}.tmp`);
+    await fs.writeFile(tmp, content, "utf8");
+    await fs.rename(tmp, target);
+}
+function formatSimpleDiff(fileLabel, before, after) {
+    const beforeLines = before.length === 0 ? [] : before.split(/\r?\n/);
+    const afterLines = after.split(/\r?\n/);
+    const lines = [];
+    lines.push(`--- a/${fileLabel}`);
+    lines.push(`+++ b/${fileLabel}`);
+    // Show only newly added trailing block for clarity
+    const addedStart = beforeLines.length === 0 ? 0 : beforeLines.length;
+    for (let i = addedStart; i < afterLines.length; i++) {
+        const line = afterLines[i];
+        if (line === undefined) {
+            continue;
+        }
+        // Skip pure trailing empty presentation noise except keep structure
+        lines.push(`+${line}`);
+    }
+    if (before.length === 0) {
+        lines.splice(2, 0, "@@ new file @@");
+    }
+    else {
+        lines.splice(2, 0, "@@ append @@");
+    }
+    return lines.join("\n");
+}

package/dist/core/rules/context/generated-directory.js

@@ -1,3 +1,4 @@
+import { isSampleOrTestPath, isSourceNamedArtifactCollision } from "../path-kind.js";
 /** Directories commonly generated/build-related. vendor/ is ecosystem-aware. */
 const GENERATED = [
     { name: "dist", label: "build output" },
@@ -34,6 +35,12 @@ export const generatedDirectoryRule = {
         for (const entry of GENERATED) {
             const matches = context.discovery.directoriesSkipped.filter((dir) => isGeneratedPath(dir, entry.name));
             for (const relativePath of matches) {
+                if (isSampleOrTestPath(relativePath)) {
+                    continue;
+                }
+                if (isSourceNamedArtifactCollision(relativePath)) {
+                    continue;
+                }
                 if (isExcluded(context, relativePath)) {
                     continue;
                 }
@@ -57,6 +64,9 @@ export const generatedDirectoryRule = {
             !context.repository.packageManagers.includes("composer") &&
             context.repository.primaryLanguage !== "php") {
             for (const relativePath of vendorPaths) {
+                if (isSampleOrTestPath(relativePath)) {
+                    continue;
+                }
                 if (isExcluded(context, relativePath)) {
                     continue;
                 }

package/dist/core/rules/instructions/missing-path-reference.js

@@ -12,6 +12,73 @@ const INSTRUCTION_KINDS = new Set([
 ]);
 /** Extensions accepted for bare filenames (no `/`) — precision over recall. */
 const BARE_FILE_EXTENSION = /\.(mdc?|txt|tsx?|jsx?|mjs|cjs|json|ya?ml|toml|php|py|rb|go|rs|java|kt|css|scss|html|vue|svelte|sh|bash|zsh|sql|xml|svg|png|jpe?g|gif|webp|wasm|lock)$/i;
+/** Host-like first segments for Go/npm module paths (`github.com/…`, `golang.org/…`). */
+const MODULE_HOST_SEGMENT = /^(?:[a-z0-9-]+\.)+(?:com|org|net|io|dev|ai|app|cloud|co|edu|gov|info|me|tv|xyz|in|to|cc)$/i;
+/** Control-flow / language tokens that appear as `a/b` in prose, not filesystem paths. */
+const CODE_SLASH_TOKEN = /^(?:try\/finally|if\/else|for\/of|for\/in|async\/await|do\/while)$/i;
+/**
+ * First path segment of Go standard-library import paths (`io/ioutil`, `net/http`).
+ * Kept narrow so `src/utils`-style repo paths still validate.
+ */
+const GO_STDLIB_ROOTS = new Set([
+    "archive",
+    "bufio",
+    "bytes",
+    "cmp",
+    "compress",
+    "container",
+    "context",
+    "crypto",
+    "database",
+    "debug",
+    "embed",
+    "encoding",
+    "errors",
+    "expvar",
+    "flag",
+    "fmt",
+    "go",
+    "hash",
+    "html",
+    "image",
+    "index",
+    "io",
+    "log",
+    "maps",
+    "math",
+    "mime",
+    "net",
+    "os",
+    "path",
+    "plugin",
+    "reflect",
+    "regexp",
+    "runtime",
+    "slices",
+    "structs",
+    "sync",
+    "syscall",
+    "testing",
+    "text",
+    "time",
+    "unicode",
+    "unique",
+    "unsafe",
+    "weak",
+]);
+/** Optional build-output roots often documented before `npm run build`. */
+const OPTIONAL_BUILD_ROOTS = new Set(["dist", "build", "out", "target", ".next", "coverage"]);
+function isGoStdImportPath(normalized) {
+    const parts = normalized.split("/");
+    if (parts.length < 2 || parts.length > 4) {
+        return false;
+    }
+    const root = parts[0] ?? "";
+    if (!GO_STDLIB_ROOTS.has(root)) {
+        return false;
+    }
+    return parts.every((part) => /^[a-z][a-z0-9]*$/.test(part));
+}
 function stripAnchor(value) {
     return value.split("#")[0] ?? value;
 }
@@ -42,12 +109,34 @@ export function isLikelyLocalPathReference(value) {
     // CSS class / id-like bare selectors: `.content`, `.button`
     if (/^\.[A-Za-z_][\w-]*$/.test(value))
         return false;
+    // npm scoped packages: `@scope/name`
+    if (/^@[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+/.test(value))
+        return false;
+    // Glob / brace patterns are not concrete paths
+    if (/[*?[\]{}]/.test(value))
+        return false;
+    // Language tokens that look like paths (`try/finally`)
+    if (CODE_SLASH_TOKEN.test(value))
+        return false;
+    const withoutDotSlash = value.replace(/^\.\//, "");
+    const trimmedDir = withoutDotSlash.replace(/\/+$/, "");
+    // Documented build outputs often missing until a local build
+    if (OPTIONAL_BUILD_ROOTS.has(trimmedDir))
+        return false;
     if (value.includes("/")) {
-        // Reject empty segments like `foo//bar` while allowing trailing slash dirs
         const normalized = value.replace(/\/+$/, "");
         if (!normalized || normalized.split("/").some((part) => part === "")) {
             return false;
         }
+        const firstSegment = normalized.split("/")[0] ?? "";
+        // Go/npm module imports: `github.com/foo/bar`, `golang.org/x/…`
+        if (MODULE_HOST_SEGMENT.test(firstSegment)) {
+            return false;
+        }
+        // Go stdlib: `io/ioutil`, `net/http`, `path/filepath`
+        if (isGoStdImportPath(normalized)) {
+            return false;
+        }
         return true;
     }
     // Bare filename: require a known file extension (not `.content`-style tokens)

package/dist/core/rules/path-kind.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared path classification for rule precision.
+ * Paths under intentional sample/test/demo trees are not production secrets for agent readiness.
+ */
+/**
+ * True when any path segment marks fixture, test, example, or sample material.
+ * Uses POSIX relative paths (discovery output).
+ */
+export declare function isSampleOrTestPath(relativePath: string): boolean;
+/**
+ * True for paths like `scripts/build` or `internal/build` that are source trees
+ * named after a common artifact directory, not generated output.
+ */
+export declare function isSourceNamedArtifactCollision(relativePath: string): boolean;

package/dist/core/rules/path-kind.js

@@ -0,0 +1,77 @@
+/**
+ * Shared path classification for rule precision.
+ * Paths under intentional sample/test/demo trees are not production secrets for agent readiness.
+ */
+const SAMPLE_DIRECTORY_NAMES = new Set([
+    "example",
+    "examples",
+    "fixture",
+    "fixtures",
+    "__fixtures__",
+    "integration",
+    "integrations",
+    "mock",
+    "mocks",
+    "__mocks__",
+    "sample",
+    "samples",
+    "test",
+    "tests",
+    "__tests__",
+    "testdata",
+    "test_data",
+]);
+/** Artifact dir names that commonly collide with source packages (`scripts/build`, `internal/build`). */
+const ARTIFACT_NAMES_WITH_SOURCE_COLLISIONS = new Set(["build", "target"]);
+/**
+ * Parent dirs that host source code packages/modules, not generated output trees.
+ * `packages/foo/dist` is still treated as generated (parent is the package name).
+ */
+const SOURCE_CODE_PARENT_DIRS = new Set([
+    "bin",
+    "cmd",
+    "internal",
+    "lib",
+    "pkg",
+    "script",
+    "scripts",
+    "src",
+]);
+/**
+ * True when any path segment marks fixture, test, example, or sample material.
+ * Uses POSIX relative paths (discovery output).
+ */
+export function isSampleOrTestPath(relativePath) {
+    if (!relativePath) {
+        return false;
+    }
+    const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!normalized) {
+        return false;
+    }
+    return normalized.split("/").some((segment) => SAMPLE_DIRECTORY_NAMES.has(segment.toLowerCase()));
+}
+/**
+ * True for paths like `scripts/build` or `internal/build` that are source trees
+ * named after a common artifact directory, not generated output.
+ */
+export function isSourceNamedArtifactCollision(relativePath) {
+    if (!relativePath) {
+        return false;
+    }
+    const parts = relativePath
+        .replace(/\\/g, "/")
+        .replace(/^\.\//, "")
+        .replace(/\/+$/, "")
+        .split("/")
+        .filter(Boolean);
+    if (parts.length < 2) {
+        return false;
+    }
+    const leaf = parts[parts.length - 1].toLowerCase();
+    if (!ARTIFACT_NAMES_WITH_SOURCE_COLLISIONS.has(leaf)) {
+        return false;
+    }
+    const parent = parts[parts.length - 2].toLowerCase();
+    return SOURCE_CODE_PARENT_DIRS.has(parent);
+}