@praneeth_54/agentdoctor 0.3.0-beta → 1.1.0

package/dist/core/understanding/architecture/patterns/layered.js

@@ -0,0 +1,279 @@
+import { emptyRuleResult, findRelationships, hasRelationship, relationshipEvidenceLines, } from "../models.js";
+function evaluateMvc(ctx) {
+    const result = emptyRuleResult();
+    const routeToController = findRelationships(ctx.input, {
+        relationship: "EXPOSES",
+        targetIncludes: "Controller",
+    });
+    const controllerToService = findRelationships(ctx.input, {
+        relationship: ["USES", "CALLS"],
+        sourceIncludes: "Controller",
+        targetIncludes: "Service",
+    });
+    if (routeToController.length > 0) {
+        result.matchedRules.push("Route -> Controller");
+        result.evidence.push(...relationshipEvidenceLines(routeToController));
+        result.supportScore += 1.2;
+    }
+    if (controllerToService.length > 0) {
+        result.matchedRules.push("Controller -> Service");
+        result.evidence.push(...relationshipEvidenceLines(controllerToService));
+        result.supportScore += 1.4;
+    }
+    const widgetBloc = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Widget",
+        targetIncludes: "Bloc",
+    });
+    if (widgetBloc.length > 0) {
+        result.conflictingEvidence.push(...relationshipEvidenceLines(widgetBloc).map((e) => `BLoC-style edge conflicts with MVC: ${e}`));
+        result.conflictScore += 1.1;
+    }
+    if (result.matchedRules.length > 0 && !hasRelationship(ctx.input, { evidenceIncludes: "View" })) {
+        result.unknowns.push("No View layer evidence");
+    }
+    return result;
+}
+function evaluateMvvm(ctx) {
+    const result = emptyRuleResult(["No explicit ViewModel role in relationship graph"]);
+    const viewModelish = findRelationships(ctx.input, {
+        evidenceIncludes: ["viewmodel", "view-model", "ViewModel"],
+    });
+    const widgetToService = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: ["Widget", "View"],
+        targetIncludes: ["Service", "ViewModel", "Model"],
+    });
+    if (viewModelish.length > 0) {
+        result.matchedRules.push("ViewModel naming in relationships");
+        result.evidence.push(...relationshipEvidenceLines(viewModelish));
+        result.supportScore += 1.5;
+        result.unknowns = [];
+    }
+    if (widgetToService.length > 0 && viewModelish.length > 0) {
+        result.matchedRules.push("View/Widget binds to model layer");
+        result.evidence.push(...relationshipEvidenceLines(widgetToService));
+        result.supportScore += 1;
+    }
+    const controllerService = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Controller",
+        targetIncludes: "Service",
+    });
+    if (controllerService.length > 0 && viewModelish.length === 0) {
+        result.conflictingEvidence.push("Controller -> Service edges look like MVC, not MVVM");
+        result.conflictScore += 0.8;
+    }
+    return result;
+}
+function evaluateClean(ctx) {
+    const result = emptyRuleResult();
+    const controllerService = findRelationships(ctx.input, {
+        relationship: ["USES", "CALLS"],
+        sourceIncludes: "Controller",
+        targetIncludes: "Service",
+    });
+    const serviceRepo = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Service",
+        targetIncludes: "Repository",
+    });
+    const repoDb = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Repository",
+        targetIncludes: ["Database", "Entity"],
+    });
+    const implementsPort = findRelationships(ctx.input, {
+        relationship: "IMPLEMENTS",
+    });
+    if (controllerService.length && serviceRepo.length && repoDb.length) {
+        result.matchedRules.push("Presentation -> Application -> Domain -> Infrastructure");
+        result.evidence.push(...relationshipEvidenceLines(controllerService), ...relationshipEvidenceLines(serviceRepo), ...relationshipEvidenceLines(repoDb));
+        result.supportScore += 2.2;
+    }
+    else {
+        if (controllerService.length) {
+            result.matchedRules.push("Presentation calls application services");
+            result.evidence.push(...relationshipEvidenceLines(controllerService));
+            result.supportScore += 0.7;
+        }
+        if (serviceRepo.length) {
+            result.matchedRules.push("Application depends on repositories");
+            result.evidence.push(...relationshipEvidenceLines(serviceRepo));
+            result.supportScore += 0.8;
+        }
+        if (repoDb.length) {
+            result.matchedRules.push("Repositories touch infrastructure/persistence");
+            result.evidence.push(...relationshipEvidenceLines(repoDb));
+            result.supportScore += 0.8;
+        }
+    }
+    if (implementsPort.length > 0) {
+        result.matchedRules.push("Repositories behind interfaces");
+        result.evidence.push(...relationshipEvidenceLines(implementsPort));
+        result.supportScore += 1.3;
+    }
+    else if (result.matchedRules.length > 0) {
+        result.unknowns.push("No dependency inversion metadata");
+    }
+    const controllerRepo = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Controller",
+        targetIncludes: ["Repository", "Database", "Entity"],
+    });
+    if (controllerRepo.length > 0) {
+        result.conflictingEvidence.push(`Infrastructure accessed directly in ${controllerRepo.length} module(s)`);
+        result.conflictScore += 1.2 * Math.min(controllerRepo.length, 3);
+    }
+    return result;
+}
+function evaluateLayered(ctx) {
+    const result = emptyRuleResult();
+    const layers = [
+        findRelationships(ctx.input, {
+            relationship: ["USES", "CALLS", "EXPOSES"],
+            evidenceIncludes: "Controller → Service",
+        }),
+        findRelationships(ctx.input, {
+            relationship: "USES",
+            evidenceIncludes: "Service → Repository",
+        }),
+        findRelationships(ctx.input, {
+            relationship: "USES",
+            evidenceIncludes: "Repository → Database",
+        }),
+    ];
+    let depth = 0;
+    if (layers[0]?.length) {
+        depth += 1;
+        result.matchedRules.push("Controller layer above Service layer");
+        result.evidence.push(...relationshipEvidenceLines(layers[0]));
+    }
+    if (layers[1]?.length) {
+        depth += 1;
+        result.matchedRules.push("Service layer above Repository layer");
+        result.evidence.push(...relationshipEvidenceLines(layers[1]));
+    }
+    if (layers[2]?.length) {
+        depth += 1;
+        result.matchedRules.push("Repository layer above persistence");
+        result.evidence.push(...relationshipEvidenceLines(layers[2]));
+    }
+    if (depth >= 2) {
+        result.supportScore += depth * 0.9;
+    }
+    if (depth >= 2 && findRelationships(ctx.input, { relationship: "IMPLEMENTS" }).length === 0) {
+        result.unknowns.push("Layering observed without explicit ports/interfaces");
+    }
+    return result;
+}
+function evaluateHexagonal(ctx) {
+    const result = emptyRuleResult();
+    const ports = findRelationships(ctx.input, { relationship: "IMPLEMENTS" });
+    const moduleProvides = findRelationships(ctx.input, {
+        relationship: "PROVIDES",
+        sourceIncludes: "Module",
+    });
+    const configures = findRelationships(ctx.input, { relationship: "CONFIGURES" });
+    if (ports.length > 0) {
+        result.matchedRules.push("Port interfaces implemented by adapters");
+        result.evidence.push(...relationshipEvidenceLines(ports));
+        result.supportScore += 1.4;
+    }
+    if (moduleProvides.length > 0) {
+        result.matchedRules.push("Composition root wires application ports");
+        result.evidence.push(...relationshipEvidenceLines(moduleProvides));
+        result.supportScore += 1;
+    }
+    if (configures.length > 0) {
+        result.matchedRules.push("Adapters configured at boundaries");
+        result.evidence.push(...relationshipEvidenceLines(configures));
+        result.supportScore += 0.8;
+    }
+    if (result.matchedRules.length > 0 && ports.length === 0) {
+        result.unknowns.push("No explicit port/adapter naming beyond module wiring");
+    }
+    const leak = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Controller",
+        targetIncludes: ["Database", "Entity"],
+    });
+    if (leak.length > 0) {
+        result.conflictingEvidence.push("Controllers depend on infrastructure entities");
+        result.conflictScore += 1;
+    }
+    return result;
+}
+function evaluateOnion(ctx) {
+    const result = emptyRuleResult();
+    const domainNames = ctx.input.domains.domains.map((d) => d.name);
+    const domainProvides = domainNames.length > 0
+        ? findRelationships(ctx.input, {
+            relationship: "PROVIDES",
+            targetIncludes: domainNames,
+        })
+        : [];
+    const featureContains = findRelationships(ctx.input, { relationship: "CONTAINS" });
+    const repo = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Service",
+        targetIncludes: "Repository",
+    });
+    if (ctx.input.domains.domains.length > 0 &&
+        (domainProvides.length > 0 || featureContains.length > 0)) {
+        result.matchedRules.push("Domain concepts at the center of feature slices");
+        result.evidence.push(...ctx.input.domains.domains.slice(0, 3).map((d) => `domain:${d.name}`), ...relationshipEvidenceLines(domainProvides));
+        result.supportScore += 1.2;
+    }
+    if (repo.length > 0) {
+        result.matchedRules.push("Outer layers depend inward toward repositories/domain");
+        result.evidence.push(...relationshipEvidenceLines(repo));
+        result.supportScore += 1;
+    }
+    if (result.matchedRules.length > 0 && domainProvides.length === 0) {
+        result.unknowns.push("Domain labels present but weak inward dependency proof");
+    }
+    return result;
+}
+function evaluateDdd(ctx) {
+    const result = emptyRuleResult();
+    if (ctx.input.domains.domains.length >= 1) {
+        result.matchedRules.push("Bounded domain vocabulary discovered");
+        result.evidence.push(...ctx.input.domains.domains
+            .slice(0, 4)
+            .map((d) => `domain ${d.name} (confidence ${d.confidence}) via ${d.evidence[0] ?? "path"}`));
+        result.supportScore += Math.min(ctx.input.domains.domains.length, 3) * 0.7;
+    }
+    const provides = findRelationships(ctx.input, {
+        relationship: "PROVIDES",
+        evidenceIncludes: "domain",
+    });
+    if (provides.length > 0) {
+        result.matchedRules.push("Features provide domain capabilities");
+        result.evidence.push(...relationshipEvidenceLines(provides));
+        result.supportScore += 1.1;
+    }
+    const aggregates = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Repository",
+        targetIncludes: ["Entity", "Database"],
+    });
+    if (aggregates.length > 0) {
+        result.matchedRules.push("Repositories protect persistence/entity access");
+        result.evidence.push(...relationshipEvidenceLines(aggregates));
+        result.supportScore += 0.9;
+    }
+    if (result.matchedRules.length > 0 && provides.length === 0) {
+        result.unknowns.push("No explicit aggregate/root relationship metadata");
+    }
+    return result;
+}
+export const layeredPatterns = [
+    { pattern: "MVC", evaluate: evaluateMvc },
+    { pattern: "MVVM", evaluate: evaluateMvvm },
+    { pattern: "Clean Architecture", evaluate: evaluateClean },
+    { pattern: "Layered Architecture", evaluate: evaluateLayered },
+    { pattern: "Hexagonal", evaluate: evaluateHexagonal },
+    { pattern: "Onion", evaluate: evaluateOnion },
+    { pattern: "DDD", evaluate: evaluateDdd },
+];

