@praneeth_54/agentdoctor 0.3.0-beta → 1.1.0

package/dist/core/rules/text-cache.js

@@ -32,55 +32,61 @@ export class TextCache {
             return blocked;
         }
         try {
-            const stat = await fs.stat(absolute);
-            if (!stat.isFile()) {
-                const result = {
-                    relativePath: toPosixRelative(this.root, absolute),
-                    text: null,
-                    sizeBytes: 0,
-                    empty: true,
-                    binary: false,
-                    error: "Not a regular file",
-                };
-                this.cache.set(relativePath, result);
-                return result;
-            }
-            const sizeBytes = Number(stat.size);
-            if (sizeBytes > this.maxBytes) {
+            const handle = await fs.open(absolute, "r");
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile()) {
+                    const result = {
+                        relativePath: toPosixRelative(this.root, absolute),
+                        text: null,
+                        sizeBytes: 0,
+                        empty: true,
+                        binary: false,
+                        error: "Not a regular file",
+                    };
+                    this.cache.set(relativePath, result);
+                    return result;
+                }
+                const sizeBytes = Number(stat.size);
+                if (sizeBytes > this.maxBytes) {
+                    const result = {
+                        relativePath,
+                        text: null,
+                        sizeBytes,
+                        empty: false,
+                        binary: false,
+                        error: "File exceeds max read size",
+                    };
+                    this.cache.set(relativePath, result);
+                    return result;
+                }
+                const buffer = await handle.readFile();
+                if (looksBinary(buffer)) {
+                    const result = {
+                        relativePath,
+                        text: null,
+                        sizeBytes,
+                        empty: sizeBytes === 0,
+                        binary: true,
+                        error: "Binary file skipped",
+                    };
+                    this.cache.set(relativePath, result);
+                    return result;
+                }
+                const text = buffer.toString("utf8");
                 const result = {
                     relativePath,
-                    text: null,
+                    text,
                     sizeBytes,
-                    empty: false,
+                    empty: text.trim().length === 0,
                     binary: false,
-                    error: "File exceeds max read size",
                 };
                 this.cache.set(relativePath, result);
                 return result;
             }
