@praneeth_54/agentdoctor 2.1.0 → 3.0.0

package/dist/product/features/intelligence.js

@@ -0,0 +1,158 @@
+import path from "node:path";
+import { analyzeApiSurface } from "../api/doctor.js";
+import { analyzeDatabaseSchema } from "../database/doctor.js";
+import { isLikelyRequirementsDoc, isMarkdownDoc, loadProjectSourceFiles, } from "../evidence-scan.js";
+import { readTextFile } from "../../utils/fs.js";
+import { detectProject } from "../../detectors/project.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+const FEATURE_MARKER = /^(?:#{1,4}\s+)?(?:FEATURE|Feature)[:\s-]+(.+)$|<!--\s*FEATURE:\s*(.+?)\s*-->/i;
+const FEATURE_INLINE = /FEATURE:\s*([^\n\r]+)/gi;
+const UI_HEURISTICS = [
+    /pages?\//i,
+    /views?\//i,
+    /screens?\//i,
+    /components?\//i,
+    /\.tsx$/i,
+    /\.vue$/i,
+    /filament/i,
+    /livewire/i,
+];
+const SERVICE_HEURISTICS = [/services?\//i, /usecases?\//i, /domain\//i, /handlers?\//i];
+function slugFeature(title, source, line) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 48);
+    return `${source.replace(/[^\w./-]/g, "_")}:${line}:${slug || "feature"}`;
+}
+function tokenize(title) {
+    return title
+        .toLowerCase()
+        .split(/\W+/)
+        .filter((t) => t.length > 3);
+}
+function fileMatchesTokens(relativePath, content, tokens) {
+    if (!tokens.length)
+        return false;
+    const hay = `${relativePath}\n${content}`.toLowerCase();
+    const hits = tokens.filter((t) => hay.includes(t));
+    return hits.length >= Math.min(2, tokens.length);
+}
+function classifyUiPath(relativePath) {
+    return UI_HEURISTICS.some((re) => re.test(relativePath));
+}
+function classifyServicePath(relativePath) {
+    return SERVICE_HEURISTICS.some((re) => re.test(relativePath));
+}
+async function collectFeatureMarkersFromDocs(root, maxFileSizeBytes) {
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const out = [];
+    for (const entry of detection.discovery.files) {
+        const rel = entry.relativePath.replace(/\\/g, "/");
+        if (!isMarkdownDoc(rel))
+            continue;
+        if (!isLikelyRequirementsDoc(rel) && !rel.toLowerCase().includes("feature"))
+            continue;
+        const content = await readTextFile(path.join(root, rel), maxFileSizeBytes);
+        if (content === null)
+            continue;
+        const lines = content.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i] ?? "";
+            const heading = FEATURE_MARKER.exec(line.trim());
+            if (heading) {
+                const title = (heading[1] ?? heading[2] ?? "").trim();
+                if (title)
+                    out.push({ title, sourcePath: rel, line: i + 1 });
+            }
+            FEATURE_INLINE.lastIndex = 0;
+            let inline;
+            while ((inline = FEATURE_INLINE.exec(line)) !== null) {
+                const title = inline[1]?.trim();
+                if (title) {
+                    out.push({ title, sourcePath: rel, line: i + 1 });
+                }
+            }
+        }
+    }
+    return out;
+}
+export async function analyzeFeatureIntelligence(rootInput, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE_BYTES) {
+    const root = resolveRepoRoot(rootInput);
+    const limitations = [
+        "Feature markers parsed from docs (FEATURE / HTML comments) — not a product management integration.",
+        "UI→API→service→db links are heuristic substring matches — not runtime tracing.",
+        "Zombie features = doc marker with no matching source file token hits.",
+    ];
+    const markers = await collectFeatureMarkersFromDocs(root, maxFileSizeBytes);
+    const { files } = await loadProjectSourceFiles(root, (p) => !p.includes("node_modules/") && !p.startsWith(".agentdoctor/"), maxFileSizeBytes);
+    const apiReport = await analyzeApiSurface(root);
+    const dbReport = await analyzeDatabaseSchema(root);
+    const features = [];
+    for (const marker of markers) {
+        const tokens = tokenize(marker.title);
+        const links = [];
+        let codeHits = 0;
+        for (const f of files) {
+            if (isMarkdownDoc(f.relativePath))
+                continue;
+            if (!fileMatchesTokens(f.relativePath, f.content, tokens))
+                continue;
+            codeHits += 1;
+            if (classifyUiPath(f.relativePath)) {
+                links.push({
+                    layer: "ui",
+                    label: path.basename(f.relativePath),
+                    path: f.relativePath,
+                    truth: "INFERRED",
+                    evidence: [{ path: f.relativePath, excerpt: marker.title.slice(0, 80) }],
+                });
+            }
+            else if (classifyServicePath(f.relativePath)) {
+                links.push({
+                    layer: "service",
+                    label: path.basename(f.relativePath),
+                    path: f.relativePath,
+                    truth: "INFERRED",
+                    evidence: [{ path: f.relativePath, excerpt: marker.title.slice(0, 80) }],
+                });
+            }
+        }
+        for (const ep of apiReport.endpoints) {
+            const hay = `${ep.pathPattern} ${ep.method}`.toLowerCase();
+            if (tokens.some((t) => hay.includes(t))) {
+                links.push({
+                    layer: "api",
+                    label: `${ep.method} ${ep.pathPattern}`,
+                    truth: ep.truth,
+                    evidence: ep.evidence,
+                });
+            }
+        }
+        for (const obj of dbReport.objects) {
+            const hay = obj.name.toLowerCase();
+            if (tokens.some((t) => hay.includes(t))) {
+                links.push({
+                    layer: "db",
+                    label: obj.name,
+                    truth: obj.truth,
+                    evidence: obj.evidence,
+                });
+            }
+        }
+        const zombie = codeHits === 0;
+        const truth = links.length > 0 ? "INFERRED" : zombie ? "PARTIAL" : "UNKNOWN";
+        features.push({
+            featureId: slugFeature(marker.title, marker.sourcePath, marker.line),
+            title: marker.title,
+            docSource: marker.sourcePath,
+            docLine: marker.line,
+            links,
+            zombie,
+            truth,
+        });
+    }
+    return { root, features, limitations };
+}

