@praneeth_54/agentdoctor 1.0.0 → 1.1.0

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

@@ -0,0 +1,242 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { discoverFiles } from "../../../discovery/files.js";
+import { readTextFile } from "../../../utils/fs.js";
+const MAX_BYTES = 512 * 1024;
+const CODEOWNERS_CANDIDATES = [
+    "CODEOWNERS",
+    ".github/CODEOWNERS",
+    "docs/CODEOWNERS",
+    ".gitlab/CODEOWNERS",
+];
+export function scoreOwnershipConfidence(source) {
+    switch (source) {
+        case "codeowners":
+            return 0.95;
+        case "maintainers-file":
+            return 0.85;
+        case "package-maintainers":
+            return 0.75;
+        default:
+            return 0;
+    }
+}
+/** Match a repo-relative path against a CODEOWNERS pattern (subset of GitHub rules). */
+export function matchCodeownersPattern(filePath, pattern) {
+    const normalizedFile = filePath.replace(/\\/g, "/").replace(/^\/+/, "");
+    let normalizedPattern = pattern.replace(/\\/g, "/").trim();
+    if (normalizedPattern.length === 0) {
+        return false;
+    }
+    const anchored = normalizedPattern.startsWith("/");
+    if (anchored) {
+        normalizedPattern = normalizedPattern.slice(1);
+    }
+    const dirOnly = normalizedPattern.endsWith("/");
+    if (dirOnly) {
+        normalizedPattern = normalizedPattern.slice(0, -1);
+    }
+    const escaped = normalizedPattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "{{GLOBSTAR}}")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]")
+        .replace(/{{GLOBSTAR}}/g, ".*");
+    const prefix = anchored ? "^" : "(^|/)";
+    const suffix = dirOnly ? "(/.*)?$" : "$";
+    const regex = new RegExp(`${prefix}${escaped}${suffix}`);
+    return regex.test(normalizedFile);
+}
+function parseCodeowners(content, sourcePath) {
+    const matches = [];
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#")) {
+            continue;
+        }
+        const parts = line.split(/\s+/).filter((part) => part.length > 0);
+        if (parts.length < 2) {
+            continue;
+        }
+        const pattern = parts[0];
+        if (!pattern) {
+            continue;
+        }
+        const owners = parts.slice(1).filter((part) => !part.startsWith("#"));
+        if (owners.length === 0) {
+            continue;
+        }
+        matches.push({
+            path: pattern,
+            owners,
+            confidence: scoreOwnershipConfidence("codeowners"),
+            evidence: [`${sourcePath}:${pattern}`],
+            source: "codeowners",
+        });
+    }
+    return matches;
+}
+function parseMaintainersFile(content, sourcePath) {
+    const owners = [];
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#")) {
+            continue;
+        }
+        // Common formats: "@handle", "Name <email>", plain email/name
+        owners.push(line.replace(/,\s*$/, ""));
+    }
+    if (owners.length === 0) {
+        return [];
+    }
+    return [
+        {
+            path: "*",
+            owners,
+            confidence: scoreOwnershipConfidence("maintainers-file"),
+            evidence: [sourcePath],
+            source: "maintainers-file",
+        },
+    ];
+}
+function ownersFromPackageJson(data, packageRelativePath) {
+    if (!data || typeof data !== "object") {
+        return null;
+    }
+    const record = data;
+    const owners = [];
+    const pushAuthor = (value) => {
+        if (typeof value === "string" && value.trim().length > 0) {
+            owners.push(value.trim());
+            return;
+        }
+        if (value && typeof value === "object") {
+            const author = value;
+            const name = typeof author.name === "string" ? author.name.trim() : "";
+            const email = typeof author.email === "string" ? author.email.trim() : "";
+            if (name && email) {
+                owners.push(`${name} <${email}>`);
+            }
+            else if (name) {
+                owners.push(name);
+            }
+            else if (email) {
+                owners.push(email);
+            }
+        }
+    };
+    pushAuthor(record.author);
+    if (Array.isArray(record.maintainers)) {
+        for (const item of record.maintainers) {
+            pushAuthor(item);
+        }
+    }
+    const unique = [...new Set(owners)];
+    if (unique.length === 0) {
+        return null;
+    }
+    const dir = path.posix.dirname(packageRelativePath.replace(/\\/g, "/"));
+    const covered = dir === "." ? "*" : `${dir}/**`;
+    return {
+        path: covered,
+        owners: unique,
+        confidence: scoreOwnershipConfidence("package-maintainers"),
+        evidence: [packageRelativePath],
+        source: "package-maintainers",
+    };
+}
+/**
+ * Discover ownership from explicit repository evidence only.
+ * Sources: CODEOWNERS, MAINTAINERS, package.json author/maintainers.
+ * No git-blame guessing.
+ */
+export async function discoverOwnership(options = {}) {
+    const started = performance.now();
+    const cwd = options.cwd ?? process.cwd();
+    const minConfidence = options.minConfidence ?? 0.5;
+    const ownerships = [];
+    const unknowns = [];
+    let filesConsidered = 0;
+    for (const candidate of CODEOWNERS_CANDIDATES) {
+        const absolute = path.join(cwd, candidate);
+        const text = await readTextFile(absolute, MAX_BYTES);
+        if (text === null) {
+            continue;
+        }
+        filesConsidered += 1;
+        ownerships.push(...parseCodeowners(text, candidate));
+    }
+    for (const candidate of ["MAINTAINERS", "OWNERS", "docs/MAINTAINERS"]) {
+        const text = await readTextFile(path.join(cwd, candidate), MAX_BYTES);
+        if (text === null) {
+            continue;
+        }
+        filesConsidered += 1;
+        ownerships.push(...parseMaintainersFile(text, candidate));
+    }
+    const relativePaths = options.relativePaths ??
+        (await discoverFiles({ root: cwd })).files.map((file) => file.relativePath);
+    const packageJsonPaths = relativePaths.filter((relative) => {
+        const normalized = relative.replace(/\\/g, "/");
+        return normalized === "package.json" || normalized.endsWith("/package.json");
+    });
+    for (const packageRelative of packageJsonPaths) {
+        filesConsidered += 1;
+        try {
+            const raw = await fs.readFile(path.join(cwd, packageRelative), "utf8");
+            if (Buffer.byteLength(raw, "utf8") > MAX_BYTES) {
+                continue;
+            }
+            const parsed = JSON.parse(raw);
+            const match = ownersFromPackageJson(parsed, packageRelative.replace(/\\/g, "/"));
+            if (match) {
+                ownerships.push(match);
+            }
+        }
+        catch {
+            // Malformed package.json is not ownership evidence.
+        }
+    }
+    const filtered = ownerships
+        .filter((item) => item.confidence >= minConfidence && item.owners.length > 0)
+        .sort((a, b) => b.confidence - a.confidence ||
+        a.source.localeCompare(b.source) ||
+        a.path.localeCompare(b.path));
+    if (filtered.length === 0) {
+        unknowns.push("No explicit ownership evidence found (CODEOWNERS / MAINTAINERS / package.json)");
+    }
+    return {
+        ownerships: filtered,
+        timingMs: Math.max(0, Math.round(performance.now() - started)),
+        filesConsidered,
+        unknowns,
+    };
+}
+/** Resolve owners for a path using last-matching CODEOWNERS rule semantics when possible. */
+export function ownersForPath(filePath, ownerships) {
+    const normalized = filePath.replace(/\\/g, "/").replace(/^\/+/, "");
+    let lastCodeowners = null;
+    let packageMatch = null;
+    let maintainersMatch = null;
+    for (const ownership of ownerships) {
+        if (ownership.source === "codeowners") {
+            if (matchCodeownersPattern(normalized, ownership.path)) {
+                lastCodeowners = ownership;
+            }
+            continue;
+        }
+        if (ownership.source === "package-maintainers") {
+            if (ownership.path === "*" || matchCodeownersPattern(normalized, ownership.path)) {
+                // Prefer the most specific package path (longest prefix).
+                if (!packageMatch || ownership.path.length > packageMatch.path.length) {
+                    packageMatch = ownership;
+                }
+            }
+            continue;
+        }
+        if (ownership.source === "maintainers-file" && ownership.path === "*") {
+            maintainersMatch = ownership;
+        }
+    }
+    return lastCodeowners ?? packageMatch ?? maintainersMatch;
+}

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