package/dist/core/understanding/architecture/patterns/structural.d.ts

@@ -0,0 +1,2 @@
+import type { ArchitecturePatternDefinition } from "../types.js";
+export declare const structuralPatterns: ArchitecturePatternDefinition[];

package/dist/core/understanding/architecture/patterns/structural.js

@@ -0,0 +1,197 @@
+import { emptyRuleResult, findDependencies, findEntrypoints, findRelationships, relationshipEvidenceLines, } from "../models.js";
+function evaluateRepository(ctx) {
+    const result = emptyRuleResult();
+    const serviceRepo = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Service",
+        targetIncludes: "Repository",
+    });
+    const repoDb = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Repository",
+        targetIncludes: ["Database", "Entity"],
+    });
+    if (serviceRepo.length > 0) {
+        result.matchedRules.push("Services depend on repositories");
+        result.evidence.push(...relationshipEvidenceLines(serviceRepo));
+        result.supportScore += 1.4;
+    }
+    if (repoDb.length > 0) {
+        result.matchedRules.push("Repositories encapsulate persistence");
+        result.evidence.push(...relationshipEvidenceLines(repoDb));
+        result.supportScore += 1.2;
+    }
+    const leak = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Controller",
+        targetIncludes: ["Database", "Entity"],
+    });
+    if (leak.length > 0) {
+        result.conflictingEvidence.push("Controllers bypass repositories to persistence");
+        result.conflictScore += 1;
+    }
+    if (result.matchedRules.length > 0 && repoDb.length === 0) {
+        result.unknowns.push("Repository present without clear persistence target");
+    }
+    return result;
+}
+function evaluateServiceLayer(ctx) {
+    const result = emptyRuleResult();
+    const controllerService = findRelationships(ctx.input, {
+        relationship: ["USES", "CALLS"],
+        sourceIncludes: ["Controller", "API", "Route"],
+        targetIncludes: "Service",
+    });
+    const apiService = findRelationships(ctx.input, {
+        relationship: "CALLS",
+        sourceIncludes: "API",
+        targetIncludes: "Service",
+    });
+    if (controllerService.length > 0) {
+        result.matchedRules.push("Application entrypoints delegate to services");
+        result.evidence.push(...relationshipEvidenceLines(controllerService));
+        result.supportScore += 1.5;
+    }
+    if (apiService.length > 0) {
+        result.matchedRules.push("API layer calls service layer");
+        result.evidence.push(...relationshipEvidenceLines(apiService));
+        result.supportScore += 1.1;
+    }
+    if (result.matchedRules.length > 0) {
+        const serviceRepo = findRelationships(ctx.input, {
+            relationship: "USES",
+            sourceIncludes: "Service",
+            targetIncludes: "Repository",
+        });
+        if (serviceRepo.length === 0) {
+            result.unknowns.push("Service layer detected without downstream repository edges");
+        }
+    }
+    return result;
+}
+function evaluateFeatureFirst(ctx) {
+    const result = emptyRuleResult();
+    const contains = findRelationships(ctx.input, { relationship: "CONTAINS" });
+    const consumes = findRelationships(ctx.input, { relationship: "CONSUMES" });
+    const owns = findRelationships(ctx.input, { relationship: "OWNS" });
+    if (contains.length >= 2) {
+        result.matchedRules.push("Features contain multiple components");
+        result.evidence.push(...relationshipEvidenceLines(contains, 4));
+        result.supportScore += 1.3;
+    }
+    if (consumes.length > 0) {
+        result.matchedRules.push("Cross-feature consumption edges");
+        result.evidence.push(...relationshipEvidenceLines(consumes));
+        result.supportScore += 1.2;
+    }
+    if (owns.length > 0) {
+        result.matchedRules.push("Packages own feature slices");
+        result.evidence.push(...relationshipEvidenceLines(owns));
+        result.supportScore += 0.8;
+    }
+    if (result.matchedRules.length > 0 && consumes.length === 0) {
+        result.unknowns.push("Feature folders present without cross-feature dependency proof");
+    }
+    return result;
+}
+function evaluateBloc(ctx) {
+    const result = emptyRuleResult();
+    const widgetBloc = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Widget",
+        targetIncludes: "Bloc",
+    });
+    const blocRepo = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Bloc",
+        targetIncludes: "Repository",
+    });
+    const flutter = findEntrypoints(ctx.input, { framework: "Flutter" });
+    if (widgetBloc.length > 0) {
+        result.matchedRules.push("Widget -> Bloc");
+        result.evidence.push(...relationshipEvidenceLines(widgetBloc));
+        result.supportScore += 1.6;
+    }
+    if (blocRepo.length > 0) {
+        result.matchedRules.push("Bloc -> Repository");
+        result.evidence.push(...relationshipEvidenceLines(blocRepo));
+        result.supportScore += 1.3;
+    }
+    if (flutter.length > 0 && result.matchedRules.length > 0) {
+        result.matchedRules.push("Flutter entrypoint accompanies BLoC edges");
+        result.evidence.push(...flutter.slice(0, 2).map((e) => `entrypoint:${e.file}`));
+        result.supportScore += 0.7;
+    }
+    const mvc = findRelationships(ctx.input, {
+        relationship: "USES",
+        sourceIncludes: "Controller",
+        targetIncludes: "Service",
+    });
+    if (mvc.length > 0 && widgetBloc.length > 0) {
+        result.conflictingEvidence.push("Controller/Service MVC edges coexist with BLoC UI edges");
+        result.conflictScore += 0.4;
+    }
+    if (widgetBloc.length > 0 && blocRepo.length === 0) {
+        result.unknowns.push("BLoC UI wiring without repository edge evidence");
+    }
+    return result;
+}
+function evaluateRiverpod(ctx) {
+    const result = emptyRuleResult(["No Riverpod-specific provider graph metadata"]);
+    const providerish = [
+        ...findRelationships(ctx.input, { evidenceIncludes: ["riverpod", "Provider", "ref.watch"] }),
+        ...findDependencies(ctx.input, { evidenceIncludes: ["riverpod"] }),
+        ...findEntrypoints(ctx.input, { evidenceIncludes: ["riverpod", "Provider"] }),
+    ];
+    if (providerish.length === 0) {
+        return result;
+    }
+    result.unknowns = [];
+    result.matchedRules.push("Riverpod/Provider evidence in discovery outputs");
+    result.evidence.push(...providerish.slice(0, 4).map((item) => {
+        if ("relationship" in item) {
+            return `${item.source} ${item.relationship} ${item.target}`;
+        }
+        if ("framework" in item) {
+            return `entrypoint:${item.file}`;
+        }
+        return `dependency:${item.from}->${item.to}`;
+    }));
+    result.supportScore += 1.5;
+    const flutter = findEntrypoints(ctx.input, { framework: "Flutter" });
+    if (flutter.length === 0) {
+        result.conflictingEvidence.push("Riverpod signals without Flutter entrypoints");
+        result.conflictScore += 0.6;
+    }
+    return result;
+}
+function evaluateRedux(ctx) {
+    const result = emptyRuleResult(["No reducer/store relationship metadata"]);
+    const reduxish = [
+        ...findRelationships(ctx.input, {
+            evidenceIncludes: ["redux", "reducer", "createStore", "useSelector", "dispatch"],
+        }),
+        ...findDependencies(ctx.input, { evidenceIncludes: ["redux", "reducer", "store"] }),
+    ];
+    if (reduxish.length === 0) {
+        return result;
+    }
+    result.unknowns = [];
+    result.matchedRules.push("Redux store/reducer evidence in discovery outputs");
+    result.evidence.push(...reduxish.slice(0, 4).map((item) => {
+        if ("relationship" in item) {
+            return `${item.source} ${item.relationship} ${item.target}`;
+        }
+        return `dependency:${item.from}->${item.to}`;
+    }));
+    result.supportScore += 1.5;
+    return result;
+}
+export const structuralPatterns = [
+    { pattern: "Repository Pattern", evaluate: evaluateRepository },
+    { pattern: "Service Layer", evaluate: evaluateServiceLayer },
+    { pattern: "Feature-first", evaluate: evaluateFeatureFirst },
+    { pattern: "BLoC", evaluate: evaluateBloc },
+    { pattern: "Riverpod", evaluate: evaluateRiverpod },
+    { pattern: "Redux", evaluate: evaluateRedux },
+];

