@praneeth_54/agentdoctor 1.0.0 → 1.1.0

package/dist/core/understanding/dependencies/extract.js

@@ -0,0 +1,189 @@
+import { RELATION_CONFIDENCE, extensionOf, isSourceFile } from "./models.js";
+const STRING = `["'\`]([^"'\`]+)["'\`]`;
+function pushUnique(out, specifier, type) {
+    const trimmed = specifier.trim();
+    if (!trimmed || trimmed.startsWith("node:") || trimmed === ".") {
+        return;
+    }
+    // Skip bare relative current-dir noise without a path
+    if (trimmed === "./" || trimmed === "../") {
+        return;
+    }
+    out.push({
+        specifier: trimmed,
+        type,
+        confidence: RELATION_CONFIDENCE[type],
+    });
+}
+function extractJsFamily(content) {
+    const out = [];
+    const fromImport = new RegExp(`\\bimport\\s+(?:type\\s+)?(?:[\\w*{}$,\\s]+\\s+from\\s+)?${STRING}`, "g");
+    for (const match of content.matchAll(fromImport)) {
+        pushUnique(out, match[1] ?? "", "import");
+    }
+    const sideEffect = new RegExp(`\\bimport\\s+${STRING}`, "g");
+    for (const match of content.matchAll(sideEffect)) {
+        pushUnique(out, match[1] ?? "", "import");
+    }
+    const exportFrom = new RegExp(`\\bexport\\s+(?:\\*|\\{[^}]*\\})\\s+from\\s+${STRING}`, "g");
+    for (const match of content.matchAll(exportFrom)) {
+        pushUnique(out, match[1] ?? "", "export");
+    }
+    const requireCall = new RegExp(`\\brequire\\s*\\(\\s*${STRING}\\s*\\)`, "g");
+    for (const match of content.matchAll(requireCall)) {
+        pushUnique(out, match[1] ?? "", "require");
+    }
+    const dynamicImport = new RegExp(`\\bimport\\s*\\(\\s*${STRING}\\s*\\)`, "g");
+    for (const match of content.matchAll(dynamicImport)) {
+        pushUnique(out, match[1] ?? "", "dynamic-import");
+    }
+    return out;
+}
+function extractDart(content) {
+    const out = [];
+    const importRe = /\bimport\s+['"]([^'"]+)['"]/g;
+    for (const match of content.matchAll(importRe)) {
+        pushUnique(out, match[1] ?? "", "import");
+    }
+    const exportRe = /\bexport\s+['"]([^'"]+)['"]/g;
+    for (const match of content.matchAll(exportRe)) {
+        pushUnique(out, match[1] ?? "", "export");
+    }
+    return out;
+}
+function extractJava(content) {
+    const out = [];
+    const importRe = /\bimport\s+(?:static\s+)?([a-zA-Z_][\w.]*)\s*;/g;
+    for (const match of content.matchAll(importRe)) {
+        const pkg = match[1] ?? "";
+        if (pkg.startsWith("java.") || pkg.startsWith("javax.") || pkg.startsWith("jakarta.")) {
+            continue;
+        }
+        pushUnique(out, pkg, "import");
+    }
+    return out;
+}
+function extractGo(content) {
+    const out = [];
+    const single = /\bimport\s+"([^"]+)"/g;
+    for (const match of content.matchAll(single)) {
+        pushUnique(out, match[1] ?? "", "import");
+    }
+    const block = /\bimport\s*\(([\s\S]*?)\)/g;
+    for (const match of content.matchAll(block)) {
+        const body = match[1] ?? "";
+        for (const line of body.matchAll(/"([^"]+)"/g)) {
+            pushUnique(out, line[1] ?? "", "import");
+        }
+    }
+    return out;
+}
+function extractPython(content) {
+    const out = [];
+    const fromImport = /^\s*from\s+([.\w]+)\s+import\s+/gm;
+    for (const match of content.matchAll(fromImport)) {
+        pushUnique(out, match[1] ?? "", "import");
+    }
+    const plainImport = /^\s*import\s+([.\w]+(?:\s*,\s*[.\w]+)*)/gm;
+    for (const match of content.matchAll(plainImport)) {
+        const group = match[1] ?? "";
+        for (const part of group.split(",")) {
+            const name = part
+                .trim()
+                .split(/\s+as\s+/)[0]
+                ?.trim() ?? "";
+            pushUnique(out, name, "import");
+        }
+    }
+    return out;
+}
+function extractRust(content) {
+    const out = [];
+    const useRe = /\buse\s+((?:crate|super|self)::[\w:]+|[\w]+(?:::[\w]+)+)\s*(?:;|::\{)/g;
+    for (const match of content.matchAll(useRe)) {
+        pushUnique(out, match[1] ?? "", "import");
+    }
+    const modRe = /\bmod\s+([a-zA-Z_][\w]*)\s*;/g;
+    for (const match of content.matchAll(modRe)) {
+        pushUnique(out, match[1] ?? "", "module");
+    }
+    return out;
+}
+function extractPhp(content) {
+    const out = [];
+    const useRe = /\buse\s+([A-Za-z_\\][\w\\]*)\s*;/g;
+    for (const match of content.matchAll(useRe)) {
+        pushUnique(out, (match[1] ?? "").replace(/\\/g, "/"), "import");
+    }
+    const requireRe = /\b(?:require|include)(?:_once)?\s*\(?\s*['"]([^'"]+)['"]/g;
+    for (const match of content.matchAll(requireRe)) {
+        pushUnique(out, match[1] ?? "", "require");
+    }
+    // Route::… Controller class references
+    const routeClass = /\[([A-Za-z_\\][\w\\]*)\s*::\s*class/g;
+    for (const match of content.matchAll(routeClass)) {
+        pushUnique(out, (match[1] ?? "").replace(/\\/g, "/"), "route");
+    }
+    return out;
+}
+/**
+ * Extract dependency references from source text using deterministic regex heuristics.
+ */
+export function extractReferences(relativePath, content) {
+    if (!isSourceFile(relativePath)) {
+        return [];
+    }
+    const ext = extensionOf(relativePath);
+    switch (ext) {
+        case ".ts":
+        case ".tsx":
+        case ".js":
+        case ".jsx":
+        case ".mjs":
+        case ".cjs":
+            return extractJsFamily(content);
+        case ".dart":
+            return extractDart(content);
+        case ".java":
+            return extractJava(content);
+        case ".go":
+            return extractGo(content);
+        case ".py":
+            return extractPython(content);
+        case ".rs":
+            return extractRust(content);
+        case ".php":
+            return extractPhp(content);
+        default:
+            return [];
+    }
+}
+export function refineRelationType(options) {
+    const { base, sourcePath, targetPath } = options;
+    if (base === "dynamic-import" ||
+        base === "require" ||
+        base === "export" ||
+        base === "package" ||
+        base === "route" ||
+        base === "module") {
+        return base;
+    }
+    const source = sourcePath.toLowerCase();
+    const target = targetPath.toLowerCase();
+    if (/(^|\/)routes?\//.test(source) || /(^|\/)pages?\//.test(source)) {
+        return "route";
+    }
+    if (/controller/.test(source) && /service/.test(target)) {
+        return "service";
+    }
+    if (/service/.test(source) && /repositor/.test(target)) {
+        return "repository";
+    }
+    if (/repositor/.test(target)) {
+        return "repository";
+    }
+    if (/service/.test(target) && /controller|handler|route/.test(source)) {
+        return "service";
+    }
+    return base;
+}

package/dist/core/understanding/dependencies/index.d.ts

@@ -0,0 +1,4 @@
+export { discoverDependencies, scoreDependencyConfidence } from "./discover.js";
+export { extractReferences, refineRelationType } from "./extract.js";
+export { RELATION_CONFIDENCE } from "./models.js";
+export type { DependencyDiscoveryOptions, DependencyDiscoveryResult, DependencyMatch, DependencyRelationType, ExtractedReference, } from "./types.js";

package/dist/core/understanding/dependencies/index.js

@@ -0,0 +1,3 @@
+export { discoverDependencies, scoreDependencyConfidence } from "./discover.js";
+export { extractReferences, refineRelationType } from "./extract.js";
+export { RELATION_CONFIDENCE } from "./models.js";

package/dist/core/understanding/dependencies/models.d.ts

@@ -0,0 +1,12 @@
+import type { DependencyRelationType } from "./types.js";
+/** Base confidence by relation type. Dynamic imports are intentionally lower. */
+export declare const RELATION_CONFIDENCE: Readonly<Record<DependencyRelationType, number>>;
+export declare const SOURCE_EXTENSIONS: Set<string>;
+export declare const RESOLVE_EXTENSIONS: readonly ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".dart", ".java", ".go", ".py", ".rs", ".php", "/index.ts", "/index.tsx", "/index.js", "/index.jsx", "/index.mjs", "/index.dart", "/__init__.py", "/mod.rs"];
+export declare const MANIFEST_FILES: Set<string>;
+/** Path segments skipped when deriving module labels. */
+export declare const LABEL_STOP_SEGMENTS: Set<string>;
+export declare function extensionOf(relativePath: string): string;
+export declare function isSourceFile(relativePath: string): boolean;
+export declare function titleCaseSegment(segment: string): string;
+export declare function clampConfidence(value: number): number;

package/dist/core/understanding/dependencies/models.js

@@ -0,0 +1,125 @@
+/** Base confidence by relation type. Dynamic imports are intentionally lower. */
+export const RELATION_CONFIDENCE = {
+    import: 0.97,
+    export: 0.96,
+    require: 0.95,
+    "dynamic-import": 0.75,
+    package: 0.9,
+    module: 0.85,
+    route: 0.8,
+    service: 0.88,
+    repository: 0.88,
+};
+export const SOURCE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".dart",
+    ".java",
+    ".go",
+    ".py",
+    ".rs",
+    ".php",
+]);
+export const RESOLVE_EXTENSIONS = [
+    "",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".dart",
+    ".java",
+    ".go",
+    ".py",
+    ".rs",
+    ".php",
+    "/index.ts",
+    "/index.tsx",
+    "/index.js",
+    "/index.jsx",
+    "/index.mjs",
+    "/index.dart",
+    "/__init__.py",
+    "/mod.rs",
+];
+export const MANIFEST_FILES = new Set([
+    "package.json",
+    "tsconfig.json",
+    "tsconfig.base.json",
+    "jsconfig.json",
+    "pubspec.yaml",
+    "go.mod",
+    "cargo.toml",
+    "pyproject.toml",
+]);
+/** Path segments skipped when deriving module labels. */
+export const LABEL_STOP_SEGMENTS = new Set([
+    "src",
+    "lib",
+    "libs",
+    "app",
+    "apps",
+    "packages",
+    "package",
+    "services",
+    "service",
+    "modules",
+    "module",
+    "internal",
+    "cmd",
+    "bin",
+    "dist",
+    "build",
+    "out",
+    "public",
+    "static",
+    "assets",
+    "test",
+    "tests",
+    "spec",
+    "specs",
+    "__tests__",
+    "fixtures",
+    "node_modules",
+    "vendor",
+    "main",
+    "java",
+    "kotlin",
+    "resources",
+]);
+export function extensionOf(relativePath) {
+    const base = relativePath.split("/").pop() ?? relativePath;
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0) {
+        return "";
+    }
+    return base.slice(dot).toLowerCase();
+}
+export function isSourceFile(relativePath) {
+    return SOURCE_EXTENSIONS.has(extensionOf(relativePath));
+}
+export function titleCaseSegment(segment) {
+    if (!segment) {
+        return segment;
+    }
+    const cleaned = segment.replace(/^@/, "").replace(/[^a-zA-Z0-9_-]/g, "");
+    const parts = cleaned.split(/[-_]+/).filter(Boolean);
+    if (parts.length === 0) {
+        return segment;
+    }
+    return parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()).join("");
+}
+export function clampConfidence(value) {
+    if (value < 0) {
+        return 0;
+    }
+    if (value > 1) {
+        return 1;
+    }
+    return Math.round(value * 100) / 100;
+}

