@mortice/mapwright 0.8.0

package/dist/queries/adoption.d.ts

@@ -0,0 +1,62 @@
+import type { CatalogueSnapshot } from "../catalogue/schema.js";
+export type AdoptionGapKind = "missing_public_api_docs" | "missing_capability_summary" | "missing_capability_examples" | "missing_capability_tests" | "missing_package_catalogue" | "unlinked_example" | "unlinked_test" | "unknown_reference";
+export interface AdoptionGap {
+    id: string;
+    severity: "info" | "warning" | "error";
+    kind: AdoptionGapKind;
+    target: {
+        kind: "package" | "capability" | "publicApi" | "symbol" | "file";
+        id: string;
+    };
+    filePath?: string;
+    message: string;
+    suggestedAction: string;
+    templateId?: DocumentationTemplateId;
+    provenance: {
+        source: "adoption-audit";
+    };
+}
+export interface AdoptionRecommendation {
+    id: string;
+    priority: "high" | "medium" | "low";
+    kind: AdoptionGapKind;
+    title: string;
+    templateId?: DocumentationTemplateId;
+    gapIds: string[];
+    targetIds: string[];
+    suggestedAction: string;
+    provenance: {
+        source: "adoption-audit";
+    };
+}
+export interface AdoptionAudit {
+    summary: {
+        publicApisTotal: number;
+        publicApisMissingDocs: number;
+        capabilitiesTotal: number;
+        capabilitiesMissingExamples: number;
+        capabilitiesMissingTests: number;
+        packagesTotal: number;
+        packagesMissingCatalogueDocs: number;
+        gapsTotal: number;
+        gapsReturned: number;
+        gapsTruncated: boolean;
+    };
+    gaps: AdoptionGap[];
+    recommendations: AdoptionRecommendation[];
+}
+export interface AdoptionPlan {
+    summary: AdoptionAudit["summary"];
+    groupedRecommendations: Array<{
+        priority: "high" | "medium" | "low";
+        recommendations: AdoptionRecommendation[];
+    }>;
+}
+export interface GetAdoptionAuditOptions {
+    includeInfo?: boolean;
+    includeGenerated?: boolean;
+    maxGaps?: number;
+}
+export type DocumentationTemplateId = "package-catalogue" | "capability-section" | "typescript-public-api-jsdoc" | "python-public-api-docstring" | "test-coverage-doc" | "example-reference";
+export declare function getAdoptionAudit(snapshot: CatalogueSnapshot, options?: GetAdoptionAuditOptions): AdoptionAudit;
+export declare function getAdoptionPlan(snapshot: CatalogueSnapshot, options?: GetAdoptionAuditOptions): AdoptionPlan;

package/dist/queries/adoption.js

