@mortice/mapwright 0.8.0

package/dist/queries/dependencies.d.ts

@@ -0,0 +1,17 @@
+import type { CatalogueSnapshot, RelationshipRecord } from "../catalogue/schema.js";
+export interface DependencyNeighborhoodOptions {
+    path: string;
+    depth?: number;
+    direction?: "imports" | "imported_by" | "both";
+}
+export interface DependencyNeighborhoodNode {
+    kind: "file" | "externalPackage";
+    id: string;
+    packageId?: string;
+}
+export interface DependencyNeighborhoodResult {
+    root: string;
+    nodes: DependencyNeighborhoodNode[];
+    relationships: RelationshipRecord[];
+}
+export declare function getDependencyNeighborhood(snapshot: CatalogueSnapshot, options: DependencyNeighborhoodOptions): DependencyNeighborhoodResult;

package/dist/queries/dependencies.js

@@ -0,0 +1,94 @@
+export function getDependencyNeighborhood(snapshot, options) {
+    const root = options.path.replaceAll("\\", "/");
+    const depth = Math.max(0, options.depth ?? 1);
+    const direction = options.direction ?? "both";
+    const rootNodeId = root;
+    const packageByFilePath = new Map();
+    for (const packageRecord of snapshot.packages) {
+        for (const modulePath of packageRecord.modules ?? []) {
+            packageByFilePath.set(modulePath, packageRecord.id);
+        }
+        for (const publicPath of packageRecord.publicPaths ?? []) {
+            packageByFilePath.set(publicPath, packageRecord.id);
+        }
+        if (packageRecord.path && packageRecord.path !== ".") {
+            for (const file of snapshot.files) {
+                if (file.path === packageRecord.path || file.path.startsWith(`${packageRecord.path}/`)) {
+                    packageByFilePath.set(file.path, packageRecord.id);
+                }
+            }
+        }
+        else {
+            for (const file of snapshot.files) {
+                if (!packageByFilePath.has(file.path)) {
+                    packageByFilePath.set(file.path, packageRecord.id);
+                }
+            }
+        }
+    }
+    const adjacency = new Map();
+    for (const relationship of snapshot.relationships) {
+        if (relationship.type !== "imports") {
+            continue;
+        }
+        if (relationship.from.kind === "file") {
+            const fromId = relationship.from.id;
+            const toId = relationship.to.id;
+            const list = adjacency.get(fromId) ?? [];
+            list.push({ relationship, nextId: toId });
+            adjacency.set(fromId, list);
+        }
+        if (relationship.to.kind === "file") {
+            const fromId = relationship.from.id;
+            const toId = relationship.to.id;
+            const reverseList = adjacency.get(toId) ?? [];
+            reverseList.push({ relationship, nextId: fromId });
+            adjacency.set(toId, reverseList);
+        }
+    }
+    const visited = new Set([rootNodeId]);
+    const frontier = [{ id: rootNodeId, remainingDepth: depth }];
+    const selectedRelationships = [];
+    const selectedRelationshipIds = new Set();
+    while (frontier.length > 0) {
+        const current = frontier.shift();
+        if (!current || current.remainingDepth <= 0) {
+            continue;
+        }
+        const edges = adjacency.get(current.id) ?? [];
+        for (const edge of edges) {
+            const relationship = edge.relationship;
+            const isForward = relationship.from.id === current.id;
+            const allowsForward = direction === "imports" || direction === "both";
+            const allowsReverse = direction === "imported_by" || direction === "both";
+            if ((isForward && !allowsForward) || (!isForward && !allowsReverse)) {
+                continue;
+            }
+            if (!selectedRelationshipIds.has(relationship.id)) {
+                selectedRelationshipIds.add(relationship.id);
+                selectedRelationships.push(relationship);
+            }
+            if (!visited.has(edge.nextId)) {
+                visited.add(edge.nextId);
+                frontier.push({ id: edge.nextId, remainingDepth: current.remainingDepth - 1 });
+            }
+        }
+    }
+    const nodes = [];
+    for (const nodeId of visited) {
+        if (nodeId === rootNodeId || snapshot.files.some((file) => file.path === nodeId)) {
+            nodes.push({ kind: "file", id: nodeId, packageId: packageByFilePath.get(nodeId) });
+            continue;
+        }
+        if (nodeId.startsWith("external:")) {
+            nodes.push({ kind: "externalPackage", id: nodeId });
+        }
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    selectedRelationships.sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        root,
+        nodes,
+        relationships: selectedRelationships
+    };
+}