package/dist/core/understanding/dependencies/types.d.ts

@@ -0,0 +1,27 @@
+export type DependencyRelationType = "import" | "require" | "dynamic-import" | "export" | "package" | "module" | "route" | "service" | "repository";
+export interface DependencyMatch {
+    from: string;
+    to: string;
+    type: DependencyRelationType;
+    confidence: number;
+    evidence: string[];
+}
+export interface DependencyDiscoveryResult {
+    dependencies: DependencyMatch[];
+    timingMs: number;
+    filesConsidered: number;
+    filesInspected: number;
+}
+export interface DependencyDiscoveryOptions {
+    /** Repository root. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Minimum confidence to include (0–1). Default 0.7. */
+    minConfidence?: number;
+    /** Max bytes to read from a source file. Default 256 KiB. */
+    maxReadBytes?: number;
+}
+export interface ExtractedReference {
+    specifier: string;
+    type: DependencyRelationType;
+    confidence: number;
+}

package/dist/core/understanding/dependencies/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/understanding/domain/discover.d.ts

@@ -0,0 +1,14 @@
+import type { DomainDiscoveryOptions, DomainDiscoveryResult } from "../types/index.js";
+/**
+ * Score a domain from evidence count and token hit density.
+ * Deterministic; no LLM.
+ */
+export declare function scoreDomainConfidence(options: {
+    evidenceCount: number;
+    tokenHits: number;
+}): number;
+/**
+ * Discover coarse product domains from repository path/filename heuristics.
+ * Isolated from scan — call explicitly via the understanding API.
+ */
+export declare function discoverDomains(options?: DomainDiscoveryOptions): Promise<DomainDiscoveryResult>;

