@praneeth_54/agentdoctor 2.0.1 → 3.0.0

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 };
+}

package/dist/product/index.d.ts

@@ -0,0 +1,69 @@
+export type { TruthLabel, ProductEvidence } from "./truth.js";
+export { minProductTruth, truthLabelDescription } from "./truth.js";
+export { traceRequirements } from "./requirements/trace.js";
+export type { RequirementTrace, RequirementsTraceReport } from "./requirements/trace.js";
+export { analyzeApiSurface } from "./api/doctor.js";
+export type { ApiDoctorReport, ApiEndpointFinding } from "./api/doctor.js";
+export { analyzeDatabaseSchema } from "./database/doctor.js";
+export type { DatabaseDoctorReport, SchemaObjectFinding, SchemaDriftFinding, SchemaRelationFinding, } from "./database/doctor.js";
+export { analyzeEvents } from "./events/doctor.js";
+export type { EventsDoctorReport, EventFlowNode, EventFlowEdge } from "./events/doctor.js";
+export { analyzeDependencies } from "./deps/analyze.js";
+export type { DependencyAnalysisReport, DirectDependency, DuplicatePackageName, UpgradeImpactHint, } from "./deps/analyze.js";
+export { analyzeCodeHealth } from "./health/code-health.js";
+export type { CodeHealthReport, CodeHealthIndicator } from "./health/code-health.js";
+export { buildSoftwareMap } from "./map/software-map.js";
+export type { SoftwareMap, SoftwareMapNode, SoftwareMapNodeKind } from "./map/software-map.js";
+export { appendChangeLedgerEntry, readChangeLedger, listChangeLedgerEntries, } from "./ledger/change-ledger.js";
+export type { ChangeLedgerEntry, ChangeLedgerListResult } from "./ledger/change-ledger.js";
+export { analyzeWhatIf } from "./whatif/engine.js";
+export type { WhatIfReport, WhatIfAffectedItem } from "./whatif/engine.js";
+export { loadDecisionLedger, appendDecisionLedgerEntry, parseAdrDecisions, resolveDecisionPath, } from "./decisions/ledger.js";
+export type { DecisionRecord, DecisionLedgerResult } from "./decisions/ledger.js";
+export { runForensicAnalysis, assertForensicReadOnly, ForensicWriteRefusedError, } from "./forensic/mode.js";
+export type { ForensicAnalysisReport } from "./forensic/mode.js";
+export { buildSoftwareDigitalTwinSnapshot } from "./twin/digital-twin.js";
+export type { SoftwareDigitalTwin } from "./twin/digital-twin.js";
+export { buildSoftwareDigitalTwin, updateTwin, loadTwinSnapshot, saveTwinSnapshot, invalidateTwinSnapshot, } from "./twin/store.js";
+export type { StoredTwinSnapshot, TwinSnapshotMeta } from "./twin/store.js";
+export { parsePackageLockJson, parseYarnLock, parsePnpmLockYaml, parseAllLockfiles, } from "./deps/lockfiles.js";
+export type { LockfilePackageVersion, ParsedLockfile } from "./deps/lockfiles.js";
+export { discoverOpenApiEndpoints } from "./api/openapi.js";
+export { buildIndex, searchIndex, searchHybrid, documentId } from "./search/index.js";
+export type { TfidfIndex, IndexDocument } from "./search/index.js";
+export { runEvalLab } from "./eval/lab.js";
+export type { EvalLabReport, EvalCheckResult } from "./eval/lab.js";
+export { diagnoseAgentDoctorSelf } from "./self/diagnose.js";
+export type { SelfDiagnoseReport, SelfDiagnoseFinding } from "./self/diagnose.js";
+export { analyzeInfra } from "./ops/infra.js";
+export type { InfraReport, InfraArtifact } from "./ops/infra.js";
+export { buildIncidentHypotheses } from "./ops/incident.js";
+export type { IncidentReport, IncidentTimelineItem } from "./ops/incident.js";
+export { discoverProjectRoots, resolveStartedProjectRoot } from "./discovery/roots.js";
+export type { ProjectDiscoveryReport, ProjectCandidate, DiscoverProjectOptions, } from "./discovery/roots.js";
+export { buildProjectDna, persistProjectDna } from "./dna/build.js";
+export type { ProjectDna } from "./dna/build.js";
+export { enrichGraphWithLanguageAdapters } from "./graph/enrich-languages.js";
+export type { LanguageGraphEnrichmentStats } from "./graph/enrich-languages.js";
+export { analyzeSecuritySurface } from "./security/doctor.js";
+export type { SecurityDoctorReport, SecurityPatternFinding } from "./security/doctor.js";
+export { analyzeTestBrain, persistTestBrainReport, mapTestsFromGraph, } from "./testbrain/analyze.js";
+export type { TestBrainReport, FileTestMapping, TestBrainGraphStats, FileTestMappingEvidence, } from "./testbrain/analyze.js";
+export { analyzePrivacySurface } from "./privacy/doctor.js";
+export type { PrivacyDoctorReport, PrivacyFinding } from "./privacy/doctor.js";
+export { searchSymbolsAndConcepts } from "./search/software-search.js";
+export type { SoftwareSearchReport, SoftwareSearchHit } from "./search/software-search.js";
+export { buildTechnicalDebtRoadmap } from "./techdebt/roadmap.js";
+export type { TechnicalDebtRoadmap, TechnicalDebtItem } from "./techdebt/roadmap.js";
+export { loadOrganizationModel, saveOrganizationModel, linkProjectToOrgModel, resolveLinkedProjectRoot, } from "./org/model.js";
+export type { OrganizationModel, OrgEntityRef, OrgProjectLink } from "./org/model.js";
+export { analyzeFeatureIntelligence } from "./features/intelligence.js";
+export type { FeatureIntelligenceReport, FeatureFlow, FeatureFlowLink, } from "./features/intelligence.js";
+export { buildSoftwareEvolutionTimeline } from "./evolution/timeline.js";
+export type { SoftwareEvolutionReport, EvolutionTimelineEvent, EvolutionTrend, } from "./evolution/timeline.js";
+export { queryMemory } from "./memory/institutional.js";
+export type { InstitutionalMemoryQueryResult, MemoryHit } from "./memory/institutional.js";
+export { evaluateApprovalRecord, formatApprovalRecordSummary } from "./approval/model.js";
+export type { ApprovalRecord, ApprovalState, ApprovalRisk, ApprovalEvaluationInput, ApprovalEvaluationResult, } from "./approval/model.js";
+export { issueApprovalGrant, consumeApprovalGrant, hashPlanPayload, hashFileWritePlan, } from "./approval/session.js";
+export type { ApprovalGrant, ConsumeApprovalResult } from "./approval/session.js";

