@praneeth_54/agentdoctor 1.0.0 → 1.1.0

package/dist/core/understanding/brain/query.js

@@ -0,0 +1,92 @@
+import { averageBrainConfidence } from "./confidence.js";
+import { buildBrainDelta } from "./delta.js";
+function meta(brain, queryType) {
+    return {
+        queryType,
+        brainId: brain.metadata.brainId,
+        schemaVersion: brain.metadata.schemaVersion,
+        projectName: brain.metadata.projectName,
+    };
+}
+function envelope(brain, queryType, result, evidenceIds, confidence, started) {
+    return {
+        result,
+        evidenceIds,
+        confidence,
+        snapshotId: brain.snapshot.id,
+        metadata: meta(brain, queryType),
+        executionTimeMs: Math.max(0, Math.round(performance.now() - started)),
+    };
+}
+export class BrainQueryEngine {
+    brain;
+    constructor(brain) {
+        this.brain = brain;
+    }
+    execute(query) {
+        const started = performance.now();
+        const brain = this.brain;
+        switch (query.type) {
+            case "ProjectSummary":
+                return envelope(brain, query.type, {
+                    projectName: brain.metadata.projectName,
+                    snapshotId: brain.snapshot.id,
+                    domainCount: brain.model.domains.length,
+                    componentCount: brain.components.length,
+                    claimCount: brain.claims.filter((c) => c.status === "ACTIVE").length,
+                    riskCount: brain.risks.risks.length,
+                    unknownCount: brain.unknowns.length,
+                    topDomains: brain.model.summary.topDomains,
+                }, [], averageBrainConfidence(brain.claims.map((c) => c.confidence)), started);
+            case "ListDomains":
+                return envelope(brain, query.type, brain.model.domains, brain.model.domains.flatMap((d) => brain.evidence.filter((e) => d.evidence.includes(e.locator)).map((e) => e.id)), averageBrainConfidence(brain.model.domains.map((d) => d.confidence)), started);
+            case "ListComponents":
+                return envelope(brain, query.type, brain.components, brain.components.flatMap((c) => c.evidenceIds), averageBrainConfidence(brain.components.map((c) => c.confidence)), started);
+            case "ListEntrypoints":
+                return envelope(brain, query.type, brain.model.entrypoints, [], averageBrainConfidence(brain.model.entrypoints.map((e) => e.confidence)), started);
+            case "ListDependencies":
+                return envelope(brain, query.type, brain.model.dependencies, [], averageBrainConfidence(brain.model.dependencies.map((d) => d.confidence)), started);
+            case "ListRelationships":
+                return envelope(brain, query.type, brain.model.relationships, [], averageBrainConfidence(brain.model.relationships.map((r) => r.confidence)), started);
+            case "ListArchitectures":
+                return envelope(brain, query.type, brain.model.architectures, [], averageBrainConfidence(brain.model.architectures.map((a) => a.confidence)), started);
+            case "ListOwnership":
+                return envelope(brain, query.type, brain.ownership, [], averageBrainConfidence(brain.ownership.ownerships.map((o) => o.confidence)), started);
+            case "ListRisks":
+                return envelope(brain, query.type, brain.risks, [], averageBrainConfidence(brain.risks.risks.map((r) => r.confidence)), started);
+            case "ListClaims": {
+                const filtered = query.status
+                    ? brain.claims.filter((c) => c.status === query.status)
+                    : brain.claims.filter((c) => c.status === "ACTIVE" || c.status === "CONTRADICTED");
+                return envelope(brain, query.type, filtered, filtered.flatMap((c) => c.evidenceIds), averageBrainConfidence(filtered.map((c) => c.confidence)), started);
+            }
+            case "ListEvidence":
+                return envelope(brain, query.type, brain.evidence, brain.evidence.map((e) => e.id), 1, started);
+            case "ListContradictions":
+                return envelope(brain, query.type, brain.contradictions, brain.contradictions.flatMap((c) => c.evidenceIds), averageBrainConfidence(brain.contradictions.map((c) => c.confidence)), started);
+            case "ListUnknowns":
+                return envelope(brain, query.type, brain.unknowns, [], 1, started);
+            case "ListChanges": {
+                if (!query.previous) {
+                    return envelope(brain, query.type, { message: "previous brain required for changes" }, [], 0, started);
+                }
+                const delta = buildBrainDelta(query.previous, brain);
+                return envelope(brain, query.type, delta, [], 1, started);
+            }
+            case "ListInvalidations":
+                return envelope(brain, query.type, brain.claims.filter((c) => c.status === "INVALIDATED"), [], 1, started);
+            case "Impact":
+            case "BlastRadius": {
+                const target = query.target.toLowerCase();
+                const deps = brain.model.dependencies.filter((d) => d.from.toLowerCase().includes(target) || d.to.toLowerCase().includes(target));
+                const comps = brain.components.filter((c) => c.path.toLowerCase().includes(target) || c.name.toLowerCase().includes(target));
+                return envelope(brain, query.type, { target: query.target, dependencies: deps, components: comps }, comps.flatMap((c) => c.evidenceIds), averageBrainConfidence(deps.map((d) => d.confidence)), started);
+            }
+            default:
+                throw new Error(`unsupported brain query`);
+        }
+    }
+}
+export function createBrainQueryEngine(brain) {
+    return new BrainQueryEngine(brain);
+}