package/dist/core/understanding/architecture/rules.d.ts

@@ -0,0 +1,4 @@
+import type { ArchitecturePatternDefinition } from "./types.js";
+/** Ordered pattern rule registry used by the inference engine. */
+export declare const ARCHITECTURE_RULES: readonly ArchitecturePatternDefinition[];
+export declare function listArchitecturePatterns(): string[];

package/dist/core/understanding/architecture/rules.js

@@ -0,0 +1,6 @@
+import { ARCHITECTURE_PATTERNS } from "./patterns/index.js";
+/** Ordered pattern rule registry used by the inference engine. */
+export const ARCHITECTURE_RULES = ARCHITECTURE_PATTERNS;
+export function listArchitecturePatterns() {
+    return ARCHITECTURE_RULES.map((rule) => rule.pattern);
+}

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

@@ -0,0 +1,52 @@
+import type { DependencyDiscoveryResult } from "../dependencies/types.js";
+import type { EntrypointDiscoveryResult } from "../entrypoints/types.js";
+import type { RelationshipDiscoveryResult, RelationshipKind } from "../relationships/types.js";
+import type { DomainDiscoveryResult } from "../types/index.js";
+export type ArchitecturePattern = "MVC" | "MVVM" | "Clean Architecture" | "Layered Architecture" | "Hexagonal" | "Onion" | "DDD" | "Repository Pattern" | "Service Layer" | "Feature-first" | "BLoC" | "Riverpod" | "Redux" | "Microservice" | "Modular Monolith" | "Plugin Architecture" | "Monorepo Workspace";
+export interface ArchitectureInferenceInput {
+    domains: DomainDiscoveryResult;
+    entrypoints: EntrypointDiscoveryResult;
+    dependencies: DependencyDiscoveryResult;
+    relationships: RelationshipDiscoveryResult;
+}
+export interface ArchitectureMatch {
+    pattern: ArchitecturePattern;
+    confidence: number;
+    evidence: string[];
+    matchedRules: string[];
+    conflictingEvidence: string[];
+    unknowns: string[];
+}
+export interface ArchitectureInferenceResult {
+    architectures: ArchitectureMatch[];
+    timingMs: number;
+    patternsEvaluated: number;
+}
+export interface ArchitectureInferenceOptions {
+    /** Minimum confidence to include a pattern (0–1). Default 0.55. Never reaches 1.0. */
+    minConfidence?: number;
+}
+export interface PatternRuleContext {
+    input: ArchitectureInferenceInput;
+}
+export interface PatternRuleResult {
+    matchedRules: string[];
+    evidence: string[];
+    conflictingEvidence: string[];
+    unknowns: string[];
+    /** Relative weight of support before conflict penalties. */
+    supportScore: number;
+    /** Relative weight of conflicts. */
+    conflictScore: number;
+}
+export type PatternEvaluator = (ctx: PatternRuleContext) => PatternRuleResult;
+export interface ArchitecturePatternDefinition {
+    pattern: ArchitecturePattern;
+    evaluate: PatternEvaluator;
+}
+export type RelationPredicate = {
+    relationship?: RelationshipKind | RelationshipKind[];
+    sourceIncludes?: string | string[];
+    targetIncludes?: string | string[];
+    evidenceIncludes?: string | string[];
+};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,13 @@
+import type { ProjectModel } from "../model/types.js";
+import { type OwnershipDiscoveryResult } from "../ownership/index.js";
+import { type RiskDiscoveryResult } from "../risks/index.js";
+import { type BrainClaim } from "./claims/index.js";
+import { type ProjectBrain } from "./types.js";
+export interface BuildProjectBrainOptions {
+    cwd?: string;
+    ownership?: OwnershipDiscoveryResult;
+    risks?: RiskDiscoveryResult;
+    previousClaims?: readonly BrainClaim[];
+    generatedAt?: string;
+}
+export declare function buildProjectBrain(model: ProjectModel, options?: BuildProjectBrainOptions): Promise<ProjectBrain>;