package/dist/queries/dogfood.d.ts

@@ -0,0 +1,50 @@
+import type { CatalogueSnapshot, DiagnosticRecord } from "../catalogue/schema.js";
+import { type AdoptionAudit, type AdoptionGap } from "./adoption.js";
+export interface DogfoodReportOptions {
+    workspace?: string;
+    maxDiagnostics?: number;
+    maxGaps?: number;
+}
+export interface DogfoodReport {
+    workspace?: string;
+    catalogueId: string;
+    packageCount: number;
+    stats: CatalogueSnapshot["stats"];
+    diagnostics: {
+        total: number;
+        bySeverity: {
+            info: number;
+            warning: number;
+            error: number;
+        };
+        topCodes: Array<{
+            code: string;
+            count: number;
+        }>;
+        topDiagnostics: Array<{
+            id: string;
+            severity: DiagnosticRecord["severity"];
+            code: string;
+            message: string;
+            filePath?: string;
+            target?: DiagnosticRecord["target"];
+        }>;
+    };
+    adoption: {
+        summary: AdoptionAudit["summary"];
+        topGapKinds: Array<{
+            kind: AdoptionGap["kind"];
+            count: number;
+        }>;
+        topGaps: AdoptionGap[];
+    };
+    limits: {
+        diagnosticsShown: number;
+        gapsShown: number;
+    };
+    estimatedBytes: number;
+    provenance: {
+        source: "mapwright";
+    };
+}
+export declare function getDogfoodReport(snapshot: CatalogueSnapshot, options?: DogfoodReportOptions): DogfoodReport;

package/dist/queries/dogfood.js