package/dist/core/understanding/brain/security.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectBrain } from "./types.js";
+/** Deep-safe Brain for disk/export: redact evidence and secret-like claim strings. */
+export declare function redactBrainForStorage(brain: ProjectBrain): ProjectBrain;

package/dist/core/understanding/brain/security.js

@@ -0,0 +1,43 @@
+import { looksLikeSensitiveFilename, redactSecretValue } from "../../../security/redaction.js";
+import { redactEvidenceList } from "./evidence/index.js";
+const SECRETISH = /(password|secret|token|api[_-]?key|private[_-]?key|BEGIN [A-Z ]*PRIVATE KEY|credential)/i;
+function scrubString(value) {
+    if (SECRETISH.test(value)) {
+        return redactSecretValue(value);
+    }
+    return value;
+}
+function scrubClaim(claim) {
+    return {
+        ...claim,
+        subject: looksLikeSensitiveFilename(claim.subject)
+            ? "[REDACTED_PATH]"
+            : scrubString(claim.subject),
+        object: scrubString(claim.object),
+    };
+}
+/** Deep-safe Brain for disk/export: redact evidence and secret-like claim strings. */
+export function redactBrainForStorage(brain) {
+    return {
+        ...brain,
+        claims: brain.claims.map(scrubClaim),
+        evidence: redactEvidenceList(brain.evidence),
+        ownership: {
+            ...brain.ownership,
+            // timingMs is wall-clock and must not affect durable identity.
+            timingMs: 0,
+            ownerships: brain.ownership.ownerships.map((o) => ({
+                ...o,
+                evidence: o.evidence.map((e) => looksLikeSensitiveFilename(e) ? e.replace(/[^/\\]+$/, "[REDACTED_NAME]") : e),
+            })),
+        },
+        risks: {
+            ...brain.risks,
+            timingMs: 0,
+            risks: brain.risks.risks.map((r) => ({
+                ...r,
+                evidence: r.evidence.map((e) => scrubString(e)),
+            })),
+        },
+    };
+}

package/dist/core/understanding/brain/storage/index.d.ts

@@ -0,0 +1,2 @@
+export { LocalBrainStore, BrainStorageError, serializeBrain, checksumPayload } from "./store.js";
+export type { BrainStoreMeta, SnapshotMeta, SnapshotComparison } from "./store.js";

package/dist/core/understanding/brain/storage/index.js

@@ -0,0 +1 @@
+export { LocalBrainStore, BrainStorageError, serializeBrain, checksumPayload } from "./store.js";

package/dist/core/understanding/brain/storage/store.d.ts