@@ -0,0 +1,366 @@
+const UNKNOWN_REFERENCE_CODES = new Set([
+    "example_references_unknown_capability",
+    "example_references_unknown_public_api",
+    "example_references_ambiguous_public_api",
+    "public_api_references_unknown_capability",
+    "test_references_unknown_capability",
+    "test_references_unknown_symbol",
+    "test_references_unknown_public_api",
+    "capability_references_unknown_symbol",
+    "capability_references_unknown_public_api"
+]);
+const DEFAULT_MAX_GAPS = 500;
+const GENERATED_PROVENANCE_SOURCE_FRAGMENTS = [
+    "extractor",
+    "scanner",
+    "manifest",
+    "directory",
+    "fallback",
+    "generated",
+    "inferred"
+];
+export function getAdoptionAudit(snapshot, options = {}) {
+    const gaps = [];
+    const includeGenerated = options.includeGenerated ?? false;
+    const maxGaps = options.maxGaps ?? DEFAULT_MAX_GAPS;
+    const symbolsById = new Map(snapshot.symbols.map((symbol) => [symbol.id, symbol]));
+    const filesByPath = new Map(snapshot.files.map((file) => [file.path, file]));
+    for (const api of snapshot.publicApis) {
+        const symbol = symbolsById.get(api.symbolId);
+        if (!symbol || symbol.visibility === "private" || symbol.visibility === "test_only" || symbol.visibility === "supported_internal") {
+            continue;
+        }
+        const hasCataloguePublicApiTag = Boolean(symbol.doc?.tags?.some((tag) => tag.tag === "catalogue" && tag.value === "public-api"));
+        if (!hasCataloguePublicApiTag) {
+            const hasCapabilityLink = symbol.capabilities.length > 0 || api.capabilityIds.length > 0;
+            const hasDocBody = Boolean(symbol.doc?.present && symbol.doc.text?.trim());
+            gaps.push(createGap({
+                severity: hasCapabilityLink || hasDocBody ? "warning" : "info",
+                kind: "missing_public_api_docs",
+                targetKind: "publicApi",
+                targetId: api.id,
+                filePath: symbol.filePath,
+                message: `Public API ${api.id} is missing @catalogue public-api documentation tag.`,
+                suggestedAction: "Add a conservative public API JSDoc/docstring using TODO placeholders.",
+                templateId: symbol.language === "python" ? "python-public-api-docstring" : "typescript-public-api-jsdoc"
+            }));
+        }
+    }
+    for (const capability of snapshot.capabilities) {
+        if (!includeGenerated && isCapabilityGenerated(capability)) {
+            continue;
+        }
+        if (capability.stability === "internal" || capability.stability === "test-only") {
+            continue;
+        }
+        if (!capability.summary?.trim()) {
+            gaps.push(createGap({
+                severity: "warning",
+                kind: "missing_capability_summary",
+                targetKind: "capability",
+                targetId: capability.id,
+                filePath: capability.files[0],
+                message: `Capability ${capability.id} is missing a summary.`,
+                suggestedAction: "Add a concise factual summary to the capability section.",
+                templateId: "capability-section"
+            }));
+        }
+        if (capability.examples.length === 0) {
+            gaps.push(createGap({
+                severity: "info",
+                kind: "missing_capability_examples",
+                targetKind: "capability",
+                targetId: capability.id,
+                filePath: capability.files[0],
+                message: `Capability ${capability.id} has no linked examples.`,
+                suggestedAction: "Add metadata-only example references to the capability section.",
+                templateId: "example-reference"
+            }));
+        }
+        const hasTests = capability.tests.length > 0
+            || snapshot.tests.some((test) => test.coversCapabilities.includes(capability.id));
+        if (!hasTests) {
+            gaps.push(createGap({
+                severity: "warning",
+                kind: "missing_capability_tests",
+                targetKind: "capability",
+                targetId: capability.id,
+                filePath: capability.files[0],
+                message: `Capability ${capability.id} has no linked tests.`,
+                suggestedAction: "Link at least one test using @coversCapability or capability Tests section metadata.",
+                templateId: "test-coverage-doc"
+            }));
+        }
+    }
+    for (const pkg of snapshot.packages) {
+        if (!includeGenerated && isPackageGenerated(pkg)) {
+            continue;
+        }
+        if (isPackageCatalogueAuthored(pkg)) {
+            continue;
+        }
+        gaps.push(createGap({
+            severity: "warning",
+            kind: "missing_package_catalogue",
+            targetKind: "package",
+            targetId: pkg.id,
+            filePath: packageCataloguePath(pkg),
+            message: `Package ${pkg.id} is missing authored package catalogue metadata.`,
+            suggestedAction: "Create a CATALOGUE.md package section for this package with conservative TODO placeholders.",
+            templateId: "package-catalogue"
+        }));
+    }
+    for (const example of snapshot.examples) {
+        if (!includeGenerated && example.filePath && isFileGenerated(example.filePath, filesByPath)) {
+            continue;
+        }
+        if (example.capabilityIds.length === 0 && example.publicApiIds.length === 0) {
+            gaps.push(createGap({
+                severity: "info",
+                kind: "unlinked_example",
+                targetKind: "file",
+                targetId: example.filePath ?? example.id,
+                filePath: example.filePath,
+                message: `Example ${example.id} is not linked to a capability or public API.`,
+                suggestedAction: "Link the example to a capability and/or public API metadata reference.",
+                templateId: "example-reference"
+            }));
+        }
+    }
+    for (const test of snapshot.tests) {
+        if (!includeGenerated && isFileGenerated(test.filePath, filesByPath)) {
+            continue;
+        }
+        if (test.coversCapabilities.length === 0 && test.coversSymbols.length === 0 && test.coversPublicApis.length === 0) {
+            gaps.push(createGap({
+                severity: "info",
+                kind: "unlinked_test",
+                targetKind: "file",
+                targetId: test.filePath,
+                filePath: test.filePath,
+                message: `Test ${test.id} has no @coversCapability, @coversSymbol, or @coversPublicApi links.`,
+                suggestedAction: "Add conservative coverage tags to link this test to symbols/capabilities/public APIs.",
+                templateId: "test-coverage-doc"
+            }));
+        }
+    }
+    for (const diagnostic of snapshot.diagnostics) {
+        if (!UNKNOWN_REFERENCE_CODES.has(diagnostic.code)) {
+            continue;
+        }
+        gaps.push(gapFromUnknownReferenceDiagnostic(diagnostic));
+    }
+    const fullSortedGaps = gaps
+        .filter((gap) => (options.includeInfo ?? true) || gap.severity !== "info")
+        .sort(sortGaps);
+    const sortedGaps = fullSortedGaps.slice(0, Math.max(0, maxGaps));
+    const recommendations = buildRecommendations(sortedGaps);
+    return {
+        summary: {
+            publicApisTotal: snapshot.publicApis.length,
+            publicApisMissingDocs: fullSortedGaps.filter((gap) => gap.kind === "missing_public_api_docs").length,
+            capabilitiesTotal: snapshot.capabilities.length,
+            capabilitiesMissingExamples: fullSortedGaps.filter((gap) => gap.kind === "missing_capability_examples").length,
+            capabilitiesMissingTests: fullSortedGaps.filter((gap) => gap.kind === "missing_capability_tests").length,
+            packagesTotal: snapshot.packages.length,
+            packagesMissingCatalogueDocs: fullSortedGaps.filter((gap) => gap.kind === "missing_package_catalogue").length,
+            gapsTotal: fullSortedGaps.length,
+            gapsReturned: sortedGaps.length,
+            gapsTruncated: sortedGaps.length < fullSortedGaps.length
+        },
+        gaps: sortedGaps,
+        recommendations
+    };
+}
+export function getAdoptionPlan(snapshot, options = {}) {
+    const audit = getAdoptionAudit(snapshot, options);
+    const priorities = ["high", "medium", "low"];
+    return {
+        summary: audit.summary,
+        groupedRecommendations: priorities.map((priority) => ({
+            priority,
+            recommendations: audit.recommendations
+                .filter((recommendation) => recommendation.priority === priority)
+                .sort((a, b) => a.id.localeCompare(b.id))
+        }))
+    };
+}
+function buildRecommendations(gaps) {
+    const groups = new Map();
+    for (const gap of gaps) {
+        const key = `${gap.kind}:${gap.templateId ?? "none"}`;
+        const current = groups.get(key) ?? [];
+        current.push(gap);
+        groups.set(key, current);
+    }
+    const recommendations = [];
+    for (const [key, groupedGaps] of groups.entries()) {
+        const [kind, templateIdRaw] = key.split(":", 2);
+        const templateId = templateIdRaw === "none" ? undefined : templateIdRaw;
+        const priority = groupedGaps.some((gap) => gap.severity === "error")
+            ? "high"
+            : groupedGaps.some((gap) => gap.severity === "warning")
+                ? "medium"
+                : "low";
+        const gapIds = groupedGaps.map((gap) => gap.id).sort();
+        const targetIds = [...new Set(groupedGaps.map((gap) => gap.target.id))].sort();
+        recommendations.push({
+            id: `recommendation:${kind}:${templateId ?? "none"}`,
+            priority,
+            kind: kind,
+            title: recommendationTitle(kind),
+            templateId,
+            gapIds,
+            targetIds,
+            suggestedAction: groupedGaps[0]?.suggestedAction ?? "Review adoption gaps and fill missing documentation conservatively.",
+            provenance: {
+                source: "adoption-audit"
+            }
+        });
+    }
+    return recommendations.sort((a, b) => {
+        const priorityDiff = priorityRank(a.priority) - priorityRank(b.priority);
+        if (priorityDiff !== 0) {
+            return priorityDiff;
+        }
+        return a.id.localeCompare(b.id);
+    });
+}
+function recommendationTitle(kind) {
+    switch (kind) {
+        case "missing_public_api_docs":
+            return "Add missing public API catalogue docs";
+        case "missing_capability_summary":
+            return "Complete capability summaries";
+        case "missing_capability_examples":
+            return "Link capability examples";
+        case "missing_capability_tests":
+            return "Link capability tests";
+        case "missing_package_catalogue":
+            return "Create package CATALOGUE metadata";
+        case "unlinked_example":
+            return "Link unlinked examples";
+        case "unlinked_test":
+            return "Link unlinked tests";
+        case "unknown_reference":
+            return "Resolve unknown documentation references";
+        default:
+            return "Address adoption documentation gaps";
+    }
+}
+function gapFromUnknownReferenceDiagnostic(diagnostic) {
+    const targetKind = diagnostic.target?.kind === "package"
+        ? "package"
+        : diagnostic.target?.kind === "capability"
+            ? "capability"
+            : diagnostic.target?.kind === "publicApi"
+                ? "publicApi"
+                : diagnostic.target?.kind === "symbol"
+                    ? "symbol"
+                    : "file";
+    const targetId = diagnostic.target?.id ?? diagnostic.filePath ?? diagnostic.id;
+    return createGap({
+        severity: diagnostic.severity,
+        kind: "unknown_reference",
+        targetKind,
+        targetId,
+        filePath: diagnostic.filePath,
+        message: diagnostic.message,
+        suggestedAction: "Update documentation metadata to reference existing capabilities, symbols, and public APIs."
+    });
+}
+function createGap(input) {
+    return {
+        id: `adoption-gap:${input.kind}:${input.targetKind}:${input.targetId}`,
+        severity: input.severity,
+        kind: input.kind,
+        target: {
+            kind: input.targetKind,
+            id: input.targetId
+        },
+        filePath: input.filePath,
+        message: input.message,
+        suggestedAction: input.suggestedAction,
+        templateId: input.templateId,
+        provenance: {
+            source: "adoption-audit"
+        }
+    };
+}
+function isPackageCatalogueAuthored(pkg) {
+    const source = pkg.provenance.source.toLowerCase();
+    if (source === "catalogue-md") {
+        return true;
+    }
+    return (pkg.provenance.locations ?? []).some((location) => /(^|\/)CATALOGUE\.md$/i.test(location));
+}
+function isPackageGenerated(pkg) {
+    if (pkg.path === ".") {
+        return true;
+    }
+    return isGeneratedByProvenance(pkg.provenance.source, pkg.provenance.locations);
+}
+function isCapabilityGenerated(capability) {
+    return isGeneratedByProvenance(capability.provenance.source, capability.provenance.locations);
+}
+function isFileGenerated(filePath, filesByPath) {
+    const file = filesByPath.get(filePath);
+    if (!file) {
+        return false;
+    }
+    return file.isGenerated || file.kind === "generated";
+}
+function isGeneratedByProvenance(source, locations) {
+    const normalized = (source ?? "").toLowerCase();
+    if (normalized.includes("catalogue")) {
+        return false;
+    }
+    const locationList = locations ?? [];
+    if (locationList.some((location) => /(^|\/)CATALOGUE\.md$/i.test(location))) {
+        return false;
+    }
+    return GENERATED_PROVENANCE_SOURCE_FRAGMENTS.some((fragment) => normalized.includes(fragment));
+}
+function packageCataloguePath(pkg) {
+    if (pkg.path === ".") {
+        return "CATALOGUE.md";
+    }
+    return `${pkg.path}/CATALOGUE.md`;
+}
+function sortGaps(a, b) {
+    const severityDiff = severityRank(a.severity) - severityRank(b.severity);
+    if (severityDiff !== 0) {
+        return severityDiff;
+    }
+    const kindDiff = a.kind.localeCompare(b.kind);
+    if (kindDiff !== 0) {
+        return kindDiff;
+    }
+    const targetKindDiff = a.target.kind.localeCompare(b.target.kind);
+    if (targetKindDiff !== 0) {
+        return targetKindDiff;
+    }
+    const targetIdDiff = a.target.id.localeCompare(b.target.id);
+    if (targetIdDiff !== 0) {
+        return targetIdDiff;
+    }
+    return a.id.localeCompare(b.id);
+}
+function severityRank(severity) {
+    if (severity === "error") {
+        return 0;
+    }
+    if (severity === "warning") {
+        return 1;
+    }
+    return 2;
+}
+function priorityRank(priority) {
+    if (priority === "high") {
+        return 0;
+    }
+    if (priority === "medium") {
+        return 1;
+    }
+    return 2;
+}