-            const buffer = await fs.readFile(absolute);
-            if (looksBinary(buffer)) {
-                const result = {
-                    relativePath,
-                    text: null,
-                    sizeBytes,
-                    empty: sizeBytes === 0,
-                    binary: true,
-                    error: "Binary file skipped",
-                };
-                this.cache.set(relativePath, result);
-                return result;
+            finally {
+                await handle.close();
             }
-            const text = buffer.toString("utf8");
-            const result = {
-                relativePath,
-                text,
-                sizeBytes,
-                empty: text.trim().length === 0,
-                binary: false,
-            };
-            this.cache.set(relativePath, result);
-            return result;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "Unable to read file";

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

@@ -0,0 +1,4 @@
+export { inferArchitectures } from "./infer.js";
+export { ARCHITECTURE_RULES, listArchitecturePatterns } from "./rules.js";
+export { scorePatternConfidence, clampConfidence } from "./models.js";
+export type { ArchitectureInferenceInput, ArchitectureInferenceOptions, ArchitectureInferenceResult, ArchitectureMatch, ArchitecturePattern, PatternRuleResult, } from "./types.js";

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

@@ -0,0 +1,3 @@
+export { inferArchitectures } from "./infer.js";
+export { ARCHITECTURE_RULES, listArchitecturePatterns } from "./rules.js";
+export { scorePatternConfidence, clampConfidence } from "./models.js";

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

@@ -0,0 +1,6 @@
+import type { ArchitectureInferenceInput, ArchitectureInferenceOptions, ArchitectureInferenceResult } from "./types.js";
+/**
+ * Infer architectural patterns from prior discovery outputs only.
+ * Does not scan the filesystem or repository.
+ */
+export declare function inferArchitectures(input: ArchitectureInferenceInput, options?: ArchitectureInferenceOptions): ArchitectureInferenceResult;

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

@@ -0,0 +1,39 @@
+import { finalizeMatch } from "./models.js";
+import { ARCHITECTURE_RULES } from "./rules.js";
+function assertInput(input) {
+    if (!input.domains || !input.entrypoints || !input.dependencies || !input.relationships) {
+        throw new Error("inferArchitectures requires domains, entrypoints, dependencies, and relationships inputs");
+    }
+}
+/**
+ * Infer architectural patterns from prior discovery outputs only.
+ * Does not scan the filesystem or repository.
+ */
+export function inferArchitectures(input, options = {}) {
+    const started = performance.now();
+    assertInput(input);
+    const minConfidence = options.minConfidence ?? 0.55;
+    const architectures = [];
+    for (const definition of ARCHITECTURE_RULES) {
+        const evaluated = definition.evaluate({ input });
+        const match = finalizeMatch(definition.pattern, evaluated);
+        if (!match) {
+            continue;
+        }
+        if (match.confidence < minConfidence) {
+            continue;
+        }
+        architectures.push(match);
+    }
+    architectures.sort((a, b) => {
+        if (b.confidence !== a.confidence) {
+            return b.confidence - a.confidence;
+        }
+        return a.pattern.localeCompare(b.pattern);
+    });
+    return {
+        architectures,
+        timingMs: Math.round(performance.now() - started),
+        patternsEvaluated: ARCHITECTURE_RULES.length,
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { DependencyMatch } from "../dependencies/types.js";
+import type { EntrypointMatch } from "../entrypoints/types.js";
+import type { RelationshipMatch } from "../relationships/types.js";
+import type { ArchitectureInferenceInput, ArchitectureMatch, PatternRuleResult, RelationPredicate } from "./types.js";
+export declare function clampConfidence(value: number): number;
+export declare function scorePatternConfidence(options: {
+    supportScore: number;
+    conflictScore: number;
+    matchedRuleCount: number;
+}): number;
+export declare function findRelationships(input: ArchitectureInferenceInput, predicate: RelationPredicate): RelationshipMatch[];
+export declare function hasRelationship(input: ArchitectureInferenceInput, predicate: RelationPredicate): boolean;
+export declare function relationshipEvidenceLines(rels: RelationshipMatch[], limit?: number): string[];
+export declare function findDependencies(input: ArchitectureInferenceInput, options?: {
+    type?: DependencyMatch["type"] | DependencyMatch["type"][];
+    evidenceIncludes?: string | string[];
+}): DependencyMatch[];
+export declare function findEntrypoints(input: ArchitectureInferenceInput, options?: {
+    framework?: EntrypointMatch["framework"] | EntrypointMatch["framework"][];
+    evidenceIncludes?: string | string[];
+}): EntrypointMatch[];
+export declare function emptyRuleResult(unknowns?: string[]): PatternRuleResult;
+export declare function finalizeMatch(pattern: ArchitectureMatch["pattern"], result: PatternRuleResult): ArchitectureMatch | null;

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

@@ -0,0 +1,127 @@
+export function clampConfidence(value) {
+    if (value < 0) {
+        return 0;
+    }
+    // Never claim certainty.
+    if (value > 0.95) {
+        return 0.95;
+    }
+    return Math.round(value * 100) / 100;
+}
+export function scorePatternConfidence(options) {
+    const { supportScore, conflictScore, matchedRuleCount } = options;
+    if (matchedRuleCount <= 0 || supportScore <= 0) {
+        return 0;
+    }
+    const raw = supportScore / (supportScore + conflictScore * 1.25 + 0.35);
+    const ruleBonus = Math.min(matchedRuleCount, 4) * 0.03;
+    return clampConfidence(raw + ruleBonus);
+}
+function asList(value) {
+    if (!value) {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+}
+function includesAny(haystack, needles) {
+    if (needles.length === 0) {
+        return true;
+    }
+    const lower = haystack.toLowerCase();
+    return needles.some((n) => lower.includes(n.toLowerCase()));
+}
+export function findRelationships(input, predicate) {
+    const kinds = asList(predicate.relationship);
+    const sources = asList(predicate.sourceIncludes);
+    const targets = asList(predicate.targetIncludes);
+    const evidenceNeedles = asList(predicate.evidenceIncludes);
+    return input.relationships.relationships.filter((rel) => {
+        if (kinds.length > 0 && !kinds.includes(rel.relationship)) {
+            return false;
+        }
+        if (sources.length > 0 && !includesAny(rel.source, sources)) {
+            return false;
+        }
+        if (targets.length > 0 && !includesAny(rel.target, targets)) {
+            return false;
+        }
+        if (evidenceNeedles.length > 0) {
+            const blob = `${rel.source} ${rel.target} ${rel.evidence.join(" ")}`;
+            if (!includesAny(blob, evidenceNeedles)) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+export function hasRelationship(input, predicate) {
+    return findRelationships(input, predicate).length > 0;
+}
+export function relationshipEvidenceLines(rels, limit = 3) {
+    return rels
+        .slice(0, limit)
+        .flatMap((r) => r.evidence.slice(0, 1).map((e) => `${r.source} ${r.relationship} ${r.target}: ${e}`));
+}
+export function findDependencies(input, options = {}) {
+    const types = asList(options.type);
+    const needles = asList(options.evidenceIncludes);
+    return input.dependencies.dependencies.filter((dep) => {
+        if (types.length > 0 && !types.includes(dep.type)) {
+            return false;
+        }
+        if (needles.length > 0) {
+            const blob = `${dep.from} ${dep.to} ${dep.evidence.join(" ")}`;
+            if (!includesAny(blob, needles)) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+export function findEntrypoints(input, options = {}) {
+    const frameworks = asList(options.framework);
+    const needles = asList(options.evidenceIncludes);
+    return input.entrypoints.entrypoints.filter((entry) => {
+        if (frameworks.length > 0 && !frameworks.includes(entry.framework)) {
+            return false;
+        }
+        if (needles.length > 0) {
+            const blob = `${entry.file} ${entry.evidence.join(" ")}`;
+            if (!includesAny(blob, needles)) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+export function emptyRuleResult(unknowns = []) {
+    return {
+        matchedRules: [],
+        evidence: [],
+        conflictingEvidence: [],
+        unknowns,
+        supportScore: 0,
+        conflictScore: 0,
+    };
+}
+export function finalizeMatch(pattern, result) {
+    if (result.matchedRules.length === 0 || result.supportScore <= 0) {
+        return null;
+    }
+    const confidence = scorePatternConfidence({
+        supportScore: result.supportScore,
+        conflictScore: result.conflictScore,
+        matchedRuleCount: result.matchedRules.length,
+    });
+    if (confidence <= 0) {
+        return null;
+    }
+    return {
+        pattern,
+        confidence,
+        evidence: [...result.evidence].sort((a, b) => a.localeCompare(b)),
+        matchedRules: [...result.matchedRules].sort((a, b) => a.localeCompare(b)),
+        conflictingEvidence: [...result.conflictingEvidence].sort((a, b) => a.localeCompare(b)),
+        unknowns: [...result.unknowns].sort((a, b) => a.localeCompare(b)),
+    };
+}

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

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

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

@@ -0,0 +1,115 @@
+import { emptyRuleResult, findDependencies, findEntrypoints, findRelationships, relationshipEvidenceLines, } from "../models.js";
+function evaluateMicroservice(ctx) {
+    const result = emptyRuleResult();
+    const frameworks = new Set(ctx.input.entrypoints.entrypoints.map((e) => e.framework));
+    const packageDeps = findDependencies(ctx.input, { type: "package" });
+    if (frameworks.size >= 2) {
+        result.matchedRules.push("Multiple runtime entrypoint frameworks");
+        result.evidence.push(...ctx.input.entrypoints.entrypoints
+            .slice(0, 5)
+            .map((e) => `entrypoint:${e.framework}:${e.file}`));
+        result.supportScore += frameworks.size * 0.7;
+    }
+    if (packageDeps.length >= 2) {
+        result.matchedRules.push("Multiple independently versioned package boundaries");
+        result.evidence.push(...packageDeps.slice(0, 4).map((d) => `${d.from} package-depends ${d.to}`));
+        result.supportScore += 0.8;
+    }
+    const moduleConfig = findRelationships(ctx.input, { relationship: "CONFIGURES" });
+    if (frameworks.size >= 2 && moduleConfig.length > 0 && packageDeps.length <= 1) {
+        result.conflictingEvidence.push("Shared module configuration suggests modular monolith more than pure microservices");
+        result.conflictScore += 0.7;
+    }
+    if (result.matchedRules.length > 0 && frameworks.size < 2) {
+        result.unknowns.push("Package splits without multi-runtime entrypoint proof");
+    }
+    return result;
+}
+function evaluateModularMonolith(ctx) {
+    const result = emptyRuleResult();
+    const modules = findRelationships(ctx.input, {
+        relationship: ["PROVIDES", "CONFIGURES"],
+        sourceIncludes: "Module",
+    });
+    const nest = findEntrypoints(ctx.input, { framework: "NestJS" });
+    const packageDeps = findDependencies(ctx.input, { type: "package" });
+    const frameworks = new Set(ctx.input.entrypoints.entrypoints.map((e) => e.framework));
+    if (modules.length > 0) {
+        result.matchedRules.push("Internal modules provide/configure application parts");
+        result.evidence.push(...relationshipEvidenceLines(modules));
+        result.supportScore += 1.4;
+    }
+    if (nest.length > 0 || (frameworks.size === 1 && modules.length > 0)) {
+        result.matchedRules.push("Single primary application runtime hosts modules");
+        result.evidence.push(...[...frameworks].map((f) => `runtime:${f}`), ...nest.slice(0, 2).map((e) => `entrypoint:${e.file}`));
+        result.supportScore += 1;
+    }
+    if (packageDeps.length > 0 && modules.length > 0) {
+        result.matchedRules.push("Workspace packages compose one deployable system");
+        result.evidence.push(...packageDeps.slice(0, 3).map((d) => `${d.from}->${d.to}`));
+        result.supportScore += 0.8;
+    }
+    if (frameworks.size >= 3) {
+        result.conflictingEvidence.push("Many independent runtimes weaken modular-monolith claim");
+        result.conflictScore += 0.9;
+    }
+    if (result.matchedRules.length > 0 && modules.length === 0) {
+        result.unknowns.push("Monolith packaging without module wiring evidence");
+    }
+    return result;
+}
+function evaluatePlugin(ctx) {
+    const result = emptyRuleResult();
+    const dynamic = findDependencies(ctx.input, { type: "dynamic-import" });
+    const moduleProvides = findRelationships(ctx.input, {
+        relationship: "PROVIDES",
+        sourceIncludes: "Module",
+    });
+    if (dynamic.length > 0) {
+        result.matchedRules.push("Dynamic imports indicate pluggable extension points");
+        result.evidence.push(...dynamic.slice(0, 4).map((d) => `dynamic:${d.from}->${d.to} (${d.evidence[0] ?? ""})`));
+        result.supportScore += 1.5;
+    }
+    if (moduleProvides.length > 0 && dynamic.length > 0) {
+        result.matchedRules.push("Modules expose extension surfaces");
+        result.evidence.push(...relationshipEvidenceLines(moduleProvides));
+        result.supportScore += 0.9;
+    }
+    if (dynamic.length > 0 && moduleProvides.length === 0) {
+        result.unknowns.push("Dynamic loading without explicit module/plugin registry evidence");
+    }
+    return result;
+}
+function evaluateMonorepo(ctx) {
+    const result = emptyRuleResult();
+    const packageDeps = findDependencies(ctx.input, {
+        type: "package",
+        evidenceIncludes: ["declares dependency", "package"],
+    });
+    const owns = findRelationships(ctx.input, { relationship: "OWNS" });
+    const depends = findDependencies(ctx.input, { type: "package" });
+    if (depends.length > 0) {
+        result.matchedRules.push("Workspace package dependency edges");
+        result.evidence.push(...depends.slice(0, 5).map((d) => `${d.from} DEPENDS_ON ${d.to}: ${d.evidence[0] ?? d.type}`));
+        result.supportScore += Math.min(depends.length, 4) * 0.55;
+    }
+    if (packageDeps.length > 0) {
+        result.matchedRules.push("Manifest-declared workspace references");
+        result.supportScore += 0.8;
+    }
+    if (owns.length > 0) {
+        result.matchedRules.push("Packages own feature/module slices");
+        result.evidence.push(...relationshipEvidenceLines(owns));
+        result.supportScore += 0.7;
+    }
+    if (result.matchedRules.length > 0 && depends.length < 1) {
+        result.unknowns.push("Monorepo layout cues without package dependency edges");
+    }
+    return result;
+}
+export const distributionPatterns = [
+    { pattern: "Microservice", evaluate: evaluateMicroservice },
+    { pattern: "Modular Monolith", evaluate: evaluateModularMonolith },
+    { pattern: "Plugin Architecture", evaluate: evaluatePlugin },
+    { pattern: "Monorepo Workspace", evaluate: evaluateMonorepo },
+];

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

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

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

@@ -0,0 +1,8 @@
+import { distributionPatterns } from "./distribution.js";
+import { layeredPatterns } from "./layered.js";
+import { structuralPatterns } from "./structural.js";
+export const ARCHITECTURE_PATTERNS = [
+    ...layeredPatterns,
+    ...structuralPatterns,
+    ...distributionPatterns,
+];

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

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