@praneeth_54/agentdoctor 0.1.0-beta → 0.1.2-beta

package/CHANGELOG.md

@@ -7,22 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Changed
+### Planned
+
+- Deterministic readiness scoring
+- Safe automatic fixes
+- Packaged GitHub Action
 
-- Publish as scoped package `@praneeth_54/agentdoctor` (unscoped `agentdoctor` blocked by npm as too similar to `agent-doctor`)
+## [0.1.2-beta] — 2026-07-29
+
+Backward-compatible quality patch.
 
 ### Fixed
 
-- Track fake credential fixtures required by CI (were excluded by `.gitignore`)
-- Align package and docs URLs with the public GitHub repository
-- Release workflow selects notes by tag and attaches the npm tarball
-- CLI help text matches shipped capabilities (`--min-score` no-op until scoring)
+- More reliable CLI/package binary execution (local bin shim + executable CLI entry)
+- Nested `context/generated-directory` ignore handling and precise evidence paths
+- Multi-project repository detection without requiring Node workspace tooling
+- Mixed Composer / Pub / npm package-manager detection
+- False malformed-package diagnostic when root `package.json` is absent
+- Conservative credential-file detection for `.der` and service-account JSON names
+- Quieter permission diagnostics under already-skipped directories
 
-### Planned
+### Testing
 
-- Deterministic readiness scoring
-- Safe automatic fixes
-- Packaged GitHub Action
+- Added real-world multi-app, generated-directory, credential, and CLI bin fixtures/tests
+- Total test suite is now 104 tests
+
+## [0.1.1-beta] — 2026-07-29
+
+Patch release.
+
+### Fixed
+
+- False missing-path warnings for repository-root paths referenced from nested instruction files
+- CSS-like backtick tokens such as `.content` being interpreted as filesystem paths
+
+### Testing
+
+- Added real-world regression fixtures
+- Added 17 regression tests
+- Total test suite is now 91 tests
 
 ## [0.1.0-beta] — 2026-07-29
 
@@ -40,6 +63,10 @@ First public beta.
 - Programmatic `scan()` API
 - Fixture-based unit and integration tests
 
+### Changed
+
+- Published npm package as `@praneeth_54/agentdoctor` (unscoped `agentdoctor` blocked by npm as too similar to `agent-doctor`)
+
 ### Security
 
 - Conservative wording for exposure findings
@@ -54,5 +81,7 @@ First public beta.
 - Not a complete secret scanner
 - Git “tracked secret” detection deferred
 