@@ -0,0 +1,53 @@
+import type { BrainDelta } from "../delta.js";
+import type { ProjectBrain } from "../types.js";
+import { type BrainStorageFormatVersion, type ProjectBrainSchemaVersion, type SnapshotMetaSchemaVersion } from "../version.js";
+export interface SnapshotMeta {
+    schemaVersion: SnapshotMetaSchemaVersion;
+    id: string;
+    contentHash: string;
+    createdAt: string;
+    projectName: string;
+    brainId: string;
+    checksum: string;
+}
+export interface BrainStoreMeta {
+    storageFormatVersion: BrainStorageFormatVersion;
+    schemaVersion: ProjectBrainSchemaVersion;
+    projectName: string;
+    latestSnapshotId: string | null;
+    snapshots: SnapshotMeta[];
+}
+export interface SnapshotComparison {
+    leftId: string;
+    rightId: string;
+    sameContentHash: boolean;
+    sameChecksum: boolean;
+    left: SnapshotMeta;
+    right: SnapshotMeta;
+}
+export declare class BrainStorageError extends Error {
+    constructor(message: string);
+}
+export declare function serializeBrain(brain: ProjectBrain): string;
+export declare function checksumPayload(payload: string): string;
+export declare class LocalBrainStore {
+    readonly root: string;
+    constructor(rootDir: string);
+    static underRepo(repoRoot: string): LocalBrainStore;
+    private metaPath;
+    private snapshotDir;
+    private brainPath;
+    private deltaPath;
+    ensureRoot(): Promise<void>;
+    readMeta(): Promise<BrainStoreMeta>;
+    private assertMetaCompatible;
+    writeMeta(meta: BrainStoreMeta): Promise<void>;
+    saveSnapshot(brain: ProjectBrain): Promise<SnapshotMeta>;
+    loadSnapshot(snapshotId: string): Promise<ProjectBrain>;
+    listSnapshots(): Promise<SnapshotMeta[]>;
+    latestSnapshotId(): Promise<string | null>;
+    loadLatest(): Promise<ProjectBrain | null>;
+    compareSnapshots(leftId: string, rightId: string): Promise<SnapshotComparison>;
+    saveDelta(delta: BrainDelta): Promise<string>;
+    loadDelta(beforeId: string, afterId: string): Promise<BrainDelta>;
+}

package/dist/core/understanding/brain/storage/store.js