package/dist/queries/capabilities.d.ts

@@ -0,0 +1,45 @@
+import type { CapabilityRecord, CatalogueSnapshot, DiagnosticRecord, ExampleRecord, PackageRecord, PublicApiRecord, SymbolRecord, TestRecord } from "../catalogue/schema.js";
+export interface ListCapabilitiesOptions {
+    stability?: CapabilityRecord["stability"];
+    limit?: number;
+    offset?: number;
+}
+export declare function listCapabilities(snapshot: CatalogueSnapshot, options?: ListCapabilitiesOptions): CapabilityRecord[];
+export interface CapabilityContextResult {
+    capability: CapabilityRecord;
+    packages: PackageRecord[];
+    publicApis: PublicApiRecord[];
+    symbols: SymbolRecord[];
+    examples: ExampleRecord[];
+    tests: TestRecord[];
+    contracts: string[];
+    limitations: string[];
+    relatedFiles: string[];
+    dependencyNeighborhoodSummary: {
+        relatedImportRelationships: number;
+        relatedExportRelationships: number;
+        neighboringFiles: string[];
+        neighboringExternalPackages: string[];
+    };
+    diagnostics: DiagnosticRecord[];
+    truncated: {
+        publicApis: boolean;
+        publicApisTotal: number;
+        symbols: boolean;
+        symbolsTotal: number;
+        examples: boolean;
+        examplesTotal: number;
+        tests: boolean;
+        testsTotal: number;
+        diagnostics: boolean;
+        diagnosticsTotal: number;
+    };
+}
+export interface CapabilityContextOptions {
+    maxPublicApis?: number;
+    maxSymbols?: number;
+    maxExamples?: number;
+    maxTests?: number;
+    maxDiagnostics?: number;
+}
+export declare function getCapabilityContext(snapshot: CatalogueSnapshot, capabilityId: string, options?: CapabilityContextOptions): CapabilityContextResult | undefined;

