@praneeth_54/agentdoctor 0.3.0-beta → 1.1.0

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

@@ -0,0 +1,4 @@
+export { discoverRelationships, scoreRelationshipConfidence } from "./discover.js";
+export { classifyComponent, classifyRoleFromPath, extractSemanticSignals, pascalCaseName, } from "./extract.js";
+export { ROLE_PAIR_RULES, findRolePairRule } from "./models.js";
+export type { ClassifiedComponent, ComponentRole, RelationshipDiscoveryOptions, RelationshipDiscoveryResult, RelationshipKind, RelationshipMatch, RelationshipStrength, SemanticSignal, } from "./types.js";

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

@@ -0,0 +1,3 @@
+export { discoverRelationships, scoreRelationshipConfidence } from "./discover.js";
+export { classifyComponent, classifyRoleFromPath, extractSemanticSignals, pascalCaseName, } from "./extract.js";
+export { ROLE_PAIR_RULES, findRolePairRule } from "./models.js";

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

@@ -0,0 +1,21 @@
+import type { ComponentRole, RelationshipKind, RelationshipStrength } from "./types.js";
+export interface RolePairRule {
+    source: ComponentRole;
+    target: ComponentRole;
+    relationship: RelationshipKind;
+    baseConfidence: number;
+    strength: RelationshipStrength;
+}
+/**
+ * Deterministic semantic layer rules. Only applied when both roles are evidenced.
+ */
+export declare const ROLE_PAIR_RULES: readonly RolePairRule[];
+export declare const ROLE_PATH_PATTERNS: ReadonlyArray<{
+    role: ComponentRole;
+    pattern: RegExp;
+}>;
+export declare const STRENGTH_BOOST: Readonly<Record<RelationshipStrength, number>>;
+export declare function clampConfidence(value: number): number;
+export declare function strengthRank(strength: RelationshipStrength): number;
+export declare function maxStrength(a: RelationshipStrength, b: RelationshipStrength): RelationshipStrength;
+export declare function findRolePairRule(source: ComponentRole, target: ComponentRole): RolePairRule | undefined;

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