-[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v0.1.0-beta...HEAD
+[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v0.1.2-beta...HEAD
+[0.1.2-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.2-beta
+[0.1.1-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.1-beta
 [0.1.0-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.0-beta

package/README.md

@@ -1,5 +1,12 @@
 # AgentDoctor
 
+[![npm](https://img.shields.io/npm/v/@praneeth_54/agentdoctor)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
+[![License](https://img.shields.io/github/license/pranee54/AgentDoctor)](LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/pranee54/AgentDoctor)](https://github.com/pranee54/AgentDoctor/stargazers)
+[![CI](https://img.shields.io/github/actions/workflow/status/pranee54/AgentDoctor/ci.yml?branch=main&label=CI)](https://github.com/pranee54/AgentDoctor/actions)
+[![Node](https://img.shields.io/node/v/@praneeth_54/agentdoctor)](https://nodejs.org)
+[![Release](https://img.shields.io/badge/release-v0.1.2--beta-orange)](CHANGELOG.md)
+
 **Lighthouse for AI coding agents.**
 
 AgentDoctor audits a repository’s AI coding agent configuration — instructions, ignore rules, permissions, and MCP setup — using local static analysis. No API key. No upload by default.
@@ -15,12 +22,6 @@ npx @praneeth_54/agentdoctor
 | **Install**    | `npx @praneeth_54/agentdoctor` or `npm install -g @praneeth_54/agentdoctor`         |
 | **Requires**   | Node.js 20+                                                                         |
 
-[![CI](https://img.shields.io/github/actions/workflow/status/pranee54/AgentDoctor/ci.yml?branch=main&label=CI)](https://github.com/pranee54/AgentDoctor/actions)
-[![npm](https://img.shields.io/npm/v/@praneeth_54/agentdoctor?label=npm)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
-[![Node](https://img.shields.io/node/v/@praneeth_54/agentdoctor)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Release](https://img.shields.io/badge/release-v0.1.0--beta-orange)](CHANGELOG.md)
-
 ---
 
 ## Demo
@@ -28,7 +29,7 @@ npx @praneeth_54/agentdoctor
 ```text
 $ npx @praneeth_54/agentdoctor
 
-AgentDoctor v0.1.0-beta
+AgentDoctor v0.1.2-beta
 
 Repository
   Framework: Next.js
@@ -87,13 +88,13 @@ AgentDoctor analyzes configuration files. It does not run agents or edit your pr
 ### One-shot
 
 ```bash
-npx @praneeth_54/agentdoctor
+npx @praneeth_54/agentdoctor@0.1.2-beta
 ```
 
 ### Global (optional)
 
 ```bash
-npm install -g @praneeth_54/agentdoctor
+npm install -g @praneeth_54/agentdoctor@0.1.2-beta
 agentdoctor
 ```
 
@@ -224,7 +225,7 @@ npx @praneeth_54/agentdoctor --json
 
 ```json
 {
-  "version": "0.1.0-beta",
+  "version": "0.1.2-beta",
   "repository": {
     "primaryFramework": "nextjs",
     "primaryLanguage": "typescript",

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const PACKAGE_VERSION = "0.1.0-beta";
+export declare const PACKAGE_VERSION = "0.1.2-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>;

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "0.1.0-beta";
+export const PACKAGE_VERSION = "0.1.2-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([

package/dist/core/rules/build-context.js

@@ -1,13 +1,44 @@
 import { parseProjectMcpConfigs } from "../mcp/parse.js";
-import { createIgnoreIndex, parseIgnoreFile } from "./ignore.js";
+import { createIgnoreIndex, parseIgnoreFile, relativizeIgnorePatterns } from "./ignore.js";
 import { TextCache } from "./text-cache.js";
 export async function buildRuleContext(options) {
     const textCache = new TextCache(options.root, options.maxFileSizeBytes);
-    const gitignore = await textCache.read(".gitignore");
-    const cursorignore = await textCache.read(".cursorignore");
+    const gitignorePatterns = [];
+    const cursorignorePatterns = [];
+    const rootGitignore = await textCache.read(".gitignore");
+    if (rootGitignore.text) {
+        gitignorePatterns.push(...parseIgnoreFile(rootGitignore.text));
+    }
+    const rootCursorignore = await textCache.read(".cursorignore");
+    if (rootCursorignore.text) {
+        cursorignorePatterns.push(...parseIgnoreFile(rootCursorignore.text));
+    }
+    for (const file of options.discovery.files) {
+        const base = file.relativePath.split("/").pop() ?? file.relativePath;
+        if (base !== ".gitignore" && base !== ".cursorignore") {
+            continue;
+        }
+        if (file.relativePath === ".gitignore" || file.relativePath === ".cursorignore") {
+            continue;
+        }
+        const cached = await textCache.read(file.relativePath);
+        if (!cached.text) {
+            continue;
+        }
+        const dir = file.relativePath.includes("/")
+            ? file.relativePath.slice(0, file.relativePath.lastIndexOf("/"))
+            : "";
+        const patterns = relativizeIgnorePatterns(dir, parseIgnoreFile(cached.text));
+        if (base === ".gitignore") {
+            gitignorePatterns.push(...patterns);
+        }
+        else {
+            cursorignorePatterns.push(...patterns);
+        }
+    }
     const ignore = createIgnoreIndex({
-        gitignorePatterns: gitignore.text ? parseIgnoreFile(gitignore.text) : [],
-        cursorignorePatterns: cursorignore.text ? parseIgnoreFile(cursorignore.text) : [],
+        gitignorePatterns,
+        cursorignorePatterns,
     });
     const mcp = await parseProjectMcpConfigs(options.root, options.maxFileSizeBytes);
     const instructionPaths = new Set();

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

@@ -9,6 +9,13 @@ const GENERATED = [
     { name: ".dart_tool", label: "Dart tooling cache" },
     { name: "target", label: "Rust/Java build output" },
 ];
+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));
+}
 export const generatedDirectoryRule = {
     id: "context/generated-directory",
     title: "Generated directory may enter agent context",
@@ -20,66 +27,49 @@ export const generatedDirectoryRule = {
     recommendation: "Ensure generated directories are listed in .gitignore and agent ignore configuration where applicable.",
     async check(context) {
         const findings = [];
-        const skipped = new Set(context.discovery.directoriesSkipped.map((d) => d.split("/")[0] ?? d));
-        // directoriesSkipped stores relative paths like "dist" or "packages/app/dist"
-        const present = new Set();
-        for (const dir of context.discovery.directoriesSkipped) {
-            const top = dir.split("/")[0] ?? dir;
-            present.add(top);
-            present.add(dir);
-        }
-        void skipped;
         const affected = context.agents.filter((a) => a.configured || a.detected).map((a) => a.id);
         if (affected.length === 0) {
             return [];
         }
         for (const entry of GENERATED) {
-            const found = present.has(entry.name) ||
-                [...present].some((p) => p === entry.name || p.endsWith(`/${entry.name}`));
-            if (!found) {
-                continue;
-            }
-            // If .gitignore or .cursorignore already exclude it, skip (already appropriately excluded)
-            const samplePath = `${entry.name}/`;
-            const excluded = context.ignore.matchesGitignore(samplePath) ||
-                context.ignore.matchesGitignore(entry.name) ||
-                context.ignore.matchesCursorignore(samplePath) ||
-                context.ignore.matchesCursorignore(entry.name);
-            if (excluded) {
-                continue;
+            const matches = context.discovery.directoriesSkipped.filter((dir) => isGeneratedPath(dir, entry.name));
+            for (const relativePath of matches) {
+                if (isExcluded(context, relativePath)) {
+                    continue;
+                }
+                findings.push({
+                    ruleId: "context/generated-directory",
+                    category: "context",
+                    severity: "info",
+                    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.`,
+                    affectedAgents: affected,
+                    evidence: { path: relativePath },
+                    fixability: "safe",
+                });
             }
-            // Discovery already skips these dirs by default — absence from ignore files is still useful info
-            // when agents are configured. Keep severity info.
-            findings.push({
-                ruleId: "context/generated-directory",
-                category: "context",
-                severity: "info",
-                title: "Generated directory may enter agent context",
-                message: `${entry.name}/ (${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 ${entry.name}/ to .gitignore and, for Cursor, .cursorignore if you need agent-specific exclusion beyond gitignore.`,
-                affectedAgents: affected,
-                evidence: { path: entry.name },
-                fixability: "safe",
-            });
         }
-        // vendor/ — only flag for non-PHP/Composer ecosystems
-        if ((present.has("vendor") ||
-            [...present].some((p) => p === "vendor" || p.endsWith("/vendor"))) &&
+        const vendorPaths = context.discovery.directoriesSkipped.filter((dir) => isGeneratedPath(dir, "vendor"));
+        if (vendorPaths.length > 0 &&
             context.repository.primaryPackageManager !== "composer" &&
+            !context.repository.packageManagers.includes("composer") &&
             context.repository.primaryLanguage !== "php") {
-            const excluded = context.ignore.matchesGitignore("vendor/") || context.ignore.matchesCursorignore("vendor/");
-            if (!excluded) {
+            for (const relativePath of vendorPaths) {
+                if (isExcluded(context, relativePath)) {
+                    continue;
+                }
                 findings.push({
                     ruleId: "context/generated-directory",
                     category: "context",
                     severity: "info",
                     title: "Generated directory may enter agent context",
-                    message: "vendor/ is present outside a PHP/Composer project and no ignore pattern was detected",
+                    message: `${relativePath}/ is present outside a PHP/Composer project and no ignore pattern was detected`,
                     whyItMatters: "In non-PHP projects, vendor/ is often third-party or generated content that adds noise to agent context.",
                     recommendation: "Confirm whether vendor/ should be ignored for git and AI tooling.",
                     affectedAgents: affected,
-                    evidence: { path: "vendor" },
+                    evidence: { path: relativePath },
                     fixability: "safe",
                 });
             }

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

@@ -11,6 +11,11 @@ export interface IgnoreIndex {
     isExcludedForCursor(relativePath: string): boolean;
 }
 export declare function parseIgnoreFile(content: string): string[];
+/**
+ * Rewrite patterns from a nested ignore file so they apply relative to repository root.
+ * `baseDir` is the directory containing the ignore file (POSIX, no trailing slash), or "".
+ */
+export declare function relativizeIgnorePatterns(baseDir: string, patterns: string[]): string[];
 /**
  * Match a relative POSIX path against a single gitignore-like pattern.
  * Negation (`!`) is not fully supported for re-inclusion of parent-excluded paths.

package/dist/core/rules/ignore.js

@@ -15,6 +15,30 @@ export function parseIgnoreFile(content) {
         .map(normalizePattern)
         .filter((p) => p !== null);
 }
+/**
+ * Rewrite patterns from a nested ignore file so they apply relative to repository root.
+ * `baseDir` is the directory containing the ignore file (POSIX, no trailing slash), or "".
+ */
+export function relativizeIgnorePatterns(baseDir, patterns) {
+    if (!baseDir || baseDir === ".") {
+        return patterns;
+    }
+    return patterns.map((pattern) => {
+        const negated = pattern.startsWith("!");
+        const body = negated ? pattern.slice(1) : pattern;
+        let rewritten;
+        if (body.startsWith("/")) {
+            rewritten = `${baseDir}${body}`;
+        }
+        else if (body.startsWith("**/")) {
+            rewritten = `${baseDir}/${body.slice(3)}`;
+        }
+        else {
+            rewritten = `${baseDir}/${body}`;
+        }
+        return negated ? `!${rewritten}` : rewritten;
+    });
+}
 /**
  * Match a relative POSIX path against a single gitignore-like pattern.
  * Negation (`!`) is not fully supported for re-inclusion of parent-excluded paths.
@@ -24,25 +48,44 @@ export function matchIgnorePattern(relativePath, pattern) {
     if (pat.startsWith("!")) {
         pat = pat.slice(1);
     }
-    const pathNorm = relativePath.replace(/^\/+/, "");
+    const pathNorm = relativePath.replace(/^\/+/, "").replace(/\/+$/, "");
     let matched = false;
     if (pat.endsWith("/")) {
         const dir = pat.slice(0, -1);
-        matched =
-            pathNorm === dir ||
-                pathNorm.startsWith(`${dir}/`) ||
-                globMatch(pathNorm, dir) ||
-                pathNorm.split("/").some((_, i, parts) => globMatch(parts.slice(0, i + 1).join("/"), dir));
+        if (!dir.includes("/")) {
+            // `build/` matches build at any directory level (gitignore semantics)
+            matched =
+                pathNorm === dir ||
+                    pathNorm.endsWith(`/${dir}`) ||
+                    pathNorm.split("/").includes(dir) ||
+                    globMatch(pathNorm, `**/${dir}`) ||
+                    globMatch(pathNorm, `**/${dir}/**`);
+        }
+        else {
+            matched =
+                pathNorm === dir ||
+                    pathNorm.startsWith(`${dir}/`) ||
+                    globMatch(pathNorm, dir) ||
+                    globMatch(pathNorm, `${dir}/**`);
+        }
     }
     else if (pat.startsWith("/")) {
         matched = globMatch(pathNorm, pat.slice(1));
     }
     else if (pat.includes("/")) {
-        matched = globMatch(pathNorm, pat) || pathNorm.endsWith(`/${pat}`);
+        matched =
+            globMatch(pathNorm, pat) ||
+                globMatch(pathNorm, `${pat}/**`) ||
+                pathNorm.endsWith(`/${pat}`) ||
+                pathNorm.startsWith(`${pat}/`);
     }
     else {
         const base = pathNorm.split("/").pop() ?? pathNorm;
-        matched = globMatch(base, pat) || globMatch(pathNorm, pat) || globMatch(pathNorm, `**/${pat}`);
+        matched =
+            globMatch(base, pat) ||
+                globMatch(pathNorm, pat) ||
+                globMatch(pathNorm, `**/${pat}`) ||
+                pathNorm.split("/").includes(pat);
     }
     return matched;
 }
@@ -90,7 +133,6 @@ export function createIgnoreIndex(options) {
             if (pathMatchesAny(relativePath, gitignorePatterns)) {
                 return true;
             }
-            // Documented default ignore list includes .env*
             return pathMatchesAny(relativePath, CURSOR_DEFAULT_ENV_PATTERNS);
         },
     };

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

@@ -1,2 +1,22 @@
 import type { RuleDefinition } from "../types.js";
+export type ResolvedPathReference = {
+    status: "ok";
+    pathsToCheck: string[];
+    primaryRelative: string;
+} | {
+    status: "escape";
+    attempted: string;
+};
+/**
+ * Conservative local path classification for markdown links / backticks.
+ * Precision is more important than recall for this rule.
+ */
+export declare function isLikelyLocalPathReference(value: string): boolean;
+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/`)
+ */
+export declare function resolveInstructionPathReference(instructionRelativePath: string, candidate: string): ResolvedPathReference;
 export declare const missingPathReferenceRule: RuleDefinition;

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

@@ -10,49 +10,97 @@ const INSTRUCTION_KINDS = new Set([
     "claude-local-md",
     "claude-rule-md",
 ]);
-/**
- * Conservative local path extraction:
- * - Markdown links: [text](relative/path.ext)
- * - Backticked paths with separators or extensions
- */
-function extractPathCandidates(text) {
-    const found = new Set();
-    for (const match of text.matchAll(/\[[^\]]*]\(([^)]+)\)/g)) {
-        const target = (match[1] ?? "").trim();
-        if (isConservativeLocalPath(target)) {
-            found.add(stripAnchor(target));
-        }
-    }
-    for (const match of text.matchAll(/`([^`]+)`/g)) {
-        const target = (match[1] ?? "").trim();
-        if (isConservativeLocalPath(target)) {
-            found.add(stripAnchor(target));
-        }
-    }
-    return [...found];
-}
+/** 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;
 function stripAnchor(value) {
     return value.split("#")[0] ?? value;
 }
-function isConservativeLocalPath(value) {
+function isExplicitRelativePath(value) {
+    return value.startsWith("./") || value.startsWith("../");
+}
+/**
+ * Conservative local path classification for markdown links / backticks.
+ * Precision is more important than recall for this rule.
+ */
+export function isLikelyLocalPathReference(value) {
     if (!value || value.length > 200)
         return false;
     if (/^(https?:|mailto:|file:)/i.test(value))
         return false;
     if (value.startsWith("#"))
         return false;
+    if (value.startsWith("--"))
+        return false;
     if (value.includes("://"))
         return false;
     if (value.includes("\n") || value.includes(" "))
         return false;
-    // Must look like a path: has / or a file extension
-    if (!value.includes("/") && !/\.[a-z0-9]{1,8}$/i.test(value))
-        return false;
-    // Reject shell-looking fragments
     if (/[;&|$]/.test(value))
         return false;
-    // Reject traversal escape attempts — still check but flag separately
-    return true;
+    if (value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value))
+        return false;
+    // CSS class / id-like bare selectors: `.content`, `.button`
+    if (/^\.[A-Za-z_][\w-]*$/.test(value))
+        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;
+        }
+        return true;
+    }
+    // Bare filename: require a known file extension (not `.content`-style tokens)
+    return BARE_FILE_EXTENSION.test(value) && !value.startsWith(".");
+}
+export function extractPathCandidates(text) {
+    const found = new Set();
+    for (const match of text.matchAll(/\[[^\]]*]\(([^)]+)\)/g)) {
+        const target = stripAnchor((match[1] ?? "").trim());
+        if (isLikelyLocalPathReference(target)) {
+            found.add(target);
+        }
+    }
+    for (const match of text.matchAll(/`([^`]+)`/g)) {
+        const target = stripAnchor((match[1] ?? "").trim());
+        if (isLikelyLocalPathReference(target)) {
+            found.add(target);
+        }
+    }
+    return [...found];
+}
+function isEscapingRepoRelative(relativePath) {
+    return relativePath === ".." || relativePath.startsWith("../");
+}
+/**
+ * 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/`)
+ */
+export function resolveInstructionPathReference(instructionRelativePath, candidate) {
+    const instructionDir = path.posix.dirname(instructionRelativePath);
+    if (isExplicitRelativePath(candidate)) {
+        const joined = instructionDir === "."
+            ? path.posix.normalize(candidate)
+            : path.posix.normalize(path.posix.join(instructionDir, candidate));
+        if (isEscapingRepoRelative(joined)) {
+            return { status: "escape", attempted: joined };
+        }
+        return {
+            status: "ok",
+            pathsToCheck: [joined],
+            primaryRelative: joined,
+        };
+    }
+    const rootRelative = path.posix.normalize(candidate);
+    if (isEscapingRepoRelative(rootRelative) || rootRelative.startsWith("/")) {
+        return { status: "escape", attempted: rootRelative };
+    }
+    return {
+        status: "ok",
+        pathsToCheck: [rootRelative],
+        primaryRelative: rootRelative,
+    };
 }
 export const missingPathReferenceRule = {
     id: "instructions/missing-path-reference",
@@ -81,10 +129,8 @@ export const missingPathReferenceRule = {
                 }
                 const candidates = extractPathCandidates(cached.text);
                 for (const candidate of candidates) {
-                    // Resolve relative to instruction file directory, stay inside root
-                    const baseDir = path.posix.dirname(file.relativePath);
-                    const resolvedRelative = path.posix.normalize(baseDir === "." ? candidate : path.posix.join(baseDir, candidate));
-                    if (resolvedRelative.startsWith("../") || resolvedRelative === "..") {
+                    const resolved = resolveInstructionPathReference(file.relativePath, candidate);
+                    if (resolved.status === "escape") {
                         findings.push({
                             ruleId: "instructions/missing-path-reference",
                             category: "instructions",
@@ -101,11 +147,17 @@ export const missingPathReferenceRule = {
                         });
                         continue;
                     }
-                    const absolute = path.resolve(context.root, resolvedRelative);
-                    if (!isPathInsideRoot(context.root, absolute)) {
-                        continue;
+                    let exists = false;
+                    for (const relativePath of resolved.pathsToCheck) {
+                        const absolute = path.resolve(context.root, relativePath);
+                        if (!isPathInsideRoot(context.root, absolute)) {
+                            continue;
+                        }
+                        if (await pathExistsInsideRoot(context.root, relativePath)) {
+                            exists = true;
+                            break;
+                        }
                     }
-                    const exists = await pathExistsInsideRoot(context.root, resolvedRelative);
                     if (exists) {
                         continue;
                     }
@@ -120,7 +172,10 @@ export const missingPathReferenceRule = {
                         affectedAgents: context.agents
                             .filter((a) => a.configPaths.includes(file.relativePath))
                             .map((a) => a.id),
-                        evidence: { path: file.relativePath, detail: `missing=${resolvedRelative}` },
+                        evidence: {
+                            path: file.relativePath,
+                            detail: `missing=${resolved.primaryRelative}`,
+                        },
                         fixability: "manual",
                     });
                 }

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

@@ -6,10 +6,14 @@ const PRIVATE_KEY_PATTERNS = [
         test: (b) => /\.pem$/i.test(b) && !/cert|certificate|public|ca-bundle/i.test(b),
         label: "PEM private key",
     },
+    {
+        test: (b) => /\.der$/i.test(b) && !/cert|certificate|public|ca-bundle/i.test(b),
+        label: "DER-encoded key or credential material",
+    },
     { 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) => /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",

package/dist/detectors/monorepo.d.ts

@@ -7,7 +7,8 @@ export interface MonorepoDetectionResult {
     monorepo: MonorepoToolId;
 }
 /**
- * Detect common monorepo tooling from config markers.
+ * Detect common monorepo tooling from config markers, or multi-project layouts
+ * with multiple independently buildable manifests.
  */
 export declare function detectMonorepo(input: MonorepoDetectionInput): MonorepoDetectionResult;
 export declare function formatMonorepo(id: MonorepoToolId): string;

package/dist/detectors/monorepo.js

@@ -1,5 +1,15 @@
+const PROJECT_MANIFESTS = new Set([
+    "package.json",
+    "pubspec.yaml",
+    "composer.json",
+    "cargo.toml",
+    "go.mod",
+    "pyproject.toml",
+    "gemfile",
+]);
 /**
- * Detect common monorepo tooling from config markers.
+ * Detect common monorepo tooling from config markers, or multi-project layouts
+ * with multiple independently buildable manifests.
  */
 export function detectMonorepo(input) {
     const basenames = new Set(input.relativePaths.map((p) => {
@@ -26,6 +36,25 @@ export function detectMonorepo(input) {
             return { monorepo: "npm-workspaces" };
         }
     }
+    const projectRoots = new Set();
+    for (const relativePath of input.relativePaths) {
+        const parts = relativePath.split("/");
+        const base = (parts[parts.length - 1] ?? relativePath).toLowerCase();
+        if (!PROJECT_MANIFESTS.has(base)) {
+            continue;
+        }
+        if (parts.length === 1) {
+            projectRoots.add(".");
+            continue;
+        }
+        // Count only first-level project directories (e.g. mobile-apps/pubspec.yaml)
+        if (parts.length === 2) {
+            projectRoots.add(parts[0] ?? relativePath);
+        }
+    }
+    if (projectRoots.size >= 2) {
+        return { monorepo: "multi-project" };
+    }
     return { monorepo: "none" };
 }
 export function formatMonorepo(id) {
@@ -38,6 +67,8 @@ export function formatMonorepo(id) {
             return "Turborepo";
         case "nx":
             return "Nx";
+        case "multi-project":
+            return "Multi-project";
         default:
             return "None";
     }

package/dist/detectors/package-manager.d.ts

@@ -8,7 +8,8 @@ export interface PackageManagerDetectionResult {
 }
 /**
  * Detect package managers from lockfiles and manifests.
- * Lockfiles take precedence over generic manifests for primary selection.
+ * Primary selection prefers root-level evidence and avoids inventing certainty for mixed ecosystems.
  */
 export declare function detectPackageManagers(input: PackageManagerDetectionInput): PackageManagerDetectionResult;
 export declare function formatPackageManager(id: PackageManagerId): string;
+export declare function formatPackageManagers(ids: PackageManagerId[]): string;

package/dist/detectors/package-manager.js

@@ -1,32 +1,83 @@
 const MARKERS = [
-    { id: "pnpm", files: ["pnpm-lock.yaml", "pnpm-workspace.yaml"] },
-    { id: "yarn", files: ["yarn.lock", ".yarnrc.yml"] },
-    { id: "bun", files: ["bun.lockb", "bun.lock"] },
-    { id: "npm", files: ["package-lock.json", "npm-shrinkwrap.json"] },
-    { id: "composer", files: ["composer.lock", "composer.json"] },
-    { id: "poetry", files: ["poetry.lock", "pyproject.toml"] },
-    { id: "pip", files: ["requirements.txt", "Pipfile", "Pipfile.lock"] },
-    { id: "cargo", files: ["Cargo.lock", "Cargo.toml"] },
-    { id: "gradle", files: ["gradlew", "build.gradle", "build.gradle.kts", "settings.gradle"] },
+    { id: "pnpm", files: ["pnpm-lock.yaml", "pnpm-workspace.yaml"], lockfiles: ["pnpm-lock.yaml"] },
+    { id: "yarn", files: ["yarn.lock", ".yarnrc.yml"], lockfiles: ["yarn.lock"] },
+    { id: "bun", files: ["bun.lockb", "bun.lock"], lockfiles: ["bun.lockb", "bun.lock"] },
+    {
+        id: "npm",
+        files: ["package-lock.json", "npm-shrinkwrap.json", "package.json"],
+        lockfiles: ["package-lock.json", "npm-shrinkwrap.json"],
+    },
+    { id: "composer", files: ["composer.lock", "composer.json"], lockfiles: ["composer.lock"] },
+    { id: "pub", files: ["pubspec.yaml", "pubspec.lock"], lockfiles: ["pubspec.lock"] },
+    { id: "poetry", files: ["poetry.lock", "pyproject.toml"], lockfiles: ["poetry.lock"] },
+    {
+        id: "pip",
+        files: ["requirements.txt", "Pipfile", "Pipfile.lock"],
+        lockfiles: ["Pipfile.lock"],
+    },
+    { id: "cargo", files: ["Cargo.lock", "Cargo.toml"], lockfiles: ["Cargo.lock"] },
+    {
+        id: "gradle",
+        files: ["gradlew", "build.gradle", "build.gradle.kts", "settings.gradle"],
+        lockfiles: [],
+    },
 ];
+const NODE_IDS = new Set(["npm", "pnpm", "yarn", "bun"]);
+function basename(relativePath) {
+    const parts = relativePath.split("/");
+    return (parts[parts.length - 1] ?? relativePath).toLowerCase();
+}
+function isRootPath(relativePath) {
+    return !relativePath.includes("/");
+}
 /**
  * Detect package managers from lockfiles and manifests.
- * Lockfiles take precedence over generic manifests for primary selection.
+ * Primary selection prefers root-level evidence and avoids inventing certainty for mixed ecosystems.
  */
 export function detectPackageManagers(input) {
-    const basenames = new Set(input.relativePaths.map((p) => {
-        const parts = p.split("/");
-        return (parts[parts.length - 1] ?? p).toLowerCase();
-    }));
+    const paths = input.relativePaths;
+    const basenames = new Set(paths.map(basename));
+    const rootBasenames = new Set(paths.filter(isRootPath).map(basename));
     const found = [];
+    const rootFound = [];
+    const lockFound = [];
+    const rootLockFound = [];
     for (const marker of MARKERS) {
-        if (marker.files.some((f) => basenames.has(f.toLowerCase()))) {
-            found.push(marker.id);
+        if (marker.id === "npm") {
+            const hasNpmLock = marker.lockfiles.some((f) => basenames.has(f.toLowerCase()));
+            const hasRootPackage = rootBasenames.has("package.json");
+            const hasAnyPackage = paths.some((p) => basename(p) === "package.json");
+            if (!hasNpmLock && !hasAnyPackage) {
+                continue;
+            }
+            found.push("npm");
+            if (hasRootPackage || hasNpmLock) {
+                if (hasRootPackage) {
+                    rootFound.push("npm");
+                }
+                if (hasNpmLock) {
+                    lockFound.push("npm");
+                }
+                if (marker.lockfiles.some((f) => rootBasenames.has(f.toLowerCase()))) {
+                    rootLockFound.push("npm");
+                }
+            }
+            continue;
+        }
+        const hasAny = marker.files.some((f) => basenames.has(f.toLowerCase()));
+        if (!hasAny) {
+            continue;
+        }
+        found.push(marker.id);
+        if (marker.files.some((f) => rootBasenames.has(f.toLowerCase()))) {
+            rootFound.push(marker.id);
+        }
+        if (marker.lockfiles.some((f) => basenames.has(f.toLowerCase()))) {
+            lockFound.push(marker.id);
+        }
+        if (marker.lockfiles.some((f) => rootBasenames.has(f.toLowerCase()))) {
+            rootLockFound.push(marker.id);
         }
-    }
-    if (basenames.has("package.json") &&
-        !found.some((id) => ["npm", "pnpm", "yarn", "bun"].includes(id))) {
-        found.push("npm");
     }
     const unique = [...new Set(found)];
     const lockPriority = [
@@ -34,19 +85,43 @@ export function detectPackageManagers(input) {
         "yarn",
         "bun",
         "npm",
-        "poetry",
         "composer",
+        "pub",
+        "poetry",
         "cargo",
         "gradle",
         "pip",
     ];
     let primary = "unknown";
     for (const id of lockPriority) {
-        if (unique.includes(id)) {
+        if (rootLockFound.includes(id)) {
             primary = id;
             break;
         }
     }
+    if (primary === "unknown") {
+        for (const id of lockPriority) {
+            if (rootFound.includes(id)) {
+                primary = id;
+                break;
+            }
+        }
+    }
+    if (primary === "unknown") {
+        const ecosystems = new Set(unique.map((id) => (NODE_IDS.has(id) ? "node" : id === "unknown" ? "unknown" : id)));
+        ecosystems.delete("unknown");
+        if (ecosystems.size > 1) {
+            primary = "unknown";
+        }
+        else {
+            for (const id of lockPriority) {
+                if (lockFound.includes(id) || unique.includes(id)) {
+                    primary = id;
+                    break;
+                }
+            }
+        }
+    }
     return {
         packageManagers: unique.length > 0 ? unique : ["unknown"],
         primaryPackageManager: primary,
@@ -64,6 +139,8 @@ export function formatPackageManager(id) {
             return "Bun";
         case "composer":
             return "Composer";
+        case "pub":
+            return "Pub";
         case "pip":
             return "pip";
         case "poetry":
@@ -76,3 +153,13 @@ export function formatPackageManager(id) {
             return "Unknown";
     }
 }
+export function formatPackageManagers(ids) {
+    const unique = [...new Set(ids)];
+    if (unique.length === 0 || (unique.length === 1 && unique[0] === "unknown")) {
+        return "Unknown";
+    }
+    return unique
+        .filter((id) => id !== "unknown")
+        .map((id) => formatPackageManager(id))
+        .join(", ");
+}

package/dist/detectors/project.js

@@ -1,11 +1,11 @@
 import path from "node:path";
-import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../constants.js";
+import { DEFAULT_IGNORE_DIRECTORIES, DEFAULT_MAX_FILE_SIZE_BYTES } from "../constants.js";
 import { discoverFiles } from "../discovery/files.js";
 import { detectFrameworks } from "./framework.js";
 import { detectLanguages } from "./language.js";
 import { detectMonorepo } from "./monorepo.js";
 import { detectPackageManagers } from "./package-manager.js";
-import { isDirectory, readJsonFile } from "../utils/fs.js";
+import { isDirectory, pathExists, readJsonFile } from "../utils/fs.js";
 import { resolveRepoRoot } from "../utils/path.js";
 /**
  * Discover files and detect repository characteristics.
@@ -19,16 +19,26 @@ export async function detectProject(cwd, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZ
     const discovery = await discoverFiles({ root, maxFileSizeBytes });
     const relativePaths = discovery.files.map((f) => f.relativePath);
     for (const err of discovery.permissionErrors) {
+        const relative = err.split(":")[0] ?? err;
+        const underIgnored = relative
+            .split("/")
+            .some((segment) => segment.length > 0 && DEFAULT_IGNORE_DIRECTORIES.has(segment));
+        if (underIgnored) {
+            continue;
+        }
         diagnostics.push(`Permission/read issue: ${err}`);
     }
     let packageJson;
     const packageJsonPath = path.join(root, "package.json");
-    const packageResult = await readJsonFile(packageJsonPath, maxFileSizeBytes);
-    if (packageResult.ok) {
-        packageJson = packageResult.data;
-    }
-    else if (relativePaths.some((p) => p === "package.json" || p.endsWith("/package.json"))) {
-        diagnostics.push(`Malformed package.json: ${packageResult.error}`);
+    const rootPackageExists = await pathExists(packageJsonPath);
+    if (rootPackageExists) {
+        const packageResult = await readJsonFile(packageJsonPath, maxFileSizeBytes);
+        if (packageResult.ok) {
+            packageJson = packageResult.data;
+        }
+        else {
+            diagnostics.push(`Malformed package.json: ${packageResult.error}`);
+        }
     }
     const deps = {
         ...(packageJson?.dependencies ?? {}),

package/dist/reporters/terminal/report.js

@@ -3,7 +3,7 @@ import { AGENT_DISPLAY_NAMES } from "../../constants.js";
 import { formatFramework } from "../../detectors/framework.js";
 import { formatLanguage } from "../../detectors/language.js";
 import { formatMonorepo } from "../../detectors/monorepo.js";
-import { formatPackageManager } from "../../detectors/package-manager.js";
+import { formatPackageManager, formatPackageManagers } from "../../detectors/package-manager.js";
 import { colors, symbolFail, symbolInfo, symbolOk, symbolWarn } from "../../utils/colors.js";
 import { sanitizeTerminalText } from "../../security/redaction.js";
 const DEFAULT_FINDING_LIMIT = 12;
@@ -64,7 +64,11 @@ export function renderTerminalReport(result, options = {}) {
     lines.push(colors.bold("Repository"));
     lines.push(`  Framework: ${sanitizeTerminalText(formatFramework(result.repository.primaryFramework))}`);
     lines.push(`  Language: ${sanitizeTerminalText(formatLanguage(result.repository.primaryLanguage))}`);
-    lines.push(`  Package manager: ${sanitizeTerminalText(formatPackageManager(result.repository.primaryPackageManager))}`);
+    const packageManagerLabel = result.repository.packageManagers.length > 1 ||
+        result.repository.primaryPackageManager === "unknown"
+        ? formatPackageManagers(result.repository.packageManagers)
+        : formatPackageManager(result.repository.primaryPackageManager);
+    lines.push(`  Package manager: ${sanitizeTerminalText(packageManagerLabel)}`);
     if (result.repository.monorepo !== "none") {
         lines.push(`  Monorepo: ${sanitizeTerminalText(formatMonorepo(result.repository.monorepo))}`);
     }

package/dist/types/index.d.ts

@@ -7,8 +7,8 @@ export type Severity = "critical" | "warning" | "info";
 export type RuleCategory = "security" | "context" | "instructions" | "mcp" | "performance" | "compatibility";
 export type LanguageId = "typescript" | "javascript" | "python" | "dart" | "php" | "go" | "rust" | "java" | "kotlin" | "unknown";
 export type FrameworkId = "nextjs" | "react" | "vue" | "nuxt" | "svelte" | "nodejs" | "express" | "nestjs" | "flutter" | "laravel" | "django" | "fastapi" | "unknown";
-export type PackageManagerId = "npm" | "pnpm" | "yarn" | "bun" | "composer" | "pip" | "poetry" | "cargo" | "gradle" | "unknown";
-export type MonorepoToolId = "npm-workspaces" | "pnpm-workspaces" | "turborepo" | "nx" | "none";
+export type PackageManagerId = "npm" | "pnpm" | "yarn" | "bun" | "composer" | "pub" | "pip" | "poetry" | "cargo" | "gradle" | "unknown";
+export type MonorepoToolId = "npm-workspaces" | "pnpm-workspaces" | "turborepo" | "nx" | "multi-project" | "none";
 export type AgentId = "cursor" | "claude-code" | "codex";
 export interface DiscoveredFile {
     /** Absolute path */

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@praneeth_54/agentdoctor",
-  "version": "0.1.0-beta",
+  "version": "0.1.2-beta",
   "description": "Audit AI coding agent configuration in a repository — local, deterministic, no API key.",
   "type": "module",
   "bin": {
-    "agentdoctor": "dist/cli/index.js"
+    "agentdoctor": "./dist/cli/index.js"
   },
   "exports": {
     ".": {
@@ -24,7 +24,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/ensure-cli-bin.mjs",
     "dev": "tsx src/cli/index.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.build.json --noEmit",
     "lint": "eslint .",
@@ -34,6 +34,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "verify": "npm run typecheck && npm run lint && npm run format:check && npm test && npm run build",
+    "prepare": "node scripts/ensure-cli-bin.mjs",
     "prepublishOnly": "npm run verify"
   },
   "keywords": [