@praneeth_54/agentdoctor 0.1.0-beta

package/dist/detectors/framework.js

@@ -0,0 +1,148 @@
+function hasDep(deps, name) {
+    return Boolean(deps && name in deps);
+}
+function hasFile(paths, ...names) {
+    return names.some((name) => paths.has(name.toLowerCase()));
+}
+/**
+ * Detect frameworks from config markers and dependency names.
+ * Does not fail when nothing matches — returns unknown.
+ */
+export function detectFrameworks(input) {
+    const pathSet = new Set(input.relativePaths.map((p) => p.toLowerCase()));
+    const basenames = new Set(input.relativePaths.map((p) => {
+        const parts = p.split("/");
+        return (parts[parts.length - 1] ?? p).toLowerCase();
+    }));
+    const deps = {
+        ...(input.packageJsonDependencies ?? {}),
+    };
+    const composer = input.composerJsonRequire ?? {};
+    const detected = [];
+    const isNext = hasFile(basenames, "next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs") ||
+        hasDep(deps, "next");
+    if (isNext) {
+        detected.push("nextjs");
+    }
+    const isNuxt = hasFile(basenames, "nuxt.config.ts", "nuxt.config.js", "nuxt.config.mjs") ||
+        hasDep(deps, "nuxt");
+    if (isNuxt) {
+        detected.push("nuxt");
+    }
+    const isNest = hasDep(deps, "@nestjs/core") ||
+        hasFile(basenames, "nest-cli.json") ||
+        pathSet.has("nest-cli.json");
+    if (isNest) {
+        detected.push("nestjs");
+    }
+    const isExpress = hasDep(deps, "express") && !isNest && !isNext;
+    if (isExpress) {
+        detected.push("express");
+    }
+    const isVue = hasDep(deps, "vue") ||
+        ([...pathSet].some((p) => p.endsWith(".vue")) &&
+            (hasFile(basenames, "vite.config.ts", "vite.config.js", "vue.config.js") ||
+                hasDep(deps, "vite")));
+    if (isVue && !isNuxt) {
+        detected.push("vue");
+    }
+    const isSvelte = hasDep(deps, "svelte") ||
+        hasDep(deps, "@sveltejs/kit") ||
+        hasFile(basenames, "svelte.config.js", "svelte.config.ts");
+    if (isSvelte) {
+        detected.push("svelte");
+    }
+    const isReact = (hasDep(deps, "react") || hasDep(deps, "react-dom")) && !isNext && !detected.includes("react");
+    if (isReact) {
+        detected.push("react");
+    }
+    if (!isNext &&
+        !isNuxt &&
+        !isNest &&
+        !isExpress &&
+        !isVue &&
+        !isSvelte &&
+        !isReact &&
+        (hasFile(basenames, "package.json") || hasDep(deps, "express") === false) &&
+        hasFile(basenames, "package.json")) {
+        // Generic Node.js project with package.json but no web framework
+        if (!detected.includes("nodejs")) {
+            detected.push("nodejs");
+        }
+    }
+    if (hasFile(basenames, "pubspec.yaml") || input.pubspecName !== undefined) {
+        // Flutter: pubspec presence implies Flutter/Dart project context for detection
+        if (hasFile(pathSet, "pubspec.yaml") || basenames.has("pubspec.yaml")) {
+            detected.push("flutter");
+        }
+    }
+    if (hasDep(composer, "laravel/framework") || hasFile(basenames, "artisan")) {
+        detected.push("laravel");
+    }
+    if (hasFile(basenames, "manage.py") ||
+        [...pathSet].some((p) => p.endsWith("/settings.py") || p === "settings.py")) {
+        detected.push("django");
+    }
+    // FastAPI: path heuristics only (requirements/pyproject often lack a stable marker)
+    if ([...pathSet].some((p) => p.includes("fastapi") || p.endsWith("requirements-fastapi.txt") || p === "app/main.py")) {
+        detected.push("fastapi");
+    }
+    // Deduplicate while preserving order
+    const unique = [...new Set(detected)];
+    // Priority for primary framework
+    const priority = [
+        "nextjs",
+        "nuxt",
+        "nestjs",
+        "laravel",
+        "django",
+        "fastapi",
+        "flutter",
+        "svelte",
+        "vue",
+        "react",
+        "express",
+        "nodejs",
+    ];
+    let primaryFramework = "unknown";
+    for (const candidate of priority) {
+        if (unique.includes(candidate)) {
+            primaryFramework = candidate;
+            break;
+        }
+    }
+    if (unique.length === 0) {
+        return { frameworks: ["unknown"], primaryFramework: "unknown" };
+    }
+    return { frameworks: unique, primaryFramework };
+}
+export function formatFramework(framework) {
+    switch (framework) {
+        case "nextjs":
+            return "Next.js";
+        case "react":
+            return "React";
+        case "vue":
+            return "Vue";
+        case "nuxt":
+            return "Nuxt";
+        case "svelte":
+            return "Svelte";
+        case "nodejs":
+            return "Node.js";
+        case "express":
+            return "Express";
+        case "nestjs":
+            return "NestJS";
+        case "flutter":
+            return "Flutter";
+        case "laravel":
+            return "Laravel";
+        case "django":
+            return "Django";
+        case "fastapi":
+            return "FastAPI";
+        default:
+            return "Unknown";
+    }
+}