@@ -0,0 +1,185 @@
+/**
+ * Deterministic semantic layer rules. Only applied when both roles are evidenced.
+ */
+export const ROLE_PAIR_RULES = [
+    {
+        source: "Controller",
+        target: "Service",
+        relationship: "USES",
+        baseConfidence: 0.96,
+        strength: "medium",
+    },
+    {
+        source: "Service",
+        target: "Repository",
+        relationship: "USES",
+        baseConfidence: 0.95,
+        strength: "medium",
+    },
+    {
+        source: "Repository",
+        target: "Database",
+        relationship: "USES",
+        baseConfidence: 0.94,
+        strength: "medium",
+    },
+    {
+        source: "Route",
+        target: "Controller",
+        relationship: "EXPOSES",
+        baseConfidence: 0.93,
+        strength: "medium",
+    },
+    {
+        source: "Widget",
+        target: "Bloc",
+        relationship: "USES",
+        baseConfidence: 0.92,
+        strength: "medium",
+    },
+    {
+        source: "Bloc",
+        target: "Repository",
+        relationship: "USES",
+        baseConfidence: 0.91,
+        strength: "medium",
+    },
+    {
+        source: "API",
+        target: "Service",
+        relationship: "CALLS",
+        baseConfidence: 0.9,
+        strength: "medium",
+    },
+    {
+        source: "Module",
+        target: "Configuration",
+        relationship: "CONFIGURES",
+        baseConfidence: 0.9,
+        strength: "medium",
+    },
+    {
+        source: "Module",
+        target: "Controller",
+        relationship: "PROVIDES",
+        baseConfidence: 0.88,
+        strength: "medium",
+    },
+    {
+        source: "Module",
+        target: "Service",
+        relationship: "PROVIDES",
+        baseConfidence: 0.88,
+        strength: "medium",
+    },
+    {
+        source: "EntryPoint",
+        target: "Feature",
+        relationship: "ENTERS",
+        baseConfidence: 0.9,
+        strength: "medium",
+    },
+    {
+        source: "Package",
+        target: "Module",
+        relationship: "CONTAINS",
+        baseConfidence: 0.9,
+        strength: "strong",
+    },
+    {
+        source: "Package",
+        target: "Feature",
+        relationship: "OWNS",
+        baseConfidence: 0.88,
+        strength: "strong",
+    },
+    {
+        source: "Feature",
+        target: "Domain",
+        relationship: "PROVIDES",
+        baseConfidence: 0.85,
+        strength: "medium",
+    },
+    {
+        source: "Feature",
+        target: "Controller",
+        relationship: "CONTAINS",
+        baseConfidence: 0.86,
+        strength: "strong",
+    },
+    {
+        source: "Feature",
+        target: "Service",
+        relationship: "CONTAINS",
+        baseConfidence: 0.86,
+        strength: "strong",
+    },
+    {
+        source: "Service",
+        target: "Service",
+        relationship: "CALLS",
+        baseConfidence: 0.8,
+        strength: "weak",
+    },
+    {
+        source: "Controller",
+        target: "Repository",
+        relationship: "USES",
+        baseConfidence: 0.84,
+        strength: "weak",
+    },
+];
+export const ROLE_PATH_PATTERNS = [
+    // Filename-specific roles first (win over directory names like apps/api/)
+    { role: "Module", pattern: /\.module\.(t|j)sx?$/i },
+    { role: "Configuration", pattern: /(^|\/|[-_.])config(uration)?([-_.]|$)/i },
+    { role: "Controller", pattern: /(^|\/|[-_.])controllers?([-_.]|$)|controller\.(t|j)sx?$/i },
+    { role: "Service", pattern: /(^|\/|[-_.])services?([-_.]|$)|service\.(t|j)sx?$/i },
+    { role: "Repository", pattern: /(^|\/|[-_.])repositor(y|ies)([-_.]|$)|repository\.(t|j)sx?$/i },
+    {
+        role: "Database",
+        pattern: /(^|\/|[-_.])(entity|entities|schema|models?|prisma|migration)([-_.]|$)/i,
+    },
+    {
+        role: "Route",
+        pattern: /(^|\/)routes?\/|(^|\/|[-_.])router([-_.]|$)|routes?\.(t|j)sx?$|web\.php$/i,
+    },
+    { role: "Widget", pattern: /widget\.(dart|tsx?|jsx?)$|_widget\.dart$/i },
+    { role: "Bloc", pattern: /bloc\.(dart|tsx?)$|cubit\.dart$/i },
+    {
+        role: "EntryPoint",
+        pattern: /(^|\/)main\.(t|j)sx?$|(^|\/)main\.dart$|(^|\/)index\.(t|j)sx?$/i,
+    },
+    // Broad directory heuristics last
+    { role: "API", pattern: /(^|\/)api\/[^/]+$|api\.(t|j)sx?$/i },
+];
+export const STRENGTH_BOOST = {
+    strong: 0.03,
+    medium: 0,
+    weak: -0.05,
+};
+export function clampConfidence(value) {
+    if (value < 0) {
+        return 0;
+    }
+    if (value > 0.99) {
+        return 0.99;
+    }
+    return Math.round(value * 100) / 100;
+}
+export function strengthRank(strength) {
+    switch (strength) {
+        case "strong":
+            return 3;
+        case "medium":
+            return 2;
+        case "weak":
+            return 1;
+    }
+}
+export function maxStrength(a, b) {
+    return strengthRank(a) >= strengthRank(b) ? a : b;
+}
+export function findRolePairRule(source, target) {
+    return ROLE_PAIR_RULES.find((rule) => rule.source === source && rule.target === target);
+}

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

