@praneeth_54/agentdoctor 0.3.0-beta → 1.1.0

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

@@ -0,0 +1,207 @@
+function normalize(value) {
+    return value.replace(/\\/g, "/").toLowerCase();
+}
+/** Prefer exact path match; fall back to path-segment containment (not bare substring). */
+function pathMatches(value, target) {
+    const v = normalize(value);
+    const t = normalize(target);
+    if (t.length === 0) {
+        return false;
+    }
+    if (v === t) {
+        return true;
+    }
+    // Segment-aware containment: "/foo/bar" matches target "foo/bar" or "bar" as a segment.
+    if (t.length < 2) {
+        return false;
+    }
+    return (v.endsWith(`/${t}`) ||
+        v.includes(`/${t}/`) ||
+        v.startsWith(`${t}/`) ||
+        t.endsWith(`/${v}`) ||
+        t.includes(`/${v}/`));
+}
+const MAX_DEPTH = 25;
+const MAX_EDGES = 5_000;
+export function traceBrain(brain, target, mode = "blast-radius") {
+    const nodes = new Map();
+    const edgeKeys = new Set();
+    const edges = [];
+    const visiting = new Set();
+    const expanded = new Set();
+    const cycles = [];
+    const addNode = (node) => {
+        if (!nodes.has(node.id)) {
+            nodes.set(node.id, node);
+        }
+    };
+    const addEdge = (edge) => {
+        if (edges.length >= MAX_EDGES) {
+            return;
+        }
+        const key = `${edge.from}\0${edge.to}\0${edge.type}`;
+        if (edgeKeys.has(key)) {
+            return;
+        }
+        edgeKeys.add(key);
+        edges.push(edge);
+    };
+    const rootId = `root:${target}`;
+    addNode({
+        id: rootId,
+        label: target,
+        kind: "component",
+        path: target,
+        confidence: 1,
+    });
+    if (mode === "domain-modules") {
+        for (const domain of brain.model.domains) {
+            if (!pathMatches(domain.name, target) && !domain.paths.some((p) => pathMatches(p, target))) {
+                continue;
+            }
+            const domainNode = `domain:${domain.name}`;
+            addNode({
+                id: domainNode,
+                label: domain.name,
+                kind: "domain",
+                confidence: domain.confidence,
+            });
+            addEdge({
+                from: rootId,
+                to: domainNode,
+                type: "domain",
+                evidence: [...domain.evidence],
+                confidence: domain.confidence,
+            });
+            for (const comp of brain.components) {
+                if (!comp.domainIds.includes(domain.id) &&
+                    !domain.paths.some((p) => pathMatches(comp.path, p))) {
+                    continue;
+                }
+                addNode({
+                    id: comp.id,
+                    label: comp.name,
+                    kind: "component",
+                    path: comp.path,
+                    confidence: comp.confidence,
+                });
+                addEdge({
+                    from: domainNode,
+                    to: comp.id,
+                    type: "contains",
+                    evidence: [...comp.evidenceIds],
+                    confidence: comp.confidence,
+                });
+            }
+        }
+    }
+    else {
+        const walk = (current, depth) => {
+            if (depth > MAX_DEPTH || edges.length >= MAX_EDGES) {
+                return;
+            }
+            if (visiting.has(current)) {
+                cycles.push(current);
+                return;
+            }
+            if (expanded.has(current)) {
+                return;
+            }
+            visiting.add(current);
+            for (const dep of brain.model.dependencies) {
+                const fromMatch = pathMatches(dep.from, current);
+                const toMatch = pathMatches(dep.to, current);
+                if (mode === "dependencies" && !fromMatch) {
+                    continue;
+                }
+                if (mode === "dependents" && !toMatch) {
+                    continue;
+                }
+                if (mode === "entrypoint-downstream" && depth === 0) {
+                    if (!pathMatches(dep.from, target) && !pathMatches(dep.to, target)) {
+                        continue;
+                    }
+                }
+                else if (mode === "blast-radius" || mode === "entrypoint-downstream") {
+                    if (!fromMatch && !toMatch) {
+                        continue;
+                    }
+                }
+                const fromId = `node:${dep.from}`;
+                const toId = `node:${dep.to}`;
+                addNode({
+                    id: fromId,
+                    label: dep.from,
+                    kind: "dependency-endpoint",
+                    path: dep.from,
+                    confidence: dep.confidence,
+                });
+                addNode({
+                    id: toId,
+                    label: dep.to,
+                    kind: "dependency-endpoint",
+                    path: dep.to,
+                    confidence: dep.confidence,
+                });
+                addEdge({
+                    from: fromId,
+                    to: toId,
+                    type: dep.type,
+                    evidence: [...dep.evidence],
+                    confidence: dep.confidence,
+                });
+                if (mode === "dependencies" ||
+                    mode === "blast-radius" ||
+                    mode === "entrypoint-downstream") {
+                    if (fromMatch) {
+                        walk(dep.to, depth + 1);
+                    }
+                }
+                if (mode === "dependents" || mode === "blast-radius") {
+                    if (toMatch) {
+                        walk(dep.from, depth + 1);
+                    }
+                }
+            }
+            if (mode === "entrypoint-downstream" || mode === "blast-radius") {
+                for (const entry of brain.model.entrypoints) {
+                    if (!pathMatches(entry.file, current) && !pathMatches(entry.file, target)) {
+                        continue;
+                    }
+                    const entryId = `entry:${entry.file}`;
+                    addNode({
+                        id: entryId,
+                        label: entry.file,
+                        kind: "entrypoint",
+                        path: entry.file,
+                        confidence: entry.confidence,
+                    });
+                    addEdge({
+                        from: rootId,
+                        to: entryId,
+                        type: "entrypoint",
+                        evidence: [...entry.evidence],
+                        confidence: entry.confidence,
+                    });
+                }
+            }
+            visiting.delete(current);
+            expanded.add(current);
+        };
+        walk(target, 0);
+    }
+    const nodeList = [...nodes.values()].sort((a, b) => a.id.localeCompare(b.id));
+    const edgeList = edges
+        .map((e) => ({ ...e, evidence: [...e.evidence].sort() }))
+        .sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.type.localeCompare(b.type));
+    const confidence = edgeList.length === 0
+        ? 0
+        : Math.round((edgeList.reduce((s, e) => s + e.confidence, 0) / edgeList.length) * 100) / 100;
+    return {
+        root: target,
+        nodes: nodeList,
+        edges: edgeList,
+        cycles: [...new Set(cycles)].sort(),
+        confidence,
+    };
+}

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

