@praneeth_54/agentdoctor 0.3.0-beta → 1.1.0

package/dist/core/understanding/query/query.js

@@ -0,0 +1,145 @@
+import { QueryValidationError } from "./errors.js";
+function requireNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new QueryValidationError(`${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function optionalString(value, field) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return requireNonEmptyString(value, field);
+}
+/**
+ * Validate and normalize a raw query object into a typed Query.
+ */
+export function validateQuery(input) {
+    if (!input || typeof input !== "object") {
+        throw new QueryValidationError("query must be an object");
+    }
+    const record = input;
+    if (typeof record.type !== "string") {
+        throw new QueryValidationError("query.type is required");
+    }
+    switch (record.type) {
+        case "RepositorySummary":
+            return { type: "RepositorySummary" };
+        case "ListDomains":
+            return { type: "ListDomains" };
+        case "ListEntrypoints":
+            return { type: "ListEntrypoints" };
+        case "ListArchitectures":
+            return { type: "ListArchitectures" };
+        case "ListRelationships":
+            return { type: "ListRelationships" };
+        case "ListDependencies":
+            return { type: "ListDependencies" };
+        case "Statistics":
+            return { type: "Statistics" };
+        case "FindDomain":
+            return { type: "FindDomain", name: requireNonEmptyString(record.name, "name") };
+        case "FindEntrypoint": {
+            const file = optionalString(record.file, "file");
+            const framework = optionalString(record.framework, "framework");
+            const id = optionalString(record.id, "id");
+            if (!file && !framework && !id) {
+                throw new QueryValidationError("FindEntrypoint requires file, framework, or id");
+            }
+            const query = { type: "FindEntrypoint" };
+            if (file !== undefined) {
+                query.file = file;
+            }
+            if (framework !== undefined) {
+                query.framework = framework;
+            }
+            if (id !== undefined) {
+                query.id = id;
+            }
+            return query;
+        }
+        case "FindArchitecture":
+            return {
+                type: "FindArchitecture",
+                pattern: requireNonEmptyString(record.pattern, "pattern"),
+            };
+        case "FindComponent":
+            return { type: "FindComponent", name: requireNonEmptyString(record.name, "name") };
+        case "FindRelationship": {
+            const source = optionalString(record.source, "source");
+            const target = optionalString(record.target, "target");
+            const relationship = optionalString(record.relationship, "relationship");
+            const id = optionalString(record.id, "id");
+            if (!source && !target && !relationship && !id) {
+                throw new QueryValidationError("FindRelationship requires source, target, relationship, or id");
+            }
+            const query = { type: "FindRelationship" };
+            if (source !== undefined) {
+                query.source = source;
+            }
+            if (target !== undefined) {
+                query.target = target;
+            }
+            if (relationship !== undefined) {
+                query.relationship = relationship;
+            }
+            if (id !== undefined) {
+                query.id = id;
+            }
+            return query;
+        }
+        case "FindDependency": {
+            const from = optionalString(record.from, "from");
+            const to = optionalString(record.to, "to");
+            const dependencyType = optionalString(record.dependencyType, "dependencyType");
+            const id = optionalString(record.id, "id");
+            if (!from && !to && !dependencyType && !id) {
+                throw new QueryValidationError("FindDependency requires from, to, dependencyType, or id");
+            }
+            const query = { type: "FindDependency" };
+            if (from !== undefined) {
+                query.from = from;
+            }
+            if (to !== undefined) {
+                query.to = to;
+            }
+            if (dependencyType !== undefined) {
+                query.dependencyType = dependencyType;
+            }
+            if (id !== undefined) {
+                query.id = id;
+            }
+            return query;
+        }
+        case "FindEvidence":
+            return { type: "FindEvidence", needle: requireNonEmptyString(record.needle, "needle") };
+        default:
+            throw new QueryValidationError(`unsupported query type: ${String(record.type)}`);
+    }
+}
+function pickDefined(base, fields) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** Typed query constructors (internal ergonomics). */
+export const Queries = {
+    repositorySummary: () => ({ type: "RepositorySummary" }),
+    listDomains: () => ({ type: "ListDomains" }),
+    listEntrypoints: () => ({ type: "ListEntrypoints" }),
+    listArchitectures: () => ({ type: "ListArchitectures" }),
+    listRelationships: () => ({ type: "ListRelationships" }),
+    listDependencies: () => ({ type: "ListDependencies" }),
+    findDomain: (name) => ({ type: "FindDomain", name }),
+    findEntrypoint: (options) => pickDefined({ type: "FindEntrypoint" }, options),
+    findArchitecture: (pattern) => ({ type: "FindArchitecture", pattern }),
+    findComponent: (name) => ({ type: "FindComponent", name }),
+    findRelationship: (options) => pickDefined({ type: "FindRelationship" }, options),
+    findDependency: (options) => pickDefined({ type: "FindDependency" }, options),
+    findEvidence: (needle) => ({ type: "FindEvidence", needle }),
+    statistics: () => ({ type: "Statistics" }),
+};

package/dist/core/understanding/query/registry.d.ts

@@ -0,0 +1,8 @@
+import type { QueryHandlerContext, QueryHandlerOutput, QueryResultMap } from "./models.js";
+import type { Query, QueryType } from "./types.js";
+type Handler<T extends QueryType> = (query: Extract<Query, {
+    type: T;
+}>, ctx: QueryHandlerContext) => QueryHandlerOutput<QueryResultMap[T]>;
+export declare function getQueryHandler<T extends QueryType>(type: T): Handler<T>;
+export declare function listSupportedQueryTypes(): QueryType[];
+export {};

package/dist/core/understanding/query/registry.js

@@ -0,0 +1,340 @@
+import { QueryNotFoundError } from "./errors.js";
+function average(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sum = values.reduce((acc, value) => acc + value, 0);
+    return Math.round((sum / values.length) * 100) / 100;
+}
+function includesIgnoreCase(haystack, needle) {
+    return haystack.toLowerCase().includes(needle.toLowerCase());
+}
+function equalsIgnoreCase(left, right) {
+    return left.toLowerCase() === right.toLowerCase();
+}
+function domainRelatedPaths(domain) {
+    return [...domain.paths, ...domain.evidence];
+}
+function entrypointsForDomain(model, domain) {
+    const paths = domainRelatedPaths(domain);
+    return model.entrypoints.filter((entry) => paths.some((path) => includesIgnoreCase(path, entry.file) || includesIgnoreCase(entry.file, path)));
+}
+function relationshipsForDomain(model, domain) {
+    return model.relationships.filter((rel) => equalsIgnoreCase(rel.source, domain.name) ||
+        equalsIgnoreCase(rel.target, domain.name) ||
+        rel.evidence.some((e) => includesIgnoreCase(e, domain.name)) ||
+        domainRelatedPaths(domain).some((path) => includesIgnoreCase(rel.source, path) ||
+            includesIgnoreCase(rel.target, path) ||
+            rel.evidence.some((e) => includesIgnoreCase(e, path))));
+}
+function dependenciesForDomain(model, domain) {
+    return model.dependencies.filter((dep) => equalsIgnoreCase(dep.from, domain.name) ||
+        equalsIgnoreCase(dep.to, domain.name) ||
+        dep.evidence.some((e) => includesIgnoreCase(e, domain.name)));
+}
+function architecturesForDomain(model, domain) {
+    const related = model.architectures.filter((arch) => arch.evidence.some((e) => includesIgnoreCase(e, domain.name)) ||
+        arch.matchedRules.some((r) => includesIgnoreCase(r, domain.name)));
+    if (related.length > 0) {
+        return related;
+    }
+    // Fall back to top architectures when domain exists but has no direct arch mentions.
+    return model.architectures.slice(0, 3);
+}
+const handlers = {
+    RepositorySummary: (_query, ctx) => {
+        const { model } = ctx;
+        const result = {
+            projectName: model.metadata.project.name,
+            schemaVersion: model.metadata.schemaVersion,
+            compilerVersion: model.compilerMetadata.compilerVersion,
+            generatedAt: model.compilerMetadata.generatedAt,
+            topDomains: model.summary.topDomains,
+            topArchitectures: model.summary.topArchitectures,
+            frameworks: model.summary.frameworks,
+            statistics: model.summary.statistics,
+        };
+        return {
+            result,
+            evidence: [...model.metadata.evidence],
+            confidence: model.metadata.confidence,
+        };
+    },
+    ListDomains: (_query, ctx) => {
+        const domains = ctx.model.domains;
+        const result = { domains, count: domains.length };
+        return {
+            result,
+            evidence: domains.flatMap((d) => d.evidence).slice(0, 20),
+            confidence: average(domains.map((d) => d.confidence)),
+        };
+    },
+    ListEntrypoints: (_query, ctx) => {
+        const entrypoints = ctx.model.entrypoints;
+        const result = { entrypoints, count: entrypoints.length };
+        return {
+            result,
+            evidence: entrypoints.flatMap((e) => e.evidence).slice(0, 20),
+            confidence: average(entrypoints.map((e) => e.confidence)),
+        };
+    },
+    ListArchitectures: (_query, ctx) => {
+        const architectures = ctx.model.architectures;
+        const result = { architectures, count: architectures.length };
+        return {
+            result,
+            evidence: architectures.flatMap((a) => a.evidence).slice(0, 20),
+            confidence: average(architectures.map((a) => a.confidence)),
+        };
+    },
+    ListRelationships: (_query, ctx) => {
+        const relationships = ctx.model.relationships;
+        const result = { relationships, count: relationships.length };
+        return {
+            result,
+            evidence: relationships.flatMap((r) => r.evidence).slice(0, 20),
+            confidence: average(relationships.map((r) => r.confidence)),
+        };
+    },
+    ListDependencies: (_query, ctx) => {
+        const dependencies = ctx.model.dependencies;
+        const result = { dependencies, count: dependencies.length };
+        return {
+            result,
+            evidence: dependencies.flatMap((d) => d.evidence).slice(0, 20),
+            confidence: average(dependencies.map((d) => d.confidence)),
+        };
+    },
+    FindDomain: (query, ctx) => {
+        const domain = ctx.model.domains.find((d) => equalsIgnoreCase(d.name, query.name));
+        if (!domain) {
+            throw new QueryNotFoundError(`domain not found: ${query.name}`);
+        }
+        const entrypoints = entrypointsForDomain(ctx.model, domain);
+        const relationships = relationshipsForDomain(ctx.model, domain);
+        const dependencies = dependenciesForDomain(ctx.model, domain);
+        const architectures = architecturesForDomain(ctx.model, domain);
+        const result = {
+            domain,
+            entrypoints,
+            relationships,
+            dependencies,
+            architectures,
+        };
+        return {
+            result,
+            evidence: [
+                ...domain.evidence,
+                ...entrypoints.flatMap((e) => e.evidence).slice(0, 5),
+                ...relationships.flatMap((r) => r.evidence).slice(0, 5),
+            ],
+            confidence: domain.confidence,
+        };
+    },
+    FindEntrypoint: (query, ctx) => {
+        const entrypoint = ctx.model.entrypoints.find((entry) => {
+            if (query.id && entry.id === query.id) {
+                return true;
+            }
+            if (query.file && equalsIgnoreCase(entry.file, query.file)) {
+                return true;
+            }
+            if (query.framework &&
+                equalsIgnoreCase(entry.framework, query.framework) &&
+                !query.file &&
+                !query.id) {
+                return true;
+            }
+            if (query.framework &&
+                query.file &&
+                equalsIgnoreCase(entry.framework, query.framework) &&
+                equalsIgnoreCase(entry.file, query.file)) {
+                return true;
+            }
+            return false;
+        });
+        if (!entrypoint) {
+            throw new QueryNotFoundError("entrypoint not found");
+        }
+        const result = { entrypoint };
+        return {
+            result,
+            evidence: [...entrypoint.evidence],
+            confidence: entrypoint.confidence,
+        };
+    },
+    FindArchitecture: (query, ctx) => {
+        const architecture = ctx.model.architectures.find((arch) => equalsIgnoreCase(arch.pattern, query.pattern));
+        if (!architecture) {
+            throw new QueryNotFoundError(`architecture not found: ${query.pattern}`);
+        }
+        const result = { architecture };
+        return {
+            result,
+            evidence: [...architecture.evidence, ...architecture.matchedRules],
+            confidence: architecture.confidence,
+        };
+    },
+    FindComponent: (query, ctx) => {
+        const name = query.name;
+        const asRelationshipSource = ctx.model.relationships.filter((r) => equalsIgnoreCase(r.source, name));
+        const asRelationshipTarget = ctx.model.relationships.filter((r) => equalsIgnoreCase(r.target, name));
+        const asDependencyEndpoint = ctx.model.dependencies.filter((d) => equalsIgnoreCase(d.from, name) || equalsIgnoreCase(d.to, name));
+        const matchingEntrypoints = ctx.model.entrypoints.filter((e) => includesIgnoreCase(e.file, name) || e.evidence.some((ev) => includesIgnoreCase(ev, name)));
+        const matchingDomains = ctx.model.domains.filter((d) => equalsIgnoreCase(d.name, name) || d.evidence.some((ev) => includesIgnoreCase(ev, name)));
+        if (asRelationshipSource.length === 0 &&
+            asRelationshipTarget.length === 0 &&
+            asDependencyEndpoint.length === 0 &&
+            matchingEntrypoints.length === 0 &&
+            matchingDomains.length === 0) {
+            throw new QueryNotFoundError(`component not found: ${name}`);
+        }
+        const result = {
+            name,
+            asRelationshipSource,
+            asRelationshipTarget,
+            asDependencyEndpoint,
+            matchingEntrypoints,
+            matchingDomains,
+        };
+        const confidences = [
+            ...asRelationshipSource.map((r) => r.confidence),
+            ...asRelationshipTarget.map((r) => r.confidence),
+            ...asDependencyEndpoint.map((d) => d.confidence),
+            ...matchingEntrypoints.map((e) => e.confidence),
+            ...matchingDomains.map((d) => d.confidence),
+        ];
+        return {
+            result,
+            evidence: [
+                ...asRelationshipSource.flatMap((r) => r.evidence),
+                ...asRelationshipTarget.flatMap((r) => r.evidence),
+                ...asDependencyEndpoint.flatMap((d) => d.evidence),
+            ].slice(0, 30),
+            confidence: average(confidences),
+        };
+    },
+    FindRelationship: (query, ctx) => {
+        const matches = ctx.model.relationships.filter((rel) => {
+            if (query.id) {
+                return rel.id === query.id;
+            }
+            if (query.source && !equalsIgnoreCase(rel.source, query.source)) {
+                return false;
+            }
+            if (query.target && !equalsIgnoreCase(rel.target, query.target)) {
+                return false;
+            }
+            if (query.relationship && !equalsIgnoreCase(rel.relationship, query.relationship)) {
+                return false;
+            }
+            return Boolean(query.source || query.target || query.relationship);
+        });
+        const relationship = matches[0];
+        if (!relationship) {
+            throw new QueryNotFoundError("relationship not found");
+        }
+        const result = { relationship };
+        return {
+            result,
+            evidence: [...relationship.evidence],
+            confidence: relationship.confidence,
+        };
+    },
+    FindDependency: (query, ctx) => {
+        const matches = ctx.model.dependencies.filter((dep) => {
+            if (query.id) {
+                return dep.id === query.id;
+            }
+            if (query.from && !equalsIgnoreCase(dep.from, query.from)) {
+                return false;
+            }
+            if (query.to && !equalsIgnoreCase(dep.to, query.to)) {
+                return false;
+            }
+            if (query.dependencyType && !equalsIgnoreCase(dep.type, query.dependencyType)) {
+                return false;
+            }
+            return Boolean(query.from || query.to || query.dependencyType);
+        });
+        const dependency = matches[0];
+        if (!dependency) {
+            throw new QueryNotFoundError("dependency not found");
+        }
+        const result = { dependency };
+        return {
+            result,
+            evidence: [...dependency.evidence],
+            confidence: dependency.confidence,
+        };
+    },
+    FindEvidence: (query, ctx) => {
+        const needle = query.needle;
+        const hits = [];
+        const push = (collection, id, label, evidence) => {
+            const matched = evidence.filter((item) => includesIgnoreCase(item, needle));
+            if (matched.length > 0) {
+                hits.push({ collection, id, label, evidence: matched });
+            }
+        };
+        push("metadata", ctx.model.metadata.id, ctx.model.metadata.project.name, ctx.model.metadata.evidence);
+        for (const domain of ctx.model.domains) {
+            push("domains", domain.id, domain.name, domain.evidence);
+        }
+        for (const entry of ctx.model.entrypoints) {
+            push("entrypoints", entry.id, entry.file, entry.evidence);
+        }
+        for (const dep of ctx.model.dependencies) {
+            push("dependencies", dep.id, `${dep.from}->${dep.to}`, dep.evidence);
+        }
+        for (const rel of ctx.model.relationships) {
+            push("relationships", rel.id, `${rel.source}->${rel.target}`, rel.evidence);
+        }
+        for (const arch of ctx.model.architectures) {
+            push("architectures", arch.id, arch.pattern, [
+                ...arch.evidence,
+                ...arch.matchedRules,
+                ...arch.conflictingEvidence,
+                ...arch.unknowns,
+            ]);
+        }
+        hits.sort((a, b) => a.collection.localeCompare(b.collection) || a.label.localeCompare(b.label));
+        if (hits.length === 0) {
+            throw new QueryNotFoundError(`evidence not found for needle: ${needle}`);
+        }
+        const result = { needle, hits, count: hits.length };
+        return {
+            result,
+            evidence: hits.flatMap((hit) => hit.evidence).slice(0, 40),
+            confidence: Math.min(0.99, 0.5 + Math.min(hits.length, 10) * 0.04),
+        };
+    },
+    Statistics: (_query, ctx) => {
+        const result = {
+            summary: ctx.model.summary,
+            model: {
+                projectName: ctx.model.metadata.project.name,
+                schemaVersion: ctx.model.metadata.schemaVersion,
+                compilerVersion: ctx.model.compilerMetadata.compilerVersion,
+                generatedAt: ctx.model.compilerMetadata.generatedAt,
+            },
+        };
+        return {
+            result,
+            evidence: [
+                `domains:${ctx.model.summary.statistics.domainCount}`,
+                `entrypoints:${ctx.model.summary.statistics.entrypointCount}`,
+                `dependencies:${ctx.model.summary.statistics.dependencyCount}`,
+                `relationships:${ctx.model.summary.statistics.relationshipCount}`,
+                `architectures:${ctx.model.summary.statistics.architectureCount}`,
+            ],
+            confidence: ctx.model.summary.statistics.averageConfidence,
+        };
+    },
+};
+export function getQueryHandler(type) {
+    return handlers[type];
+}
+export function listSupportedQueryTypes() {
+    return Object.keys(handlers).sort((a, b) => a.localeCompare(b));
+}

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

@@ -0,0 +1,63 @@
+export type QueryType = "RepositorySummary" | "ListDomains" | "ListEntrypoints" | "ListArchitectures" | "ListRelationships" | "ListDependencies" | "FindDomain" | "FindEntrypoint" | "FindArchitecture" | "FindComponent" | "FindRelationship" | "FindDependency" | "FindEvidence" | "Statistics";
+export type Query = {
+    type: "RepositorySummary";
+} | {
+    type: "ListDomains";
+} | {
+    type: "ListEntrypoints";
+} | {
+    type: "ListArchitectures";
+} | {
+    type: "ListRelationships";
+} | {
+    type: "ListDependencies";
+} | {
+    type: "FindDomain";
+    name: string;
+} | {
+    type: "FindEntrypoint";
+    file?: string;
+    framework?: string;
+    id?: string;
+} | {
+    type: "FindArchitecture";
+    pattern: string;
+} | {
+    type: "FindComponent";
+    name: string;
+} | {
+    type: "FindRelationship";
+    source?: string;
+    target?: string;
+    relationship?: string;
+    id?: string;
+} | {
+    type: "FindDependency";
+    from?: string;
+    to?: string;
+    dependencyType?: string;
+    id?: string;
+} | {
+    type: "FindEvidence";
+    needle: string;
+} | {
+    type: "Statistics";
+};
+export interface QueryMetadata {
+    queryType: QueryType;
+    projectName: string;
+    modelId: string;
+    schemaVersion: string;
+    compilerVersion: string;
+    modelGeneratedAt: string;
+}
+/**
+ * Canonical envelope returned by every query execution.
+ */
+export interface QueryResponse<T> {
+    result: T;
+    evidence: readonly string[];
+    confidence: number;
+    metadata: QueryMetadata;
+    executionTimeMs: number;
+}

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

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

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

@@ -0,0 +1,11 @@
+import type { RelationshipDiscoveryOptions, RelationshipDiscoveryResult, RelationshipStrength } from "./types.js";
+/**
+ * Discover semantic component relationships using deterministic heuristics.
+ * Reuses dependency, entrypoint, and domain discovery. Isolated from scan/CLI.
+ */
+export declare function discoverRelationships(options?: RelationshipDiscoveryOptions): Promise<RelationshipDiscoveryResult>;
+export declare function scoreRelationshipConfidence(options: {
+    base: number;
+    strength: RelationshipStrength;
+    evidenceCount: number;
+}): number;