package/dist/product/index.js

@@ -0,0 +1,35 @@
+export { minProductTruth, truthLabelDescription } from "./truth.js";
+export { traceRequirements } from "./requirements/trace.js";
+export { analyzeApiSurface } from "./api/doctor.js";
+export { analyzeDatabaseSchema } from "./database/doctor.js";
+export { analyzeEvents } from "./events/doctor.js";
+export { analyzeDependencies } from "./deps/analyze.js";
+export { analyzeCodeHealth } from "./health/code-health.js";
+export { buildSoftwareMap } from "./map/software-map.js";
+export { appendChangeLedgerEntry, readChangeLedger, listChangeLedgerEntries, } from "./ledger/change-ledger.js";
+export { analyzeWhatIf } from "./whatif/engine.js";
+export { loadDecisionLedger, appendDecisionLedgerEntry, parseAdrDecisions, resolveDecisionPath, } from "./decisions/ledger.js";
+export { runForensicAnalysis, assertForensicReadOnly, ForensicWriteRefusedError, } from "./forensic/mode.js";
+export { buildSoftwareDigitalTwinSnapshot } from "./twin/digital-twin.js";
+export { buildSoftwareDigitalTwin, updateTwin, loadTwinSnapshot, saveTwinSnapshot, invalidateTwinSnapshot, } from "./twin/store.js";
+export { parsePackageLockJson, parseYarnLock, parsePnpmLockYaml, parseAllLockfiles, } from "./deps/lockfiles.js";
+export { discoverOpenApiEndpoints } from "./api/openapi.js";
+export { buildIndex, searchIndex, searchHybrid, documentId } from "./search/index.js";
+export { runEvalLab } from "./eval/lab.js";
+export { diagnoseAgentDoctorSelf } from "./self/diagnose.js";
+export { analyzeInfra } from "./ops/infra.js";
+export { buildIncidentHypotheses } from "./ops/incident.js";
+export { discoverProjectRoots, resolveStartedProjectRoot } from "./discovery/roots.js";
+export { buildProjectDna, persistProjectDna } from "./dna/build.js";
+export { enrichGraphWithLanguageAdapters } from "./graph/enrich-languages.js";
+export { analyzeSecuritySurface } from "./security/doctor.js";
+export { analyzeTestBrain, persistTestBrainReport, mapTestsFromGraph, } from "./testbrain/analyze.js";
+export { analyzePrivacySurface } from "./privacy/doctor.js";
+export { searchSymbolsAndConcepts } from "./search/software-search.js";
+export { buildTechnicalDebtRoadmap } from "./techdebt/roadmap.js";
+export { loadOrganizationModel, saveOrganizationModel, linkProjectToOrgModel, resolveLinkedProjectRoot, } from "./org/model.js";
+export { analyzeFeatureIntelligence } from "./features/intelligence.js";
+export { buildSoftwareEvolutionTimeline } from "./evolution/timeline.js";
+export { queryMemory } from "./memory/institutional.js";
+export { evaluateApprovalRecord, formatApprovalRecordSummary } from "./approval/model.js";
+export { issueApprovalGrant, consumeApprovalGrant, hashPlanPayload, hashFileWritePlan, } from "./approval/session.js";