package/dist/queries/capabilities.js

@@ -0,0 +1,124 @@
+export function listCapabilities(snapshot, options = {}) {
+    const filtered = snapshot.capabilities.filter((capability) => {
+        if (options.stability && capability.stability !== options.stability) {
+            return false;
+        }
+        return true;
+    });
+    const offset = Math.max(0, options.offset ?? 0);
+    const limit = Math.max(1, options.limit ?? 50);
+    return filtered.slice(offset, offset + limit);
+}
+const DEFAULT_CAPABILITY_CONTEXT_LIMITS = {
+    maxPublicApis: 100,
+    maxSymbols: 200,
+    maxExamples: 100,
+    maxTests: 100,
+    maxDiagnostics: 200
+};
+export function getCapabilityContext(snapshot, capabilityId, options = {}) {
+    const limits = {
+        maxPublicApis: normalizeLimit(options.maxPublicApis, DEFAULT_CAPABILITY_CONTEXT_LIMITS.maxPublicApis),
+        maxSymbols: normalizeLimit(options.maxSymbols, DEFAULT_CAPABILITY_CONTEXT_LIMITS.maxSymbols),
+        maxExamples: normalizeLimit(options.maxExamples, DEFAULT_CAPABILITY_CONTEXT_LIMITS.maxExamples),
+        maxTests: normalizeLimit(options.maxTests, DEFAULT_CAPABILITY_CONTEXT_LIMITS.maxTests),
+        maxDiagnostics: normalizeLimit(options.maxDiagnostics, DEFAULT_CAPABILITY_CONTEXT_LIMITS.maxDiagnostics)
+    };
+    const capability = snapshot.capabilities.find((item) => item.id === capabilityId);
+    if (!capability) {
+        return undefined;
+    }
+    const allPublicApis = snapshot.publicApis.filter((api) => capability.publicApis.includes(api.id)).sort((a, b) => a.id.localeCompare(b.id));
+    const publicApis = allPublicApis.slice(0, limits.maxPublicApis);
+    const allSymbols = snapshot.symbols.filter((symbol) => capability.symbols.includes(symbol.id)).sort((a, b) => a.id.localeCompare(b.id));
+    const symbols = allSymbols.slice(0, limits.maxSymbols);
+    const packages = snapshot.packages.filter((pkg) => capability.packages.includes(pkg.id)).sort((a, b) => a.id.localeCompare(b.id));
+    const allExamples = snapshot.examples
+        .filter((example) => example.capabilityIds.includes(capability.id) || example.publicApiIds.some((apiId) => capability.publicApis.includes(apiId)))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const examples = allExamples.slice(0, limits.maxExamples);
+    const testsByCoverage = snapshot.tests.filter((test) => test.coversCapabilities.includes(capability.id));
+    const testsByReference = snapshot.tests.filter((test) => capability.tests.includes(test.filePath) || capability.tests.includes(test.id));
+    const allTests = [...new Map([...testsByCoverage, ...testsByReference].map((test) => [test.id, test])).values()].sort((a, b) => a.id.localeCompare(b.id));
+    const tests = allTests.slice(0, limits.maxTests);
+    const relatedFiles = [...new Set([
+            ...capability.files,
+            ...symbols.map((symbol) => symbol.filePath),
+            ...tests.map((test) => test.filePath),
+            ...examples.map((example) => example.filePath).filter((filePath) => Boolean(filePath))
+        ])].sort();
+    const relatedFileSet = new Set(relatedFiles);
+    const importRels = snapshot.relationships.filter((relationship) => {
+        if (relationship.type !== "imports") {
+            return false;
+        }
+        return (relationship.from.kind === "file" && relatedFileSet.has(relationship.from.id))
+            || (relationship.to.kind === "file" && relatedFileSet.has(relationship.to.id));
+    });
+    const exportRels = snapshot.relationships.filter((relationship) => {
+        if (relationship.type !== "exports") {
+            return false;
+        }
+        return (relationship.from.kind === "file" && relatedFileSet.has(relationship.from.id))
+            || (relationship.to.kind === "file" && relatedFileSet.has(relationship.to.id));
+    });
+    const neighboringFiles = [...new Set(importRels
+            .flatMap((relationship) => [relationship.from, relationship.to])
+            .filter((endpoint) => endpoint.kind === "file")
+            .map((endpoint) => endpoint.id)
+            .filter((filePath) => !relatedFileSet.has(filePath)))].sort();
+    const neighboringExternalPackages = [...new Set(importRels
+            .flatMap((relationship) => [relationship.from, relationship.to])
+            .filter((endpoint) => endpoint.kind === "externalPackage")
+            .map((endpoint) => endpoint.id))].sort();
+    const allDiagnostics = snapshot.diagnostics.filter((diagnostic) => {
+        if (diagnostic.target?.kind === "capability" && diagnostic.target.id === capability.id) {
+            return true;
+        }
+        if (diagnostic.filePath && relatedFileSet.has(diagnostic.filePath)) {
+            return true;
+        }
+        return false;
+    }).sort((a, b) => a.id.localeCompare(b.id));
+    const diagnostics = allDiagnostics.slice(0, limits.maxDiagnostics);
+    return {
+        capability,
+        packages,
+        publicApis,
+        symbols,
+        examples,
+        tests,
+        contracts: [...new Set(capability.contracts)].sort(),
+        limitations: [...new Set(capability.limitations)].sort(),
+        relatedFiles,
+        dependencyNeighborhoodSummary: {
+            relatedImportRelationships: importRels.length,
+            relatedExportRelationships: exportRels.length,
+            neighboringFiles,
+            neighboringExternalPackages
+        },
+        diagnostics,
+        truncated: {
+            publicApis: publicApis.length < allPublicApis.length,
+            publicApisTotal: allPublicApis.length,
+            symbols: symbols.length < allSymbols.length,
+            symbolsTotal: allSymbols.length,
+            examples: examples.length < allExamples.length,
+            examplesTotal: allExamples.length,
+            tests: tests.length < allTests.length,
+            testsTotal: allTests.length,
+            diagnostics: diagnostics.length < allDiagnostics.length,
+            diagnosticsTotal: allDiagnostics.length
+        }
+    };
+}
+function normalizeLimit(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    const normalized = Math.floor(value);
+    if (normalized <= 0) {
+        return fallback;
+    }
+    return normalized;
+}