package/dist/core/understanding/domain/discover.js

@@ -0,0 +1,90 @@
+import { discoverFiles } from "../../../discovery/files.js";
+import { domainForToken, tokenizeRelativePath } from "../shared/index.js";
+function clampConfidence(value) {
+    if (value < 0) {
+        return 0;
+    }
+    if (value > 1) {
+        return 1;
+    }
+    return Math.round(value * 100) / 100;
+}
+/**
+ * Score a domain from evidence count and token hit density.
+ * Deterministic; no LLM.
+ */
+export function scoreDomainConfidence(options) {
+    const { evidenceCount, tokenHits } = options;
+    if (evidenceCount <= 0) {
+        return 0;
+    }
+    // Base rises with distinct files; bonus for repeated token hits in those files.
+    const base = 0.45 + Math.min(evidenceCount, 8) * 0.06;
+    const densityBonus = Math.min(tokenHits / Math.max(evidenceCount, 1), 3) * 0.05;
+    return clampConfidence(base + densityBonus);
+}
+/**
+ * Discover coarse product domains from repository path/filename heuristics.
+ * Isolated from scan — call explicitly via the understanding API.
+ */
+export async function discoverDomains(options = {}) {
+    const started = performance.now();
+    const cwd = options.cwd ?? process.cwd();
+    const minConfidence = options.minConfidence ?? 0.5;
+    const minEvidence = options.minEvidence ?? 1;
+    const discovery = await discoverFiles({ root: cwd });
+    const byDomain = new Map();
+    for (const file of discovery.files) {
+        const tokens = tokenizeRelativePath(file.relativePath);
+        if (tokens.length === 0) {
+            continue;
+        }
+        const matchedDomains = new Set();
+        for (const token of tokens) {
+            const domain = domainForToken(token);
+            if (!domain) {
+                continue;
+            }
+            matchedDomains.add(domain);
+            const bucket = byDomain.get(domain) ?? { evidence: new Set(), tokenHits: 0 };
+            bucket.tokenHits += 1;
+            byDomain.set(domain, bucket);
+        }
+        for (const domain of matchedDomains) {
+            const bucket = byDomain.get(domain);
+            if (!bucket) {
+                continue;
+            }
+            bucket.evidence.add(file.relativePath);
+        }
+    }
+    const domains = [];
+    for (const [name, bucket] of byDomain) {
+        if (bucket.evidence.size < minEvidence) {
+            continue;
+        }
+        const confidence = scoreDomainConfidence({
+            evidenceCount: bucket.evidence.size,
+            tokenHits: bucket.tokenHits,
+        });
+        if (confidence < minConfidence) {
+            continue;
+        }
+        domains.push({
+            name,
+            confidence,
+            evidence: [...bucket.evidence].sort((a, b) => a.localeCompare(b)),
+        });
+    }
+    domains.sort((a, b) => {
+        if (b.confidence !== a.confidence) {
+            return b.confidence - a.confidence;
+        }
+        return a.name.localeCompare(b.name);
+    });
+    return {
+        domains,
+        timingMs: Math.round(performance.now() - started),
+        filesConsidered: discovery.files.length,
+    };
+}

