@mortice/mapwright 0.8.0

package/dist/queries/ranking.js

@@ -0,0 +1,387 @@
+import { normalizeIdentityString } from "../catalogue/identity.js";
+/** Version of the ranking + match-reason contract exposed to MCP callers. */
+export const RANKING_CONTRACT_VERSION = "1";
+/**
+ * Closed vocabulary of match reasons. Order here is also the canonical
+ * emission order for a single result's `matchReasons`.
+ */
+export const MATCH_REASONS = [
+    "exact_exported_name",
+    "exact_declared_name",
+    "exact_qualified_name",
+    "exact_import_path",
+    "case_insensitive_exact",
+    "whole_token",
+    "prefix",
+    "substring",
+    "public_export",
+    "package_root_export",
+    "subpath_export",
+    "canonical_source",
+    "explicit_documentation",
+    "explicit_public_api",
+    "has_explicit_example",
+    "has_explicit_test",
+    "has_direct_usage"
+];
+const REASON_RANK = new Map(MATCH_REASONS.map((reason, index) => [reason, index]));
+/**
+ * Rank-affecting weights. Reasons absent from this map are explanatory only and
+ * do not influence ordering (they still appear in `matchReasons`).
+ */
+const REASON_WEIGHTS = {
+    exact_exported_name: 1000,
+    exact_declared_name: 1000,
+    exact_qualified_name: 700,
+    exact_import_path: 900,
+    case_insensitive_exact: 600,
+    whole_token: 300,
+    prefix: 150,
+    substring: 60,
+    public_export: 40,
+    package_root_export: 30,
+    subpath_export: 10,
+    canonical_source: 25,
+    explicit_public_api: 20,
+    has_explicit_example: 8,
+    has_explicit_test: 8,
+    has_direct_usage: 6,
+    explicit_documentation: 5
+};
+/** NFC-normalize and trim a raw query. */
+export function normalizeQuery(query) {
+    return normalizeIdentityString(query ?? "").trim();
+}
+/** Lowercase alphanumeric tokens, splitting on separators and camelCase boundaries. */
+export function tokenize(value) {
+    if (!value) {
+        return [];
+    }
+    const spaced = normalizeIdentityString(value)
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2");
+    return spaced
+        .split(/[^\p{L}\p{N}]+/u)
+        .map((token) => token.toLowerCase())
+        .filter(Boolean);
+}
+function orderReasons(reasons) {
+    return [...reasons].sort((a, b) => (REASON_RANK.get(a) ?? 99) - (REASON_RANK.get(b) ?? 99));
+}
+function scoreReasons(reasons) {
+    let score = 0;
+    for (const reason of reasons) {
+        score += REASON_WEIGHTS[reason] ?? 0;
+    }
+    return score;
+}
+/**
+ * Compute name-oriented match reasons for a candidate string against the query.
+ * `exactReason` selects the exported vs declared exact-name reason.
+ */
+function matchName(candidate, normalizedQuery, exactReason) {
+    const reasons = [];
+    if (!candidate || !normalizedQuery) {
+        return { reasons, matched: false };
+    }
+    const name = normalizeIdentityString(candidate);
+    const nameLower = name.toLowerCase();
+    const queryLower = normalizedQuery.toLowerCase();
+    if (name === normalizedQuery) {
+        reasons.push(exactReason);
+    }
+    else if (nameLower === queryLower) {
+        reasons.push("case_insensitive_exact");
+    }
+    const nameTokens = tokenize(name);
+    if (nameTokens.includes(queryLower)) {
+        reasons.push("whole_token");
+    }
+    if (nameLower.startsWith(queryLower)) {
+        reasons.push("prefix");
+    }
+    if (nameLower.includes(queryLower)) {
+        reasons.push("substring");
+    }
+    return { reasons, matched: reasons.length > 0 };
+}
+/**
+ * Public helper: compute the ordered string-oriented match reasons for a
+ * candidate name against a raw query. Used by lighter-weight rankers (e.g.
+ * reuse candidates) that want explanatory reasons without full scoring.
+ */
+export function nameMatchReasons(candidate, query, exactReason = "exact_declared_name") {
+    const match = matchName(candidate, normalizeQuery(query), exactReason);
+    return orderReasons(new Set(match.reasons));
+}
+function buildFiltersApplied(filters) {
+    const applied = {};
+    const keys = [
+        "packageId",
+        "language",
+        "kind",
+        "publicOnly",
+        "capabilityId",
+        "hasExamples",
+        "hasTests",
+        "stability"
+    ];
+    for (const key of keys) {
+        const value = filters[key];
+        if (value !== undefined) {
+            applied[key] = value;
+        }
+    }
+    return applied;
+}
+function classifyExport(api) {
+    if (api.exportKey === ".") {
+        return "root";
+    }
+    if (api.exportKey && api.exportKey !== ".") {
+        return "subpath";
+    }
+    const importPath = api.importPath;
+    if (!importPath) {
+        return undefined;
+    }
+    let rest = importPath;
+    if (rest.startsWith("@")) {
+        const parts = rest.split("/");
+        return parts.length > 2 && parts.slice(2).join("/").length > 0 ? "subpath" : "root";
+    }
+    return rest.includes("/") ? "subpath" : "root";
+}
+function isCanonicalSource(symbol) {
+    if (!symbol) {
+        return false;
+    }
+    if (symbol.duplicateOf) {
+        return false;
+    }
+    if (symbol.symbolProvenance === "generated_only" || symbol.symbolProvenance === "generated_declaration") {
+        return false;
+    }
+    if (symbol.canonicalSymbolId && symbol.canonicalSymbolId !== symbol.id) {
+        return false;
+    }
+    return true;
+}
+function isPublicSymbol(symbol) {
+    return symbol.exported === true || symbol.visibility === "published" || symbol.visibility === "supported_internal";
+}
+function buildDirectUsageIndex(snapshot) {
+    const publicApiIds = new Set();
+    const symbolIds = new Set();
+    for (const relationship of snapshot.relationships) {
+        if (relationship.type !== "resolved_direct_usage") {
+            continue;
+        }
+        for (const endpoint of [relationship.from, relationship.to]) {
+            if (endpoint.kind === "publicApi") {
+                publicApiIds.add(endpoint.id);
+            }
+            else if (endpoint.kind === "symbol") {
+                symbolIds.add(endpoint.id);
+            }
+        }
+    }
+    return { publicApiIds, symbolIds };
+}
+/** Semantic sort key for public APIs (mirrors ordering.ts sortPublicApis). */
+function publicApiSortKey(api) {
+    return [
+        api.packageId ?? "",
+        api.importPath ?? "",
+        api.name,
+        api.exportKind ?? "named",
+        api.id
+    ]
+        .map((part) => normalizeIdentityString(String(part)))
+        .join("\u0000");
+}
+/** Semantic sort key for symbols (mirrors ordering.ts sortSymbols). */
+function symbolSortKey(symbol) {
+    return [
+        symbol.packageId ?? "",
+        symbol.filePath,
+        symbol.qualifiedName,
+        symbol.kind,
+        symbol.id
+    ]
+        .map((part) => normalizeIdentityString(String(part)))
+        .join("\u0000");
+}
+function finalize(scored) {
+    scored.sort((a, b) => {
+        if (b.score !== a.score) {
+            return b.score - a.score;
+        }
+        if (a.sortKey < b.sortKey)
+            return -1;
+        if (a.sortKey > b.sortKey)
+            return 1;
+        return 0;
+    });
+    return scored.map((entry) => ({ record: entry.record, matchReasons: entry.reasons }));
+}
+export function rankPublicApis(query, records, filters, snapshot) {
+    const normalizedQuery = normalizeQuery(query);
+    const symbolsById = new Map(snapshot.symbols.map((symbol) => [symbol.id, symbol]));
+    const directUsage = buildDirectUsageIndex(snapshot);
+    const scored = [];
+    for (const api of records) {
+        const symbol = api.symbolId ? symbolsById.get(api.symbolId) : undefined;
+        // Hard eligibility filters (before ranking).
+        if (filters.packageId && api.packageId !== filters.packageId)
+            continue;
+        if (filters.stability && api.stability !== filters.stability)
+            continue;
+        if (filters.capabilityId && !api.capabilityIds.includes(filters.capabilityId))
+            continue;
+        if (filters.hasExamples && api.examples.length === 0)
+            continue;
+        if (filters.hasTests && api.tests.length === 0)
+            continue;
+        if (filters.language) {
+            if (!symbol || symbol.language !== filters.language)
+                continue;
+        }
+        // publicOnly is a no-op for public APIs (all are public exports).
+        const reasons = new Set();
+        if (normalizedQuery) {
+            const nameMatch = matchName(api.name, normalizedQuery, "exact_exported_name");
+            for (const reason of nameMatch.reasons)
+                reasons.add(reason);
+            if (api.importPath && normalizeIdentityString(api.importPath).toLowerCase() === normalizedQuery.toLowerCase()) {
+                reasons.add("exact_import_path");
+            }
+            // Require a query match to be eligible when a query is provided.
+            if (reasons.size === 0) {
+                continue;
+            }
+        }
+        reasons.add("public_export");
+        reasons.add("explicit_public_api");
+        const exportClass = classifyExport(api);
+        if (exportClass === "root")
+            reasons.add("package_root_export");
+        else if (exportClass === "subpath")
+            reasons.add("subpath_export");
+        if (isCanonicalSource(symbol))
+            reasons.add("canonical_source");
+        if (symbol?.doc?.present)
+            reasons.add("explicit_documentation");
+        if (api.examples.length > 0)
+            reasons.add("has_explicit_example");
+        if (api.tests.length > 0)
+            reasons.add("has_explicit_test");
+        if (directUsage.publicApiIds.has(api.id))
+            reasons.add("has_direct_usage");
+        scored.push({
+            record: api,
+            reasons: orderReasons(reasons),
+            score: scoreReasons(reasons),
+            sortKey: publicApiSortKey(api)
+        });
+    }
+    return finalize(scored);
+}
+export function rankSymbols(query, records, filters, snapshot) {
+    const normalizedQuery = normalizeQuery(query);
+    const directUsage = buildDirectUsageIndex(snapshot);
+    const symbolsWithExample = new Set();
+    for (const example of snapshot.examples) {
+        for (const symbolId of example.symbolIds)
+            symbolsWithExample.add(symbolId);
+    }
+    const symbolsWithTest = new Set();
+    for (const test of snapshot.tests) {
+        for (const symbolId of test.coversSymbols)
+            symbolsWithTest.add(symbolId);
+    }
+    const scored = [];
+    for (const symbol of records) {
+        // Hard eligibility filters (before ranking).
+        if (filters.packageId && symbol.packageId !== filters.packageId)
+            continue;
+        if (filters.language && symbol.language !== filters.language)
+            continue;
+        if (filters.kind && symbol.kind !== filters.kind)
+            continue;
+        if (filters.publicOnly && !isPublicSymbol(symbol))
+            continue;
+        if (filters.capabilityId && !symbol.capabilities.includes(filters.capabilityId))
+            continue;
+        if (filters.hasExamples && !symbolsWithExample.has(symbol.id))
+            continue;
+        if (filters.hasTests && !symbolsWithTest.has(symbol.id))
+            continue;
+        const reasons = new Set();
+        if (normalizedQuery) {
+            const nameMatch = matchName(symbol.name, normalizedQuery, "exact_declared_name");
+            for (const reason of nameMatch.reasons)
+                reasons.add(reason);
+            if (symbol.qualifiedName) {
+                const qualified = normalizeIdentityString(symbol.qualifiedName);
+                if (qualified === normalizedQuery) {
+                    reasons.add("exact_qualified_name");
+                }
+                else if (qualified.toLowerCase().includes(normalizedQuery.toLowerCase())) {
+                    reasons.add("substring");
+                }
+            }
+            if (reasons.size === 0) {
+                continue;
+            }
+        }
+        if (isPublicSymbol(symbol))
+            reasons.add("public_export");
+        if (symbol.publicApi)
+            reasons.add("explicit_public_api");
+        if (isCanonicalSource(symbol))
+            reasons.add("canonical_source");
+        if (symbol.doc?.present)
+            reasons.add("explicit_documentation");
+        if (symbolsWithExample.has(symbol.id))
+            reasons.add("has_explicit_example");
+        if (symbolsWithTest.has(symbol.id))
+            reasons.add("has_explicit_test");
+        if (directUsage.symbolIds.has(symbol.id))
+            reasons.add("has_direct_usage");
+        scored.push({
+            record: symbol,
+            reasons: orderReasons(reasons),
+            score: scoreReasons(reasons),
+            sortKey: symbolSortKey(symbol)
+        });
+    }
+    return finalize(scored);
+}
+/** Generic pagination + compaction helper for ranked results. */
+export function paginateRanked(ranked, toCompact, params) {
+    const total = ranked.length;
+    const offset = Math.max(0, Math.floor(params.offset ?? 0));
+    const limit = Math.max(1, Math.floor(params.limit ?? 20));
+    const page = ranked.slice(offset, offset + limit);
+    const records = page.map((entry) => ({ ...toCompact(entry.record), matchReasons: entry.matchReasons }));
+    return {
+        total,
+        returned: records.length,
+        offset,
+        limit,
+        truncated: offset + records.length < total,
+        rankingContractVersion: RANKING_CONTRACT_VERSION,
+        filtersApplied: params.filtersApplied,
+        normalizedQuery: params.normalizedQuery,
+        records
+    };
+}
+export function buildRankedEnvelope(query, ranked, toCompact, filters, paging) {
+    return paginateRanked(ranked, toCompact, {
+        offset: paging.offset,
+        limit: paging.limit,
+        normalizedQuery: normalizeQuery(query),
+        filtersApplied: buildFiltersApplied(filters)
+    });
+}