@@ -0,0 +1,2 @@
+export { discoverOwnership, ownersForPath, matchCodeownersPattern, scoreOwnershipConfidence, } from "./discover.js";
+export type { OwnershipDiscoveryOptions, OwnershipDiscoveryResult, OwnershipMatch, OwnershipSource, } from "./types.js";

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

@@ -0,0 +1 @@
+export { discoverOwnership, ownersForPath, matchCodeownersPattern, scoreOwnershipConfidence, } from "./discover.js";

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

@@ -0,0 +1,23 @@
+export type OwnershipSource = "codeowners" | "package-maintainers" | "maintainers-file";
+export interface OwnershipMatch {
+    /** Repository-relative path or glob covered by this ownership claim. */
+    path: string;
+    /** Owner handles / emails / team refs as written in evidence. */
+    owners: readonly string[];
+    confidence: number;
+    evidence: readonly string[];
+    source: OwnershipSource;
+}
+export interface OwnershipDiscoveryResult {
+    ownerships: OwnershipMatch[];
+    timingMs: number;
+    filesConsidered: number;
+    /** Explicit unknowns — never invent owners. */
+    unknowns: string[];
+}
+export interface OwnershipDiscoveryOptions {
+    cwd?: string;
+    /** Optional file list (repo-relative). When omitted, discovery walks the tree. */
+    relativePaths?: readonly string[];
+    minConfidence?: number;
+}

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

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

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

