@praneeth_54/agentdoctor 0.2.0-beta → 1.0.0

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

@@ -1,3 +1,6 @@
+import { claudeDeniesPath } from "../claude-deny.js";
+import { codexDeniesPath } from "../codex-deny.js";
+import { isCheckedInGithubActionDist, isSampleOrTestPath, isSourceNamedArtifactCollision, } from "../path-kind.js";
 /** Directories commonly generated/build-related. vendor/ is ecosystem-aware. */
 const GENERATED = [
     { name: "dist", label: "build output" },
@@ -12,9 +15,27 @@ const GENERATED = [
 function isGeneratedPath(relativePath, name) {
     return relativePath === name || relativePath.endsWith(`/${name}`);
 }
-function isExcluded(context, relativePath) {
-    const variants = [relativePath, `${relativePath}/`];
-    return variants.some((candidate) => context.ignore.matchesGitignore(candidate) || context.ignore.matchesCursorignore(candidate));
+function isGitIgnored(context, relativePath) {
+    return (context.ignore.matchesGitignore(relativePath) ||
+        context.ignore.matchesGitignore(`${relativePath}/`));
+}
+async function agentsStillExposed(context, relativePath, configured) {
+    const exposed = [];
+    for (const agent of configured) {
+        if (agent === "cursor" &&
+            (context.ignore.matchesCursorignore(relativePath) ||
+                context.ignore.matchesCursorignore(`${relativePath}/`))) {
+            continue;
+        }
+        if (agent === "claude-code" && (await claudeDeniesPath(context, relativePath))) {
+            continue;
+        }
+        if (agent === "codex" && (await codexDeniesPath(context, relativePath))) {
+            continue;
+        }
+        exposed.push(agent);
+    }
+    return exposed;
 }
 export const generatedDirectoryRule = {
     id: "context/generated-directory",
@@ -27,14 +48,27 @@ export const generatedDirectoryRule = {
     recommendation: "Ensure generated directories are listed in .gitignore and agent ignore configuration where applicable.",
     async check(context) {
         const findings = [];
-        const affected = context.agents.filter((a) => a.configured || a.detected).map((a) => a.id);
-        if (affected.length === 0) {
+        const configured = context.agents.filter((a) => a.configured || a.detected).map((a) => a.id);
+        if (configured.length === 0) {
             return [];
         }
         for (const entry of GENERATED) {
             const matches = context.discovery.directoriesSkipped.filter((dir) => isGeneratedPath(dir, entry.name));
             for (const relativePath of matches) {
-                if (isExcluded(context, relativePath)) {
+                if (isSampleOrTestPath(relativePath)) {
+                    continue;
+                }
+                if (isSourceNamedArtifactCollision(relativePath)) {
+                    continue;
+                }
+                if (isCheckedInGithubActionDist(relativePath)) {
+                    continue;
+                }
+                if (isGitIgnored(context, relativePath)) {
+                    continue;
+                }
+                const affected = await agentsStillExposed(context, relativePath, configured);
+                if (affected.length === 0) {
                     continue;
                 }
                 findings.push({
@@ -44,7 +78,7 @@ export const generatedDirectoryRule = {
                     title: "Generated directory may enter agent context",
                     message: `${relativePath}/ (${entry.label}) is present and no project ignore pattern was detected`,
                     whyItMatters: "Generated directories are usually low-value for coding agents and can bloat indexing/context when not excluded.",
-                    recommendation: `Add an ignore pattern covering ${relativePath}/ to .gitignore and, for Cursor, .cursorignore if you need agent-specific exclusion beyond gitignore.`,
+                    recommendation: `Add an ignore pattern covering ${relativePath}/ to .gitignore and agent exclusions (.cursorignore, Claude Code Read deny, and/or Codex filesystem deny).`,
                     affectedAgents: affected,
                     evidence: { path: relativePath },
                     fixability: "safe",
@@ -57,7 +91,17 @@ export const generatedDirectoryRule = {
             !context.repository.packageManagers.includes("composer") &&
             context.repository.primaryLanguage !== "php") {
             for (const relativePath of vendorPaths) {
-                if (isExcluded(context, relativePath)) {
+                if (isSampleOrTestPath(relativePath)) {
+                    continue;
+                }
+                if (isSourceNamedArtifactCollision(relativePath)) {
+                    continue;
+                }
+                if (isGitIgnored(context, relativePath)) {
+                    continue;
+                }
+                const affected = await agentsStillExposed(context, relativePath, configured);
+                if (affected.length === 0) {
                     continue;
                 }
                 findings.push({

package/dist/core/rules/context/large-log-file.js

@@ -1,6 +1,7 @@
+import { isLogLikePath } from "../../../discovery/log-like.js";
+import { claudeDeniesPath } from "../claude-deny.js";
+import { codexDeniesPath } from "../codex-deny.js";
 import { THRESHOLDS } from "../thresholds.js";
-const LOG_LIKE = /\.(log|out|dump)$/i;
-const HEAVY_NAME = /(^|\/)(debug|trace|coverage-final|chrome-devtools|heapdump)/i;
 export const largeLogFileRule = {
     id: "context/large-log-file",
     title: "Large log or dump file in repository",
@@ -12,19 +13,35 @@ export const largeLogFileRule = {
     recommendation: "Delete or ignore large logs; add them to .gitignore and agent ignore files.",
     async check(context) {
         const findings = [];
-        const affected = context.agents.filter((a) => a.configured || a.detected).map((a) => a.id);
+        const configured = context.agents
+            .filter((a) => a.configured || a.detected)
+            .map((a) => a.id);
         for (const file of context.discovery.files) {
-            const base = file.relativePath.split("/").pop() ?? file.relativePath;
-            const looksLog = LOG_LIKE.test(base) || HEAVY_NAME.test(file.relativePath);
-            if (!looksLog) {
+            if (!isLogLikePath(file.relativePath)) {
                 continue;
             }
             if (file.sizeBytes < THRESHOLDS.largeLogBytes) {
                 continue;
             }
-            // Skip if clearly ignored for Cursor and no other agents configured
-            if (context.ignore.matchesGitignore(file.relativePath) ||
-                context.ignore.matchesCursorignore(file.relativePath)) {
+            if (context.ignore.matchesGitignore(file.relativePath)) {
+                continue;
+            }
+            const defaultAgents = ["cursor", "claude-code", "codex"];
+            const candidates = configured.length > 0 ? configured : defaultAgents;
+            const affected = [];
+            for (const agent of candidates) {
+                if (agent === "cursor" && context.ignore.matchesCursorignore(file.relativePath)) {
+                    continue;
+                }
+                if (agent === "claude-code" && (await claudeDeniesPath(context, file.relativePath))) {
+                    continue;
+                }
+                if (agent === "codex" && (await codexDeniesPath(context, file.relativePath))) {
+                    continue;
+                }
+                affected.push(agent);
+            }
+            if (affected.length === 0) {
                 continue;
             }
             findings.push({
@@ -35,7 +52,7 @@ export const largeLogFileRule = {
                 message: `${file.relativePath} is ${(file.sizeBytes / 1024).toFixed(0)} KB`,
                 whyItMatters: "Large logs and dumps rarely help coding agents and can crowd out useful source context.",
                 recommendation: "Remove or ignore this file for both git and AI agent tooling.",
-                affectedAgents: affected.length > 0 ? affected : ["cursor", "claude-code", "codex"],
+                affectedAgents: affected,
                 evidence: { path: file.relativePath, detail: `${file.sizeBytes} bytes` },
                 fixability: "safe",
             });

package/dist/core/rules/ignore.js

@@ -1,7 +1,4 @@
-/**
- * Minimal gitignore-style pattern matching for .gitignore / .cursorignore.
- * Supports common patterns used in agent ignore files — not a full gitignore clone.
- */
+import { toRepoRelativePosix } from "../../utils/path.js";
 function normalizePattern(pattern) {
     const trimmed = pattern.trim();
     if (!trimmed || trimmed.startsWith("#")) {
@@ -48,7 +45,7 @@ export function matchIgnorePattern(relativePath, pattern) {
     if (pat.startsWith("!")) {
         pat = pat.slice(1);
     }
-    const pathNorm = relativePath.replace(/^\/+/, "").replace(/\/+$/, "");
+    const pathNorm = toRepoRelativePosix(relativePath);
     let matched = false;
     if (pat.endsWith("/")) {
         const dir = pat.slice(0, -1);

package/dist/core/rules/instructions/missing-path-reference.d.ts

@@ -16,7 +16,11 @@ export declare function extractPathCandidates(text: string): string[];
 /**
  * Resolve a candidate path reference with repository-aware semantics:
  * - `./` and `../` → relative to the instruction file directory
- * - otherwise → repository-root relative (avoids nesting under `.cursor/rules/`)
+ * - otherwise → repository-root relative, plus the same path under the
+ *   instruction file directory when nested (monorepo package docs)
+ *
+ * Does not search sibling packages: a root `AGENTS.md` reference must still
+ * exist at the repository root (or via `./` / `../`).
  */
 export declare function resolveInstructionPathReference(instructionRelativePath: string, candidate: string): ResolvedPathReference;
 export declare const missingPathReferenceRule: RuleDefinition;

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

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { pathExistsInsideRoot } from "../../../agents/inspect.js";
+import { preparePathReference } from "../../path-resolution/index.js";
 import { isPathInsideRoot } from "../../../utils/path.js";
 const INSTRUCTION_KINDS = new Set([
     "cursor-rule-mdc",
@@ -12,6 +13,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 +110,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)
@@ -75,7 +165,11 @@ function isEscapingRepoRelative(relativePath) {
 /**
  * Resolve a candidate path reference with repository-aware semantics:
  * - `./` and `../` → relative to the instruction file directory
- * - otherwise → repository-root relative (avoids nesting under `.cursor/rules/`)
+ * - otherwise → repository-root relative, plus the same path under the
+ *   instruction file directory when nested (monorepo package docs)
+ *
+ * Does not search sibling packages: a root `AGENTS.md` reference must still
+ * exist at the repository root (or via `./` / `../`).
  */
 export function resolveInstructionPathReference(instructionRelativePath, candidate) {
     const instructionDir = path.posix.dirname(instructionRelativePath);
@@ -96,9 +190,18 @@ export function resolveInstructionPathReference(instructionRelativePath, candida
     if (isEscapingRepoRelative(rootRelative) || rootRelative.startsWith("/")) {
         return { status: "escape", attempted: rootRelative };
     }
+    const pathsToCheck = [rootRelative];
+    if (instructionDir !== ".") {
+        const fromInstruction = path.posix.normalize(path.posix.join(instructionDir, rootRelative));
+        if (!isEscapingRepoRelative(fromInstruction) &&
+            !fromInstruction.startsWith("/") &&
+            fromInstruction !== rootRelative) {
+            pathsToCheck.push(fromInstruction);
+        }
+    }
     return {
         status: "ok",
-        pathsToCheck: [rootRelative],
+        pathsToCheck,
         primaryRelative: rootRelative,
     };
 }
@@ -129,20 +232,24 @@ export const missingPathReferenceRule = {
                 }
                 const candidates = extractPathCandidates(cached.text);
                 for (const candidate of candidates) {
-                    const resolved = resolveInstructionPathReference(file.relativePath, candidate);
+                    const prepared = preparePathReference(candidate);
+                    if (prepared.status === "reject") {
+                        continue;
+                    }
+                    const resolved = resolveInstructionPathReference(file.relativePath, prepared.normalized);
                     if (resolved.status === "escape") {
                         findings.push({
                             ruleId: "instructions/missing-path-reference",
                             category: "instructions",
                             severity: "warning",
                             title: "Instruction references a missing path",
-                            message: `${file.relativePath} references \`${candidate}\`, which escapes the repository root`,
+                            message: `${file.relativePath} references \`${prepared.original}\`, which escapes the repository root`,
                             whyItMatters: "Path references outside the repository cannot be validated and may confuse agents.",
                             recommendation: "Use repository-relative paths only.",
                             affectedAgents: context.agents
                                 .filter((a) => a.configPaths.includes(file.relativePath))
                                 .map((a) => a.id),
-                            evidence: { path: file.relativePath, detail: `ref=${candidate}` },
+                            evidence: { path: file.relativePath, detail: `ref=${prepared.original}` },
                             fixability: "manual",
                         });
                         continue;
@@ -166,7 +273,7 @@ export const missingPathReferenceRule = {
                         category: "instructions",
                         severity: "warning",
                         title: "Instruction references a missing path",
-                        message: `${file.relativePath} references \`${candidate}\`, but that path does not exist`,
+                        message: `${file.relativePath} references \`${prepared.original}\`, but that path does not exist`,
                         whyItMatters: "Agents may follow documented paths that no longer exist, causing failed reads and wasted context.",
                         recommendation: "Fix the path or remove the stale reference.",
                         affectedAgents: context.agents

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

@@ -0,0 +1,27 @@
+/**
+ * Shared path classification for rule precision.
+ * Paths under intentional sample/test/demo trees are not production secrets for agent readiness.
+ */
+/**
+ * True when a single path segment denotes sample/test/fixture material.
+ * Handles exact names, leading-underscore variants, hyphen/underscore compounds,
+ * and camelCase forms (dockerTest, testFixtures) without matching production roots.
+ */
+export declare function isSampleOrTestSegment(segment: string): boolean;
+/**
+ * True when any path segment marks fixture, test, example, or sample material.
+ * Uses POSIX relative paths (discovery output).
+ * Filenames never qualify alone (root `test-private-key.pem` must still flag).
+ */
+export declare function isSampleOrTestPath(relativePath: string): boolean;
+/**
+ * True for paths like `scripts/build`, `internal/build`, or `packages/foo/src/core/build`
+ * that are source trees named after a common artifact directory, not generated output.
+ * Any source-marker ancestor qualifies (not only the immediate parent).
+ */
+export declare function isSourceNamedArtifactCollision(relativePath: string): boolean;
+/**
+ * True for checked-in GitHub Action package output (`.github/actions/<name>/dist`).
+ * These are intentional publish artifacts, not ambient generated junk.
+ */
+export declare function isCheckedInGithubActionDist(relativePath: string): boolean;

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

@@ -0,0 +1,180 @@
+/**
+ * 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",
+    "testing",
+    "__tests__",
+    "testdata",
+    "test_data",
+    "spec",
+    "specs",
+    "demo",
+    "demos",
+    "e2e",
+    "bench",
+    "benchmark",
+    "benchmarks",
+    "playground",
+    "playgrounds",
+    "sandbox",
+    "sandboxes",
+]);
+/** Strong tokens that mark intentional non-production material when present in a segment. */
+const STRONG_TEST_TOKENS = new Set([
+    "test",
+    "tests",
+    "testing",
+    "fixture",
+    "fixtures",
+    "mock",
+    "mocks",
+    "testdata",
+    "spec",
+    "specs",
+    "e2e",
+    "bench",
+    "benchmark",
+    "benchmarks",
+    "playground",
+    "playgrounds",
+    "sandbox",
+    "sandboxes",
+    "example",
+    "examples",
+    "sample",
+    "samples",
+    "demo",
+    "demos",
+]);
+/**
+ * Artifact dir names that commonly collide with source packages
+ * (scripts/build, packages/foo/src/core/build, src/.../vendor).
+ * Intentionally excludes dist — paths like src/js/dist are often real build output.
+ */
+const ARTIFACT_NAMES_WITH_SOURCE_COLLISIONS = new Set(["build", "target", "vendor"]);
+/**
+ * Dir names that host source code packages/modules, not generated output trees.
+ * packages/foo/dist is still treated as generated (no source-marker ancestor).
+ */
+const SOURCE_CODE_MARKER_DIRS = new Set([
+    "bin",
+    "cmd",
+    "internal",
+    "lib",
+    "pkg",
+    "script",
+    "scripts",
+    "src",
+]);
+function splitCamelCase(segment) {
+    return segment
+        .replace(/([a-z0-9])([A-Z])/g, "$1\0$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1\0$2")
+        .split("\0")
+        .filter(Boolean);
+}
+/**
+ * True when a single path segment denotes sample/test/fixture material.
+ * Handles exact names, leading-underscore variants, hyphen/underscore compounds,
+ * and camelCase forms (dockerTest, testFixtures) without matching production roots.
+ */
+export function isSampleOrTestSegment(segment) {
+    if (!segment) {
+        return false;
+    }
+    const lower = segment.toLowerCase();
+    if (SAMPLE_DIRECTORY_NAMES.has(lower)) {
+        return true;
+    }
+    // _fixture, _fixtures, _testdata, __fixture
+    const stripped = lower.replace(/^_+/, "");
+    if (stripped !== lower && SAMPLE_DIRECTORY_NAMES.has(stripped)) {
+        return true;
+    }
+    // integration-test, smoke-test, docker-test, integration_tests, test-certs
+    const hyphenTokens = lower.split(/[-_]+/).filter(Boolean);
+    if (hyphenTokens.length >= 2 && hyphenTokens.some((token) => STRONG_TEST_TOKENS.has(token))) {
+        return true;
+    }
+    // dockerTest, testFixtures, httpTestServer, integrationTests
+    if (/[A-Z]/.test(segment)) {
+        const camelTokens = splitCamelCase(segment).map((part) => part.toLowerCase());
+        if (camelTokens.some((token) => STRONG_TEST_TOKENS.has(token))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * True when any path segment marks fixture, test, example, or sample material.
+ * Uses POSIX relative paths (discovery output).
+ * Filenames never qualify alone (root `test-private-key.pem` must still flag).
+ */
+export function isSampleOrTestPath(relativePath) {
+    if (!relativePath) {
+        return false;
+    }
+    const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!normalized) {
+        return false;
+    }
+    const parts = normalized.split("/").filter(Boolean);
+    return parts.some((segment, index) => {
+        const isLast = index === parts.length - 1;
+        const looksLikeFile = isLast && /\.[A-Za-z0-9_+-]+$/.test(segment);
+        if (looksLikeFile) {
+            return false;
+        }
+        return isSampleOrTestSegment(segment);
+    });
+}
+/**
+ * True for paths like `scripts/build`, `internal/build`, or `packages/foo/src/core/build`
+ * that are source trees named after a common artifact directory, not generated output.
+ * Any source-marker ancestor qualifies (not only the immediate parent).
+ */
+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;
+    }
+    return parts.slice(0, -1).some((segment) => SOURCE_CODE_MARKER_DIRS.has(segment.toLowerCase()));
+}
+/**
+ * True for checked-in GitHub Action package output (`.github/actions/<name>/dist`).
+ * These are intentional publish artifacts, not ambient generated junk.
+ */
+export function isCheckedInGithubActionDist(relativePath) {
+    if (!relativePath) {
+        return false;
+    }
+    const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+    return /^\.github\/actions\/[^/]+\/dist$/i.test(normalized);
+}