package/dist/queries/recommendConfig.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Read-only configuration recommendations (Gate 4).
+ *
+ * Detects high-noise generated trees that are *currently indexed* in the
+ * snapshot (e.g. `.next`, `dist`, `build`, `out`, `coverage`) and suggests
+ * exclude patterns to remove them from indexing. Impact is reported using the
+ * current snapshot only: `directImpact` counts existing files/symbols/packages
+ * under the tree, and `diagnosticImpact` is reported as `requires_simulation`
+ * because excluding a tree can alter resolution/unresolved-import diagnostics
+ * elsewhere and cannot be safely estimated without a re-index.
+ *
+ * This engine never re-indexes per candidate and never writes configuration.
+ */
+import type { CatalogueSnapshot } from "../catalogue/schema.js";
+/** Path segments treated as high-noise generated trees. */
+export declare const NOISE_SEGMENTS: readonly [".next", "dist", "build", "out", "coverage"];
+export type RecommendationConfidence = "high" | "medium" | "low";
+export type DiagnosticImpactMode = "requires_simulation" | "direct" | "not_estimable";
+export interface ConfigRecommendation {
+    pattern: string;
+    confidence: RecommendationConfidence;
+    rationale: string;
+    directImpact: {
+        files: number;
+        symbols: number;
+        packages: number;
+    };
+    diagnosticImpact: {
+        mode: DiagnosticImpactMode;
+        value: number | null;
+    };
+}
+export interface RecommendConfigResult {
+    summary: {
+        filesTotal: number;
+        candidatesTotal: number;
+        candidatesReturned: number;
+        truncated: boolean;
+        filesImpacted: number;
+    };
+    recommendations: ConfigRecommendation[];
+}
+export interface RecommendConfigOptions {
+    /** Maximum number of recommendations returned. Default 50. */
+    limit?: number;
+}
+export declare function recommendConfig(snapshot: CatalogueSnapshot, options?: RecommendConfigOptions): RecommendConfigResult;