package/dist/detectors/language.d.ts

@@ -0,0 +1,14 @@
+import type { LanguageId } from "../types/index.js";
+export interface LanguageDetectionInput {
+    relativePaths: string[];
+}
+export interface LanguageDetectionResult {
+    languages: LanguageId[];
+    primaryLanguage: LanguageId;
+}
+/**
+ * Detect languages from known marker files and source extensions.
+ * TypeScript is preferred over JavaScript when both appear.
+ */
+export declare function detectLanguages(input: LanguageDetectionInput): LanguageDetectionResult;
+export declare function formatLanguage(language: LanguageId): string;

package/dist/detectors/language.js

@@ -0,0 +1,122 @@
+const LANGUAGE_MARKERS = [
+    {
+        language: "typescript",
+        files: ["tsconfig.json", "tsconfig.base.json"],
+        extensions: [".ts", ".tsx", ".mts", ".cts"],
+    },
+    {
+        language: "javascript",
+        files: ["jsconfig.json", "package.json"],
+        extensions: [".js", ".jsx", ".mjs", ".cjs"],
+    },
+    {
+        language: "python",
+        files: ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"],
+        extensions: [".py"],
+    },
+    {
+        language: "dart",
+        files: ["pubspec.yaml"],
+        extensions: [".dart"],
+    },
+    {
+        language: "php",
+        files: ["composer.json"],
+        extensions: [".php"],
+    },
+    {
+        language: "go",
+        files: ["go.mod", "go.work"],
+        extensions: [".go"],
+    },
+    {
+        language: "rust",
+        files: ["Cargo.toml"],
+        extensions: [".rs"],
+    },
+    {
+        language: "java",
+        files: ["pom.xml", "build.gradle", "build.gradle.kts"],
+        extensions: [".java"],
+    },
+    {
+        language: "kotlin",
+        files: ["build.gradle.kts"],
+        extensions: [".kt", ".kts"],
+    },
+];
+function hasExtension(filePath, extensions) {
+    const lower = filePath.toLowerCase();
+    return extensions.some((ext) => lower.endsWith(ext));
+}
+/**
+ * Detect languages from known marker files and source extensions.
+ * TypeScript is preferred over JavaScript when both appear.
+ */
+export function detectLanguages(input) {
+    const pathSet = new Set(input.relativePaths.map((p) => p.toLowerCase()));
+    const basenameSet = new Set(input.relativePaths.map((p) => {
+        const parts = p.split("/");
+        return (parts[parts.length - 1] ?? p).toLowerCase();
+    }));
+    const scores = new Map();
+    for (const marker of LANGUAGE_MARKERS) {
+        let score = 0;
+        for (const file of marker.files) {
+            if (basenameSet.has(file.toLowerCase()) || pathSet.has(file.toLowerCase())) {
+                score += 10;
+            }
+        }
+        for (const relative of input.relativePaths) {
+            if (hasExtension(relative, marker.extensions)) {
+                score += 1;
+            }
+        }
+        if (score > 0) {
+            scores.set(marker.language, score);
+        }
+    }
+    // Prefer TypeScript over JavaScript when both present with TS markers.
+    if (scores.has("typescript") && scores.has("javascript")) {
+        const jsScore = scores.get("javascript") ?? 0;
+        // package.json alone shouldn't claim JS over TS
+        if ((scores.get("typescript") ?? 0) >= 10) {
+            scores.set("javascript", Math.min(jsScore, 5));
+        }
+    }
+    const ordered = [...scores.entries()].sort((a, b) => b[1] - a[1]);
+    const languages = ordered.map(([lang]) => lang);
+    let primaryLanguage = languages[0] ?? "unknown";
+    // Explicit preference: TS > JS when both detected with meaningful scores
+    if (languages.includes("typescript") && languages.includes("javascript")) {
+        primaryLanguage = "typescript";
+    }
+    return {
+        languages: languages.length > 0 ? languages : ["unknown"],
+        primaryLanguage,
+    };
+}
+export function formatLanguage(language) {
+    switch (language) {
+        case "typescript":
+            return "TypeScript";
+        case "javascript":
+            return "JavaScript";
+        case "python":
+            return "Python";
+        case "dart":
+            return "Dart";
+        case "php":
+            return "PHP";
+        case "go":
+            return "Go";
+        case "rust":
+            return "Rust";
+        case "java":
+            return "Java";
+        case "kotlin":
+            return "Kotlin";
+        default:
+            return "Unknown";
+    }
+}