@@ -0,0 +1,24 @@
+import type { ProjectModel } from "../model/types.js";
+import type { QueryResultMap } from "./models.js";
+import { Queries } from "./query.js";
+import type { Query, QueryResponse } from "./types.js";
+/**
+ * Runtime query facade over an immutable ProjectModel.
+ * This is the only supported read interface for future Explain/Trace/Understand/Verify/Search layers.
+ */
+export declare class QueryEngine {
+    private readonly model;
+    constructor(model: ProjectModel);
+    /** Execute any supported query against the bound ProjectModel. */
+    execute<T extends Query>(query: T): QueryResponse<QueryResultMap[T["type"]]>;
+    /** Validate a raw query object without executing it. */
+    validate(query: unknown): Query;
+    supportedQueries(): readonly string[];
+    getModelIdentity(): {
+        projectName: string;
+        modelId: string;
+        schemaVersion: string;
+    };
+}
+export declare function createQueryEngine(model: ProjectModel): QueryEngine;
+export { Queries };

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

@@ -0,0 +1,35 @@
+import { executeQuery } from "./executor.js";
+import { Queries, validateQuery } from "./query.js";
+import { listSupportedQueryTypes } from "./registry.js";
+/**
+ * Runtime query facade over an immutable ProjectModel.
+ * This is the only supported read interface for future Explain/Trace/Understand/Verify/Search layers.
+ */
+export class QueryEngine {
+    model;
+    constructor(model) {
+        this.model = model;
+    }
+    /** Execute any supported query against the bound ProjectModel. */
+    execute(query) {
+        return executeQuery(this.model, query);
+    }
+    /** Validate a raw query object without executing it. */
+    validate(query) {
+        return validateQuery(query);
+    }
+    supportedQueries() {
+        return listSupportedQueryTypes();
+    }
+    getModelIdentity() {
+        return {
+            projectName: this.model.metadata.project.name,
+            modelId: this.model.metadata.id,
+            schemaVersion: this.model.metadata.schemaVersion,
+        };
+    }
+}
+export function createQueryEngine(model) {
+    return new QueryEngine(model);
+}
+export { Queries };

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

@@ -0,0 +1,13 @@
+export declare class QueryError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class QueryValidationError extends QueryError {
+    constructor(message: string);
+}
+export declare class QueryNotFoundError extends QueryError {
+    constructor(message: string);
+}
+export declare class QueryUnsupportedError extends QueryError {
+    constructor(message: string);
+}

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