package/dist/product/ledger/change-ledger.d.ts

@@ -0,0 +1,23 @@
+export interface ChangeLedgerEntry {
+    id: string;
+    recordedAt: string;
+    task?: string;
+    plan?: string;
+    approval?: string;
+    files?: string[];
+    tests?: string[];
+    proofIds?: string[];
+    note?: string;
+}
+export interface ChangeLedgerListResult {
+    root: string;
+    ledgerDir: string;
+    entries: ChangeLedgerEntry[];
+    limitations: string[];
+}
+export declare function appendChangeLedgerEntry(rootInput: string, entry: Omit<ChangeLedgerEntry, "id" | "recordedAt"> & {
+    id?: string;
+    recordedAt?: string;
+}): Promise<ChangeLedgerEntry>;
+export declare function readChangeLedger(rootInput: string): Promise<ChangeLedgerListResult>;
+export declare function listChangeLedgerEntries(rootInput: string): Promise<ChangeLedgerEntry[]>;

package/dist/product/ledger/change-ledger.js

@@ -0,0 +1,64 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { safeRelPath } from "../../security/paths.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { pathExists } from "../../utils/fs.js";
+function ledgerDirFor(root) {
+    return path.join(resolveRepoRoot(root), ".agentdoctor", "change-ledger");
+}
+function ledgerFileFor(root) {
+    return path.join(ledgerDirFor(root), "entries.jsonl");
+}
+async function ensureLedgerDir(root) {
+    const dir = ledgerDirFor(root);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+}
+function newEntryId() {
+    return `cle_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export async function appendChangeLedgerEntry(rootInput, entry) {
+    const root = resolveRepoRoot(rootInput);
+    await ensureLedgerDir(root);
+    const record = {
+        id: entry.id ?? newEntryId(),
+        recordedAt: entry.recordedAt ?? new Date().toISOString(),
+        ...(entry.task !== undefined ? { task: entry.task } : {}),
+        ...(entry.plan !== undefined ? { plan: entry.plan } : {}),
+        ...(entry.approval !== undefined ? { approval: entry.approval } : {}),
+        ...(entry.files !== undefined ? { files: entry.files.map((f) => safeRelPath(root, f)) } : {}),
+        ...(entry.tests !== undefined ? { tests: entry.tests } : {}),
+        ...(entry.proofIds !== undefined ? { proofIds: entry.proofIds } : {}),
+        ...(entry.note !== undefined ? { note: entry.note } : {}),
+    };
+    const line = `${JSON.stringify(record)}\n`;
+    await fs.appendFile(ledgerFileFor(root), line, "utf8");
+    return record;
+}
+export async function readChangeLedger(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const ledgerDir = ledgerDirFor(root);
+    const limitations = ["Append-only JSONL; entries are not cryptographically signed."];
+    const file = ledgerFileFor(root);
+    if (!(await pathExists(file))) {
+        return { root, ledgerDir, entries: [], limitations };
+    }
+    const text = await fs.readFile(file, "utf8");
+    const entries = [];
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        catch {
+            limitations.push("Skipped malformed JSONL line in change ledger.");
+        }
+    }
+    return { root, ledgerDir, entries, limitations };
+}
+export async function listChangeLedgerEntries(rootInput) {
+    const result = await readChangeLedger(rootInput);
+    return result.entries;
+}

package/dist/product/map/software-map.d.ts

@@ -0,0 +1,17 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export type SoftwareMapNodeKind = "root" | "package" | "directory" | "workspace" | "docs" | "tests" | "unknown";
+export interface SoftwareMapNode {
+    id: string;
+    kind: SoftwareMapNodeKind;
+    label: string;
+    path?: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+    children?: SoftwareMapNode[];
+}
+export interface SoftwareMap {
+    root: string;
+    tree: SoftwareMapNode;
+    limitations: string[];
+}
+export declare function buildSoftwareMap(rootInput: string, maxFileSizeBytes?: number): Promise<SoftwareMap>;

package/dist/product/map/software-map.js

@@ -0,0 +1,95 @@
+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 { detectMonorepo } from "../../detectors/monorepo.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+function nodeId(prefix, p) {
+    return `${prefix}:${p.replace(/[^\w./-]/g, "_")}`;
+}
+async function topLevelEntries(root) {
+    try {
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function buildSoftwareMap(rootInput, 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 rootPkgPath = path.join(root, "package.json");
+    try {
+        const raw = await fs.readFile(rootPkgPath, "utf8");
+        rootWorkspaces = JSON.parse(raw).workspaces;
+    }
+    catch {
+        rootWorkspaces = undefined;
+    }
+    const monorepo = detectMonorepo({
+        relativePaths,
+        packageJsonWorkspaces: rootWorkspaces,
+    }).monorepo;
+    const limitations = [
+        "Map is structural (directories/packages), not a full module dependency graph.",
+        `Monorepo signal: ${monorepo}`,
+    ];
+    const packageJsonPaths = relativePaths.filter((p) => p.endsWith("package.json"));
+    const packageNodes = packageJsonPaths.map((p) => ({
+        id: nodeId("pkg", p),
+        kind: p === "package.json" ? "root" : "package",
+        label: path.dirname(p) === "." ? "root package" : path.dirname(p),
+        path: p,
+        truth: "VERIFIED",
+        evidence: [{ path: p }],
+    }));
+    const dirs = await topLevelEntries(root);
+    const dirNodes = dirs.map((name) => {
+        let kind = "directory";
+        if (name === "docs")
+            kind = "docs";
+        if (name === "tests" || name === "test")
+            kind = "tests";
+        return {
+            id: nodeId("dir", name),
+            kind,
+            label: name,
+            path: name,
+            truth: "VERIFIED",
+            evidence: [{ path: name, excerpt: "top-level directory listing" }],
+        };
+    });
+    const tree = {
+        id: nodeId("root", root),
+        kind: "root",
+        label: path.basename(root) || root,
+        path: ".",
+        truth: "VERIFIED",
+        evidence: [{ path: ".", excerpt: "detectProject root" }],
+        children: [
+            {
+                id: "packages-section",
+                kind: "workspace",
+                label: "packages",
+                truth: packageNodes.length ? "VERIFIED" : "UNKNOWN",
+                evidence: packageNodes.slice(0, 3).map((n) => ({ path: n.path ?? "." })),
+                children: packageNodes,
+            },
+            {
+                id: "directories-section",
+                kind: "directory",
+                label: "top-level directories",
+                truth: dirNodes.length ? "VERIFIED" : "PARTIAL",
+                evidence: dirNodes.slice(0, 5).map((n) => ({ path: n.path ?? n.label })),
+                children: dirNodes,
+            },
+        ],
+    };
+    return { root, tree, limitations };
+}