@praneeth_54/agentdoctor 1.1.1 → 2.0.1

package/dist/mcp/intelligence/registry.js

@@ -0,0 +1,228 @@
+import { handleArchitectureCheckTool, handleArchitectureTool, handleCallGraphLookup, handleChangeAnalyzeTool, handleCodeHealthTool, handleCodebaseSearch, handleDependencyLookup, handleEvidenceInspectTool, handleGraphQueryTool, handleKnowledgeTool, handlePolicyEvalTool, handleProofInspectTool, handleRefactorImpactTool, handleRepoOverview, handleSymbolLookup, handleTestImpactTool, } from "./handlers.js";
+export const INTELLIGENCE_MCP_TOOL_NAMES = [
+    "repo_overview",
+    "codebase_search",
+    "symbol_lookup",
+    "dependency_lookup",
+    "call_graph_lookup",
+    "test_impact",
+    "refactor_impact",
+    "code_health",
+    "architecture_info",
+    "architecture_check",
+    "knowledge_retrieve",
+    "policy_evaluate",
+    "change_analyze",
+    "proof_inspect",
+    "evidence_inspect",
+    "graph_query",
+];
+const emptyObjectSchema = {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+};
+export function listIntelligenceMcpTools() {
+    return [
+        {
+            name: "repo_overview",
+            description: "READ: Repository intelligence overview (graph builder, node/edge counts, limitations). No shell execution.",
+            inputSchema: emptyObjectSchema,
+        },
+        {
+            name: "codebase_search",
+            description: "READ: Search graph nodes by label/path substring. Bounded to 50 hits.",
+            inputSchema: {
+                type: "object",
+                properties: { query: { type: "string" } },
+                required: ["query"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "symbol_lookup",
+            description: "READ: Lookup symbols/functions/classes/interfaces by name.",
+            inputSchema: {
+                type: "object",
+                properties: { name: { type: "string" } },
+                required: ["name"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "dependency_lookup",
+            description: "READ: Edges connected to a graph node (id/path/label).",
+            inputSchema: {
+                type: "object",
+                properties: { target: { type: "string" } },
+                required: ["target"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "call_graph_lookup",
+            description: "READ: Call edges involving a symbol (best-effort; AST when available).",
+            inputSchema: {
+                type: "object",
+                properties: { symbol: { type: "string" } },
+                required: ["symbol"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "test_impact",
+            description: "READ: Test-impact analysis for current git changes. Coverage-backed mapping not bundled.",
+            inputSchema: emptyObjectSchema,
+        },
+        {
+            name: "refactor_impact",
+            description: "READ: Rename/refactor blast radius for a symbol.",
+            inputSchema: {
+                type: "object",
+                properties: { symbol: { type: "string" } },
+                required: ["symbol"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "code_health",
+            description: "READ: Git hotspot / engineering intelligence with method disclosure.",
+            inputSchema: emptyObjectSchema,
+        },
+        {
+            name: "architecture_info",
+            description: "READ: C4-style views inferred from graph evidence (labeled proposed/inferred).",
+            inputSchema: emptyObjectSchema,
+        },
+        {
+            name: "architecture_check",
+            description: "READ: Check import edges against .agentdoctor/architecture.json|.yml contract (repo-local).",
+            inputSchema: emptyObjectSchema,
+        },
+        {
+            name: "knowledge_retrieve",
+            description: "READ: Governed knowledge retrieval. Abstains when no approved authoritative record matches.",
+            inputSchema: {
+                type: "object",
+                properties: { query: { type: "string" } },
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "policy_evaluate",
+            description: "READ: Evaluate a shell command against local policy. Never executes. Always executionResult=not-executed.",
+            inputSchema: {
+                type: "object",
+                properties: { command: { type: "string" } },
+                required: ["command"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "change_analyze",
+            description: "READ: Change assurance assessment (evidence/heuristics). Never claims verified engineering correctness.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    since: { type: "string" },
+                    changeId: { type: "string" },
+                    coveragePath: { type: "string", description: "Repo-relative coverage file path" },
+                },
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "proof_inspect",
+            description: "READ: Inspect ChangeProof by proofId or changeId (hash integrity metadata only).",
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string" } },
+                required: ["id"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "evidence_inspect",
+            description: "READ: Inspect change evidence bundle artifacts for a changeId.",
+            inputSchema: {
+                type: "object",
+                properties: { changeId: { type: "string" } },
+                required: ["changeId"],
+                additionalProperties: false,
+            },
+        },
+        {
+            name: "graph_query",
+            description: "READ: Substring query over intelligence graph nodes/edges. Optional kind/path filters; path validated.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string" },
+                    kind: { type: "string" },
+                    path: { type: "string" },
+                    limit: { type: "number" },
+                },
+                required: ["query"],
+                additionalProperties: false,
+            },
+        },
+    ];
+}
+export async function invokeIntelligenceMcpTool(root, name, args) {
+    try {
+        switch (name) {
+            case "repo_overview":
+                return { structured: await handleRepoOverview(root), isError: false };
+            case "codebase_search":
+                return { structured: await handleCodebaseSearch(root, args), isError: false };
+            case "symbol_lookup":
+                return { structured: await handleSymbolLookup(root, args), isError: false };
+            case "dependency_lookup":
+                return { structured: await handleDependencyLookup(root, args), isError: false };
+            case "call_graph_lookup":
+                return { structured: await handleCallGraphLookup(root, args), isError: false };
+            case "test_impact":
+                return { structured: await handleTestImpactTool(root), isError: false };
+            case "refactor_impact":
+                return { structured: await handleRefactorImpactTool(root, args), isError: false };
+            case "code_health":
+                return { structured: await handleCodeHealthTool(root), isError: false };
+            case "architecture_info":
+                return { structured: await handleArchitectureTool(root), isError: false };
+            case "architecture_check":
+                return { structured: await handleArchitectureCheckTool(root), isError: false };
+            case "knowledge_retrieve":
+                return { structured: await handleKnowledgeTool(root, args), isError: false };
+            case "policy_evaluate":
+                return { structured: await handlePolicyEvalTool(root, args), isError: false };
+            case "change_analyze":
+                return { structured: await handleChangeAnalyzeTool(root, args), isError: false };
+            case "proof_inspect":
+                return { structured: await handleProofInspectTool(root, args), isError: false };
+            case "evidence_inspect":
+                return { structured: await handleEvidenceInspectTool(root, args), isError: false };
+            case "graph_query":
+                return { structured: await handleGraphQueryTool(root, args), isError: false };
+            default:
+                return {
+                    structured: {
+                        ok: false,
+                        error: { code: "invalid_argument", message: `unknown intelligence tool: ${name}` },
+                    },
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        return {
+            structured: {
+                ok: false,
+                error: {
+                    code: "internal",
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            },
+            isError: true,
+        };
+    }
+}

package/dist/ops/health.d.ts

@@ -0,0 +1,18 @@
+import { DEFAULT_FEATURE_FLAGS } from "../contracts/index.js";
+export interface OpsHealthReport {
+    ok: boolean;
+    version: string;
+    contractsVersion: string;
+    root: string;
+    featureFlags: typeof DEFAULT_FEATURE_FLAGS;
+    checks: Array<{
+        id: string;
+        ok: boolean;
+        detail: string;
+    }>;
+    timestamp: string;
+}
+/**
+ * Local ops health probe — no network calls, no agent interception.
+ */
+export declare function collectOpsHealth(rootInput?: string): Promise<OpsHealthReport>;

package/dist/ops/health.js

@@ -0,0 +1,51 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { PACKAGE_VERSION } from "../constants.js";
+import { CONTRACTS_VERSION, DEFAULT_FEATURE_FLAGS } from "../contracts/index.js";
+import { resolveRepoRoot } from "../utils/path.js";
+/**
+ * Local ops health probe — no network calls, no agent interception.
+ */
+export async function collectOpsHealth(rootInput) {
+    const root = resolveRepoRoot(rootInput ?? process.cwd());
+    const checks = [];
+    try {
+        await fs.access(root);
+        checks.push({ id: "root-readable", ok: true, detail: root });
+    }
+    catch {
+        checks.push({ id: "root-readable", ok: false, detail: "cannot access root" });
+    }
+    const agentdoctorDir = path.join(root, ".agentdoctor");
+    try {
+        await fs.access(agentdoctorDir);
+        checks.push({ id: "agentdoctor-dir", ok: true, detail: ".agentdoctor present" });
+    }
+    catch {
+        checks.push({
+            id: "agentdoctor-dir",
+            ok: true,
+            detail: ".agentdoctor absent (created on first scan/init)",
+        });
+    }
+    checks.push({
+        id: "evaluate-only-firewall",
+        ok: true,
+        detail: "Action Policy Evaluator remains evaluate-only by default",
+    });
+    checks.push({
+        id: "local-dev-auth",
+        ok: true,
+        detail: "Team auth is local-dev only unless external IdP is configured (not bundled)",
+    });
+    const ok = checks.every((c) => c.ok);
+    return {
+        ok,
+        version: PACKAGE_VERSION,
+        contractsVersion: CONTRACTS_VERSION,
+        root,
+        featureFlags: DEFAULT_FEATURE_FLAGS,
+        checks,
+        timestamp: new Date().toISOString(),
+    };
+}

package/dist/platform/ai-quality/analyze.d.ts

@@ -0,0 +1,9 @@
+import type { PlatformFinding } from "../types.js";
+/**
+ * Module M — AI code quality analysis over git diff (when available).
+ * AI attribution is unknown unless provided.
+ */
+export declare function analyzeAiChangeQuality(options: {
+    root: string;
+    aiAssisted?: boolean | "unknown";
+}): Promise<PlatformFinding[]>;

package/dist/platform/ai-quality/analyze.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { resolveRepoRoot } from "../../utils/path.js";
+/**
+ * Module M — AI code quality analysis over git diff (when available).
+ * AI attribution is unknown unless provided.
+ */
+export async function analyzeAiChangeQuality(options) {
+    const root = resolveRepoRoot(options.root);
+    const attribution = options.aiAssisted === true ? "ai-assisted" : "unknown";
+    const findings = [];
+    const diff = spawnSync("git", ["diff", "--unified=0"], {
+        cwd: root,
+        encoding: "utf8",
+        maxBuffer: 4 * 1024 * 1024,
+    });
+    if (diff.status !== 0) {
+        return [
+            {
+                id: "aiq_no_diff",
+                module: "ai-quality",
+                severity: "info",
+                title: "No git diff available",
+                message: "Cannot analyze working-tree changes",
+                recommendation: "Run inside a git repo with local changes",
+                confidence: 1,
+                evidence: [{ kind: "unknown", detail: "git diff unavailable" }],
+            },
+        ];
+    }
+    const text = diff.stdout ?? "";
+    const added = text
+        .split(/\r?\n/)
+        .filter((l) => l.startsWith("+") && !l.startsWith("+++"))
+        .map((l) => l.slice(1));
+    const checks = [
+        { re: /eval\s*\(/, title: "Added eval()", severity: "critical" },
+        { re: /innerHTML\s*=/, title: "Added innerHTML assignment", severity: "high" },
+        {
+            re: /password\s*=\s*['"][^'"]+['"]/i,
+            title: "Hardcoded password-like literal",
+            severity: "critical",
+        },
+        { re: /TODO|FIXME/, title: "Added TODO/FIXME in change", severity: "low" },
+        { re: /catch\s*\([^)]*\)\s*\{\s*\}/, title: "Added empty catch", severity: "medium" },
+    ];
+    for (const [i, line] of added.entries()) {
+        for (const check of checks) {
+            if (!check.re.test(line))
+                continue;
+            findings.push({
+                id: `aiq_${createHash("sha1").update(`${check.title}:${i}:${line}`).digest("hex").slice(0, 12)}`,
+                module: "ai-quality",
+                severity: check.severity,
+                title: check.title,
+                message: `In working-tree addition (attribution=${attribution}): ${line.slice(0, 120)}`,
+                recommendation: "Review before commit; add tests for behavioral changes",
+                confidence: 0.6,
+                evidence: [{ kind: "inferred", detail: line.slice(0, 160) }],
+                falsePositiveWarning: "Diff-line heuristic only",
+            });
+        }
+    }
+    return findings.sort((a, b) => a.id.localeCompare(b.id));
+}

package/dist/platform/architecture/drift.d.ts

@@ -0,0 +1,17 @@
+import type { PlatformFinding, RepositoryGraph } from "../types.js";
+export interface ArchitectureRule {
+    id: string;
+    description: string;
+    forbidImportFrom?: string;
+    forbidImportTo?: string;
+    severity: PlatformFinding["severity"];
+}
+export interface ArchitecturePolicy {
+    version: "2.0";
+    rules: ArchitectureRule[];
+}
+export declare function loadArchitecturePolicy(root: string): Promise<ArchitecturePolicy>;
+/**
+ * Module I — Architecture drift detection.
+ */
+export declare function analyzeArchitectureDrift(rootInput: string, graph: RepositoryGraph): Promise<PlatformFinding[]>;

package/dist/platform/architecture/drift.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { writeJsonArtifact, platformDir } from "../store.js";
+const DEFAULT_POLICY = {
+    version: "2.0",
+    rules: [
+        {
+            id: "no-src-to-dist",
+            description: "Source should not import built dist artifacts",
+            forbidImportFrom: "src/",
+            forbidImportTo: "dist/",
+            severity: "high",
+        },
+        {
+            id: "tests-not-imported-by-src",
+            description: "Production source should not import test files",
+            forbidImportFrom: "src/",
+            forbidImportTo: ".test.",
+            severity: "medium",
+        },
+    ],
+};
+export async function loadArchitecturePolicy(root) {
+    const file = path.join(platformDir(root), "architecture-policy.json");
+    try {
+        const raw = await fs.readFile(file, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.version === "2.0")
+            return parsed;
+    }
+    catch {
+        // default
+    }
+    await writeJsonArtifact(resolveRepoRoot(root), "architecture-policy.json", DEFAULT_POLICY);
+    return DEFAULT_POLICY;
+}
+/**
+ * Module I — Architecture drift detection.
+ */
+export async function analyzeArchitectureDrift(rootInput, graph) {
+    const root = resolveRepoRoot(rootInput);
+    const policy = await loadArchitecturePolicy(root);
+    const findings = [];
+    for (const edge of graph.edges.filter((e) => e.kind === "imports")) {
+        const fromNode = graph.nodes.find((n) => n.id === edge.from);
+        const toLabel = graph.nodes.find((n) => n.id === edge.to)?.label ?? edge.to;
+        const fromPath = fromNode?.path ?? "";
+        for (const rule of policy.rules) {
+            const fromHit = rule.forbidImportFrom ? fromPath.includes(rule.forbidImportFrom) : true;
+            const toHit = rule.forbidImportTo ? toLabel.includes(rule.forbidImportTo) : true;
+            if (fromHit && toHit && rule.forbidImportFrom && rule.forbidImportTo) {
+                findings.push({
+                    id: `arch_${createHash("sha1").update(`${rule.id}:${edge.id}`).digest("hex").slice(0, 12)}`,
+                    module: "architecture-drift",
+                    severity: rule.severity,
+                    title: `Architecture rule violated: ${rule.id}`,
+                    message: `${fromPath} imports ${toLabel}`,
+                    recommendation: rule.description,
+                    confidence: edge.evidence === "verified" ? 0.7 : 0.4,
+                    evidence: [
+                        {
+                            kind: edge.evidence,
+                            path: fromPath,
+                            detail: `edge=${edge.kind} rule=${rule.id}`,
+                        },
+                    ],
+                });
+            }
+        }
+    }
+    return findings.sort((a, b) => a.id.localeCompare(b.id));
+}

package/dist/platform/auth/local.d.ts

@@ -0,0 +1,15 @@
+import type { LocalRole } from "../types.js";
+export interface LocalAuthConfig {
+    /** Local-only roles map. Not a cloud IdP. */
+    users: Array<{
+        id: string;
+        role: LocalRole;
+    }>;
+    defaultRole: LocalRole;
+}
+export declare function loadLocalAuthConfig(root: string): Promise<LocalAuthConfig>;
+export declare function resolveRole(config: LocalAuthConfig, userId?: string): LocalRole;
+export declare function roleAtLeast(role: LocalRole, required: LocalRole): boolean;
+/** Permission matrix for local dashboard/API (no network auth; spoofable via local config). */
+export declare function canAccess(role: LocalRole, resource: "read-findings" | "manage-policies" | "approve-actions" | "read-audit" | "export-reports" | "admin-settings"): boolean;
+export declare function ensureAuthConfig(root: string): Promise<string>;

package/dist/platform/auth/local.js

@@ -0,0 +1,58 @@
+import path from "node:path";
+import { platformDir, readJsonIfExists, writeJsonArtifact } from "../store.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+const DEFAULT_CONFIG = {
+    defaultRole: "readonly",
+    users: [
+        { id: "local-admin", role: "admin" },
+        { id: "local-developer", role: "developer" },
+        { id: "local-reviewer", role: "reviewer" },
+        { id: "local-auditor", role: "auditor" },
+    ],
+};
+const ROLE_RANK = {
+    readonly: 0,
+    auditor: 1,
+    developer: 2,
+    reviewer: 3,
+    admin: 4,
+};
+export async function loadLocalAuthConfig(root) {
+    const file = path.join(platformDir(root), "auth.json");
+    const existing = await readJsonIfExists(file);
+    if (existing?.users && existing.defaultRole)
+        return existing;
+    await writeJsonArtifact(resolveRepoRoot(root), "auth.json", DEFAULT_CONFIG);
+    return DEFAULT_CONFIG;
+}
+export function resolveRole(config, userId) {
+    if (!userId)
+        return config.defaultRole;
+    return config.users.find((u) => u.id === userId)?.role ?? config.defaultRole;
+}
+export function roleAtLeast(role, required) {
+    return (ROLE_RANK[role] ?? 0) >= (ROLE_RANK[required] ?? 0);
+}
+/** Permission matrix for local dashboard/API (no network auth; spoofable via local config). */
+export function canAccess(role, resource) {
+    switch (resource) {
+        case "read-findings":
+            return roleAtLeast(role, "readonly");
+        case "read-audit":
+            return roleAtLeast(role, "auditor");
+        case "export-reports":
+            return roleAtLeast(role, "developer");
+        case "approve-actions":
+            return roleAtLeast(role, "reviewer");
+        case "manage-policies":
+            return roleAtLeast(role, "admin");
+        case "admin-settings":
+            return role === "admin";
+        default:
+            return false;
+    }
+}
+export async function ensureAuthConfig(root) {
+    await loadLocalAuthConfig(root);
+    return path.join(platformDir(root), "auth.json");
+}

package/dist/platform/context-security/analyze.d.ts

@@ -0,0 +1,6 @@
+import type { PlatformFinding } from "../types.js";
+/**
+ * Module F — Context security / poisoning detection (pluggable pattern set).
+ * Does not claim perfect detection. Evidence snippets are secret-redacted.
+ */
+export declare function analyzeContextSecurity(rootInput: string): Promise<PlatformFinding[]>;

package/dist/platform/context-security/analyze.js

@@ -0,0 +1,97 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { resolveRepoRoot, toPosixRelative } from "../../utils/path.js";
+import { redactEvidenceDetail } from "../security/redact.js";
+const INJECTION_PATTERNS = [
+    {
+        id: "ignore-previous",
+        re: /ignore (all )?(previous|prior|above) (instructions|rules|policies)/i,
+        severity: "critical",
+        title: "Prompt-injection: ignore previous instructions",
+    },
+    {
+        id: "exfiltrate",
+        re: /exfiltrat|send (all )?(secrets|credentials|api keys) to/i,
+        severity: "critical",
+        title: "Suspected exfiltration instruction",
+    },
+    {
+        id: "bypass-policy",
+        re: /bypass (the )?(firewall|policy|approval|security|action policy)/i,
+        severity: "high",
+        title: "Policy-bypass instruction",
+    },
+    {
+        id: "hidden-html",
+        re: /<!--\s*(system|assistant|secret instruction)/i,
+        severity: "high",
+        title: "Hidden HTML instruction comment",
+    },
+    {
+        id: "social-eng",
+        re: /do not tell (the )?user|hide this from (the )?developer/i,
+        severity: "high",
+        title: "Social-engineering pattern",
+    },
+    {
+        id: "obfuscated-b64",
+        re: /eval\s*\(\s*atob\s*\(|Buffer\.from\([^,]+,\s*['"]base64['"]/i,
+        severity: "medium",
+        title: "Obfuscated execution pattern",
+    },
+];
+/**
+ * Module F — Context security / poisoning detection (pluggable pattern set).
+ * Does not claim perfect detection. Evidence snippets are secret-redacted.
+ */
+export async function analyzeContextSecurity(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const findings = [];
+    const candidates = [
+        "AGENTS.md",
+        "CLAUDE.md",
+        "GEMINI.md",
+        "CONVENTIONS.md",
+        "README.md",
+        ".cursorrules",
+        ".github/copilot-instructions.md",
+    ];
+    for (const rel of candidates) {
+        const absolute = path.join(root, rel);
+        let text;
+        try {
+            text = await fs.readFile(absolute, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const lines = text.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? "";
+            for (const pattern of INJECTION_PATTERNS) {
+                if (!pattern.re.test(line))
+                    continue;
+                findings.push({
+                    id: `ctxsec_${createHash("sha1").update(`${rel}:${i}:${pattern.id}`).digest("hex").slice(0, 12)}`,
+                    module: "context-security",
+                    severity: pattern.severity,
+                    title: pattern.title,
+                    message: `Pattern ${pattern.id} in ${rel}:${i + 1}`,
+                    recommendation: "Review and remove untrusted instructions; tighten agent policies",
+                    confidence: 0.65,
+                    evidence: [
+                        {
+                            kind: "inferred",
+                            path: toPosixRelative(root, absolute),
+                            line: i + 1,
+                            detail: redactEvidenceDetail(line.slice(0, 200)),
+                        },
+                    ],
+                    falsePositiveWarning: "Pattern match only — confirm intent before treating as an attack",
+                });
+            }
+        }
+    }
+    return findings.sort((a, b) => a.id.localeCompare(b.id));
+}