@praneeth_54/agentdoctor 2.0.0 → 2.0.1

package/dist/architecture/contract.js

@@ -0,0 +1,373 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveRepoRoot } from "../utils/path.js";
+import { atomicWriteTextFile } from "../utils/fs.js";
+const CONTRACT_JSON = ".agentdoctor/architecture.json";
+const CONTRACT_YML = ".agentdoctor/architecture.yml";
+export const DEFAULT_ARCHITECTURE_CONTRACT = {
+    version: "1",
+    layers: [
+        { id: "cli", paths: ["src/cli/"] },
+        { id: "platform", paths: ["src/platform/"] },
+        { id: "core", paths: ["src/core/"] },
+        { id: "tests", paths: ["tests/"] },
+    ],
+    forbidden: [
+        {
+            id: "core-must-not-import-cli",
+            fromLayer: "core",
+            toLayer: "cli",
+            description: "Core must not depend on CLI surfaces",
+        },
+        {
+            id: "src-must-not-import-tests",
+            fromLayer: "core",
+            toLayer: "tests",
+            description: "Production core must not import test files",
+        },
+        {
+            id: "platform-must-not-import-tests",
+            fromLayer: "platform",
+            toLayer: "tests",
+            description: "Platform must not import test files",
+        },
+    ],
+    allowed: [
+        { fromLayer: "cli", toLayer: "platform" },
+        { fromLayer: "cli", toLayer: "core" },
+        { fromLayer: "platform", toLayer: "core" },
+        { fromLayer: "tests", toLayer: "core" },
+        { fromLayer: "tests", toLayer: "platform" },
+        { fromLayer: "tests", toLayer: "cli" },
+    ],
+};
+function normalizeRel(p) {
+    return p.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+export function layerForPath(filePath, layers) {
+    const rel = normalizeRel(filePath);
+    let best = null;
+    for (const layer of layers) {
+        for (const prefix of layer.paths) {
+            const p = normalizeRel(prefix);
+            if (rel === p.replace(/\/$/, "") ||
+                rel.startsWith(p) ||
+                rel.startsWith(p.replace(/\/$/, "") + "/")) {
+                if (!best || p.length > best.len)
+                    best = { id: layer.id, len: p.length };
+            }
+        }
+    }
+    return best?.id ?? null;
+}
+/**
+ * Minimal YAML subset parser for architecture contracts.
+ * Also accepts JSON content inside .yml files.
+ */
+export function parseArchitectureYamlSubset(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{")) {
+        return parseArchitectureJson(trimmed);
+    }
+    // Line-oriented subset: version, layers/forbidden/allowed with indented keys
+    const lines = text.split(/\r?\n/);
+    let version = "1";
+    const layers = [];
+    const forbidden = [];
+    const allowed = [];
+    let section = "none";
+    let current = null;
+    const pushCurrent = () => {
+        if (!current)
+            return;
+        if (section === "layers" && typeof current.id === "string") {
+            const paths = Array.isArray(current.paths)
+                ? current.paths.filter((p) => typeof p === "string")
+                : [];
+            layers.push({ id: current.id, paths });
+        }
+        else if (section === "forbidden" && typeof current.id === "string") {
+            forbidden.push({
+                id: current.id,
+                fromLayer: String(current.fromLayer ?? ""),
+                toLayer: String(current.toLayer ?? ""),
+                description: String(current.description ?? ""),
+            });
+        }
+        else if (section === "allowed") {
+            allowed.push({
+                fromLayer: String(current.fromLayer ?? ""),
+                toLayer: String(current.toLayer ?? ""),
+            });
+        }
+        current = null;
+    };
+    for (const raw of lines) {
+        if (!raw.trim() || raw.trimStart().startsWith("#"))
+            continue;
+        const indent = raw.match(/^ */)?.[0].length ?? 0;
+        const line = raw.trim();
+        if (indent === 0 && line.startsWith("version:")) {
+            pushCurrent();
+            version = unquote(line.slice("version:".length).trim()) || "1";
+            section = "none";
+            continue;
+        }
+        if (indent === 0 && line === "layers:") {
+            pushCurrent();
+            section = "layers";
+            continue;
+        }
+        if (indent === 0 && line === "forbidden:") {
+            pushCurrent();
+            section = "forbidden";
+            continue;
+        }
+        if (indent === 0 && line === "allowed:") {
+            pushCurrent();
+            section = "allowed";
+            continue;
+        }
+        if (section !== "none" && line.startsWith("- ")) {
+            pushCurrent();
+            current = {};
+            const rest = line.slice(2).trim();
+            if (rest.includes(":")) {
+                const [k, ...restParts] = rest.split(":");
+                current[k.trim()] = parseYamlValue(restParts.join(":").trim());
+            }
+            continue;
+        }
+        if (current && indent >= 2 && line.includes(":")) {
+            const [k, ...restParts] = line.split(":");
+            const key = k.trim();
+            const val = restParts.join(":").trim();
+            if (val === "" || val === "|" || val === ">") {
+                // multi-line not supported; ignore
+                continue;
+            }
+            if (key === "paths" && val.startsWith("[")) {
+                try {
+                    current.paths = JSON.parse(val.replace(/'/g, '"'));
+                }
+                catch {
+                    current.paths = val
+                        .replace(/^\[/, "")
+                        .replace(/\]$/, "")
+                        .split(",")
+                        .map((s) => unquote(s.trim()))
+                        .filter(Boolean);
+                }
+            }
+            else {
+                current[key] = parseYamlValue(val);
+            }
+        }
+    }
+    pushCurrent();
+    if (version !== "1") {
+        throw new Error(`Unsupported architecture contract version: ${version}`);
+    }
+    return { version: "1", layers, forbidden, allowed };
+}
+function parseYamlValue(val) {
+    if (val.startsWith("[") && val.endsWith("]")) {
+        try {
+            return JSON.parse(val.replace(/'/g, '"'));
+        }
+        catch {
+            return val
+                .slice(1, -1)
+                .split(",")
+                .map((s) => unquote(s.trim()))
+                .filter(Boolean);
+        }
+    }
+    return unquote(val);
+}
+function unquote(s) {
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        return s.slice(1, -1);
+    }
+    return s;
+}
+export function parseArchitectureJson(text) {
+    const parsed = JSON.parse(text);
+    if (parsed.version !== "1") {
+        throw new Error(`Unsupported architecture contract version: ${String(parsed.version)}`);
+    }
+    if (!Array.isArray(parsed.layers) || !Array.isArray(parsed.forbidden)) {
+        throw new Error("Architecture contract requires layers and forbidden arrays");
+    }
+    return {
+        version: "1",
+        layers: parsed.layers,
+        forbidden: parsed.forbidden,
+        allowed: Array.isArray(parsed.allowed) ? parsed.allowed : [],
+    };
+}
+export async function loadArchitectureContract(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const jsonPath = path.join(root, CONTRACT_JSON);
+    const ymlPath = path.join(root, CONTRACT_YML);
+    try {
+        const text = await fs.readFile(jsonPath, "utf8");
+        return { contract: parseArchitectureJson(text), path: jsonPath };
+    }
+    catch {
+        // try yml
+    }
+    try {
+        const text = await fs.readFile(ymlPath, "utf8");
+        return { contract: parseArchitectureYamlSubset(text), path: ymlPath };
+    }
+    catch {
+        return null;
+    }
+}
+export async function initArchitecture(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const out = path.join(root, CONTRACT_JSON);
+    await fs.mkdir(path.dirname(out), { recursive: true });
+    try {
+        await fs.access(out);
+        return out; // already exists — do not overwrite
+    }
+    catch {
+        // create
+    }
+    await atomicWriteTextFile(out, `${JSON.stringify(DEFAULT_ARCHITECTURE_CONTRACT, null, 2)}\n`);
+    return out;
+}
+function resolveNodePath(graph, nodeId) {
+    const node = graph.nodes.find((n) => n.id === nodeId);
+    if (node?.path)
+        return normalizeRel(node.path);
+    if (node?.label)
+        return normalizeRel(node.label);
+    return normalizeRel(nodeId.replace(/^file:/, ""));
+}
+/**
+ * Check import edges against the architecture contract.
+ * Forbidden rules always apply. When `allowed` is non-empty, cross-layer
+ * imports not listed in allowed (and not same-layer) are reported as not-allowed.
+ */
+export function checkArchitecture(rootInput, graph, contract, contractPath) {
+    const root = resolveRepoRoot(rootInput);
+    const limitations = [
+        "Architecture check uses static import edges from the repository graph",
+        "Layer assignment is path-prefix based — not runtime topology",
+    ];
+    if (!contract) {
+        return {
+            root,
+            contractPath: contractPath ?? null,
+            contract: null,
+            violations: [],
+            importEdgesChecked: 0,
+            limitations: [
+                ...limitations,
+                "No architecture contract found — run: agentdoctor architecture init",
+            ],
+        };
+    }
+    const violations = [];
+    const importEdges = graph.edges.filter((e) => e.kind === "imports" || e.kind === "depends_on");
+    const allowSet = new Set(contract.allowed.map((a) => `${a.fromLayer}->${a.toLayer}`));
+    const enforceAllowList = contract.allowed.length > 0;
+    for (const edge of importEdges) {
+        const fromPath = resolveNodePath(graph, edge.from);
+        const toPath = resolveNodePath(graph, edge.to);
+        const fromLayer = layerForPath(fromPath, contract.layers);
+        const toLayer = layerForPath(toPath, contract.layers);
+        if (!fromLayer || !toLayer)
+            continue;
+        if (fromLayer === toLayer)
+            continue;
+        for (const rule of contract.forbidden) {
+            if (rule.fromLayer === fromLayer && rule.toLayer === toLayer) {
+                violations.push({
+                    ruleId: rule.id,
+                    kind: "forbidden",
+                    description: rule.description,
+                    fromPath,
+                    toPath,
+                    fromLayer,
+                    toLayer,
+                    evidence: {
+                        edgeId: edge.id,
+                        edgeKind: edge.kind,
+                        evidenceKind: edge.evidence,
+                    },
+                });
+            }
+        }
+        if (enforceAllowList && !allowSet.has(`${fromLayer}->${toLayer}`)) {
+            const alreadyForbidden = violations.some((v) => v.fromPath === fromPath &&
+                v.toPath === toPath &&
+                v.fromLayer === fromLayer &&
+                v.toLayer === toLayer &&
+                v.kind === "forbidden");
+            if (!alreadyForbidden) {
+                violations.push({
+                    ruleId: `not-allowed:${fromLayer}->${toLayer}`,
+                    kind: "not-allowed",
+                    description: `Cross-layer import ${fromLayer} → ${toLayer} is not in the allowed list`,
+                    fromPath,
+                    toPath,
+                    fromLayer,
+                    toLayer,
+                    evidence: {
+                        edgeId: edge.id,
+                        edgeKind: edge.kind,
+                        evidenceKind: edge.evidence,
+                    },
+                });
+            }
+        }
+    }
+    violations.sort((a, b) => `${a.ruleId}:${a.fromPath}:${a.toPath}`.localeCompare(`${b.ruleId}:${b.fromPath}:${b.toPath}`));
+    return {
+        root,
+        contractPath: contractPath ?? null,
+        contract,
+        violations,
+        importEdgesChecked: importEdges.length,
+        limitations,
+    };
+}
+export async function checkArchitectureAtRoot(rootInput, graph) {
+    const loaded = await loadArchitectureContract(rootInput);
+    return checkArchitecture(rootInput, graph, loaded?.contract ?? null, loaded?.path ?? null);
+}
+export function explainArchitecture(contract, check) {
+    const lines = ["AgentDoctor architecture contract"];
+    if (!contract) {
+        lines.push("  No contract loaded. Run: agentdoctor architecture init");
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push(`  version: ${contract.version}`);
+    lines.push(`  layers: ${contract.layers.map((l) => l.id).join(", ") || "(none)"}`);
+    for (const layer of contract.layers) {
+        lines.push(`    - ${layer.id}: ${layer.paths.join(", ")}`);
+    }
+    lines.push(`  forbidden rules: ${contract.forbidden.length}`);
+    for (const rule of contract.forbidden) {
+        lines.push(`    - [${rule.id}] ${rule.fromLayer} → ${rule.toLayer}: ${rule.description}`);
+    }
+    lines.push(`  allowed pairs: ${contract.allowed.length}`);
+    for (const a of contract.allowed) {
+        lines.push(`    - ${a.fromLayer} → ${a.toLayer}`);
+    }
+    if (check) {
+        lines.push(`  import edges checked: ${check.importEdgesChecked}`);
+        lines.push(`  violations: ${check.violations.length}`);
+        for (const v of check.violations.slice(0, 20)) {
+            lines.push(`    - ${v.kind} ${v.ruleId}: ${v.fromPath} → ${v.toPath} (${v.fromLayer}→${v.toLayer})`);
+        }
+        for (const lim of check.limitations.slice(0, 5)) {
+            lines.push(`  limitation: ${lim}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/assurance/change.d.ts

@@ -0,0 +1,211 @@
+export declare const EVIDENCE_SCHEMA_VERSION = "1.0.0";
+export type VerificationStatus = "not-run" | "partial" | "evidence-produced" | "failed" | "verified";
+export interface ChangeAssessment {
+    changeId: string;
+    schemaVersion: string;
+    agentDoctorVersion: string;
+    repository: {
+        root: string;
+        remote: string | null;
+        branch: string | null;
+    };
+    baseRevision: string | null;
+    targetRevision: string | null;
+    changedFiles: Array<{
+        path: string;
+        kind: string;
+    }>;
+    changedSymbols: string[];
+    /** Graph nodes / paths that call or import into changed symbols/files. */
+    callers: string[];
+    /** Graph targets called or imported from changed symbols/files. */
+    callees: string[];
+    /** Files that import changed files (reverse import deps). */
+    reverseDependencies: string[];
+    /** Workspace packages touched by changed files (from package.json workspaces when present). */
+    packageImpact: string[];
+    affectedComponents: string[];
+    dependencyImpact: {
+        status: "observed" | "unknown" | "heuristic";
+        relatedPaths: string[];
+        edgeCount: number;
+        limitations: string[];
+    };
+    architectureImpact: {
+        status: "inferred" | "unknown";
+        viewLevels: string[];
+        limitations: string[];
+    };
+    knowledgeReferences: Array<{
+        id: string;
+        title: string;
+        status: string;
+        authoritative: boolean;
+    }>;
+    securityFindings: {
+        secretFindingCount: number;
+        mode: "heuristic";
+        limitations: string[];
+    };
+    policyResults: Array<{
+        policyId: string;
+        decision: string;
+        reason: string;
+        subject: string;
+        action: string;
+        evidence: string;
+    }>;
+    testImpact: {
+        mode: "heuristic" | "coverage-backed";
+        recommendedTests: string[];
+        confidence: "low" | "medium" | "high";
+        limitations: string[];
+    };
+    evidence: {
+        directory: string | null;
+        files: string[];
+    };
+    verificationStatus: VerificationStatus;
+    limitations: string[];
+    createdAt: string;
+}
+export interface EvidenceManifest {
+    schemaVersion: string;
+    agentDoctorVersion: string;
+    changeId: string;
+    repositoryRoot: string;
+    baseRevision: string | null;
+    targetRevision: string | null;
+    createdAt: string;
+    files: Array<{
+        name: string;
+        sha256: string;
+    }>;
+    verificationStatus: VerificationStatus;
+}
+/**
+ * Derive callers / callees / reverse import deps from the intelligence graph
+ * for the given changed files and symbol ids. Honest: empty when graph lacks edges.
+ */
+export declare function deriveGraphChangeImpact(graph: {
+    nodes: Array<{
+        id: string;
+        kind: string;
+        label: string;
+        path?: string;
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+        kind: string;
+    }>;
+}, changedFiles: Array<{
+    path: string;
+    kind: string;
+}>, changedSymbols: string[]): {
+    callers: string[];
+    callees: string[];
+    reverseDependencies: string[];
+};
+/**
+ * Map changed files onto package.json workspaces (string globs or packages/*).
+ * Returns [] when workspaces are absent — does not invent packages.
+ */
+export declare function derivePackageImpact(root: string, changedFiles: Array<{
+    path: string;
+}>): Promise<string[]>;
+/**
+ * Assemble a ChangeAssessment from existing AgentDoctor signals.
+ * Never sets verificationStatus to "verified" — that requires evidence verify.
+ */
+export declare function analyzeChange(options: {
+    root: string;
+    since?: string;
+    changeId?: string;
+    coveragePath?: string;
+}): Promise<ChangeAssessment>;
+/**
+ * Persist evidence bundle. Status becomes evidence-produced (not "verified").
+ * "verified" is reserved for evidence verify when artifact hashes match.
+ */
+export declare function verifyChange(options: {
+    root: string;
+    since?: string;
+    changeId?: string;
+    coveragePath?: string;
+}): Promise<{
+    assessment: ChangeAssessment;
+    manifest: EvidenceManifest;
+}>;
+/**
+ * Human-readable explanation of a ChangeAssessment (does not claim correctness).
+ */
+export declare function explainChange(assessment: ChangeAssessment): string;
+/**
+ * Summarize base/target file diffs from git for a change.
+ */
+export declare function diffChange(options: {
+    root: string;
+    since?: string;
+    changeId?: string;
+}): Promise<{
+    changeId: string | null;
+    baseRevision: string | null;
+    targetRevision: string | null;
+    files: Array<{
+        path: string;
+        kind: string;
+    }>;
+    summary: {
+        added: number;
+        modified: number;
+        deleted: number;
+        renamed: number;
+        untracked: number;
+    };
+    stat: string | null;
+    limitations: string[];
+}>;
+/**
+ * Verification / evidence status for latest evidence or a specific change id.
+ */
+export declare function changeStatus(options: {
+    root: string;
+    changeId?: string;
+}): Promise<{
+    changeId: string | null;
+    evidenceDirectory: string | null;
+    verificationStatus: VerificationStatus;
+    evidencePresent: boolean;
+    proofPresent: boolean;
+    proofId: string | null;
+    integrityNote: string;
+    files: string[];
+}>;
+export declare function inspectEvidence(options: {
+    root: string;
+    changeId: string;
+}): Promise<{
+    ok: boolean;
+    directory: string;
+    manifest: EvidenceManifest | null;
+    presentFiles: string[];
+    error?: string;
+}>;
+/**
+ * Hash-check evidence bundle. Returns "verified" only when all listed files match.
+ */
+export declare function verifyEvidence(options: {
+    root: string;
+    changeId: string;
+}): Promise<{
+    ok: boolean;
+    verificationStatus: VerificationStatus;
+    checked: Array<{
+        name: string;
+        match: boolean;
+        expected?: string;
+        actual?: string;
+    }>;
+    error?: string;
+}>;