@@ -0,0 +1,116 @@
+import { getAdoptionAudit } from "./adoption.js";
+export function getDogfoodReport(snapshot, options = {}) {
+    const maxDiagnostics = Math.max(0, options.maxDiagnostics ?? 20);
+    const maxGaps = Math.max(0, options.maxGaps ?? 20);
+    const diagnostics = [...snapshot.diagnostics].sort(sortDiagnostics);
+    const audit = getAdoptionAudit(snapshot, {
+        includeInfo: true,
+        includeGenerated: false,
+        maxGaps: Number.MAX_SAFE_INTEGER
+    });
+    const diagnosticTotals = countBySeverity(diagnostics);
+    const topDiagnosticCodes = buildTopDiagnosticCodes(diagnostics);
+    const topDiagnostics = diagnostics.slice(0, maxDiagnostics).map((diagnostic) => ({
+        id: diagnostic.id,
+        severity: diagnostic.severity,
+        code: diagnostic.code,
+        message: diagnostic.message,
+        filePath: diagnostic.filePath,
+        target: diagnostic.target
+    }));
+    const topGapKinds = buildTopGapKinds(audit.gaps);
+    const topGaps = audit.gaps.slice(0, maxGaps);
+    const report = {
+        workspace: options.workspace,
+        catalogueId: snapshot.catalogueId,
+        packageCount: snapshot.packages.length,
+        stats: snapshot.stats,
+        diagnostics: {
+            total: diagnostics.length,
+            bySeverity: diagnosticTotals,
+            topCodes: topDiagnosticCodes,
+            topDiagnostics
+        },
+        adoption: {
+            summary: audit.summary,
+            topGapKinds,
+            topGaps
+        },
+        limits: {
+            diagnosticsShown: maxDiagnostics,
+            gapsShown: maxGaps
+        },
+        estimatedBytes: estimateReportSize(snapshot, diagnostics.length, audit.gaps.length, maxDiagnostics, maxGaps),
+        provenance: {
+            source: "mapwright"
+        }
+    };
+    return report;
+}
+function sortDiagnostics(a, b) {
+    const severityDiff = severityRank(a.severity) - severityRank(b.severity);
+    if (severityDiff !== 0) {
+        return severityDiff;
+    }
+    const codeDiff = a.code.localeCompare(b.code);
+    if (codeDiff !== 0) {
+        return codeDiff;
+    }
+    return a.id.localeCompare(b.id);
+}
+function severityRank(severity) {
+    if (severity === "error") {
+        return 0;
+    }
+    if (severity === "warning") {
+        return 1;
+    }
+    return 2;
+}
+function countBySeverity(diagnostics) {
+    const counts = { info: 0, warning: 0, error: 0 };
+    for (const diagnostic of diagnostics) {
+        counts[diagnostic.severity] += 1;
+    }
+    return counts;
+}
+function buildTopDiagnosticCodes(diagnostics) {
+    const counts = new Map();
+    for (const diagnostic of diagnostics) {
+        counts.set(diagnostic.code, (counts.get(diagnostic.code) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([code, count]) => ({ code, count }))
+        .sort((a, b) => {
+        const countDiff = b.count - a.count;
+        if (countDiff !== 0) {
+            return countDiff;
+        }
+        return a.code.localeCompare(b.code);
+    });
+}
+function buildTopGapKinds(gaps) {
+    const counts = new Map();
+    for (const gap of gaps) {
+        counts.set(gap.kind, (counts.get(gap.kind) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([kind, count]) => ({ kind, count }))
+        .sort((a, b) => {
+        const countDiff = b.count - a.count;
+        if (countDiff !== 0) {
+            return countDiff;
+        }
+        return a.kind.localeCompare(b.kind);
+    });
+}
+function estimateReportSize(snapshot, diagnosticsTotal, gapsTotal, diagnosticsShown, gapsShown) {
+    return JSON.stringify({
+        catalogueId: snapshot.catalogueId,
+        diagnosticsTotal,
+        gapsTotal,
+        diagnosticsShown,
+        gapsShown,
+        stats: snapshot.stats
+    }).length;
+}

package/dist/queries/editingContext.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Bounded, opt-in editing context (Gate 4).
+ *
+ * Assembles a compact, advisory "what should I know before editing this?"
+ * bundle for a public API or symbol. Every list-like section carries its own
+ * `{ total, returned, truncated, records }` budget so callers always know which
+ * section was cut, and no section can emit an unbounded graph.
+ *
+ * Edges are resolved to canonical symbol endpoints where possible so that
+ * dependency/dependant references point at authored declarations rather than
+ * generated duplicates. This helper is read-only and never mutates the
+ * snapshot; its output is advisory context, not authoritative coverage.
+ */
+import type { CatalogueSnapshot, PublicApiRecord, RelationshipType, SymbolRecord } from "../catalogue/schema.js";
+/** Small per-section default budget (kept intentionally tight). */
+export declare const DEFAULT_EDITING_CONTEXT_LIMIT = 6;
+/** Maximum per-section budget a caller may request. */
+export declare const MAX_EDITING_CONTEXT_LIMIT = 25;
+/** Human-readable advisory attached to every editing-context payload. */
+export declare const EDITING_CONTEXT_ADVISORY: string;
+export interface EditingContextSection<T> {
+    total: number;
+    returned: number;
+    truncated: boolean;
+    records: T[];
+}
+export interface EditingContextRef {
+    kind: "symbol" | "publicApi" | "file" | "package" | "capability" | "test" | "example" | "externalPackage";
+    id: string;
+    name?: string;
+    /** Present when the referenced endpoint resolves to a canonical declaration. */
+    canonicalSymbolId?: string;
+    /** Import path for public entrypoints. */
+    importPath?: string;
+    /** Export kind for public entrypoints. */
+    exportKind?: PublicApiRecord["exportKind"];
+    /** Relationship type when the record represents an edge. */
+    relationshipType?: RelationshipType;
+}
+export interface EditingContextDefinition {
+    symbolId?: string;
+    publicApiId?: string;
+    name: string;
+    kind?: SymbolRecord["kind"];
+    qualifiedName?: string;
+    filePath?: string;
+    language?: string;
+    visibility?: SymbolRecord["visibility"];
+    exported?: boolean;
+    canonicalSymbolId?: string;
+    range?: SymbolRecord["range"];
+}
+export interface EditingContextPackage {
+    id: string;
+    name: string;
+    path: string;
+    ecosystem?: string;
+}
+export interface EditingContext {
+    advisory: string;
+    perSectionLimit: number;
+    definition: EditingContextDefinition | null;
+    owningPackage: EditingContextPackage | null;
+    publicEntrypoints: EditingContextSection<EditingContextRef>;
+    reExportChain: EditingContextSection<EditingContextRef>;
+    dependencies: EditingContextSection<EditingContextRef>;
+    dependants: EditingContextSection<EditingContextRef>;
+    tests: EditingContextSection<EditingContextRef>;
+    examples: EditingContextSection<EditingContextRef>;
+    capabilities: EditingContextSection<EditingContextRef>;
+    contracts: EditingContextSection<string>;
+    limitations: EditingContextSection<string>;
+    diagnostics: EditingContextSection<EditingContextRef>;
+}
+export interface EditingContextFocus {
+    symbol?: SymbolRecord;
+    publicApi?: PublicApiRecord;
+}
+export interface BuildEditingContextOptions {
+    /** Per-section budget; clamped to [1, MAX_EDITING_CONTEXT_LIMIT]. */
+    perSectionLimit?: number;
+}
+export declare function normalizeEditingContextLimit(value: number | undefined): number;
+export declare function buildEditingContext(snapshot: CatalogueSnapshot, focus: EditingContextFocus, options?: BuildEditingContextOptions): EditingContext;

package/dist/queries/editingContext.js

@@ -0,0 +1,240 @@
+/** Small per-section default budget (kept intentionally tight). */
+export const DEFAULT_EDITING_CONTEXT_LIMIT = 6;
+/** Maximum per-section budget a caller may request. */
+export const MAX_EDITING_CONTEXT_LIMIT = 25;
+/** Human-readable advisory attached to every editing-context payload. */
+export const EDITING_CONTEXT_ADVISORY = "Advisory editing context. Sections are bounded per-section and may be truncated; "
+    + "inferred edges are not authoritative coverage. Use the canonical list/search tools for complete data.";
+const EDGE_TYPES = ["imports", "resolved_direct_import", "resolved_direct_usage"];
+export function normalizeEditingContextLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_EDITING_CONTEXT_LIMIT;
+    }
+    const floored = Math.floor(value);
+    if (floored <= 0) {
+        return DEFAULT_EDITING_CONTEXT_LIMIT;
+    }
+    return Math.min(floored, MAX_EDITING_CONTEXT_LIMIT);
+}
+export function buildEditingContext(snapshot, focus, options = {}) {
+    const perSectionLimit = normalizeEditingContextLimit(options.perSectionLimit);
+    const symbolsById = new Map(snapshot.symbols.map((symbol) => [symbol.id, symbol]));
+    const publicApi = focus.publicApi
+        ?? (focus.symbol?.publicApi ? snapshot.publicApis.find((api) => api.id === focus.symbol.publicApi) : undefined);
+    const symbol = focus.symbol
+        ?? (publicApi ? symbolsById.get(publicApi.symbolId) : undefined);
+    const filePath = symbol?.filePath;
+    const focusSymbolIds = new Set();
+    if (symbol) {
+        focusSymbolIds.add(symbol.id);
+        if (symbol.canonicalSymbolId) {
+            focusSymbolIds.add(symbol.canonicalSymbolId);
+        }
+    }
+    const focusPublicApiId = publicApi?.id;
+    const canonicalize = (symbolId) => {
+        const record = symbolsById.get(symbolId);
+        return record?.canonicalSymbolId ?? symbolId;
+    };
+    const refFromEndpoint = (endpoint, relationshipType) => {
+        if (endpoint.kind === "symbol") {
+            const canonicalSymbolId = canonicalize(endpoint.id);
+            const record = symbolsById.get(canonicalSymbolId) ?? symbolsById.get(endpoint.id);
+            return {
+                kind: "symbol",
+                id: canonicalSymbolId,
+                name: record?.name,
+                canonicalSymbolId,
+                relationshipType
+            };
+        }
+        if (endpoint.kind === "file"
+            || endpoint.kind === "externalPackage"
+            || endpoint.kind === "package"
+            || endpoint.kind === "publicApi"
+            || endpoint.kind === "capability"
+            || endpoint.kind === "test") {
+            return { kind: endpoint.kind, id: endpoint.id, relationshipType };
+        }
+        return undefined;
+    };
+    const endpointMatchesFocus = (endpoint) => {
+        if (endpoint.kind === "symbol") {
+            return focusSymbolIds.has(endpoint.id) || focusSymbolIds.has(canonicalize(endpoint.id));
+        }
+        if (endpoint.kind === "publicApi") {
+            return focusPublicApiId !== undefined && endpoint.id === focusPublicApiId;
+        }
+        if (endpoint.kind === "file") {
+            return filePath !== undefined && endpoint.id === filePath;
+        }
+        return false;
+    };
+    const dependencyRefs = [];
+    const dependantRefs = [];
+    const reExportRefs = [];
+    for (const relationship of snapshot.relationships) {
+        if (relationship.type === "exports") {
+            if (endpointMatchesFocus(relationship.from) || endpointMatchesFocus(relationship.to)) {
+                const other = endpointMatchesFocus(relationship.from) ? relationship.to : relationship.from;
+                const ref = refFromEndpoint(other, relationship.type);
+                if (ref) {
+                    reExportRefs.push(ref);
+                }
+            }
+            continue;
+        }
+        if (!EDGE_TYPES.includes(relationship.type)) {
+            continue;
+        }
+        if (endpointMatchesFocus(relationship.from)) {
+            const ref = refFromEndpoint(relationship.to, relationship.type);
+            if (ref) {
+                dependencyRefs.push(ref);
+            }
+        }
+        if (endpointMatchesFocus(relationship.to)) {
+            const ref = refFromEndpoint(relationship.from, relationship.type);
+            if (ref) {
+                dependantRefs.push(ref);
+            }
+        }
+    }
+    const owningPackage = resolveOwningPackage(snapshot, symbol, publicApi);
+    const publicEntrypointRefs = owningPackage
+        ? snapshot.publicApis
+            .filter((api) => api.packageId === owningPackage.id)
+            .map((api) => ({
+            kind: "publicApi",
+            id: api.id,
+            name: api.name,
+            importPath: api.importPath,
+            exportKind: api.exportKind
+        }))
+        : [];
+    const testRefs = snapshot.tests
+        .filter((test) => {
+        if (publicApi && test.coversPublicApis.includes(publicApi.id))
+            return true;
+        if (publicApi && (publicApi.tests.includes(test.id) || publicApi.tests.includes(test.filePath)))
+            return true;
+        if (symbol && test.coversSymbols.some((id) => focusSymbolIds.has(id) || focusSymbolIds.has(canonicalize(id))))
+            return true;
+        return false;
+    })
+        .map((test) => ({ kind: "test", id: test.id, name: test.name }));
+    const exampleRefs = snapshot.examples
+        .filter((example) => {
+        if (publicApi && example.publicApiIds.includes(publicApi.id))
+            return true;
+        if (symbol && example.symbolIds.some((id) => focusSymbolIds.has(id) || focusSymbolIds.has(canonicalize(id))))
+            return true;
+        return false;
+    })
+        .map((example) => ({ kind: "example", id: example.id, name: example.title }));
+    const capabilityIds = new Set([
+        ...(publicApi?.capabilityIds ?? []),
+        ...(symbol?.capabilities ?? [])
+    ]);
+    const capabilityRefs = snapshot.capabilities
+        .filter((capability) => capabilityIds.has(capability.id))
+        .map((capability) => ({ kind: "capability", id: capability.id, name: capability.name }));
+    const linkedCapabilities = snapshot.capabilities.filter((capability) => capabilityIds.has(capability.id));
+    const contracts = [
+        ...new Set([
+            ...(publicApi?.contracts ?? []),
+            ...linkedCapabilities.flatMap((capability) => capability.contracts)
+        ])
+    ].filter((value) => value.trim().length > 0);
+    const limitations = [
+        ...new Set(linkedCapabilities.flatMap((capability) => capability.limitations))
+    ].filter((value) => value.trim().length > 0);
+    const diagnosticRefs = snapshot.diagnostics
+        .filter((diagnostic) => {
+        if (publicApi && diagnostic.target?.kind === "publicApi" && diagnostic.target.id === publicApi.id)
+            return true;
+        if (symbol && diagnostic.target?.kind === "symbol"
+            && (focusSymbolIds.has(diagnostic.target.id) || focusSymbolIds.has(canonicalize(diagnostic.target.id))))
+            return true;
+        if (filePath && diagnostic.filePath === filePath)
+            return true;
+        return false;
+    })
+        .map((diagnostic) => ({ kind: "file", id: diagnostic.id, name: diagnostic.code }));
+    return {
+        advisory: EDITING_CONTEXT_ADVISORY,
+        perSectionLimit,
+        definition: buildDefinition(symbol, publicApi),
+        owningPackage,
+        publicEntrypoints: toSection(dedupeRefs(publicEntrypointRefs), perSectionLimit),
+        reExportChain: toSection(dedupeRefs(reExportRefs), perSectionLimit),
+        dependencies: toSection(dedupeRefs(dependencyRefs), perSectionLimit),
+        dependants: toSection(dedupeRefs(dependantRefs), perSectionLimit),
+        tests: toSection(dedupeRefs(testRefs), perSectionLimit),
+        examples: toSection(dedupeRefs(exampleRefs), perSectionLimit),
+        capabilities: toSection(dedupeRefs(capabilityRefs), perSectionLimit),
+        contracts: toStringSection(contracts.sort((a, b) => a.localeCompare(b)), perSectionLimit),
+        limitations: toStringSection(limitations.sort((a, b) => a.localeCompare(b)), perSectionLimit),
+        diagnostics: toSection(dedupeRefs(diagnosticRefs), perSectionLimit)
+    };
+}
+function buildDefinition(symbol, publicApi) {
+    if (!symbol && !publicApi) {
+        return null;
+    }
+    return {
+        symbolId: symbol?.id,
+        publicApiId: publicApi?.id,
+        name: symbol?.name ?? publicApi?.name ?? "",
+        kind: symbol?.kind,
+        qualifiedName: symbol?.qualifiedName,
+        filePath: symbol?.filePath,
+        language: symbol?.language,
+        visibility: symbol?.visibility,
+        exported: symbol?.exported,
+        canonicalSymbolId: symbol?.canonicalSymbolId,
+        range: symbol?.range
+    };
+}
+function resolveOwningPackage(snapshot, symbol, publicApi) {
+    const packageId = publicApi?.packageId ?? symbol?.packageId;
+    let pkg = packageId ? snapshot.packages.find((candidate) => candidate.id === packageId) : undefined;
+    if (!pkg && symbol?.filePath) {
+        const candidates = snapshot.packages.filter((candidate) => {
+            if (candidate.path === ".")
+                return true;
+            return symbol.filePath === candidate.path || symbol.filePath.startsWith(`${candidate.path}/`);
+        });
+        candidates.sort((a, b) => b.path.length - a.path.length || a.id.localeCompare(b.id));
+        pkg = candidates[0];
+    }
+    if (!pkg) {
+        return null;
+    }
+    return { id: pkg.id, name: pkg.name, path: pkg.path, ecosystem: pkg.ecosystem };
+}
+function refSortKey(ref) {
+    return [ref.kind, ref.relationshipType ?? "", ref.id].join("\u0000");
+}
+function dedupeRefs(refs) {
+    const byKey = new Map();
+    for (const ref of refs) {
+        const key = refSortKey(ref);
+        if (!byKey.has(key)) {
+            byKey.set(key, ref);
+        }
+    }
+    return [...byKey.values()].sort((a, b) => refSortKey(a).localeCompare(refSortKey(b)));
+}
+function toSection(records, limit) {
+    const sliced = records.slice(0, limit);
+    return {
+        total: records.length,
+        returned: sliced.length,
+        truncated: sliced.length < records.length,
+        records: sliced
+    };
+}
+function toStringSection(records, limit) {
+    return toSection(records, limit);
+}

package/dist/queries/examples.d.ts

@@ -0,0 +1,8 @@
+import type { CatalogueSnapshot, ExampleRecord } from "../catalogue/schema.js";
+export interface ListExamplesOptions {
+    capabilityId?: string;
+    publicApiId?: string;
+    limit?: number;
+    offset?: number;
+}
+export declare function listExamples(snapshot: CatalogueSnapshot, options?: ListExamplesOptions): ExampleRecord[];

package/dist/queries/examples.js

@@ -0,0 +1,16 @@
+export function listExamples(snapshot, options = {}) {
+    const filtered = snapshot.examples
+        .filter((example) => {
+        if (options.capabilityId && !example.capabilityIds.includes(options.capabilityId)) {
+            return false;
+        }
+        if (options.publicApiId && !example.publicApiIds.includes(options.publicApiId)) {
+            return false;
+        }
+        return true;
+    })
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const offset = Math.max(0, Math.floor(options.offset ?? 0));
+    const limit = Math.max(1, Math.floor(options.limit ?? 50));
+    return filtered.slice(offset, offset + limit);
+}

package/dist/queries/files.d.ts

@@ -0,0 +1,8 @@
+import type { CatalogueSnapshot, FileRecord } from "../catalogue/schema.js";
+export interface ListFilesOptions {
+    language?: string;
+    kind?: FileRecord["kind"];
+    limit?: number;
+    offset?: number;
+}
+export declare function listFiles(snapshot: CatalogueSnapshot, options?: ListFilesOptions): FileRecord[];

package/dist/queries/files.js

@@ -0,0 +1,14 @@
+export function listFiles(snapshot, options = {}) {
+    const filtered = snapshot.files.filter((file) => {
+        if (options.language && file.language !== options.language) {
+            return false;
+        }
+        if (options.kind && file.kind !== options.kind) {
+            return false;
+        }
+        return true;
+    });
+    const offset = Math.max(0, options.offset ?? 0);
+    const limit = Math.max(1, options.limit ?? 100);
+    return filtered.slice(offset, offset + limit);
+}