package/dist/queries/recommendConfig.js

@@ -0,0 +1,123 @@
+/** Path segments treated as high-noise generated trees. */
+export const NOISE_SEGMENTS = [".next", "dist", "build", "out", "coverage"];
+const DEFAULT_LIMIT = 50;
+/** Normalize a path to forward slashes for segment analysis. */
+function normalizePath(value) {
+    return value.replaceAll("\\", "/");
+}
+/**
+ * Find the first noise segment in a path and return the tree prefix up to and
+ * including it, or undefined when no noise segment is present.
+ */
+function findNoiseTree(filePath) {
+    const segments = normalizePath(filePath).split("/").filter((segment) => segment.length > 0);
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        if (NOISE_SEGMENTS.includes(segment)) {
+            return { prefix: segments.slice(0, index + 1).join("/"), segment };
+        }
+    }
+    return undefined;
+}
+function isUnder(path, prefix) {
+    const normalized = normalizePath(path);
+    return normalized === prefix || normalized.startsWith(`${prefix}/`);
+}
+export function recommendConfig(snapshot, options = {}) {
+    const limit = normalizeLimit(options.limit);
+    const trees = new Map();
+    for (const file of snapshot.files) {
+        const tree = findNoiseTree(file.path);
+        if (!tree) {
+            continue;
+        }
+        const pattern = `${tree.prefix}/**`;
+        const existing = trees.get(pattern);
+        if (existing) {
+            existing.filePaths.push(file.path);
+        }
+        else {
+            trees.set(pattern, { pattern, segment: tree.segment, prefix: tree.prefix, filePaths: [file.path] });
+        }
+    }
+    const filesByPath = new Map(snapshot.files.map((file) => [file.path, file]));
+    const impactedFilePaths = new Set();
+    const recommendations = [];
+    for (const tree of trees.values()) {
+        const files = tree.filePaths.length;
+        for (const filePath of tree.filePaths) {
+            impactedFilePaths.add(filePath);
+        }
+        const symbols = snapshot.symbols.filter((symbol) => isUnder(symbol.filePath, tree.prefix)).length;
+        const packages = snapshot.packages.filter((pkg) => pkg.path !== "." && isUnder(pkg.path, tree.prefix)).length;
+        const generatedCount = tree.filePaths.filter((filePath) => {
+            const file = filesByPath.get(filePath);
+            return Boolean(file && (file.isGenerated || file.kind === "generated"));
+        }).length;
+        const confidence = classifyConfidence(generatedCount, files);
+        recommendations.push({
+            pattern: tree.pattern,
+            confidence,
+            rationale: buildRationale(tree.segment, tree.prefix, files, symbols, generatedCount),
+            directImpact: { files, symbols, packages },
+            diagnosticImpact: { mode: "requires_simulation", value: null }
+        });
+    }
+    recommendations.sort((a, b) => {
+        const confidenceDiff = confidenceRank(a.confidence) - confidenceRank(b.confidence);
+        if (confidenceDiff !== 0) {
+            return confidenceDiff;
+        }
+        if (b.directImpact.files !== a.directImpact.files) {
+            return b.directImpact.files - a.directImpact.files;
+        }
+        return a.pattern.localeCompare(b.pattern);
+    });
+    const returned = recommendations.slice(0, limit);
+    return {
+        summary: {
+            filesTotal: snapshot.files.length,
+            candidatesTotal: recommendations.length,
+            candidatesReturned: returned.length,
+            truncated: returned.length < recommendations.length,
+            filesImpacted: impactedFilePaths.size
+        },
+        recommendations: returned
+    };
+}
+function classifyConfidence(generatedCount, files) {
+    if (files === 0) {
+        return "low";
+    }
+    if (generatedCount === files) {
+        return "high";
+    }
+    if (generatedCount * 2 >= files) {
+        return "medium";
+    }
+    return "low";
+}
+function buildRationale(segment, prefix, files, symbols, generatedCount) {
+    return (`Tree "${prefix}" matches the high-noise generated directory segment "${segment}" and currently contributes `
+        + `${files} indexed file(s) and ${symbols} symbol(s) (${generatedCount} file(s) already classified as generated). `
+        + "Excluding it should reduce catalogue noise. Advisory only; configuration is never written automatically.");
+}
+function confidenceRank(confidence) {
+    if (confidence === "high") {
+        return 0;
+    }
+    if (confidence === "medium") {
+        return 1;
+    }
+    return 2;
+}
+function normalizeLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_LIMIT;
+    }
+    const floored = Math.floor(value);
+    if (floored <= 0) {
+        return DEFAULT_LIMIT;
+    }
+    return floored;
+}