@@ -0,0 +1,305 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { atomicWriteTextFile } from "../../../../utils/fs.js";
+import { parseBrainDelta, serializeBrainDelta } from "../delta.js";
+import { checkBrainCompatibility, migrateBrain } from "../migrate.js";
+import { assertBrainContract } from "../contract.js";
+import { redactBrainForStorage } from "../security.js";
+import { BRAIN_STORAGE_FORMAT_VERSION, PROJECT_BRAIN_SCHEMA_VERSION, SNAPSHOT_META_SCHEMA_VERSION, } from "../version.js";
+export class BrainStorageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BrainStorageError";
+    }
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeysDeep);
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        const sorted = {};
+        for (const key of Object.keys(record).sort((a, b) => a.localeCompare(b))) {
+            sorted[key] = sortKeysDeep(record[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+export function serializeBrain(brain) {
+    const safe = redactBrainForStorage(brain);
+    return `${JSON.stringify(sortKeysDeep(safe), null, 2)}\n`;
+}
+export function checksumPayload(payload) {
+    return createHash("sha256").update(payload).digest("hex");
+}
+function assertInsideRoot(root, candidate) {
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(candidate);
+    const rel = path.relative(resolvedRoot, resolved);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new BrainStorageError("path escapes brain storage root");
+    }
+    return resolved;
+}
+async function assertInsideRootResolved(root, candidate) {
+    const lexical = assertInsideRoot(root, candidate);
+    try {
+        const realRoot = await fs.realpath(root);
+        // Walk up until an existing ancestor can be realpath'd (catches symlink dirs).
+        let probe = lexical;
+        for (;;) {
+            try {
+                const realProbe = await fs.realpath(probe);
+                const rel = path.relative(realRoot, realProbe);
+                if (rel.startsWith("..") || path.isAbsolute(rel)) {
+                    throw new BrainStorageError("path escapes brain storage root via symlink");
+                }
+                // Existing path is inside root; return lexical target for create/read of leaf.
+                return lexical;
+            }
+            catch (error) {
+                if (error instanceof BrainStorageError) {
+                    throw error;
+                }
+                if (error.code !== "ENOENT") {
+                    throw error;
+                }
+                const parent = path.dirname(probe);
+                if (parent === probe) {
+                    return lexical;
+                }
+                probe = parent;
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof BrainStorageError) {
+            throw error;
+        }
+        if (error.code === "ENOENT") {
+            return lexical;
+        }
+        throw error;
+    }
+}
+export class LocalBrainStore {
+    root;
+    constructor(rootDir) {
+        this.root = path.resolve(rootDir);
+    }
+    static underRepo(repoRoot) {
+        return new LocalBrainStore(path.join(repoRoot, ".agentdoctor", "project-brain"));
+    }
+    metaPath() {
+        return path.join(this.root, "store.json");
+    }
+    snapshotDir(snapshotId) {
+        if (!/^snap_[a-f0-9]+$/i.test(snapshotId) && !/^snap_[a-z0-9_]+$/i.test(snapshotId)) {
+            // Allow our snap_ hex ids; reject path tricks.
+            if (snapshotId.includes("..") || snapshotId.includes("/") || snapshotId.includes("\\")) {
+                throw new BrainStorageError("invalid snapshot id");
+            }
+        }
+        if (snapshotId.includes("..") || snapshotId.includes("/") || snapshotId.includes("\\")) {
+            throw new BrainStorageError("invalid snapshot id");
+        }
+        return assertInsideRoot(this.root, path.join(this.root, "snapshots", snapshotId));
+    }
+    brainPath(snapshotId) {
+        return path.join(this.snapshotDir(snapshotId), "brain.json");
+    }
+    deltaPath(beforeId, afterId) {
+        if (beforeId.includes("..") ||
+            afterId.includes("..") ||
+            beforeId.includes("/") ||
+            afterId.includes("/") ||
+            beforeId.includes("\\") ||
+            afterId.includes("\\")) {
+            throw new BrainStorageError("invalid delta snapshot ids");
+        }
+        const name = `delta_${beforeId}__${afterId}.json`;
+        return assertInsideRoot(this.root, path.join(this.root, "deltas", name));
+    }
+    async ensureRoot() {
+        await fs.mkdir(path.join(this.root, "snapshots"), { recursive: true });
+        await fs.mkdir(path.join(this.root, "deltas"), { recursive: true });
+    }
+    async readMeta() {
+        await this.ensureRoot();
+        try {
+            const raw = await fs.readFile(this.metaPath(), "utf8");
+            const parsed = JSON.parse(raw);
+            this.assertMetaCompatible(parsed);
+            return parsed;
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return {
+                    storageFormatVersion: BRAIN_STORAGE_FORMAT_VERSION,
+                    schemaVersion: PROJECT_BRAIN_SCHEMA_VERSION,
+                    projectName: "",
+                    latestSnapshotId: null,
+                    snapshots: [],
+                };
+            }
+            throw error;
+        }
+    }
+    assertMetaCompatible(meta) {
+        const check = checkBrainCompatibility({
+            schemaVersion: meta.schemaVersion,
+            storageFormatVersion: meta.storageFormatVersion,
+        });
+        if (!check.compatible) {
+            throw new BrainStorageError(check.reason ?? "incompatible store meta");
+        }
+    }
+    async writeMeta(meta) {
+        this.assertMetaCompatible(meta);
+        await this.ensureRoot();
+        await atomicWriteTextFile(this.metaPath(), `${JSON.stringify(sortKeysDeep(meta), null, 2)}\n`);
+    }
+    async saveSnapshot(brain) {
+        await this.ensureRoot();
+        const snapshotId = brain.snapshot.id;
+        const dir = await assertInsideRootResolved(this.root, this.snapshotDir(snapshotId));
+        await fs.mkdir(dir, { recursive: true });
+        const target = await assertInsideRootResolved(this.root, path.join(dir, "brain.json"));
+        const payload = serializeBrain(brain);
+        const nextChecksum = checksumPayload(payload);
+        try {
+            const existing = await fs.readFile(target, "utf8");
+            const existingChecksum = checksumPayload(existing);
+            if (existingChecksum !== nextChecksum) {
+                throw new BrainStorageError(`snapshot ${snapshotId} already exists with different content; refusing overwrite`);
+            }
+            const meta = await this.readMeta();
+            const found = meta.snapshots.find((s) => s.id === snapshotId);
+            if (found) {
+                return found;
+            }
+        }
+        catch (error) {
+            if (error instanceof BrainStorageError) {
+                throw error;
+            }
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        await atomicWriteTextFile(target, payload);
+        const snapMeta = {
+            schemaVersion: SNAPSHOT_META_SCHEMA_VERSION,
+            id: snapshotId,
+            contentHash: brain.snapshot.contentHash,
+            createdAt: brain.snapshot.generatedAt,
+            projectName: brain.metadata.projectName,
+            brainId: brain.metadata.brainId,
+            checksum: nextChecksum,
+        };
+        const meta = await this.readMeta();
+        const snapshots = meta.snapshots.filter((s) => s.id !== snapshotId);
+        snapshots.push(snapMeta);
+        snapshots.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        await this.writeMeta({
+            storageFormatVersion: BRAIN_STORAGE_FORMAT_VERSION,
+            schemaVersion: PROJECT_BRAIN_SCHEMA_VERSION,
+            projectName: brain.metadata.projectName,
+            latestSnapshotId: snapshotId,
+            snapshots,
+        });
+        return snapMeta;
+    }
+    async loadSnapshot(snapshotId) {
+        const target = await assertInsideRootResolved(this.root, this.brainPath(snapshotId));
+        let raw;
+        try {
+            raw = await fs.readFile(target, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new BrainStorageError(`snapshot not found: ${snapshotId}`);
+            }
+            throw error;
+        }
+        const meta = await this.readMeta();
+        const snap = meta.snapshots.find((s) => s.id === snapshotId);
+        if (snap) {
+            const actual = checksumPayload(raw);
+            if (actual !== snap.checksum) {
+                throw new BrainStorageError(`checksum mismatch for snapshot ${snapshotId}`);
+            }
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object") {
+            throw new BrainStorageError("corrupt brain JSON");
+        }
+        const version = String(parsed.metadata?.schemaVersion ?? "");
+        const check = checkBrainCompatibility({ schemaVersion: version });
+        let brain;
+        if (!check.compatible) {
+            brain = migrateBrain(parsed, version);
+        }
+        else {
+            try {
+                brain = assertBrainContract(parsed);
+            }
+            catch (error) {
+                throw new BrainStorageError(error instanceof Error ? error.message : "invalid brain contract");
+            }
+        }
+        return brain;
+    }
+    async listSnapshots() {
+        const meta = await this.readMeta();
+        return [...meta.snapshots];
+    }
+    async latestSnapshotId() {
+        const meta = await this.readMeta();
+        return meta.latestSnapshotId;
+    }
+    async loadLatest() {
+        const id = await this.latestSnapshotId();
+        if (!id) {
+            return null;
+        }
+        return this.loadSnapshot(id);
+    }
+    async compareSnapshots(leftId, rightId) {
+        const meta = await this.readMeta();
+        const left = meta.snapshots.find((s) => s.id === leftId);
+        const right = meta.snapshots.find((s) => s.id === rightId);
+        if (!left || !right) {
+            throw new BrainStorageError("cannot compare: snapshot missing from registry");
+        }
+        return {
+            leftId,
+            rightId,
+            sameContentHash: left.contentHash === right.contentHash,
+            sameChecksum: left.checksum === right.checksum,
+            left,
+            right,
+        };
+    }
+    async saveDelta(delta) {
+        await this.ensureRoot();
+        const target = this.deltaPath(delta.beforeSnapshotId, delta.afterSnapshotId);
+        await atomicWriteTextFile(target, serializeBrainDelta(delta));
+        return target;
+    }
+    async loadDelta(beforeId, afterId) {
+        const target = this.deltaPath(beforeId, afterId);
+        try {
+            const raw = await fs.readFile(target, "utf8");
+            return parseBrainDelta(raw);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new BrainStorageError(`delta not found: ${beforeId} → ${afterId}`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/core/understanding/brain/trace.d.ts

@@ -0,0 +1,24 @@
+import type { ProjectBrain } from "./types.js";
+export interface TraceNode {
+    id: string;
+    label: string;
+    kind: "component" | "dependency-endpoint" | "entrypoint" | "domain";
+    path?: string;
+    confidence: number;
+}
+export interface TraceEdge {
+    from: string;
+    to: string;
+    type: string;
+    evidence: readonly string[];
+    confidence: number;
+}
+export interface TraceResult {
+    root: string;
+    nodes: readonly TraceNode[];
+    edges: readonly TraceEdge[];
+    cycles: readonly string[];
+    confidence: number;
+}
+export type TraceMode = "dependencies" | "dependents" | "entrypoint-downstream" | "blast-radius" | "domain-modules";
+export declare function traceBrain(brain: ProjectBrain, target: string, mode?: TraceMode): TraceResult;