@praneeth_54/agentdoctor 1.1.1 → 2.0.0

package/dist/core/brain-product/init.d.ts

@@ -0,0 +1,45 @@
+import type { KnowledgeStatus } from "../../contracts/index.js";
+export interface ProjectInitAnswers {
+    projectName: string;
+    projectType: string;
+    businessDomain: string;
+    languages: string[];
+    frameworks: string[];
+    database: string;
+    deploymentModel: string;
+    teamStructure: string;
+    securityRequirements: string;
+    preferredArchitecture: string;
+    aiAgentEnvironments: string[];
+}
+export interface BrainProposalArtifact {
+    id: string;
+    kind: string;
+    title: string;
+    path: string;
+    status: KnowledgeStatus;
+    content: string;
+}
+export interface BrainReviewItem {
+    id: string;
+    artifactId: string;
+    status: KnowledgeStatus;
+    decidedBy?: string;
+    decidedAt?: string;
+    note?: string;
+}
+export declare function ensureRepositoryBrainDirs(rootInput: string): Promise<string>;
+/** Generate draft proposal artifacts — never auto-approved. */
+export declare function runProjectInit(rootInput: string, answers: Partial<ProjectInitAnswers>): Promise<{
+    root: string;
+    artifacts: BrainProposalArtifact[];
+}>;
+export declare function listProposals(rootInput: string): Promise<BrainProposalArtifact[]>;
+export declare function reviewProposal(options: {
+    root: string;
+    artifactId: string;
+    decision: "approved" | "rejected" | "pending-review" | "deprecated";
+    by?: string;
+    note?: string;
+}): Promise<BrainReviewItem>;
+export declare function writeBrainProductSnapshot(rootInput: string): Promise<string>;

package/dist/core/brain-product/init.js