package/dist/core/understanding/domain/index.d.ts

@@ -0,0 +1,2 @@
+export { discoverDomains, scoreDomainConfidence } from "./discover.js";
+export type { DomainDiscoveryOptions, DomainDiscoveryResult, DomainMatch } from "../types/index.js";

package/dist/core/understanding/domain/index.js

@@ -0,0 +1 @@
+export { discoverDomains, scoreDomainConfidence } from "./discover.js";

package/dist/core/understanding/entrypoints/discover.d.ts

@@ -0,0 +1,6 @@
+import type { EntrypointDiscoveryOptions, EntrypointDiscoveryResult } from "./types.js";
+/**
+ * Discover likely application entrypoints via deterministic path + content heuristics.
+ * Isolated from scan — internal understanding API only.
+ */
+export declare function discoverEntrypoints(options?: EntrypointDiscoveryOptions): Promise<EntrypointDiscoveryResult>;

package/dist/core/understanding/entrypoints/discover.js

@@ -0,0 +1,62 @@
+import { discoverFiles } from "../../../discovery/files.js";
+import { ENTRYPOINT_MODELS } from "./models.js";
+import { extractEntrypointSignals, scoreEntrypointConfidence } from "./extract.js";
+const DEFAULT_MAX_READ_BYTES = 256 * 1024;
+/**
+ * Discover likely application entrypoints via deterministic path + content heuristics.
+ * Isolated from scan — internal understanding API only.
+ */
+export async function discoverEntrypoints(options = {}) {
+    const started = performance.now();
+    const cwd = options.cwd ?? process.cwd();
+    const minConfidence = options.minConfidence ?? 0.55;
+    const maxReadBytes = options.maxReadBytes ?? DEFAULT_MAX_READ_BYTES;
+    const discovery = await discoverFiles({ root: cwd });
+    const entrypoints = [];
+    let filesInspected = 0;
+    for (const file of discovery.files) {
+        for (const model of ENTRYPOINT_MODELS) {
+            if (!model.pathTest(file.relativePath)) {
+                continue;
+            }
+            filesInspected += 1;
+            const extracted = await extractEntrypointSignals({
+                absolutePath: file.absolutePath,
+                model,
+                maxReadBytes,
+            });
+            const confidence = scoreEntrypointConfidence({
+                pathConfidence: model.pathConfidence,
+                signalBoost: model.signalBoost,
+                signalHits: extracted.signalHits,
+                requireSignal: model.requireSignal,
+            });
+            if (confidence === null || confidence < minConfidence) {
+                continue;
+            }
+            const evidence = [`path:${file.relativePath}`, ...extracted.evidence];
+            entrypoints.push({
+                framework: model.framework,
+                file: file.relativePath,
+                confidence,
+                evidence,
+            });
+        }
+    }
+    entrypoints.sort((a, b) => {
+        if (b.confidence !== a.confidence) {
+            return b.confidence - a.confidence;
+        }
+        const frameworkCmp = a.framework.localeCompare(b.framework);
+        if (frameworkCmp !== 0) {
+            return frameworkCmp;
+        }
+        return a.file.localeCompare(b.file);
+    });
+    return {
+        entrypoints,
+        timingMs: Math.round(performance.now() - started),
+        filesConsidered: discovery.files.length,
+        filesInspected,
+    };
+}