package/dist/product/forensic/mode.d.ts

@@ -0,0 +1,25 @@
+import { analyzeGitIntelligence } from "../../intelligence/git/analyze.js";
+import { getBrainStatus } from "../../core/brain-cli/service.js";
+import type { TruthLabel } from "../truth.js";
+export interface ForensicAnalysisReport {
+    root: string;
+    mode: "read-only";
+    brainStatus: Awaited<ReturnType<typeof getBrainStatus>>;
+    git: Awaited<ReturnType<typeof analyzeGitIntelligence>>;
+    changeLedgerEntryCount: number;
+    decisionCount: number;
+    findings: Array<{
+        id: string;
+        label: string;
+        truth: TruthLabel;
+        detail: string;
+    }>;
+    limitations: string[];
+}
+export declare class ForensicWriteRefusedError extends Error {
+    readonly code = "FORENSIC_READ_ONLY";
+    constructor(message?: string);
+}
+/** Call before any mutating product operation when forensic mode is active. */
+export declare function assertForensicReadOnly(forensicMode: boolean): void;
+export declare function runForensicAnalysis(rootInput: string): Promise<ForensicAnalysisReport>;

package/dist/product/forensic/mode.js

@@ -0,0 +1,70 @@
+import { analyzeGitIntelligence } from "../../intelligence/git/analyze.js";
+import { getBrainStatus } from "../../core/brain-cli/service.js";
+import { readChangeLedger } from "../ledger/change-ledger.js";
+import { loadDecisionLedger } from "../decisions/ledger.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+export class ForensicWriteRefusedError extends Error {
+    code = "FORENSIC_READ_ONLY";
+    constructor(message = "Forensic mode refuses write operations") {
+        super(message);
+        this.name = "ForensicWriteRefusedError";
+    }
+}
+/** Call before any mutating product operation when forensic mode is active. */
+export function assertForensicReadOnly(forensicMode) {
+    if (forensicMode) {
+        throw new ForensicWriteRefusedError();
+    }
+}
+export async function runForensicAnalysis(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const limitations = [
+        "Forensic mode aggregates read-only signals; it does not modify the repository.",
+        "Change/decision ledgers may be incomplete if never used.",
+    ];
+    const [brainStatus, git, changeLedger, decisions] = await Promise.all([
+        getBrainStatus(root),
+        analyzeGitIntelligence(root),
+        readChangeLedger(root),
+        loadDecisionLedger(root),
+    ]);
+    const findings = [];
+    findings.push({
+        id: "brain-snapshot",
+        label: "Project Brain snapshot present",
+        truth: brainStatus.hasSnapshot ? "VERIFIED" : "UNKNOWN",
+        detail: brainStatus.hasSnapshot
+            ? `latest=${brainStatus.latestSnapshotId}`
+            : "No snapshot in .agentdoctor/project-brain",
+    });
+    findings.push({
+        id: "git-available",
+        label: "Git repository available",
+        truth: git.gitAvailable ? "VERIFIED" : "UNKNOWN",
+        detail: git.gitAvailable
+            ? `hotspots=${git.hotspots.length}`
+            : "Not a git repo or git unavailable",
+    });
+    findings.push({
+        id: "change-ledger",
+        label: "AI change ledger entries",
+        truth: changeLedger.entries.length ? "VERIFIED" : "UNKNOWN",
+        detail: `entries=${changeLedger.entries.length}`,
+    });
+    findings.push({
+        id: "decisions",
+        label: "Decision records (ADR + ledger)",
+        truth: decisions.decisions.length ? "VERIFIED" : "PARTIAL",
+        detail: `decisions=${decisions.decisions.length}`,
+    });
+    return {
+        root,
+        mode: "read-only",
+        brainStatus,
+        git,
+        changeLedgerEntryCount: changeLedger.entries.length,
+        decisionCount: decisions.decisions.length,
+        findings,
+        limitations,
+    };
+}