@@ -0,0 +1,26 @@
+export class QueryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "QueryError";
+        this.code = code;
+    }
+}
+export class QueryValidationError extends QueryError {
+    constructor(message) {
+        super("QUERY_VALIDATION", message);
+        this.name = "QueryValidationError";
+    }
+}
+export class QueryNotFoundError extends QueryError {
+    constructor(message) {
+        super("QUERY_NOT_FOUND", message);
+        this.name = "QueryNotFoundError";
+    }
+}
+export class QueryUnsupportedError extends QueryError {
+    constructor(message) {
+        super("QUERY_UNSUPPORTED", message);
+        this.name = "QueryUnsupportedError";
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { ProjectModel } from "../model/types.js";
+import type { QueryResultMap } from "./models.js";
+import type { Query, QueryResponse } from "./types.js";
+/**
+ * Execute a validated query against an immutable ProjectModel.
+ * Pure: no I/O, no compiler passes, no model mutation.
+ */
+export declare function executeQuery<T extends Query>(model: ProjectModel, rawQuery: T): QueryResponse<QueryResultMap[T["type"]]>;

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

@@ -0,0 +1,34 @@
+import { QueryUnsupportedError } from "./errors.js";
+import { getQueryHandler } from "./registry.js";
+import { validateQuery } from "./query.js";
+function buildMetadata(model, queryType) {
+    return {
+        queryType,
+        projectName: model.metadata.project.name,
+        modelId: model.metadata.id,
+        schemaVersion: model.metadata.schemaVersion,
+        compilerVersion: model.compilerMetadata.compilerVersion,
+        modelGeneratedAt: model.compilerMetadata.generatedAt,
+    };
+}
+/**
+ * Execute a validated query against an immutable ProjectModel.
+ * Pure: no I/O, no compiler passes, no model mutation.
+ */
+export function executeQuery(model, rawQuery) {
+    const started = performance.now();
+    const query = validateQuery(rawQuery);
+    const handler = getQueryHandler(query.type);
+    if (!handler) {
+        throw new QueryUnsupportedError(`no handler registered for ${query.type}`);
+    }
+    const output = handler(query, { model });
+    const executionTimeMs = Math.max(0, Math.round(performance.now() - started));
+    return {
+        result: output.result,
+        evidence: Object.freeze([...output.evidence]),
+        confidence: output.confidence,
+        metadata: buildMetadata(model, query.type),
+        executionTimeMs,
+    };
+}

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

@@ -0,0 +1,7 @@
+export { QueryEngine, createQueryEngine, Queries } from "./engine.js";
+export { executeQuery } from "./executor.js";
+export { validateQuery } from "./query.js";
+export { listSupportedQueryTypes } from "./registry.js";
+export { QueryError, QueryValidationError, QueryNotFoundError, QueryUnsupportedError, } from "./errors.js";
+export type { Query, QueryType, QueryResponse, QueryMetadata } from "./types.js";
+export type { RepositorySummaryResult, ListDomainsResult, FindDomainResult, FindComponentResult, FindEvidenceResult, StatisticsResult, QueryResultMap, } from "./models.js";

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

@@ -0,0 +1,5 @@
+export { QueryEngine, createQueryEngine, Queries } from "./engine.js";
+export { executeQuery } from "./executor.js";
+export { validateQuery } from "./query.js";
+export { listSupportedQueryTypes } from "./registry.js";
+export { QueryError, QueryValidationError, QueryNotFoundError, QueryUnsupportedError, } from "./errors.js";

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

@@ -0,0 +1,102 @@
+import type { ProjectArchitecture, ProjectDependency, ProjectDomain, ProjectEntrypoint, ProjectModel, ProjectRelationship, ProjectStatistics, ProjectSummary } from "../model/types.js";
+export interface RepositorySummaryResult {
+    projectName: string;
+    schemaVersion: string;
+    compilerVersion: string;
+    generatedAt: string;
+    topDomains: readonly string[];
+    topArchitectures: readonly string[];
+    frameworks: readonly string[];
+    statistics: ProjectStatistics;
+}
+export interface ListDomainsResult {
+    domains: readonly ProjectDomain[];
+    count: number;
+}
+export interface ListEntrypointsResult {
+    entrypoints: readonly ProjectEntrypoint[];
+    count: number;
+}
+export interface ListArchitecturesResult {
+    architectures: readonly ProjectArchitecture[];
+    count: number;
+}
+export interface ListRelationshipsResult {
+    relationships: readonly ProjectRelationship[];
+    count: number;
+}
+export interface ListDependenciesResult {
+    dependencies: readonly ProjectDependency[];
+    count: number;
+}
+export interface FindDomainResult {
+    domain: ProjectDomain;
+    entrypoints: readonly ProjectEntrypoint[];
+    relationships: readonly ProjectRelationship[];
+    dependencies: readonly ProjectDependency[];
+    architectures: readonly ProjectArchitecture[];
+}
+export interface FindEntrypointResult {
+    entrypoint: ProjectEntrypoint;
+}
+export interface FindArchitectureResult {
+    architecture: ProjectArchitecture;
+}
+export interface FindComponentResult {
+    name: string;
+    asRelationshipSource: readonly ProjectRelationship[];
+    asRelationshipTarget: readonly ProjectRelationship[];
+    asDependencyEndpoint: readonly ProjectDependency[];
+    matchingEntrypoints: readonly ProjectEntrypoint[];
+    matchingDomains: readonly ProjectDomain[];
+}
+export interface FindRelationshipResult {
+    relationship: ProjectRelationship;
+}
+export interface FindDependencyResult {
+    dependency: ProjectDependency;
+}
+export interface EvidenceHit {
+    collection: "domains" | "entrypoints" | "dependencies" | "relationships" | "architectures" | "metadata";
+    id: string;
+    label: string;
+    evidence: readonly string[];
+}
+export interface FindEvidenceResult {
+    needle: string;
+    hits: readonly EvidenceHit[];
+    count: number;
+}
+export interface StatisticsResult {
+    summary: ProjectSummary;
+    model: {
+        projectName: string;
+        schemaVersion: string;
+        compilerVersion: string;
+        generatedAt: string;
+    };
+}
+export type QueryResultMap = {
+    RepositorySummary: RepositorySummaryResult;
+    ListDomains: ListDomainsResult;
+    ListEntrypoints: ListEntrypointsResult;
+    ListArchitectures: ListArchitecturesResult;
+    ListRelationships: ListRelationshipsResult;
+    ListDependencies: ListDependenciesResult;
+    FindDomain: FindDomainResult;
+    FindEntrypoint: FindEntrypointResult;
+    FindArchitecture: FindArchitectureResult;
+    FindComponent: FindComponentResult;
+    FindRelationship: FindRelationshipResult;
+    FindDependency: FindDependencyResult;
+    FindEvidence: FindEvidenceResult;
+    Statistics: StatisticsResult;
+};
+export interface QueryHandlerContext {
+    model: ProjectModel;
+}
+export interface QueryHandlerOutput<T> {
+    result: T;
+    evidence: string[];
+    confidence: number;
+}

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

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

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

@@ -0,0 +1,68 @@
+import type { Query } from "./types.js";
+/**
+ * Validate and normalize a raw query object into a typed Query.
+ */
+export declare function validateQuery(input: unknown): Query;
+/** Typed query constructors (internal ergonomics). */
+export declare const Queries: {
+    readonly repositorySummary: () => {
+        type: "RepositorySummary";
+    };
+    readonly listDomains: () => {
+        type: "ListDomains";
+    };
+    readonly listEntrypoints: () => {
+        type: "ListEntrypoints";
+    };
+    readonly listArchitectures: () => {
+        type: "ListArchitectures";
+    };
+    readonly listRelationships: () => {
+        type: "ListRelationships";
+    };
+    readonly listDependencies: () => {
+        type: "ListDependencies";
+    };
+    readonly findDomain: (name: string) => {
+        type: "FindDomain";
+        name: string;
+    };
+    readonly findEntrypoint: (options: {
+        file?: string;
+        framework?: string;
+        id?: string;
+    }) => {
+        type: "FindEntrypoint";
+    };
+    readonly findArchitecture: (pattern: string) => {
+        type: "FindArchitecture";
+        pattern: string;
+    };
+    readonly findComponent: (name: string) => {
+        type: "FindComponent";
+        name: string;
+    };
+    readonly findRelationship: (options: {
+        source?: string;
+        target?: string;
+        relationship?: string;
+        id?: string;
+    }) => {
+        type: "FindRelationship";
+    };
+    readonly findDependency: (options: {
+        from?: string;
+        to?: string;
+        dependencyType?: string;
+        id?: string;
+    }) => {
+        type: "FindDependency";
+    };
+    readonly findEvidence: (needle: string) => {
+        type: "FindEvidence";
+        needle: string;
+    };
+    readonly statistics: () => {
+        type: "Statistics";
+    };
+};