@@ -0,0 +1,232 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { resolveRepoRoot, isPathInsideRoot } from "../../utils/path.js";
+import { atomicWriteTextFile } from "../../utils/fs.js";
+function proposalsDir(root) {
+    return path.join(resolveRepoRoot(root), ".agentdoctor", "repository-brain", "proposals");
+}
+function reviewFile(root) {
+    return path.join(resolveRepoRoot(root), ".agentdoctor", "repository-brain", "reviews.json");
+}
+export async function ensureRepositoryBrainDirs(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const base = path.join(root, ".agentdoctor", "repository-brain");
+    await fs.mkdir(path.join(base, "proposals"), { recursive: true });
+    await fs.mkdir(path.join(base, "snapshots"), { recursive: true });
+    return base;
+}
+/** Generate draft proposal artifacts — never auto-approved. */
+export async function runProjectInit(rootInput, answers) {
+    const root = resolveRepoRoot(rootInput);
+    await ensureRepositoryBrainDirs(root);
+    const filled = {
+        projectName: answers.projectName ?? path.basename(root),
+        projectType: answers.projectType ?? "application",
+        businessDomain: answers.businessDomain ?? "unknown",
+        languages: answers.languages?.length ? answers.languages : ["typescript"],
+        frameworks: answers.frameworks ?? [],
+        database: answers.database ?? "unknown",
+        deploymentModel: answers.deploymentModel ?? "unknown",
+        teamStructure: answers.teamStructure ?? "unknown",
+        securityRequirements: answers.securityRequirements ?? "local-first; no secrets in VCS",
+        preferredArchitecture: answers.preferredArchitecture ?? "modular-monolith",
+        aiAgentEnvironments: answers.aiAgentEnvironments?.length
+            ? answers.aiAgentEnvironments
+            : ["cursor", "claude-code"],
+    };
+    const docs = [
+        {
+            kind: "architecture-overview",
+            title: "Architecture overview (proposed)",
+            body: `# Architecture overview\n\nStatus: **proposed** (not approved)\n\nProject: ${filled.projectName}\nType: ${filled.projectType}\nPreferred architecture: ${filled.preferredArchitecture}\nLanguages: ${filled.languages.join(", ")}\nFrameworks: ${filled.frameworks.join(", ") || "(none specified)"}\n\nThis document is AI/tool-generated scaffolding. Human review required before treating as fact.\n`,
+        },
+        {
+            kind: "business-domain-map",
+            title: "Business domain map (proposed)",
+            body: `# Business domain map\n\nPrimary domain: ${filled.businessDomain}\n\n- Core domain: ${filled.businessDomain}\n- Supporting domains: (to be filled during review)\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "feature-map",
+            title: "Feature map (proposed)",
+            body: `# Feature map\n\n1. Core product workflows for ${filled.projectName}\n2. Operator / admin surfaces\n3. Integrations\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "module-plan",
+            title: "Module plan (proposed)",
+            body: `# Module plan\n\nSuggested modules (review before creating):\n- \`core\` — domain logic\n- \`api\` — HTTP / CLI surfaces\n- \`infra\` — persistence / adapters\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "folder-structure",
+            title: "Folder structure proposal",
+            body: `# Folder structure\n\n\`\`\`\nsrc/\n  core/\n  adapters/\n  cli/\ntests/\ndocs/\n\`\`\`\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "domain-model",
+            title: "Domain model (proposed)",
+            body: `# Domain model\n\nEntities TBD for domain **${filled.businessDomain}**.\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "api-proposal",
+            title: "API proposal",
+            body: `# API proposal\n\nLocal-first CLI and optional HTTP API. No public cloud assumed.\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "data-model",
+            title: "Data model proposal",
+            body: `# Data model\n\nDatabase preference: ${filled.database}\nDefault local store: filesystem JSON under \`.agentdoctor/\`.\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "coding-standards",
+            title: "Coding standards (proposed)",
+            body: `# Coding standards\n\n- TypeScript strict\n- Deterministic analysis where claimed\n- No secrets in logs\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "security-rules",
+            title: "Security rules (proposed)",
+            body: `# Security rules\n\nRequirements: ${filled.securityRequirements}\nDeployment: ${filled.deploymentModel}\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "ai-agent-instructions",
+            title: "AI agent instructions (proposed)",
+            body: `# AI agent instructions\n\nEnvironments: ${filled.aiAgentEnvironments.join(", ")}\n\n- Prefer Project Brain / MCP evidence over guessing\n- Never treat proposed docs as approved facts\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "testing-strategy",
+            title: "Testing strategy (proposed)",
+            body: `# Testing strategy\n\n- Unit + integration + CLI smoke\n- Hostile input / path traversal cases\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "deployment-assumptions",
+            title: "Deployment assumptions (proposed)",
+            body: `# Deployment assumptions\n\nModel: ${filled.deploymentModel}\nTeam: ${filled.teamStructure}\n\nStatus: **proposed**\n`,
+        },
+        {
+            kind: "adr-0001",
+            title: "ADR-0001 Local-first storage",
+            body: `# ADR-0001: Local-first storage\n\n## Status\nproposed\n\n## Context\nAgentDoctor must work offline.\n\n## Decision\nFilesystem under \`.agentdoctor/\` is default; SQLite/Postgres optional.\n\n## Consequences\nNo cloud required for core operation.\n`,
+        },
+    ];
+    const artifacts = [];
+    const dir = proposalsDir(root);
+    for (const doc of docs) {
+        const id = `prop_${createHash("sha1").update(doc.kind).digest("hex").slice(0, 10)}`;
+        const rel = `${doc.kind}.md`;
+        const absolute = path.join(dir, rel);
+        if (!isPathInsideRoot(dir, absolute))
+            throw new Error("proposal path escape");
+        await atomicWriteTextFile(absolute, doc.body);
+        artifacts.push({
+            id,
+            kind: doc.kind,
+            title: doc.title,
+            path: path.posix.join(".agentdoctor/repository-brain/proposals", rel),
+            status: "proposed",
+            content: doc.body,
+        });
+    }
+    const meta = {
+        version: "2.0",
+        createdAt: new Date().toISOString(),
+        answers: filled,
+        artifactIds: artifacts.map((a) => a.id),
+        notice: "All init artifacts are proposed/draft — not approved facts",
+    };
+    await atomicWriteTextFile(path.join(root, ".agentdoctor", "repository-brain", "init.json"), `${JSON.stringify(meta, null, 2)}\n`);
+    return { root, artifacts };
+}
+export async function listProposals(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const dir = proposalsDir(root);
+    let files = [];
+    try {
+        files = (await fs.readdir(dir)).filter((f) => f.endsWith(".md")).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const reviews = await loadReviews(root);
+    for (const file of files) {
+        const content = await fs.readFile(path.join(dir, file), "utf8");
+        const kind = file.replace(/\.md$/, "");
+        const id = `prop_${createHash("sha1").update(kind).digest("hex").slice(0, 10)}`;
+        const review = reviews.find((r) => r.artifactId === id);
+        out.push({
+            id,
+            kind,
+            title: kind,
+            path: `.agentdoctor/repository-brain/proposals/${file}`,
+            status: review?.status ?? "proposed",
+            content,
+        });
+    }
+    return out;
+}
+async function loadReviews(root) {
+    try {
+        const raw = await fs.readFile(reviewFile(root), "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.items) ? parsed.items : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function reviewProposal(options) {
+    const root = resolveRepoRoot(options.root);
+    await ensureRepositoryBrainDirs(root);
+    const items = await loadReviews(root);
+    const item = {
+        id: randomUUID(),
+        artifactId: options.artifactId,
+        status: options.decision,
+        decidedBy: options.by ?? "local-reviewer",
+        decidedAt: new Date().toISOString(),
+        ...(options.note ? { note: options.note } : {}),
+    };
+    const next = [...items.filter((i) => i.artifactId !== options.artifactId), item];
+    await atomicWriteTextFile(reviewFile(root), `${JSON.stringify({ version: "2.0", items: next }, null, 2)}\n`);
+    // Keep proposal markdown status in sync with the review decision.
+    const proposals = await listProposals(root);
+    const match = proposals.find((p) => p.id === options.artifactId);
+    if (match) {
+        const abs = path.join(root, match.path);
+        if (isPathInsideRoot(root, abs)) {
+            let content = await fs.readFile(abs, "utf8");
+            const statusLine = `Status: **${options.decision}**`;
+            if (/Status:\s*\*\*[^*]+\*\*/.test(content)) {
+                content = content.replace(/Status:\s*\*\*[^*]+\*\*[^\n]*/g, statusLine);
+            }
+            else {
+                content = `${statusLine}\n\n${content}`;
+            }
+            // Drop stale "not approved" parenthetical if present after replacement edge cases
+            content = content.replace(/\s*\(not approved\)/g, "");
+            await atomicWriteTextFile(abs, content.endsWith("\n") ? content : `${content}\n`);
+        }
+    }
+    return item;
+}
+export async function writeBrainProductSnapshot(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    await ensureRepositoryBrainDirs(root);
+    const proposals = await listProposals(root);
+    const id = `rbs_${Date.now().toString(36)}`;
+    const snapshot = {
+        id,
+        version: "2.0",
+        createdAt: new Date().toISOString(),
+        proposals: proposals.map((p) => ({
+            id: p.id,
+            kind: p.kind,
+            status: p.status,
+            path: p.path,
+        })),
+        notice: "Proposal statuses are human-reviewed when present; otherwise proposed/draft",
+    };
+    const target = path.join(root, ".agentdoctor", "repository-brain", "snapshots", `${id}.json`);
+    await atomicWriteTextFile(target, `${JSON.stringify(snapshot, null, 2)}\n`);
+    await atomicWriteTextFile(path.join(root, ".agentdoctor", "repository-brain", "snapshots", "latest.json"), `${JSON.stringify(snapshot, null, 2)}\n`);
+    return target;
+}

package/dist/core/changes/analyze.d.ts

@@ -0,0 +1,41 @@
+export type ChangeKind = "added" | "modified" | "deleted" | "renamed" | "untracked" | "unknown";
+export interface ChangedFile {
+    path: string;
+    kind: ChangeKind;
+    staged: boolean;
+    /** Module / component attribution when Brain evidence matches this path */
+    modules?: string[];
+}
+export interface ImpactEdge {
+    from: string;
+    to: string;
+    type: string;
+    confidence: number;
+}
+export interface ChangeImpact {
+    status: "observed" | "unknown";
+    reason: string;
+    edges: ImpactEdge[];
+    relatedPaths: string[];
+}
+export interface ChangeReport {
+    root: string;
+    gitAvailable: boolean;
+    head: string | null;
+    since: string | null;
+    files: ChangedFile[];
+    summary: {
+        added: number;
+        modified: number;
+        deleted: number;
+        renamed: number;
+        untracked: number;
+    };
+    impact?: ChangeImpact;
+    limitations: string[];
+}
+export declare function analyzeChanges(options: {
+    root: string;
+    since?: string;
+    impact?: boolean;
+}): Promise<ChangeReport>;

package/dist/core/changes/analyze.js

@@ -0,0 +1,223 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { loadLatestBrain } from "../brain-cli/service.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+function runGit(root, args) {
+    const result = spawnSync("git", args, {
+        cwd: root,
+        encoding: "utf8",
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    return {
+        ok: result.status === 0,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+    };
+}
+function parseNameStatus(line, staged) {
+    const trimmed = line.trimEnd();
+    if (!trimmed) {
+        return null;
+    }
+    const parts = trimmed.split(/\t/);
+    const code = parts[0]?.trim() ?? "";
+    if (!code) {
+        return null;
+    }
+    const kindChar = code[0] ?? "";
+    let kind = "unknown";
+    if (kindChar === "A")
+        kind = "added";
+    else if (kindChar === "M")
+        kind = "modified";
+    else if (kindChar === "D")
+        kind = "deleted";
+    else if (kindChar === "R")
+        kind = "renamed";
+    const filePath = parts.length >= 3 ? (parts[2] ?? parts[1] ?? "") : (parts[1] ?? "");
+    if (!filePath) {
+        return null;
+    }
+    return { path: filePath.split(path.sep).join("/"), kind, staged };
+}
+function pathMatches(changed, candidate) {
+    const a = changed.replace(/^\.\//, "");
+    const b = candidate.replace(/^\.\//, "").split(path.sep).join("/");
+    return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`) || b.endsWith(`/${a}`);
+}
+function attributeModules(brain, filePath) {
+    const hits = new Set();
+    for (const component of brain.components) {
+        if (pathMatches(filePath, component.path) || pathMatches(filePath, component.name)) {
+            hits.add(component.name || component.id);
+        }
+    }
+    for (const domain of brain.model.domains) {
+        for (const p of domain.paths) {
+            if (pathMatches(filePath, p)) {
+                hits.add(domain.name || domain.id);
+            }
+        }
+    }
+    return [...hits].sort();
+}
+function computeImpact(brain, files) {
+    if (!brain) {
+        return {
+            status: "unknown",
+            reason: "No Project Brain snapshot available; run agentdoctor brain rebuild",
+            edges: [],
+            relatedPaths: [],
+        };
+    }
+    const deps = brain.model.dependencies;
+    if (!deps || deps.length === 0) {
+        return {
+            status: "unknown",
+            reason: "No observed dependency edges in Project Brain",
+            edges: [],
+            relatedPaths: [],
+        };
+    }
+    const changed = new Set(files.map((f) => f.path));
+    const edges = [];
+    const related = new Set();
+    for (const dep of deps) {
+        const fromHit = [...changed].some((p) => pathMatches(p, dep.from));
+        const toHit = [...changed].some((p) => pathMatches(p, dep.to));
+        if (fromHit || toHit) {
+            edges.push({
+                from: dep.from,
+                to: dep.to,
+                type: dep.type,
+                confidence: dep.confidence,
+            });
+            related.add(dep.from);
+            related.add(dep.to);
+        }
+    }
+    if (edges.length === 0) {
+        return {
+            status: "unknown",
+            reason: "No dependency edges touch the changed files (evidence insufficient)",
+            edges: [],
+            relatedPaths: [],
+        };
+    }
+    return {
+        status: "observed",
+        reason: `${edges.length} observed dependency edge(s) touch changed files`,
+        edges: edges.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to)),
+        relatedPaths: [...related].sort(),
+    };
+}
+export async function analyzeChanges(options) {
+    const root = resolveRepoRoot(options.root);
+    const limitations = [];
+    const probe = runGit(root, ["rev-parse", "--is-inside-work-tree"]);
+    if (!probe.ok || probe.stdout.trim() !== "true") {
+        return {
+            root,
+            gitAvailable: false,
+            head: null,
+            since: options.since ?? null,
+            files: [],
+            summary: { added: 0, modified: 0, deleted: 0, renamed: 0, untracked: 0 },
+            ...(options.impact
+                ? {
+                    impact: {
+                        status: "unknown",
+                        reason: "Git repository not available",
+                        edges: [],
+                        relatedPaths: [],
+                    },
+                }
+                : {}),
+            limitations: ["Git repository not available; change intelligence degraded"],
+        };
+    }
+    const head = runGit(root, ["rev-parse", "HEAD"]);
+    const headId = head.ok ? head.stdout.trim() : null;
+    const files = [];
+    if (options.since) {
+        const diff = runGit(root, ["diff", "--name-status", `${options.since}...HEAD`]);
+        if (!diff.ok) {
+            limitations.push(`Unable to diff since ${options.since}: ${diff.stderr.trim() || "git error"}`);
+        }
+        else {
+            for (const line of diff.stdout.split(/\r?\n/)) {
+                const parsed = parseNameStatus(line, false);
+                if (parsed)
+                    files.push(parsed);
+            }
+        }
+    }
+    else {
+        const staged = runGit(root, ["diff", "--cached", "--name-status"]);
+        if (staged.ok) {
+            for (const line of staged.stdout.split(/\r?\n/)) {
+                const parsed = parseNameStatus(line, true);
+                if (parsed)
+                    files.push(parsed);
+            }
+        }
+        const unstaged = runGit(root, ["diff", "--name-status"]);
+        if (unstaged.ok) {
+            for (const line of unstaged.stdout.split(/\r?\n/)) {
+                const parsed = parseNameStatus(line, false);
+                if (parsed)
+                    files.push(parsed);
+            }
+        }
+        const untracked = runGit(root, ["ls-files", "--others", "--exclude-standard"]);
+        if (untracked.ok) {
+            for (const line of untracked.stdout.split(/\r?\n/)) {
+                const p = line.trim();
+                if (p) {
+                    files.push({ path: p.split(path.sep).join("/"), kind: "untracked", staged: false });
+                }
+            }
+        }
+    }
+    let brain = null;
+    if (options.impact || files.length > 0) {
+        try {
+            brain = await loadLatestBrain(root);
+        }
+        catch {
+            brain = null;
+        }
+    }
+    if (brain) {
+        for (const file of files) {
+            const modules = attributeModules(brain, file.path);
+            if (modules.length > 0) {
+                file.modules = modules;
+            }
+        }
+    }
+    else if (options.impact) {
+        limitations.push("Project Brain unavailable for module attribution");
+    }
+    const summary = {
+        added: files.filter((f) => f.kind === "added").length,
+        modified: files.filter((f) => f.kind === "modified").length,
+        deleted: files.filter((f) => f.kind === "deleted").length,
+        renamed: files.filter((f) => f.kind === "renamed").length,
+        untracked: files.filter((f) => f.kind === "untracked").length,
+    };
+    const impact = options.impact ? computeImpact(brain, files) : undefined;
+    if (!options.impact) {
+        limitations.push("Pass --impact to compute observed dependency impact from Project Brain (UNKNOWN when evidence is missing)");
+    }
+    return {
+        root,
+        gitAvailable: true,
+        head: headId,
+        since: options.since ?? null,
+        files: files.sort((a, b) => a.path.localeCompare(b.path)),
+        summary,
+        ...(impact ? { impact } : {}),
+        limitations,
+    };
+}

package/dist/core/context-health/analyze.d.ts

@@ -0,0 +1,15 @@
+export type ContextConflictKind = "duplicate-instruction-surface" | "contradictory-tone" | "overlapping-ignore" | "empty-instruction-file" | "oversized-instruction-file" | "invalid-path-reference" | "ambiguous-marker" | "outdated-year-reference" | "terminology-inconsistency" | "unused-ignore-candidate";
+export interface ContextConflict {
+    kind: ContextConflictKind;
+    severity: "warning" | "info";
+    files: string[];
+    message: string;
+    confidence: "high" | "medium" | "low";
+}
+export interface ContextHealthReport {
+    root: string;
+    conflicts: ContextConflict[];
+    instructionFiles: string[];
+    ignoreFiles: string[];
+}
+export declare function analyzeContextHealth(rootInput: string): Promise<ContextHealthReport>;