package/dist/detectors/monorepo.d.ts

@@ -0,0 +1,13 @@
+import type { MonorepoToolId } from "../types/index.js";
+export interface MonorepoDetectionInput {
+    relativePaths: string[];
+    packageJsonWorkspaces?: unknown;
+}
+export interface MonorepoDetectionResult {
+    monorepo: MonorepoToolId;
+}
+/**
+ * Detect common monorepo tooling from config markers.
+ */
+export declare function detectMonorepo(input: MonorepoDetectionInput): MonorepoDetectionResult;
+export declare function formatMonorepo(id: MonorepoToolId): string;

package/dist/detectors/monorepo.js

@@ -0,0 +1,44 @@
+/**
+ * Detect common monorepo tooling from config markers.
+ */
+export function detectMonorepo(input) {
+    const basenames = new Set(input.relativePaths.map((p) => {
+        const parts = p.split("/");
+        return (parts[parts.length - 1] ?? p).toLowerCase();
+    }));
+    if (basenames.has("turbo.json") || basenames.has("turbo.jsonc")) {
+        return { monorepo: "turborepo" };
+    }
+    if (basenames.has("nx.json")) {
+        return { monorepo: "nx" };
+    }
+    if (basenames.has("pnpm-workspace.yaml")) {
+        return { monorepo: "pnpm-workspaces" };
+    }
+    if (input.packageJsonWorkspaces !== undefined && input.packageJsonWorkspaces !== null) {
+        const ws = input.packageJsonWorkspaces;
+        const hasWorkspaces = Array.isArray(ws) ||
+            (typeof ws === "object" &&
+                ws !== null &&
+                "packages" in ws &&
+                Array.isArray(ws.packages));
+        if (hasWorkspaces) {
+            return { monorepo: "npm-workspaces" };
+        }
+    }
+    return { monorepo: "none" };
+}
+export function formatMonorepo(id) {
+    switch (id) {
+        case "npm-workspaces":
+            return "npm workspaces";
+        case "pnpm-workspaces":
+            return "pnpm workspaces";
+        case "turborepo":
+            return "Turborepo";
+        case "nx":
+            return "Nx";
+        default:
+            return "None";
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { PackageManagerId } from "../types/index.js";
+export interface PackageManagerDetectionInput {
+    relativePaths: string[];
+}
+export interface PackageManagerDetectionResult {
+    packageManagers: PackageManagerId[];
+    primaryPackageManager: PackageManagerId;
+}
+/**
+ * Detect package managers from lockfiles and manifests.
+ * Lockfiles take precedence over generic manifests for primary selection.
+ */
+export declare function detectPackageManagers(input: PackageManagerDetectionInput): PackageManagerDetectionResult;
+export declare function formatPackageManager(id: PackageManagerId): string;

package/dist/detectors/package-manager.js

@@ -0,0 +1,78 @@
+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"] },
+];
+/**
+ * Detect package managers from lockfiles and manifests.
+ * Lockfiles take precedence over generic manifests for primary selection.
+ */
+export function detectPackageManagers(input) {
+    const basenames = new Set(input.relativePaths.map((p) => {
+        const parts = p.split("/");
+        return (parts[parts.length - 1] ?? p).toLowerCase();
+    }));
+    const found = [];
+    for (const marker of MARKERS) {
+        if (marker.files.some((f) => basenames.has(f.toLowerCase()))) {
+            found.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 = [
+        "pnpm",
+        "yarn",
+        "bun",
+        "npm",
+        "poetry",
+        "composer",
+        "cargo",
+        "gradle",
+        "pip",
+    ];
+    let primary = "unknown";
+    for (const id of lockPriority) {
+        if (unique.includes(id)) {
+            primary = id;
+            break;
+        }
+    }
+    return {
+        packageManagers: unique.length > 0 ? unique : ["unknown"],
+        primaryPackageManager: primary,
+    };
+}
+export function formatPackageManager(id) {
+    switch (id) {
+        case "npm":
+            return "npm";
+        case "pnpm":
+            return "pnpm";
+        case "yarn":
+            return "Yarn";
+        case "bun":
+            return "Bun";
+        case "composer":
+            return "Composer";
+        case "pip":
+            return "pip";
+        case "poetry":
+            return "Poetry";
+        case "cargo":
+            return "Cargo";
+        case "gradle":
+            return "Gradle";
+        default:
+            return "Unknown";
+    }
+}

package/dist/detectors/project.d.ts

@@ -0,0 +1,10 @@
+import type { DiscoveryResult, RepositoryInfo } from "../types/index.js";
+export interface ProjectDetectionResult {
+    repository: RepositoryInfo;
+    discovery: DiscoveryResult;
+    diagnostics: string[];
+}
+/**
+ * Discover files and detect repository characteristics.
+ */
+export declare function detectProject(cwd: string, maxFileSizeBytes?: number): Promise<ProjectDetectionResult>;

package/dist/detectors/project.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { 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 { resolveRepoRoot } from "../utils/path.js";
+/**
+ * Discover files and detect repository characteristics.
+ */
+export async function detectProject(cwd, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE_BYTES) {
+    const root = resolveRepoRoot(cwd);
+    const diagnostics = [];
+    if (!(await isDirectory(root))) {
+        throw new Error(`Not a directory: ${root}`);
+    }
+    const discovery = await discoverFiles({ root, maxFileSizeBytes });
+    const relativePaths = discovery.files.map((f) => f.relativePath);
+    for (const err of discovery.permissionErrors) {
+        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 deps = {
+        ...(packageJson?.dependencies ?? {}),
+        ...(packageJson?.devDependencies ?? {}),
+        ...(packageJson?.peerDependencies ?? {}),
+    };
+    const languages = detectLanguages({ relativePaths });
+    const frameworks = detectFrameworks({
+        relativePaths,
+        packageJsonDependencies: deps,
+    });
+    const packageManagers = detectPackageManagers({ relativePaths });
+    const monorepo = detectMonorepo({
+        relativePaths,
+        packageJsonWorkspaces: packageJson?.workspaces,
+    });
+    const repository = {
+        root,
+        languages: languages.languages,
+        primaryLanguage: languages.primaryLanguage,
+        frameworks: frameworks.frameworks,
+        primaryFramework: frameworks.primaryFramework,
+        packageManagers: packageManagers.packageManagers,
+        primaryPackageManager: packageManagers.primaryPackageManager,
+        monorepo: monorepo.monorepo,
+        filesScanned: discovery.files.length,
+    };
+    return { repository, discovery, diagnostics };
+}

package/dist/discovery/files.d.ts

@@ -0,0 +1,15 @@
+import type { DiscoveryResult } from "../types/index.js";
+export interface DiscoverFilesOptions {
+    root: string;
+    maxFileSizeBytes?: number;
+    ignoreDirectories?: Set<string>;
+}
+/**
+ * Walk the repository without blindly reading every file.
+ * Skips common generated/dependency directories and records permission errors.
+ */
+export declare function discoverFiles(options: DiscoverFilesOptions): Promise<DiscoveryResult>;
+/**
+ * Targeted existence checks for known config files (O(1) per path).
+ */
+export declare function findKnownFiles(root: string, candidates: readonly string[]): Promise<string[]>;

package/dist/discovery/files.js

@@ -0,0 +1,118 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_IGNORE_DIRECTORIES, DEFAULT_MAX_FILE_SIZE_BYTES } from "../constants.js";
+import { isPathInsideRoot, toPosixRelative } from "../utils/path.js";
+/**
+ * Walk the repository without blindly reading every file.
+ * Skips common generated/dependency directories and records permission errors.
+ */
+export async function discoverFiles(options) {
+    const started = performance.now();
+    const root = path.resolve(options.root);
+    const maxFileSizeBytes = options.maxFileSizeBytes ?? DEFAULT_MAX_FILE_SIZE_BYTES;
+    const ignoreDirectories = options.ignoreDirectories ?? DEFAULT_IGNORE_DIRECTORIES;
+    const files = [];
+    const directoriesSkipped = [];
+    const permissionErrors = [];
+    let filesSkippedOversized = 0;
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (!current) {
+            continue;
+        }
+        if (!isPathInsideRoot(root, current)) {
+            continue;
+        }
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "permission denied";
+            permissionErrors.push(`${toPosixRelative(root, current) || "."}: ${message}`);
+            continue;
+        }
+        for (const entry of entries) {
+            const absolutePath = path.join(current, entry.name);
+            const relativePath = toPosixRelative(root, absolutePath);
+            if (!isPathInsideRoot(root, absolutePath)) {
+                continue;
+            }
+            let isDirectory = entry.isDirectory();
+            const isSymlink = entry.isSymbolicLink();
+            let isFile = entry.isFile();
+            // Resolve symlink type carefully without escaping the root.
+            if (isSymlink) {
+                try {
+                    const real = await fs.realpath(absolutePath);
+                    if (!isPathInsideRoot(root, real)) {
+                        continue;
+                    }
+                    const realStat = await fs.stat(real);
+                    isDirectory = realStat.isDirectory();
+                    isFile = realStat.isFile();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDirectory) {
+                if (ignoreDirectories.has(entry.name)) {
+                    directoriesSkipped.push(relativePath);
+                    continue;
+                }
+                queue.push(absolutePath);
+                continue;
+            }
+            if (!isFile) {
+                continue;
+            }
+            try {
+                const stat = await fs.lstat(absolutePath);
+                if (stat.size > maxFileSizeBytes) {
+                    filesSkippedOversized += 1;
+                    continue;
+                }
+                files.push({
+                    absolutePath,
+                    relativePath,
+                    sizeBytes: Number(stat.size),
+                    isSymlink,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "stat failed";
+                permissionErrors.push(`${relativePath}: ${message}`);
+            }
+        }
+    }
+    files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return {
+        files,
+        directoriesSkipped,
+        filesSkippedOversized,
+        permissionErrors,
+        elapsedMs: Math.round(performance.now() - started),
+    };
+}
+/**
+ * Targeted existence checks for known config files (O(1) per path).
+ */
+export async function findKnownFiles(root, candidates) {
+    const found = [];
+    await Promise.all(candidates.map(async (relative) => {
+        const absolute = path.join(root, relative);
+        if (!isPathInsideRoot(root, absolute)) {
+            return;
+        }
+        try {
+            await fs.access(absolute);
+            found.push(relative.split(path.sep).join("/"));
+        }
+        catch {
+            // missing is fine
+        }
+    }));
+    return found.sort((a, b) => a.localeCompare(b));
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { scan } from "./core/scanner/scan.js";
+export { PACKAGE_VERSION } from "./constants.js";
+export type { ScanOptions, ScanResult, RepositoryInfo, Finding, FindingsSummary, Scores, AgentPresence, AgentDetectionResult, CliOptions, ExitCode, } from "./types/index.js";
+export { EXIT_CODES } from "./types/index.js";
+export { agentRegistry } from "./agents/registry.js";
+export { detectAgents } from "./agents/detect-agents.js";
+export { ruleRegistry, getRuleById } from "./core/rules/registry.js";
+export { runRules } from "./core/rules/run-rules.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { scan } from "./core/scanner/scan.js";
+export { PACKAGE_VERSION } from "./constants.js";
+export { EXIT_CODES } from "./types/index.js";
+export { agentRegistry } from "./agents/registry.js";
+export { detectAgents } from "./agents/detect-agents.js";
+export { ruleRegistry, getRuleById } from "./core/rules/registry.js";
+export { runRules } from "./core/rules/run-rules.js";

package/dist/reporters/json/report.d.ts

@@ -0,0 +1,5 @@
+import type { ScanResult } from "../../types/index.js";
+/**
+ * Stable machine-readable scan output. No decorative terminal formatting.
+ */
+export declare function renderJsonReport(result: ScanResult): string;