package/dist/queries/relationships.d.ts

@@ -0,0 +1,5 @@
+import type { CatalogueSnapshot, RelationshipRecord } from "../catalogue/schema.js";
+export declare function listRelationships(snapshot: CatalogueSnapshot): RelationshipRecord[];
+export declare function listImportRelationships(snapshot: CatalogueSnapshot): RelationshipRecord[];
+export declare function listExportRelationships(snapshot: CatalogueSnapshot): RelationshipRecord[];
+export declare function listRelationshipsByFile(snapshot: CatalogueSnapshot, filePath: string): RelationshipRecord[];

package/dist/queries/relationships.js

@@ -0,0 +1,15 @@
+export function listRelationships(snapshot) {
+    return snapshot.relationships;
+}
+export function listImportRelationships(snapshot) {
+    return snapshot.relationships.filter((relationship) => relationship.type === "imports");
+}
+export function listExportRelationships(snapshot) {
+    return snapshot.relationships.filter((relationship) => relationship.type === "exports");
+}
+export function listRelationshipsByFile(snapshot, filePath) {
+    return snapshot.relationships.filter((relationship) => {
+        return (relationship.from.kind === "file" && relationship.from.id === filePath)
+            || (relationship.to.kind === "file" && relationship.to.id === filePath);
+    });
+}

