@praneeth_54/agentdoctor 2.1.0 → 3.0.0

package/dist/product/decisions/ledger.js

@@ -0,0 +1,110 @@
+import fs from "node:fs/promises";
+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 { resolveSafeRepoPath } from "../../security/paths.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { pathExists } from "../../utils/fs.js";
+function ledgerFile(root) {
+    return path.join(resolveRepoRoot(root), ".agentdoctor", "decisions", "entries.jsonl");
+}
+function isAdrPath(relativePath) {
+    const norm = relativePath.replace(/\\/g, "/").toLowerCase();
+    return (norm.startsWith("docs/adr/") ||
+        norm.startsWith("adr/") ||
+        norm.includes("/adr/") ||
+        /^adr-\d+/i.test(path.basename(relativePath)));
+}
+function parseAdr(relativePath, content) {
+    const lines = content.split(/\r?\n/);
+    let title = "";
+    let status;
+    for (const line of lines) {
+        if (!title && /^#\s+/.test(line)) {
+            title = line.replace(/^#\s+/, "").trim();
+        }
+        const statusMatch = /^\*\*Status\*\*:\s*(.+)$/i.exec(line.trim());
+        if (statusMatch)
+            status = statusMatch[1].trim();
+    }
+    if (!title)
+        return null;
+    const id = relativePath.replace(/[^\w./-]/g, "_");
+    return {
+        id,
+        title,
+        ...(status !== undefined ? { status } : {}),
+        source: "adr-file",
+        truth: "VERIFIED",
+        evidence: [{ path: relativePath, line: 1, excerpt: title.slice(0, 120) }],
+        bodyExcerpt: content.slice(0, 400),
+    };
+}
+export async function parseAdrDecisions(rootInput, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE_BYTES) {
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const decisions = [];
+    for (const entry of detection.discovery.files) {
+        const rel = entry.relativePath.replace(/\\/g, "/");
+        if (!isAdrPath(rel) || !rel.toLowerCase().endsWith(".md"))
+            continue;
+        const text = await readTextFile(path.join(root, rel), maxFileSizeBytes);
+        if (!text)
+            continue;
+        const parsed = parseAdr(rel, text);
+        if (parsed)
+            decisions.push(parsed);
+    }
+    decisions.sort((a, b) => a.id.localeCompare(b.id));
+    return decisions;
+}
+export async function appendDecisionLedgerEntry(rootInput, record) {
+    const root = resolveRepoRoot(rootInput);
+    const dir = path.dirname(ledgerFile(root));
+    await fs.mkdir(dir, { recursive: true });
+    const full = {
+        ...record,
+        source: record.source ?? "ledger",
+        truth: record.truth ?? "VERIFIED",
+        recordedAt: record.recordedAt ?? new Date().toISOString(),
+    };
+    await fs.appendFile(ledgerFile(root), `${JSON.stringify(full)}\n`, "utf8");
+    return full;
+}
+export async function loadDecisionLedger(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const limitations = [
+        "ADR parsing reads markdown titles and Status lines only.",
+        "Ledger JSONL entries are merged with discovered ADR files (deduped by id).",
+    ];
+    const fromAdr = await parseAdrDecisions(root);
+    const fromLedger = [];
+    const file = ledgerFile(root);
+    if (await pathExists(file)) {
+        const text = await fs.readFile(file, "utf8");
+        for (const line of text.split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            try {
+                fromLedger.push(JSON.parse(line));
+            }
+            catch {
+                limitations.push("Skipped malformed decision ledger line.");
+            }
+        }
+    }
+    const byId = new Map();
+    for (const d of [...fromAdr, ...fromLedger]) {
+        byId.set(d.id, d);
+    }
+    return {
+        root,
+        decisions: [...byId.values()].sort((a, b) => a.title.localeCompare(b.title)),
+        ledgerPath: ledgerFile(root),
+        limitations,
+    };
+}
+export function resolveDecisionPath(rootInput, candidate) {
+    return resolveSafeRepoPath(rootInput, candidate);
+}

package/dist/product/deps/analyze.d.ts

@@ -0,0 +1,46 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+import { type LockfilePackageVersion } from "./lockfiles.js";
+export interface DirectDependency {
+    name: string;
+    versionRange: string;
+    packageJsonPath: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface DuplicatePackageName {
+    name: string;
+    paths: string[];
+    truth: TruthLabel;
+}
+export interface UpgradeImpactHint {
+    dependency: string;
+    importers: string[];
+    truth: TruthLabel;
+}
+export interface DependencyAnalysisReport {
+    root: string;
+    monorepo: string;
+    directDependencies: DirectDependency[];
+    duplicateNames: DuplicatePackageName[];
+    lockfilesPresent: string[];
+    lockfilesParsed: string[];
+    transitiveFromLockfile: LockfilePackageVersion[];
+    upgradeImpact: UpgradeImpactHint[];
+    limitations: string[];
+}
+export declare function analyzeDependencies(rootInput: string, options?: {
+    graph?: {
+        nodes: Array<{
+            id: string;
+            kind: string;
+            label: string;
+            path?: string;
+        }>;
+        edges: Array<{
+            from: string;
+            to: string;
+            kind: string;
+        }>;
+    };
+    maxFileSizeBytes?: number;
+}): Promise<DependencyAnalysisReport>;

package/dist/product/deps/analyze.js

@@ -0,0 +1,137 @@
+import path from "node:path";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
+import { detectMonorepo } from "../../detectors/monorepo.js";
+import { readJsonFile } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { parseAllLockfiles } from "./lockfiles.js";
+function basename(rel) {
+    const parts = rel.split("/");
+    return parts[parts.length - 1] ?? rel;
+}
+function lockfilesFromPaths(relativePaths) {
+    const names = new Set();
+    for (const p of relativePaths) {
+        const base = basename(p).toLowerCase();
+        if (base === "package-lock.json" ||
+            base === "yarn.lock" ||
+            base === "pnpm-lock.yaml" ||
+            base === "bun.lockb") {
+            names.add(p.replace(/\\/g, "/"));
+        }
+    }
+    return [...names].sort();
+}
+function importersForPackage(depName, graph) {
+    if (!graph)
+        return [];
+    const importers = new Set();
+    for (const edge of graph.edges) {
+        if (edge.kind !== "imports" && edge.kind !== "depends-on")
+            continue;
+        const target = graph.nodes.find((n) => n.id === edge.to);
+        const source = graph.nodes.find((n) => n.id === edge.from);
+        if (!target || !source)
+            continue;
+        const label = target.label ?? target.id;
+        if (label === depName || label.endsWith(`/${depName}`) || label.includes(depName)) {
+            if (source.path)
+                importers.add(source.path.replace(/\\/g, "/"));
+            else if (source.label)
+                importers.add(source.label);
+        }
+    }
+    return [...importers].sort();
+}
+export async function analyzeDependencies(rootInput, options) {
+    const maxFileSizeBytes = options?.maxFileSizeBytes ?? DEFAULT_MAX_FILE_SIZE_BYTES;
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const relativePaths = detection.discovery.files.map((f) => f.relativePath.replace(/\\/g, "/"));
+    let rootWorkspaces;
+    const rootPkg = await readJsonFile(path.join(root, "package.json"), maxFileSizeBytes);
+    if (rootPkg.ok)
+        rootWorkspaces = rootPkg.data.workspaces;
+    const monorepo = detectMonorepo({
+        relativePaths,
+        packageJsonWorkspaces: rootWorkspaces,
+    }).monorepo;
+    const lockfilesPresent = lockfilesFromPaths(relativePaths);
+    const limitations = [
+        "Direct dependencies are read from package.json files only.",
+        "Transitive versions are VERIFIED only when a lockfile was parsed successfully.",
+    ];
+    if (!lockfilesPresent.length) {
+        limitations.push("No lockfile detected; transitive upgrade impact is UNKNOWN.");
+    }
+    const lockParse = await parseAllLockfiles(root, lockfilesPresent, maxFileSizeBytes);
+    limitations.push(...lockParse.limitations);
+    const packageJsonPaths = relativePaths.filter((p) => basename(p).toLowerCase() === "package.json");
+    const directDependencies = [];
+    const nameToPaths = new Map();
+    for (const rel of packageJsonPaths) {
+        const parsed = await readJsonFile(path.join(root, rel), maxFileSizeBytes);
+        if (!parsed.ok)
+            continue;
+        const pkgName = parsed.data.name?.trim();
+        if (pkgName) {
+            const list = nameToPaths.get(pkgName) ?? [];
+            list.push(rel);
+            nameToPaths.set(pkgName, list);
+        }
+        const sections = [
+            ["dependencies", parsed.data.dependencies],
+            ["devDependencies", parsed.data.devDependencies],
+            ["peerDependencies", parsed.data.peerDependencies],
+        ];
+        for (const [section, deps] of sections) {
+            if (!deps)
+                continue;
+            for (const [name, versionRange] of Object.entries(deps)) {
+                directDependencies.push({
+                    name,
+                    versionRange,
+                    packageJsonPath: rel,
+                    truth: "VERIFIED",
+                    evidence: [{ path: rel, excerpt: `${section}.${name}` }],
+                });
+            }
+        }
+    }
+    directDependencies.sort((a, b) => a.name === b.name
+        ? a.packageJsonPath.localeCompare(b.packageJsonPath)
+        : a.name.localeCompare(b.name));
+    const duplicateNames = [];
+    for (const [name, paths] of nameToPaths) {
+        if (paths.length > 1) {
+            duplicateNames.push({
+                name,
+                paths: [...paths].sort(),
+                truth: "VERIFIED",
+            });
+        }
+    }
+    const upgradeImpact = [];
+    const uniqueDeps = [...new Set(directDependencies.map((d) => d.name))];
+    for (const dep of uniqueDeps) {
+        const importers = importersForPackage(dep, options?.graph);
+        if (importers.length) {
+            upgradeImpact.push({
+                dependency: dep,
+                importers,
+                truth: options?.graph ? "INFERRED" : "UNKNOWN",
+            });
+        }
+    }
+    return {
+        root,
+        monorepo,
+        directDependencies,
+        duplicateNames,
+        lockfilesPresent,
+        lockfilesParsed: lockParse.parsedLockfiles,
+        transitiveFromLockfile: lockParse.packages,
+        upgradeImpact,
+        limitations,
+    };
+}

package/dist/product/deps/lockfiles.d.ts

@@ -0,0 +1,25 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface LockfilePackageVersion {
+    name: string;
+    version: string;
+    lockfile: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface ParsedLockfile {
+    lockfilePath: string;
+    format: "npm" | "yarn" | "pnpm" | "unknown";
+    packages: LockfilePackageVersion[];
+    limitations: string[];
+}
+export declare function parsePackageLockJson(content: string, lockfilePath: string): ParsedLockfile;
+export declare function parseYarnLock(content: string, lockfilePath: string): ParsedLockfile;
+export declare function parsePnpmLockYaml(content: string, lockfilePath: string): ParsedLockfile;
+export declare function parseLockfileAtPath(root: string, relativePath: string, maxBytes: number): Promise<ParsedLockfile | null>;
+export declare function parseAllLockfiles(root: string, lockfilePaths: string[], maxBytes: number): Promise<{
+    packages: LockfilePackageVersion[];
+    parsedLockfiles: string[];
+    limitations: string[];
+}>;
+/** Test helper: read lockfile from disk */
+export declare function readLockfileFile(filePath: string): Promise<string>;

package/dist/product/deps/lockfiles.js

@@ -0,0 +1,200 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readTextFile } from "../../utils/fs.js";
+function npmPackageNameFromKey(key) {
+    if (!key || key === "")
+        return null;
+    const idx = key.lastIndexOf("node_modules/");
+    const tail = idx >= 0 ? key.slice(idx + "node_modules/".length) : key;
+    if (!tail || (tail.startsWith("@") === false && tail.includes("@"))) {
+        const at = tail.indexOf("@");
+        if (at > 0)
+            return tail.slice(0, at);
+    }
+    return tail.split("/").filter(Boolean).pop() ?? null;
+}
+export function parsePackageLockJson(content, lockfilePath) {
+    const limitations = [];
+    let data;
+    try {
+        data = JSON.parse(content);
+    }
+    catch {
+        return {
+            lockfilePath,
+            format: "npm",
+            packages: [],
+            limitations: ["package-lock.json is not valid JSON"],
+        };
+    }
+    const obj = data;
+    const packages = [];
+    const seen = new Set();
+    if (obj.packages && typeof obj.packages === "object") {
+        for (const [key, entry] of Object.entries(obj.packages)) {
+            const version = entry?.version?.trim();
+            if (!version)
+                continue;
+            const name = entry.name?.trim() ||
+                npmPackageNameFromKey(key) ||
+                (key === "" ? null : key.replace(/^node_modules\//, ""));
+            if (!name)
+                continue;
+            const dedupe = `${name}@${version}`;
+            if (seen.has(dedupe))
+                continue;
+            seen.add(dedupe);
+            packages.push({
+                name,
+                version,
+                lockfile: lockfilePath,
+                truth: "VERIFIED",
+                evidence: [{ path: lockfilePath, excerpt: `packages["${key}"].version=${version}` }],
+            });
+        }
+    }
+    else if (obj.dependencies && typeof obj.dependencies === "object") {
+        limitations.push("npm lockfile v1 dependencies tree — shallow direct entries only");
+        for (const [name, entry] of Object.entries(obj.dependencies)) {
+            const version = entry?.version?.trim();
+            if (!version)
+                continue;
+            packages.push({
+                name,
+                version,
+                lockfile: lockfilePath,
+                truth: "VERIFIED",
+                evidence: [{ path: lockfilePath, excerpt: `dependencies.${name}=${version}` }],
+            });
+        }
+    }
+    else {
+        limitations.push("Unrecognized package-lock.json shape");
+    }
+    packages.sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version));
+    return { lockfilePath, format: "npm", packages, limitations };
+}
+export function parseYarnLock(content, lockfilePath) {
+    const packages = [];
+    const seen = new Set();
+    const lines = content.split(/\r?\n/);
+    let currentKey = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const header = /^([^\s].+):$/.exec(line);
+        if (header) {
+            currentKey = header[1].trim();
+            continue;
+        }
+        if (currentKey && /^\s+version\s+/.test(line)) {
+            const verMatch = /version\s+"([^"]+)"/.exec(line);
+            if (!verMatch)
+                continue;
+            const version = verMatch[1];
+            const resolvedName = (() => {
+                const first = currentKey.split(",")[0].trim();
+                const at = first.lastIndexOf("@");
+                if (at <= 0)
+                    return first;
+                return first.slice(0, at);
+            })();
+            const dedupe = `${resolvedName}@${version}`;
+            if (seen.has(dedupe))
+                continue;
+            seen.add(dedupe);
+            packages.push({
+                name: resolvedName,
+                version,
+                lockfile: lockfilePath,
+                truth: "VERIFIED",
+                evidence: [{ path: lockfilePath, line: i + 1, excerpt: line.trim().slice(0, 120) }],
+            });
+        }
+        if (line.trim() === "" && currentKey) {
+            currentKey = null;
+        }
+    }
+    packages.sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version));
+    return {
+        lockfilePath,
+        format: "yarn",
+        packages,
+        limitations: ["yarn.lock parsing uses version blocks — workspace aliases may be incomplete"],
+    };
+}
+export function parsePnpmLockYaml(content, lockfilePath) {
+    const packages = [];
+    const seen = new Set();
+    const limitations = [
+        "pnpm-lock.yaml parsing is heuristic (packages: keys) — not a full YAML AST",
+    ];
+    const pkgSection = /(?:^|\n)packages:\s*\n([\s\S]*?)(?:\n\S|\n*$)/.exec(content);
+    const body = pkgSection?.[1] ?? content;
+    for (const line of body.split(/\r?\n/)) {
+        const keyMatch = /^\s{2}(['"]?)(\/[^'":]+@[^'":]+)\1:\s*$/.exec(line);
+        if (!keyMatch)
+            continue;
+        const key = keyMatch[2];
+        const at = key.lastIndexOf("@");
+        if (at <= 1)
+            continue;
+        const name = key.slice(1, at);
+        const version = key.slice(at + 1);
+        const dedupe = `${name}@${version}`;
+        if (seen.has(dedupe))
+            continue;
+        seen.add(dedupe);
+        packages.push({
+            name,
+            version,
+            lockfile: lockfilePath,
+            truth: "VERIFIED",
+            evidence: [{ path: lockfilePath, excerpt: key.slice(0, 120) }],
+        });
+    }
+    packages.sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version));
+    return { lockfilePath, format: "pnpm", packages, limitations };
+}
+export async function parseLockfileAtPath(root, relativePath, maxBytes) {
+    const abs = path.join(root, relativePath);
+    const base = path.basename(relativePath).toLowerCase();
+    const text = await readTextFile(abs, maxBytes);
+    if (text === null)
+        return null;
+    if (base === "package-lock.json" || base === "npm-shrinkwrap.json") {
+        return parsePackageLockJson(text, relativePath);
+    }
+    if (base === "yarn.lock") {
+        return parseYarnLock(text, relativePath);
+    }
+    if (base === "pnpm-lock.yaml") {
+        return parsePnpmLockYaml(text, relativePath);
+    }
+    return null;
+}
+export async function parseAllLockfiles(root, lockfilePaths, maxBytes) {
+    const all = [];
+    const parsedLockfiles = [];
+    const limitations = [];
+    const seen = new Set();
+    for (const rel of lockfilePaths) {
+        const parsed = await parseLockfileAtPath(root, rel, maxBytes);
+        if (!parsed || parsed.packages.length === 0)
+            continue;
+        parsedLockfiles.push(rel);
+        limitations.push(...parsed.limitations);
+        for (const p of parsed.packages) {
+            const key = `${p.name}@${p.version}::${p.lockfile}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            all.push(p);
+        }
+    }
+    all.sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version));
+    return { packages: all, parsedLockfiles, limitations };
+}
+/** Test helper: read lockfile from disk */
+export async function readLockfileFile(filePath) {
+    return fs.readFile(filePath, "utf8");
+}

package/dist/product/discovery/roots.d.ts

@@ -0,0 +1,42 @@
+import type { TruthLabel } from "../truth.js";
+export interface ProjectCandidate {
+    root: string;
+    score: number;
+    markers: string[];
+    truth: TruthLabel;
+    reason: string;
+}
+export interface ProjectDiscoveryReport {
+    cwd: string;
+    home: string;
+    candidates: ProjectCandidate[];
+    selected: ProjectCandidate | null;
+    blocked: boolean;
+    blockReason: string | null;
+    estimatedEntries: number;
+    limitations: string[];
+}
+export interface DiscoverProjectOptions {
+    cwd?: string;
+    /** Maximum directory entries to count before aborting deep scans. */
+    maxEntries?: number;
+    /** Prefer this path if it is a valid project. */
+    prefer?: string;
+    /** Auto-select highest score when exactly one strong candidate. */
+    autoSelect?: boolean;
+}
+/**
+ * Discover likely project roots from cwd without silently scanning home/Desktop/Downloads
+ * or unbounded parent trees.
+ */
+export declare function discoverProjectRoots(options?: DiscoverProjectOptions): Promise<ProjectDiscoveryReport>;
+export declare function resolveStartedProjectRoot(pathArg: string | undefined, options?: {
+    maxEntries?: number;
+}): Promise<{
+    ok: true;
+    root: string;
+    discovery: ProjectDiscoveryReport;
+} | {
+    ok: false;
+    discovery: ProjectDiscoveryReport;
+}>;