@@ -0,0 +1,32 @@
+import type { ProjectModel } from "../model/types.js";
+import type { OwnershipDiscoveryResult } from "../ownership/types.js";
+import type { RiskDiscoveryResult } from "../risks/types.js";
+import type { SnapshotIdentity } from "../snapshot/index.js";
+import type { BrainClaim } from "./claims/types.js";
+import type { BrainComponent } from "./components/types.js";
+import type { ConfidenceMetadata } from "./confidence.js";
+import type { BrainContradiction } from "./contradictions/types.js";
+import type { BrainEvidence } from "./evidence/types.js";
+import type { ProjectBrainSchemaVersion } from "./version.js";
+export interface ProjectBrainMetadata {
+    schemaVersion: ProjectBrainSchemaVersion;
+    brainId: string;
+    projectName: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ProjectBrain {
+    metadata: ProjectBrainMetadata;
+    snapshot: SnapshotIdentity;
+    model: ProjectModel;
+    ownership: OwnershipDiscoveryResult;
+    risks: RiskDiscoveryResult;
+    components: readonly BrainComponent[];
+    claims: readonly BrainClaim[];
+    evidence: readonly BrainEvidence[];
+    contradictions: readonly BrainContradiction[];
+    unknowns: readonly string[];
+    limitations: readonly string[];
+    confidenceContract: ConfidenceMetadata;
+}
+export declare const PROJECT_BRAIN_LIMITATIONS: readonly ["Project Brain is deterministic and local-only", "Domains are path-inferred unless stronger evidence exists", "Ownership requires explicit CODEOWNERS / MAINTAINERS / package.json evidence", "Risks describe change-danger, not vulnerability scanning", "Business rules and design intent remain unknown", "Evidence never includes secret file contents"];

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

@@ -0,0 +1,8 @@
+export const PROJECT_BRAIN_LIMITATIONS = [
+    "Project Brain is deterministic and local-only",
+    "Domains are path-inferred unless stronger evidence exists",
+    "Ownership requires explicit CODEOWNERS / MAINTAINERS / package.json evidence",
+    "Risks describe change-danger, not vulnerability scanning",
+    "Business rules and design intent remain unknown",
+    "Evidence never includes secret file contents",
+];

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

@@ -0,0 +1,13 @@
+/** Project Brain schema / storage format versions (independent of AgentDoctor package). */
+export declare const PROJECT_BRAIN_SCHEMA_VERSION: "1.0.0";
+export declare const CLAIM_SCHEMA_VERSION: "1.0.0";
+export declare const EVIDENCE_SCHEMA_VERSION: "1.0.0";
+export declare const DELTA_SCHEMA_VERSION: "1.0.0";
+export declare const SNAPSHOT_META_SCHEMA_VERSION: "1.0.0";
+export declare const BRAIN_STORAGE_FORMAT_VERSION: "1.0.0";
+export type ProjectBrainSchemaVersion = typeof PROJECT_BRAIN_SCHEMA_VERSION;
+export type ClaimSchemaVersion = typeof CLAIM_SCHEMA_VERSION;
+export type EvidenceSchemaVersion = typeof EVIDENCE_SCHEMA_VERSION;
+export type DeltaSchemaVersion = typeof DELTA_SCHEMA_VERSION;
+export type SnapshotMetaSchemaVersion = typeof SNAPSHOT_META_SCHEMA_VERSION;
+export type BrainStorageFormatVersion = typeof BRAIN_STORAGE_FORMAT_VERSION;

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

@@ -0,0 +1,7 @@
+/** Project Brain schema / storage format versions (independent of AgentDoctor package). */
+export const PROJECT_BRAIN_SCHEMA_VERSION = "1.0.0";
+export const CLAIM_SCHEMA_VERSION = "1.0.0";
+export const EVIDENCE_SCHEMA_VERSION = "1.0.0";
+export const DELTA_SCHEMA_VERSION = "1.0.0";
+export const SNAPSHOT_META_SCHEMA_VERSION = "1.0.0";
+export const BRAIN_STORAGE_FORMAT_VERSION = "1.0.0";

package/dist/core/understanding/delta/compare.d.ts

@@ -0,0 +1,26 @@
+import type { ProjectModel } from "../model/types.js";
+import { type SnapshotIdentity } from "../snapshot/index.js";
+export interface SetDelta<T> {
+    added: readonly T[];
+    removed: readonly T[];
+    unchanged: readonly T[];
+}
+export interface UnderstandingDelta {
+    before: SnapshotIdentity;
+    after: SnapshotIdentity;
+    structuralEqual: boolean;
+    domains: SetDelta<string>;
+    entrypoints: SetDelta<string>;
+    dependencies: SetDelta<string>;
+    relationships: SetDelta<string>;
+    architectures: SetDelta<string>;
+    /** Model object ids present before but absent after. */
+    invalidatedIds: readonly string[];
+    /** Human-readable summary lines. */
+    summary: readonly string[];
+}
+/**
+ * Compare two ProjectModel snapshots into an understanding delta.
+ * Does not re-scan the repository.
+ */
+export declare function compareProjectModels(before: ProjectModel, after: ProjectModel): UnderstandingDelta;

package/dist/core/understanding/delta/compare.js

@@ -0,0 +1,74 @@
+import { createSnapshotIdentity } from "../snapshot/index.js";
+function setDelta(before, after) {
+    const beforeSet = new Set(before);
+    const afterSet = new Set(after);
+    const added = after.filter((item) => !beforeSet.has(item)).sort((a, b) => a.localeCompare(b));
+    const removed = before.filter((item) => !afterSet.has(item)).sort((a, b) => a.localeCompare(b));
+    const unchanged = before.filter((item) => afterSet.has(item)).sort((a, b) => a.localeCompare(b));
+    return { added, removed, unchanged };
+}
+function collectIds(model) {
+    return [
+        model.metadata.id,
+        model.metadata.project.id,
+        ...model.domains.map((d) => d.id),
+        ...model.entrypoints.map((e) => e.id),
+        ...model.dependencies.map((d) => d.id),
+        ...model.relationships.map((r) => r.id),
+        ...model.architectures.map((a) => a.id),
+    ];
+}
+/**
+ * Compare two ProjectModel snapshots into an understanding delta.
+ * Does not re-scan the repository.
+ */
+export function compareProjectModels(before, after) {
+    const beforeSnap = createSnapshotIdentity(before);
+    const afterSnap = createSnapshotIdentity(after);
+    const domains = setDelta(before.domains.map((d) => d.name), after.domains.map((d) => d.name));
+    const entrypoints = setDelta(before.entrypoints.map((e) => `${e.framework}:${e.file}`), after.entrypoints.map((e) => `${e.framework}:${e.file}`));
+    const dependencies = setDelta(before.dependencies.map((d) => `${d.from}->${d.to}:${d.type}`), after.dependencies.map((d) => `${d.from}->${d.to}:${d.type}`));
+    const relationships = setDelta(before.relationships.map((r) => `${r.source}->${r.target}:${r.relationship}`), after.relationships.map((r) => `${r.source}->${r.target}:${r.relationship}`));
+    const architectures = setDelta(before.architectures.map((a) => a.pattern), after.architectures.map((a) => a.pattern));
+    const afterIds = new Set(collectIds(after));
+    const invalidatedIds = collectIds(before)
+        .filter((id) => !afterIds.has(id))
+        .sort((a, b) => a.localeCompare(b));
+    const structuralEqual = beforeSnap.contentHash === afterSnap.contentHash;
+    const summary = [];
+    if (structuralEqual) {
+        summary.push("No structural understanding changes");
+    }
+    else {
+        if (domains.added.length || domains.removed.length) {
+            summary.push(`Domains +${domains.added.length}/-${domains.removed.length}`);
+        }
+        if (entrypoints.added.length || entrypoints.removed.length) {
+            summary.push(`Entrypoints +${entrypoints.added.length}/-${entrypoints.removed.length}`);
+        }
+        if (dependencies.added.length || dependencies.removed.length) {
+            summary.push(`Dependencies +${dependencies.added.length}/-${dependencies.removed.length}`);
+        }
+        if (relationships.added.length || relationships.removed.length) {
+            summary.push(`Relationships +${relationships.added.length}/-${relationships.removed.length}`);
+        }
+        if (architectures.added.length || architectures.removed.length) {
+            summary.push(`Architectures +${architectures.added.length}/-${architectures.removed.length}`);
+        }
+        if (invalidatedIds.length > 0) {
+            summary.push(`Invalidated claims: ${invalidatedIds.length}`);
+        }
+    }
+    return {
+        before: beforeSnap,
+        after: afterSnap,
+        structuralEqual,
+        domains,
+        entrypoints,
+        dependencies,
+        relationships,
+        architectures,
+        invalidatedIds,
+        summary,
+    };
+}

package/dist/core/understanding/delta/index.d.ts

@@ -0,0 +1,2 @@
+export { compareProjectModels } from "./compare.js";
+export type { SetDelta, UnderstandingDelta } from "./compare.js";

package/dist/core/understanding/delta/index.js

@@ -0,0 +1 @@
+export { compareProjectModels } from "./compare.js";

package/dist/core/understanding/dependencies/discover.d.ts

@@ -0,0 +1,7 @@
+import type { DependencyDiscoveryOptions, DependencyDiscoveryResult, DependencyRelationType } from "./types.js";
+/**
+ * Discover structural repository dependencies via deterministic import/reference heuristics.
+ * Isolated from scan — internal understanding API only.
+ */
+export declare function discoverDependencies(options?: DependencyDiscoveryOptions): Promise<DependencyDiscoveryResult>;
+export declare function scoreDependencyConfidence(type: DependencyRelationType): number;