package/dist/core/understanding/entrypoints/extract.d.ts

@@ -0,0 +1,19 @@
+import type { EntrypointModel } from "./models.js";
+export interface ExtractedEntrypointSignals {
+    evidence: string[];
+    signalHits: number;
+}
+/**
+ * Read a bounded slice of a candidate file and collect matching content signals.
+ */
+export declare function extractEntrypointSignals(options: {
+    absolutePath: string;
+    model: EntrypointModel;
+    maxReadBytes: number;
+}): Promise<ExtractedEntrypointSignals>;
+export declare function scoreEntrypointConfidence(options: {
+    pathConfidence: number;
+    signalBoost: number;
+    signalHits: number;
+    requireSignal: boolean;
+}): number | null;

package/dist/core/understanding/entrypoints/extract.js

@@ -0,0 +1,43 @@
+import fs from "node:fs/promises";
+/**
+ * Read a bounded slice of a candidate file and collect matching content signals.
+ */
+export async function extractEntrypointSignals(options) {
+    const { absolutePath, model, maxReadBytes } = options;
+    let content;
+    try {
+        const handle = await fs.open(absolutePath, "r");
+        try {
+            const stat = await handle.stat();
+            const size = Math.min(Number(stat.size), maxReadBytes);
+            if (size <= 0) {
+                return { evidence: [], signalHits: 0 };
+            }
+            const buffer = Buffer.alloc(size);
+            const { bytesRead } = await handle.read(buffer, 0, size, 0);
+            content = buffer.subarray(0, bytesRead).toString("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return { evidence: [], signalHits: 0 };
+    }
+    const evidence = [];
+    for (const signal of model.signals) {
+        if (signal.pattern.test(content)) {
+            evidence.push(signal.label);
+        }
+    }
+    return { evidence, signalHits: evidence.length };
+}
+export function scoreEntrypointConfidence(options) {
+    const { pathConfidence, signalBoost, signalHits, requireSignal } = options;
+    if (requireSignal && signalHits === 0) {
+        return null;
+    }
+    const raw = pathConfidence + signalHits * signalBoost;
+    const clamped = Math.min(0.99, Math.max(0, raw));
+    return Math.round(clamped * 100) / 100;
+}

package/dist/core/understanding/entrypoints/index.d.ts

@@ -0,0 +1,4 @@
+export { discoverEntrypoints } from "./discover.js";
+export { scoreEntrypointConfidence, extractEntrypointSignals } from "./extract.js";
+export { ENTRYPOINT_MODELS } from "./models.js";
+export type { EntrypointDiscoveryOptions, EntrypointDiscoveryResult, EntrypointFramework, EntrypointMatch, } from "./types.js";

package/dist/core/understanding/entrypoints/index.js

@@ -0,0 +1,3 @@
+export { discoverEntrypoints } from "./discover.js";
+export { scoreEntrypointConfidence, extractEntrypointSignals } from "./extract.js";
+export { ENTRYPOINT_MODELS } from "./models.js";

package/dist/core/understanding/entrypoints/models.d.ts

@@ -0,0 +1,26 @@
+import type { EntrypointFramework } from "./types.js";
+export interface ContentSignal {
+    /** Stable evidence label returned in JSON (e.g. "runApp()"). */
+    label: string;
+    pattern: RegExp;
+}
+export interface EntrypointModel {
+    framework: EntrypointFramework;
+    /** Path must match before we inspect content (except contentOnly models). */
+    pathTest: (relativePath: string) => boolean;
+    signals: ContentSignal[];
+    /** Confidence when only the path convention matches. */
+    pathConfidence: number;
+    /** Added per distinct content signal hit, capped with pathConfidence at 0.99. */
+    signalBoost: number;
+    /**
+     * When true, pathTest alone is insufficient — at least one content signal required.
+     * Prevents guessing from generic names like main.ts / app.ts.
+     */
+    requireSignal: boolean;
+}
+/**
+ * Deterministic entrypoint models. Order matters for stable multi-match preference
+ * when the same file could qualify under multiple frameworks (NestJS before Node).
+ */
+export declare const ENTRYPOINT_MODELS: readonly EntrypointModel[];