@@ -0,0 +1,42 @@
+import type { DependencyDiscoveryResult } from "../dependencies/types.js";
+import type { EntrypointDiscoveryResult } from "../entrypoints/types.js";
+import type { DomainDiscoveryResult } from "../types/index.js";
+export type RelationshipKind = "USES" | "OWNS" | "IMPLEMENTS" | "DEPENDS_ON" | "CALLS" | "CONFIGURES" | "EXPOSES" | "ENTERS" | "CONTAINS" | "PROVIDES" | "CONSUMES";
+export type RelationshipStrength = "strong" | "medium" | "weak";
+export type ComponentRole = "Controller" | "Service" | "Repository" | "Database" | "Route" | "Widget" | "Bloc" | "API" | "Module" | "Configuration" | "EntryPoint" | "Feature" | "Domain" | "Package" | "Component";
+export interface RelationshipMatch {
+    source: string;
+    target: string;
+    relationship: RelationshipKind;
+    confidence: number;
+    evidence: string[];
+    strength: RelationshipStrength;
+    bidirectional?: boolean;
+}
+export interface RelationshipDiscoveryResult {
+    relationships: RelationshipMatch[];
+    timingMs: number;
+    filesConsidered: number;
+    filesInspected: number;
+}
+export interface RelationshipDiscoveryOptions {
+    cwd?: string;
+    minConfidence?: number;
+    maxReadBytes?: number;
+    /** Injected dependency graph; when omitted, runs discoverDependencies. */
+    dependencies?: DependencyDiscoveryResult;
+    /** Injected entrypoints; when omitted, runs discoverEntrypoints. */
+    entrypoints?: EntrypointDiscoveryResult;
+    /** Injected domains; when omitted, runs discoverDomains. */
+    domains?: DomainDiscoveryResult;
+}
+export interface ClassifiedComponent {
+    name: string;
+    role: ComponentRole;
+    file: string;
+}
+export interface SemanticSignal {
+    kind: "constructor-injection" | "implements" | "extends" | "bloc-provider" | "entity" | "call";
+    label: string;
+    relatedName?: string;
+}

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

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

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

@@ -0,0 +1,8 @@
+import type { ProjectModel } from "../model/types.js";
+import { type OwnershipDiscoveryResult } from "../ownership/index.js";
+import type { RiskDiscoveryOptions, RiskDiscoveryResult } from "./types.js";
+/**
+ * Discover change-danger risks from ProjectModel (+ optional ownership).
+ * Deterministic; evidence-required; never invents vulnerability claims.
+ */
+export declare function discoverRisks(model: ProjectModel, ownership?: OwnershipDiscoveryResult, options?: RiskDiscoveryOptions): RiskDiscoveryResult;

package/dist/core/understanding/risks/discover.js