package/dist/queries/reuseCandidates.d.ts

@@ -0,0 +1,34 @@
+import type { CatalogueSnapshot } from "../catalogue/schema.js";
+import { type MatchReason } from "./ranking.js";
+export interface FindReuseCandidatesOptions {
+    query: string;
+    capabilityId?: string;
+    packageId?: string;
+    limit?: number;
+}
+export interface ReuseCandidate {
+    kind: "capability" | "publicApi";
+    id: string;
+    score: number;
+    reasons: string[];
+}
+export interface ReuseCandidateResult {
+    query: string;
+    tokens: string[];
+    candidates: ReuseCandidate[];
+}
+export declare function findReuseCandidates(snapshot: CatalogueSnapshot, options: FindReuseCandidatesOptions): ReuseCandidateResult;
+export interface RankedReuseCandidate extends ReuseCandidate {
+    matchReasons: MatchReason[];
+}
+export interface RankedReuseCandidateResult {
+    query: string;
+    tokens: string[];
+    candidates: RankedReuseCandidate[];
+}
+/**
+ * Thin wrapper over {@link findReuseCandidates} that annotates each candidate
+ * with closed-vocabulary match reasons derived from its name. Ordering and
+ * scoring are unchanged from the underlying reuse scorer.
+ */
+export declare function rankReuseCandidates(snapshot: CatalogueSnapshot, options: FindReuseCandidatesOptions): RankedReuseCandidateResult;