package/dist/product/graph/enrich-languages.d.ts

@@ -0,0 +1,20 @@
+import type { RepositoryGraph } from "../../platform/types.js";
+import type { LanguageId } from "../../languages/types.js";
+export interface LanguageGraphEnrichmentStats {
+    filesAttempted: number;
+    filesParsed: number;
+    filesSkippedUnsupported: number;
+    nodesAdded: number;
+    edgesAdded: number;
+    byLanguage: Partial<Record<LanguageId, number>>;
+    limitations: string[];
+}
+/**
+ * Walk a bounded set of Python/PHP/Go sources and merge adapter symbols/imports/calls into the graph.
+ */
+export declare function enrichGraphWithLanguageAdapters(graph: RepositoryGraph, rootInput: string, options?: {
+    maxFiles?: number;
+}): Promise<{
+    graph: RepositoryGraph;
+    stats: LanguageGraphEnrichmentStats;
+}>;

package/dist/product/graph/enrich-languages.js

@@ -0,0 +1,193 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { getAdapterForFile, parseSourceFile } from "../../languages/index.js";
+import { readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot, toPosixRelative } from "../../utils/path.js";
+function nodeId(kind, key) {
+    return `${kind}:${createHash("sha1").update(key).digest("hex").slice(0, 12)}`;
+}
+const LANG_FILE_RE = /\.(py|php|go|java|kt|kts|rs|dart)$/i;
+async function listLanguageSourceFiles(root, limit = 120) {
+    const out = [];
+    const skip = new Set(["node_modules", ".git", "dist", "coverage", ".agentdoctor", "vendor"]);
+    async function walk(dir) {
+        if (out.length >= limit)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (out.length >= limit)
+                return;
+            if (skip.has(e.name))
+                continue;
+            const abs = path.join(dir, e.name);
+            if (e.isSymbolicLink())
+                continue;
+            if (e.isDirectory()) {
+                await walk(abs);
+                continue;
+            }
+            if (LANG_FILE_RE.test(e.name)) {
+                out.push(abs);
+            }
+        }
+    }
+    await walk(root);
+    return out.sort();
+}
+function evidenceFromAdapter(kind) {
+    if (kind === "ast")
+        return "verified";
+    return "unknown";
+}
+/**
+ * Walk a bounded set of Python/PHP/Go sources and merge adapter symbols/imports/calls into the graph.
+ */
+export async function enrichGraphWithLanguageAdapters(graph, rootInput, options) {
+    const root = resolveRepoRoot(rootInput);
+    const maxFiles = options?.maxFiles ?? 120;
+    const limitations = [
+        "Language enrichment covers .py/.php/.go/.java/.kt/.kts/.rs/.dart, capped file budget, skips unsupported adapters.",
+        "Symbol/call edges from language adapters may be partial — evidence follows adapter (ast→verified, else unknown).",
+    ];
+    const existingNodeIds = new Set(graph.nodes.map((n) => n.id));
+    const existingEdgeIds = new Set(graph.edges.map((e) => e.id));
+    const nodes = [...graph.nodes];
+    const edges = [...graph.edges];
+    const pushNode = (n) => {
+        if (existingNodeIds.has(n.id))
+            return;
+        existingNodeIds.add(n.id);
+        nodes.push(n);
+    };
+    const pushEdge = (e) => {
+        if (existingEdgeIds.has(e.id))
+            return;
+        existingEdgeIds.add(e.id);
+        edges.push(e);
+    };
+    const nodesBefore = nodes.length;
+    const edgesBefore = edges.length;
+    const byLanguage = {};
+    let filesAttempted = 0;
+    let filesParsed = 0;
+    let filesSkippedUnsupported = 0;
+    const files = await listLanguageSourceFiles(root, maxFiles);
+    if (files.length >= maxFiles) {
+        limitations.push(`Language file walk capped at ${maxFiles} files`);
+    }
+    for (const absolute of files) {
+        filesAttempted += 1;
+        const rel = toPosixRelative(root, absolute);
+        const adapter = getAdapterForFile(rel);
+        if (!adapter) {
+            filesSkippedUnsupported += 1;
+            continue;
+        }
+        const caps = adapter.capabilities();
+        if (caps.parse !== "supported") {
+            filesSkippedUnsupported += 1;
+            continue;
+        }
+        const source = await readTextFile(absolute, 512 * 1024);
+        if (source === null)
+            continue;
+        const parsed = await parseSourceFile(rel, source);
+        if (!parsed.ok) {
+            limitations.push(`Parse failed for ${rel}: ${parsed.diagnostics[0] ?? "unknown"}`);
+            continue;
+        }
+        filesParsed += 1;
+        byLanguage[parsed.language] = (byLanguage[parsed.language] ?? 0) + 1;
+        const fileId = nodeId("file", rel);
+        pushNode({ id: fileId, kind: "file", label: path.basename(rel), path: rel });
+        for (const sym of parsed.symbols) {
+            if (sym.evidence === "unsupported")
+                continue;
+            const symId = nodeId("function", `${rel}:${sym.name}:${sym.kind}`);
+            pushNode({
+                id: symId,
+                kind: sym.kind === "class" ? "class" : "function",
+                label: sym.name,
+                path: rel,
+                meta: {
+                    parser: `language-${parsed.language}`,
+                    symbolKind: sym.kind,
+                },
+            });
+            pushEdge({
+                id: nodeId("edge", `${fileId}->${symId}`),
+                from: fileId,
+                to: symId,
+                kind: "defines",
+                evidence: evidenceFromAdapter(sym.evidence),
+            });
+        }
+        for (const imp of parsed.imports) {
+            if (imp.evidence === "unsupported")
+                continue;
+            const depId = nodeId("dependency", `${rel}->${imp.specifier}`);
+            pushNode({
+                id: depId,
+                kind: "dependency",
+                label: imp.specifier,
+                path: rel,
+                meta: { parser: `language-${parsed.language}`, specifier: imp.specifier },
+            });
+            pushEdge({
+                id: nodeId("edge", `${fileId}->${depId}`),
+                from: fileId,
+                to: depId,
+                kind: "imports",
+                evidence: evidenceFromAdapter(imp.evidence),
+            });
+        }
+        for (const call of parsed.calls) {
+            if (call.evidence === "unsupported")
+                continue;
+            const callId = nodeId("function", `call:${rel}:${call.callee}`);
+            pushNode({
+                id: callId,
+                kind: "function",
+                label: call.callee,
+                path: rel,
+                meta: { callSite: true, parser: `language-${parsed.language}` },
+            });
+            pushEdge({
+                id: nodeId("edge", `${fileId}->call:${call.callee}:${call.callee}`),
+                from: fileId,
+                to: callId,
+                kind: "calls",
+                evidence: "inferred",
+            });
+        }
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    edges.sort((a, b) => a.id.localeCompare(b.id));
+    if (filesParsed === 0 && filesAttempted > 0 && filesSkippedUnsupported === filesAttempted) {
+        limitations.push("No supported language adapters available for discovered multi-language source files.");
+    }
+    return {
+        graph: {
+            ...graph,
+            nodes,
+            edges,
+            limitations: [...graph.limitations, ...limitations],
+        },
+        stats: {
+            filesAttempted,
+            filesParsed,
+            filesSkippedUnsupported,
+            nodesAdded: nodes.length - nodesBefore,
+            edgesAdded: edges.length - edgesBefore,
+            byLanguage,
+            limitations,
+        },
+    };
+}

package/dist/product/health/code-health.d.ts

@@ -0,0 +1,20 @@
+import type { GitIntelligenceReport } from "../../intelligence/git/analyze.js";
+import type { ArchitectureCheckResult } from "../../architecture/contract.js";
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface CodeHealthIndicator {
+    id: string;
+    label: string;
+    value: number | string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface CodeHealthReport {
+    root: string;
+    indicators: CodeHealthIndicator[];
+    limitations: string[];
+}
+export declare function analyzeCodeHealth(rootInput: string, options?: {
+    gitReport?: GitIntelligenceReport;
+    architectureCheck?: ArchitectureCheckResult;
+    maxFileSizeBytes?: number;
+}): Promise<CodeHealthReport>;

package/dist/product/health/code-health.js

@@ -0,0 +1,149 @@
+import path from "node:path";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
+import { readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+function isTestPath(relativePath) {
+    const p = relativePath.toLowerCase();
+    return (p.includes(".test.") ||
+        p.includes(".spec.") ||
+        p.startsWith("tests/") ||
+        p.startsWith("test/") ||
+        p.includes("__tests__/"));
+}
+function isSourcePath(relativePath) {
+    const p = relativePath.toLowerCase();
+    if (isTestPath(p))
+        return false;
+    return (p.endsWith(".ts") ||
+        p.endsWith(".tsx") ||
+        p.endsWith(".js") ||
+        p.endsWith(".jsx") ||
+        p.endsWith(".py") ||
+        p.endsWith(".php") ||
+        p.endsWith(".go") ||
+        p.endsWith(".rs"));
+}
+async function countTodoFixme(root, files, maxBytes) {
+    let todo = 0;
+    let fixme = 0;
+    const evidence = [];
+    const re = /\b(TODO|FIXME)\b/g;
+    for (const f of files) {
+        const text = await readTextFile(path.join(root, f.relativePath), maxBytes);
+        if (!text)
+            continue;
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            if (m[1] === "TODO")
+                todo++;
+            else
+                fixme++;
+            if (evidence.length < 8) {
+                const line = text.slice(0, m.index).split("\n").length;
+                const excerpt = text.split(/\r?\n/)[line - 1]?.trim().slice(0, 100);
+                evidence.push({
+                    path: f.relativePath.replace(/\\/g, "/"),
+                    line,
+                    ...(excerpt !== undefined ? { excerpt } : {}),
+                });
+            }
+        }
+    }
+    return { todo, fixme, evidence };
+}
+export async function analyzeCodeHealth(rootInput, options) {
+    const maxFileSizeBytes = options?.maxFileSizeBytes ?? DEFAULT_MAX_FILE_SIZE_BYTES;
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const paths = detection.discovery.files.map((f) => f.relativePath.replace(/\\/g, "/"));
+    const limitations = [
+        "Scores are descriptive indicators with evidence; not a single authoritative debt score.",
+        "Hotspot overlap requires git intelligence input.",
+    ];
+    const sourceFiles = paths.filter(isSourcePath);
+    const testFiles = paths.filter(isTestPath);
+    const { todo, fixme, evidence: todoEvidence, } = await countTodoFixme(root, detection.discovery.files, maxFileSizeBytes);
+    const indicators = [
+        {
+            id: "file-count",
+            label: "Discovered files",
+            value: paths.length,
+            truth: "VERIFIED",
+            evidence: [{ path: ".", excerpt: `discovery.files.length=${paths.length}` }],
+        },
+        {
+            id: "source-file-count",
+            label: "Source-like files",
+            value: sourceFiles.length,
+            truth: "INFERRED",
+            evidence: [{ path: ".", excerpt: `extension/heuristic count=${sourceFiles.length}` }],
+        },
+        {
+            id: "test-file-count",
+            label: "Test-like files",
+            value: testFiles.length,
+            truth: "INFERRED",
+            evidence: [{ path: ".", excerpt: `test path heuristic count=${testFiles.length}` }],
+        },
+        {
+            id: "test-ratio",
+            label: "Test file ratio (test / (test+source))",
+            value: sourceFiles.length + testFiles.length === 0
+                ? "n/a"
+                : (testFiles.length / (sourceFiles.length + testFiles.length)).toFixed(3),
+            truth: "INFERRED",
+            evidence: [
+                {
+                    path: ".",
+                    excerpt: `tests=${testFiles.length}, sources=${sourceFiles.length}`,
+                },
+            ],
+        },
+        {
+            id: "todo-count",
+            label: "TODO markers",
+            value: todo,
+            truth: "VERIFIED",
+            evidence: todoEvidence.filter((e) => e.excerpt?.includes("TODO")),
+        },
+        {
+            id: "fixme-count",
+            label: "FIXME markers",
+            value: fixme,
+            truth: "VERIFIED",
+            evidence: todoEvidence.filter((e) => e.excerpt?.includes("FIXME")),
+        },
+    ];
+    if (options?.architectureCheck) {
+        indicators.push({
+            id: "architecture-violations",
+            label: "Architecture contract violations",
+            value: options.architectureCheck.violations.length,
+            truth: "VERIFIED",
+            evidence: options.architectureCheck.violations.slice(0, 5).map((v) => ({
+                path: v.fromPath || v.toPath || ".",
+                excerpt: `${v.ruleId}: ${v.description}`.slice(0, 120),
+            })),
+        });
+    }
+    if (options?.gitReport?.gitAvailable) {
+        const hotspotPaths = new Set(options.gitReport.hotspots.map((h) => h.path.replace(/\\/g, "/")));
+        const overlap = sourceFiles.filter((p) => hotspotPaths.has(p)).length;
+        indicators.push({
+            id: "hotspot-source-overlap",
+            label: "Source files overlapping git hotspots",
+            value: overlap,
+            truth: "INFERRED",
+            evidence: options.gitReport.hotspots.slice(0, 5).map((h) => ({
+                path: h.path,
+                excerpt: `commits=${h.commits}`,
+            })),
+        });
+    }
+    else {
+        limitations.push("Git hotspot overlap skipped (git unavailable or not provided).");
+    }
+    return { root, indicators, limitations };
+}