@@ -0,0 +1,155 @@
+import { ownersForPath } from "../ownership/index.js";
+function clampConfidence(value) {
+    if (value < 0) {
+        return 0;
+    }
+    if (value > 1) {
+        return 1;
+    }
+    return Math.round(value * 100) / 100;
+}
+function countFanIn(model) {
+    const fanIn = new Map();
+    for (const dep of model.dependencies) {
+        const bucket = fanIn.get(dep.to) ?? { count: 0, evidence: [] };
+        bucket.count += 1;
+        bucket.evidence.push(...dep.evidence);
+        fanIn.set(dep.to, bucket);
+    }
+    return fanIn;
+}
+function countCoupling(model) {
+    const coupling = new Map();
+    const bump = (key, evidence) => {
+        const bucket = coupling.get(key) ?? { count: 0, evidence: [] };
+        bucket.count += 1;
+        bucket.evidence.push(...evidence);
+        coupling.set(key, bucket);
+    };
+    for (const rel of model.relationships) {
+        bump(rel.source, rel.evidence);
+        bump(rel.target, rel.evidence);
+    }
+    return coupling;
+}
+/**
+ * Discover change-danger risks from ProjectModel (+ optional ownership).
+ * Deterministic; evidence-required; never invents vulnerability claims.
+ */
+export function discoverRisks(model, ownership, options = {}) {
+    const started = performance.now();
+    const centralityThreshold = options.centralityThreshold ?? 3;
+    const couplingThreshold = options.couplingThreshold ?? 4;
+    const minConfidence = options.minConfidence ?? 0.5;
+    const risks = [];
+    const unknowns = [];
+    for (const entry of model.entrypoints) {
+        risks.push({
+            kind: "critical-entrypoint",
+            target: entry.file,
+            severity: "high",
+            confidence: clampConfidence(Math.min(0.9, 0.55 + entry.confidence * 0.35)),
+            evidence: [...entry.evidence, `entrypoint:${entry.framework}`],
+            rationale: "Entrypoints are high-blast-radius change surfaces",
+        });
+    }
+    const fanIn = countFanIn(model);
+    for (const [target, bucket] of fanIn) {
+        if (bucket.count < centralityThreshold) {
+            continue;
+        }
+        risks.push({
+            kind: "dependency-centrality",
+            target,
+            severity: bucket.count >= centralityThreshold * 2 ? "high" : "medium",
+            confidence: clampConfidence(Math.min(0.92, 0.5 + bucket.count * 0.08)),
+            evidence: [...new Set(bucket.evidence)].sort((a, b) => a.localeCompare(b)).slice(0, 12),
+            rationale: `${bucket.count} inbound dependencies — changes here fan out`,
+        });
+    }
+    const coupling = countCoupling(model);
+    for (const [target, bucket] of coupling) {
+        if (bucket.count < couplingThreshold) {
+            continue;
+        }
+        risks.push({
+            kind: "high-coupling",
+            target,
+            severity: bucket.count >= couplingThreshold * 2 ? "high" : "medium",
+            confidence: clampConfidence(Math.min(0.9, 0.48 + bucket.count * 0.07)),
+            evidence: [...new Set(bucket.evidence)].sort((a, b) => a.localeCompare(b)).slice(0, 12),
+            rationale: `${bucket.count} relationship edges — tightly coupled change surface`,
+        });
+    }
+    for (const arch of model.architectures) {
+        if (arch.conflictingEvidence.length === 0) {
+            continue;
+        }
+        risks.push({
+            kind: "architecture-conflict",
+            target: arch.pattern,
+            severity: "medium",
+            confidence: clampConfidence(Math.min(0.85, 0.4 + arch.conflictingEvidence.length * 0.1)),
+            evidence: [...arch.conflictingEvidence, ...arch.evidence].slice(0, 12),
+            rationale: "Architecture hypothesis has conflicting evidence — change guidance is weaker",
+        });
+    }
+    if (ownership) {
+        const candidates = [
+            ...model.entrypoints.map((e) => e.file),
+            ...model.domains.flatMap((d) => d.paths.slice(0, 3)),
+        ];
+        const seen = new Set();
+        for (const candidate of candidates) {
+            const key = candidate.replace(/\\/g, "/");
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            const owner = ownersForPath(key, ownership.ownerships);
+            if (owner) {
+                continue;
+            }
+            risks.push({
+                kind: "unclear-ownership",
+                target: key,
+                severity: "medium",
+                confidence: 0.7,
+                evidence: [`path:${key}`, "ownership:none"],
+                rationale: "No CODEOWNERS / MAINTAINERS / package maintainers evidence covers this path",
+            });
+        }
+        if (ownership.unknowns.length > 0 && ownership.ownerships.length === 0) {
+            unknowns.push(...ownership.unknowns);
+        }
+    }
+    else {
+        unknowns.push("Ownership input omitted — unclear-ownership risks not evaluated");
+    }
+    if (model.dependencies.length === 0) {
+        unknowns.push("No dependencies modeled — centrality risks unavailable");
+    }
+    const filtered = risks
+        .filter((risk) => risk.confidence >= minConfidence)
+        .sort((a, b) => severityRank(b.severity) - severityRank(a.severity) ||
+        b.confidence - a.confidence ||
+        a.kind.localeCompare(b.kind) ||
+        a.target.localeCompare(b.target));
+    return {
+        risks: filtered,
+        timingMs: Math.max(0, Math.round(performance.now() - started)),
+        unknowns: [...new Set(unknowns)].sort((a, b) => a.localeCompare(b)),
+    };
+}
+function severityRank(severity) {
+    switch (severity) {
+        case "high":
+            return 3;
+        case "medium":
+            return 2;
+        case "low":
+            return 1;
+        default:
+            return 0;
+    }
+}

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

@@ -0,0 +1,2 @@
+export { discoverRisks } from "./discover.js";
+export type { RiskDiscoveryOptions, RiskDiscoveryResult, RiskKind, RiskMatch, RiskSeverity, } from "./types.js";

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

@@ -0,0 +1 @@
+export { discoverRisks } from "./discover.js";

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

@@ -0,0 +1,26 @@
+export type RiskKind = "critical-entrypoint" | "dependency-centrality" | "unclear-ownership" | "architecture-conflict" | "high-coupling";
+export type RiskSeverity = "high" | "medium" | "low";
+/**
+ * Change-danger risk: how dangerous is modifying this part of the software?
+ * Not generic SAST.
+ */
+export interface RiskMatch {
+    kind: RiskKind;
+    target: string;
+    severity: RiskSeverity;
+    confidence: number;
+    evidence: readonly string[];
+    rationale: string;
+}
+export interface RiskDiscoveryResult {
+    risks: RiskMatch[];
+    timingMs: number;
+    unknowns: string[];
+}
+export interface RiskDiscoveryOptions {
+    /** Minimum fan-in for dependency-centrality. Default 3. */
+    centralityThreshold?: number;
+    /** Minimum relationship edges for high-coupling. Default 4. */
+    couplingThreshold?: number;
+    minConfidence?: number;
+}

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

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