package/dist/queries/changes.d.ts

@@ -0,0 +1,33 @@
+import type { ChangeRecord, ComparisonSnapshot, CompatibilityFinding, RecordDomain } from "../comparison/schema.js";
+export declare function getChangeSummary(comparison: ComparisonSnapshot): Record<string, unknown>;
+export declare function listChanges(comparison: ComparisonSnapshot, options?: {
+    domain?: RecordDomain;
+    status?: ChangeRecord["status"];
+    offset?: number;
+    limit?: number;
+}): {
+    total: number;
+    returned: number;
+    offset: number;
+    limit: number;
+    truncated: boolean;
+    records: ChangeRecord[];
+};
+export declare function getChange(comparison: ComparisonSnapshot, changeId: string): ChangeRecord | null;
+export declare function getCompatibilityReport(comparison: ComparisonSnapshot, options?: {
+    offset?: number;
+    limit?: number;
+}): {
+    aggregate: ComparisonSnapshot["manifest"]["aggregateCompatibility"];
+    total: number;
+    returned: number;
+    offset: number;
+    limit: number;
+    truncated: boolean;
+    findings: CompatibilityFinding[];
+};
+export declare function getChangeImpact(comparison: ComparisonSnapshot, changeId: string, options?: {
+    maxDepth?: number;
+    limit?: number;
+    offset?: number;
+}): import("../comparison/schema.js").ChangeImpactResult | null;

