@praneeth_54/agentdoctor 1.0.0 → 1.1.1

package/dist/cli/commands/brain-mcp.d.ts

@@ -0,0 +1,9 @@
+export interface BrainMcpCommandOptions {
+    root: string;
+    buildIfMissing?: boolean;
+    generatedAt?: string;
+}
+/**
+ * Start Brain MCP over STDIO. Must not write protocol noise to stdout.
+ */
+export declare function runBrainMcpCommand(options: BrainMcpCommandOptions): Promise<number>;

package/dist/cli/commands/brain-mcp.js

@@ -0,0 +1,38 @@
+import { EXIT_CODES } from "../../types/index.js";
+import { BrainMcpError, runBrainMcpStdio } from "../../mcp/brain/index.js";
+/**
+ * Start Brain MCP over STDIO. Must not write protocol noise to stdout.
+ */
+export async function runBrainMcpCommand(options) {
+    try {
+        if (!options.root || options.root.trim().length === 0) {
+            process.stderr.write("Error: --root <path> is required (never scans process.cwd() implicitly)\n");
+            return EXIT_CODES.USAGE_ERROR;
+        }
+        await runBrainMcpStdio({
+            root: options.root,
+            buildIfMissing: options.buildIfMissing !== false,
+            ...(options.generatedAt !== undefined ? { generatedAt: options.generatedAt } : {}),
+            log: (message) => process.stderr.write(`${message}\n`),
+        });
+        // STDIO server runs until stdin closes; resolve when transport ends.
+        await new Promise((resolve) => {
+            const onClose = () => resolve();
+            process.stdin.on("end", onClose);
+            process.stdin.on("close", onClose);
+        });
+        return EXIT_CODES.SUCCESS;
+    }
+    catch (error) {
+        if (error instanceof BrainMcpError) {
+            process.stderr.write(`Error: ${error.message}\n`);
+            if (error.code === "invalid_root" || error.code === "invalid_argument") {
+                return EXIT_CODES.USAGE_ERROR;
+            }
+            return EXIT_CODES.INTERNAL_ERROR;
+        }
+        const message = error instanceof Error ? error.message : "brain-mcp failed";
+        process.stderr.write(`Error: ${message}\n`);
+        return EXIT_CODES.INTERNAL_ERROR;
+    }
+}

package/dist/cli/program.js

@@ -2,6 +2,7 @@ import { Command, InvalidArgumentError } from "commander";
 import { PACKAGE_VERSION } from "../constants.js";
 import { parseFailOnRules, parseSeverityGate } from "../core/policy/evaluate.js";
 import { EXIT_CODES } from "../types/index.js";
+import { runBrainMcpCommand } from "./commands/brain-mcp.js";
 import { runDoctorCommand } from "./commands/doctor.js";
 import { runExplainCommand } from "./commands/explain.js";
 import { runFixCommand } from "./commands/fix.js";
@@ -153,6 +154,18 @@ export function createProgram() {
         const code = await runDoctorCommand();
         process.exitCode = code;
     });
+    program
+        .command("brain-mcp")
+        .description("Start the local Project Brain MCP server over STDIO (evidence-backed agent context; no API key)")
+        .requiredOption("--root <path>", "Absolute or relative project root (required; never uses process.cwd() implicitly)")
+        .option("--no-build-if-missing", "Fail when no snapshot exists instead of compiling Project Brain")
+        .action(async (options) => {
+        const code = await runBrainMcpCommand({
+            root: options.root,
+            buildIfMissing: options.buildIfMissing !== false,
+        });
+        process.exitCode = code;
+    });
     program.configureOutput({
         outputError: (str, write) => write(str),
     });

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const PACKAGE_VERSION = "1.0.0";
+export declare const PACKAGE_VERSION = "1.1.1";
 export declare const DEFAULT_MAX_FILE_SIZE_BYTES: number;
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export declare const DEFAULT_IGNORE_DIRECTORIES: Set<string>;

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "1.0.0";
+export const PACKAGE_VERSION = "1.1.1";
 export const DEFAULT_MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024; // 2 MiB
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export const DEFAULT_IGNORE_DIRECTORIES = new Set([

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[];