package/dist/core/understanding/shared/domain-lexicon.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Deterministic synonym → canonical domain label map.
+ * First matching synonym wins for a token; evidence aggregates per canonical name.
+ */
+export declare const DOMAIN_LEXICON: ReadonlyArray<{
+    name: string;
+    synonyms: readonly string[];
+}>;
+export declare function domainForToken(token: string): string | undefined;

package/dist/core/understanding/shared/domain-lexicon.js

@@ -0,0 +1,107 @@
+/**
+ * Deterministic synonym → canonical domain label map.
+ * First matching synonym wins for a token; evidence aggregates per canonical name.
+ */
+export const DOMAIN_LEXICON = [
+    {
+        name: "Payments",
+        synonyms: [
+            "payment",
+            "payments",
+            "billing",
+            "invoice",
+            "invoices",
+            "checkout",
+            "stripe",
+            "paypal",
+            "refund",
+            "refunds",
+            "subscription",
+            "subscriptions",
+            "charge",
+            "charges",
+        ],
+    },
+    {
+        name: "Auth",
+        synonyms: [
+            "auth",
+            "authentication",
+            "authorization",
+            "login",
+            "logout",
+            "oauth",
+            "oidc",
+            "sso",
+            "session",
+            "sessions",
+            "password",
+            "passwords",
+            "jwt",
+            "rbac",
+        ],
+    },
+    {
+        name: "Users",
+        synonyms: [
+            "user",
+            "users",
+            "account",
+            "accounts",
+            "profile",
+            "profiles",
+            "identity",
+            "identities",
+        ],
+    },
+    {
+        name: "Orders",
+        synonyms: ["order", "orders", "cart", "carts", "checkoutcart", "fulfillment"],
+    },
+    {
+        name: "Notifications",
+        synonyms: [
+            "notification",
+            "notifications",
+            "notify",
+            "email",
+            "emails",
+            "mailer",
+            "sms",
+            "push",
+            "webhook",
+            "webhooks",
+        ],
+    },
+    {
+        name: "Inventory",
+        synonyms: ["inventory", "stock", "sku", "skus", "warehouse", "catalog", "catalogue"],
+    },
+    {
+        name: "Shipping",
+        synonyms: ["shipping", "shipment", "shipments", "delivery", "logistics", "carrier"],
+    },
+    {
+        name: "Admin",
+        synonyms: ["admin", "admins", "backoffice", "dashboard"],
+    },
+    {
+        name: "Analytics",
+        synonyms: ["analytics", "metrics", "telemetry", "tracking", "reporting", "reports"],
+    },
+    {
+        name: "Search",
+        synonyms: ["search", "elasticsearch", "opensearch", "solr", "indexer", "indexing"],
+    },
+];
+const TOKEN_TO_DOMAIN = new Map();
+for (const entry of DOMAIN_LEXICON) {
+    for (const synonym of entry.synonyms) {
+        if (!TOKEN_TO_DOMAIN.has(synonym)) {
+            TOKEN_TO_DOMAIN.set(synonym, entry.name);
+        }
+    }
+}
+export function domainForToken(token) {
+    return TOKEN_TO_DOMAIN.get(token);
+}

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

@@ -0,0 +1,2 @@
+export { tokenizeRelativePath, DOMAIN_STOP_SEGMENTS } from "./tokens.js";
+export { DOMAIN_LEXICON, domainForToken } from "./domain-lexicon.js";

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

@@ -0,0 +1,2 @@
+export { tokenizeRelativePath, DOMAIN_STOP_SEGMENTS } from "./tokens.js";
+export { DOMAIN_LEXICON, domainForToken } from "./domain-lexicon.js";

package/dist/core/understanding/shared/tokens.d.ts

@@ -0,0 +1,7 @@
+/** Path / name segments ignored when mining domain tokens. */
+export declare const DOMAIN_STOP_SEGMENTS: Set<string>;
+/**
+ * Split a relative path into lowercase semantic tokens.
+ * Deterministic: camelCase, snake_case, kebab-case, path segments.
+ */
+export declare function tokenizeRelativePath(relativePath: string): string[];