package/dist/queries/changes.js

@@ -0,0 +1,53 @@
+import { orderChangeRecords, orderCompatibilityFindings } from "../comparison/ordering.js";
+import { getChangeImpact as impactGetChangeImpact } from "../comparison/impact.js";
+export function getChangeSummary(comparison) {
+    return {
+        comparisonId: comparison.manifest.comparisonId,
+        counts: comparison.manifest.counts,
+        aggregateCompatibility: comparison.manifest.aggregateCompatibility,
+        baseCatalogueId: comparison.manifest.baseCatalogueId,
+        headCatalogueId: comparison.manifest.headCatalogueId,
+        baseGeneratorVersion: comparison.manifest.baseGeneratorVersion,
+        headGeneratorVersion: comparison.manifest.headGeneratorVersion,
+        comparisonGeneratorVersion: comparison.manifest.comparisonGeneratorVersion
+    };
+}
+export function listChanges(comparison, options) {
+    const offset = options?.offset ?? 0;
+    const limit = Math.min(options?.limit ?? 50, 200);
+    let records = orderChangeRecords(comparison.changes).filter((c) => c.status !== "unchanged");
+    if (options?.domain)
+        records = records.filter((c) => c.domain === options.domain);
+    if (options?.status)
+        records = records.filter((c) => c.status === options.status);
+    const slice = records.slice(offset, offset + limit);
+    return {
+        total: records.length,
+        returned: slice.length,
+        offset,
+        limit,
+        truncated: offset + slice.length < records.length,
+        records: slice
+    };
+}
+export function getChange(comparison, changeId) {
+    return comparison.changes.find((c) => c.id === changeId) ?? null;
+}
+export function getCompatibilityReport(comparison, options) {
+    const offset = options?.offset ?? 0;
+    const limit = Math.min(options?.limit ?? 50, 200);
+    const findings = orderCompatibilityFindings(comparison.compatibilityFindings);
+    const slice = findings.slice(offset, offset + limit);
+    return {
+        aggregate: comparison.manifest.aggregateCompatibility,
+        total: findings.length,
+        returned: slice.length,
+        offset,
+        limit,
+        truncated: offset + slice.length < findings.length,
+        findings: slice
+    };
+}
+export function getChangeImpact(comparison, changeId, options) {
+    return impactGetChangeImpact(comparison, changeId, options);
+}