wiki-formant 0.1.2

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/mcp.js

@@ -0,0 +1,317 @@
+// mcp.ts — a minimal Model Context Protocol server over Streamable HTTP
+// (JSON-RPC). Spec: https://modelcontextprotocol.io/specification/2025-03-26
+//
+// Web-standard `Request`/`Response` only, so this runs unchanged on Next route
+// handlers (NextResponse extends Response), Hono, Bun, Deno and workers.
+//
+// Two things exist here purely so a caller that gets it wrong gets it right on
+// the retry: `inputSchema` is a shape this module actually validates against —
+// naming the bad field and enumerating the legal values rather than coercing
+// junk and returning an empty result — and `instructions` rides on `initialize`
+// so an agent learns the intended call sequence before it has to guess.
+//
+// A caller-fixable mistake is a tool result with `isError`, never a -32603.
+// That split is the one most implementations get wrong.
+export const MCP_PROTOCOL_VERSION = '2025-03-26';
+/**
+ * A caller-fixable failure inside a handler (page not found, empty input).
+ * Reported as a tool result with `isError` so the model sees the text and can
+ * correct itself, per the spec's split between protocol and execution errors.
+ */
+export class McpToolError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'McpToolError';
+    }
+}
+const DEFAULT_MAX_BATCH = 20;
+const quote = (list) => list.map(s => `"${s}"`).join(', ');
+function typeOf(v) {
+    if (Array.isArray(v))
+        return 'array';
+    if (v === null)
+        return 'null';
+    return typeof v;
+}
+const rpcError = (id, code, message, data) => ({
+    jsonrpc: '2.0',
+    id,
+    error: { code, message, ...(data ? { data } : {}) },
+});
+const toolText = (id, text, isError = false) => ({
+    jsonrpc: '2.0',
+    id,
+    result: { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) },
+});
+/**
+ * Every problem with the call at once, each naming the field and its legal
+ * values, plus the schema — one retry should be able to fix all of them.
+ */
+function validateArgs(tool, args) {
+    const { properties, required = [] } = tool.inputSchema;
+    const allowed = Object.keys(properties);
+    const problems = [];
+    for (const key of Object.keys(args)) {
+        if (key in properties)
+            continue;
+        problems.push(allowed.length
+            ? `Unknown parameter "${key}". Allowed parameters: ${quote(allowed)}.`
+            : `Unknown parameter "${key}". This tool takes no parameters.`);
+    }
+    for (const key of required) {
+        if (args[key] === undefined || args[key] === null) {
+            problems.push(`Missing required parameter "${key}". Required: ${quote(required)}.`);
+        }
+    }
+    for (const [key, spec] of Object.entries(properties)) {
+        const value = args[key];
+        if (value === undefined || value === null)
+            continue;
+        const actual = typeOf(value);
+        if (spec.type === 'number') {
+            // A numeric string is accepted — some clients stringify everything.
+            const numeric = actual === 'number' ||
+                (actual === 'string' && String(value).trim() !== '' && Number.isFinite(Number(value)));
+            if (!numeric) {
+                problems.push(`Parameter "${key}" must be a number; received ${actual} (${JSON.stringify(value)}).`);
+            }
+        }
+        else if (spec.type === 'array') {
+            const itemType = spec.items?.type ?? 'string';
+            if (actual !== 'array') {
+                problems.push(`Parameter "${key}" must be an array of ${itemType}s; received ${actual} (${JSON.stringify(value)}).`);
+            }
+            else if (value.some(item => typeof item !== itemType)) {
+                problems.push(`Parameter "${key}" must contain only ${itemType}s.`);
+            }
+        }
+        else if (actual !== spec.type) {
+            problems.push(`Parameter "${key}" must be a ${spec.type}; received ${actual} (${JSON.stringify(value)}).`);
+        }
+        else if (spec.enum && !spec.enum.includes(value)) {
+            problems.push(`Parameter "${key}" must be one of ${quote(spec.enum)}; received ${JSON.stringify(value)}.`);
+        }
+    }
+    if (!problems.length)
+        return null;
+    return [
+        `Invalid arguments for ${tool.name}:`,
+        ...problems.map(p => `- ${p}`),
+        '',
+        `Expected schema: ${JSON.stringify(tool.inputSchema)}`,
+    ].join('\n');
+}
+const BASE_METHODS = ['initialize', 'ping', 'tools/list', 'tools/call'];
+function methodsFor(config) {
+    return [
+        ...BASE_METHODS,
+        ...(config.resources?.length ? ['resources/list', 'resources/read'] : []),
+        ...(config.prompts?.length ? ['prompts/list', 'prompts/get'] : []),
+    ];
+}
+async function handleRpc(req, config) {
+    const { id, method, params } = req;
+    const p = (params ?? {});
+    const resources = config.resources ?? [];
+    const prompts = config.prompts ?? [];
+    try {
+        switch (method) {
+            case 'initialize':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        protocolVersion: MCP_PROTOCOL_VERSION,
+                        // Only advertise capabilities the config actually populates — an
+                        // advertised `resources` whose list comes back empty reads as a bug
+                        // to a client, not as honesty.
+                        capabilities: {
+                            tools: {},
+                            ...(resources.length ? { resources: {} } : {}),
+                            ...(prompts.length ? { prompts: {} } : {}),
+                        },
+                        serverInfo: config.serverInfo,
+                        instructions: config.instructions,
+                    },
+                };
+            // Notifications have no response at all.
+            case 'notifications/initialized':
+            case 'notifications/cancelled':
+                return null;
+            case 'ping':
+                return { jsonrpc: '2.0', id, result: {} };
+            case 'tools/list':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        tools: config.tools.map(({ name, description, inputSchema, annotations }) => ({
+                            name,
+                            description,
+                            inputSchema,
+                            ...(annotations ? { annotations } : {}),
+                        })),
+                    },
+                };
+            case 'resources/list':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        resources: resources.map(({ uri, name, description, mimeType }) => ({
+                            uri,
+                            name,
+                            description,
+                            mimeType,
+                        })),
+                    },
+                };
+            case 'resources/read': {
+                const { uri } = p;
+                const resource = uri ? resources.find(r => r.uri === uri) : undefined;
+                const content = resource ? await resource.read() : null;
+                if (content == null) {
+                    const uris = resources.map(r => r.uri);
+                    const lead = uri ? `Unknown resource "${uri}".` : 'Missing "uri" in params.';
+                    return rpcError(id, -32602, `${lead} This server exposes: ${uris.length ? quote(uris) : 'no resources'}.`, { availableResources: uris });
+                }
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: { contents: [{ uri, mimeType: resource.mimeType, text: content }] },
+                };
+            }
+            case 'prompts/list':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: { prompts: prompts.map(({ name, description }) => ({ name, description })) },
+                };
+            case 'prompts/get': {
+                const { name } = p;
+                const prompt = name ? prompts.find(x => x.name === name) : undefined;
+                if (!prompt) {
+                    const names = prompts.map(x => x.name);
+                    const lead = name ? `Unknown prompt "${name}".` : 'Missing "name" in params.';
+                    return rpcError(id, -32602, `${lead} This server exposes: ${names.length ? quote(names) : 'no prompts'}.`, { availablePrompts: names });
+                }
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        description: prompt.description,
+                        messages: [{ role: 'user', content: { type: 'text', text: prompt.text } }],
+                    },
+                };
+            }
+            case 'tools/call': {
+                const { name, arguments: rawArgs = {} } = p;
+                const names = config.tools.map(t => t.name);
+                const tool = name ? config.tools.find(t => t.name === name) : undefined;
+                if (!tool) {
+                    const lead = name ? `Unknown tool "${name}".` : 'Missing "name" in params.';
+                    return rpcError(id, -32602, `${lead} This server exposes: ${quote(names)}.`, {
+                        availableTools: names,
+                    });
+                }
+                if (typeOf(rawArgs) !== 'object') {
+                    return toolText(id, `"arguments" must be an object; received ${typeOf(rawArgs)}. Expected schema: ${JSON.stringify(tool.inputSchema)}`, true);
+                }
+                const args = rawArgs;
+                const invalid = validateArgs(tool, args);
+                if (invalid)
+                    return toolText(id, invalid, true);
+                try {
+                    const data = await tool.handler(args);
+                    return toolText(id, typeof data === 'string' ? data : JSON.stringify(data, null, 2));
+                }
+                catch (err) {
+                    if (!(err instanceof McpToolError))
+                        throw err;
+                    return toolText(id, JSON.stringify({ error: err.message, ...err.details }, null, 2), true);
+                }
+            }
+            default: {
+                const methods = methodsFor(config);
+                return rpcError(id, -32601, `Method not found: "${method}". This server implements: ${quote(methods)}.`, { supportedMethods: methods });
+            }
+        }
+    }
+    catch (err) {
+        console.error('[MCP]', method, err);
+        return rpcError(id, -32603, 'Internal error');
+    }
+}
+/** Dispatch a parsed body. `null` means notification-only — answer 202, not 200. */
+export async function handleMcp(body, config) {
+    const maxBatch = config.maxBatch ?? DEFAULT_MAX_BATCH;
+    const isBatch = Array.isArray(body);
+    if (isBatch && body.length > maxBatch) {
+        return rpcError(null, -32600, `Batch too large: ${body.length} requests (max ${maxBatch}). Split into smaller batches.`);
+    }
+    if (isBatch && body.length === 0) {
+        return rpcError(null, -32600, 'Batch is empty. Send at least one JSON-RPC request.');
+    }
+    const responses = (await Promise.all((isBatch ? body : [body]).map(r => handleRpc(r, config)))).filter(Boolean);
+    return isBatch ? responses : (responses[0] ?? null);
+}
+// ---------------------------------------------------------------------------
+// HTTP transport — the spec edges, in one place.
+//
+// A public, anonymous, read-only server means `*` is the correct CORS posture:
+// the spec's Origin-validation MUST exists to protect localhost servers from
+// DNS rebinding, which is the opposite situation. The allow-headers list
+// matters more than it looks — MCP clients preflight with `Accept` and
+// `Mcp-Protocol-Version`, and one missing entry fails the preflight, not the
+// POST, which reads as "the server is down".
+export const MCP_CORS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID',
+    'Access-Control-Max-Age': '86400',
+};
+export function withMcpCors(res) {
+    for (const [k, v] of Object.entries(MCP_CORS))
+        res.headers.set(k, v);
+    return res;
+}
+export function mcpOptions() {
+    return new Response(null, { status: 204, headers: MCP_CORS });
+}
+/**
+ * Streamable HTTP lets a server decline the SSE leg by answering GET with 405.
+ * A framework's automatic 405 carries no CORS headers, so a browser client
+ * could not even read the refusal — answer it here, and say what to do instead.
+ */
+export function mcpGet(docsUrl) {
+    const message = 'This server speaks JSON-RPC over POST only (no SSE stream). Send your request as an HTTP POST.' +
+        (docsUrl ? ` Docs: ${docsUrl}` : '');
+    return Response.json(rpcError(null, -32600, message), {
+        status: 405,
+        headers: { ...MCP_CORS, Allow: 'POST, OPTIONS' },
+    });
+}
+/** The whole POST leg: parse, track, dispatch, and answer with the right status. */
+export async function mcpResponse(request, config) {
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        return Response.json(rpcError(null, -32700, 'Parse error: request body is not valid JSON.'), {
+            status: 400,
+            headers: MCP_CORS,
+        });
+    }
+    config.onCall?.(request, body);
+    const result = await handleMcp(body, config);
+    // Notification-only input produces no response bodies; the spec requires a
+    // bare 202 there, not a 200 carrying a JSON `null`.
+    if (result == null || (Array.isArray(result) && !result.length)) {
+        return new Response(null, { status: 202, headers: MCP_CORS });
+    }
+    return Response.json(result, { headers: MCP_CORS });
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/pagination.d.ts

@@ -0,0 +1,22 @@
+export interface Pagination {
+    page: number;
+    pageSize: number;
+}
+export interface PaginatedResponse<T> extends Pagination {
+    items: T[];
+    total: number;
+    totalPages: number;
+}
+export declare const MAX_PAGE_SIZE = 100;
+export declare const DEFAULT_PAGE_SIZE = 20;
+/** `page` clamped to ≥1, `pageSize` clamped to 1–100. Never trust either. */
+export declare function parsePagination(searchParams: URLSearchParams, defaults?: {
+    pageSize?: number;
+}): Pagination;
+export declare function paginatedResponse<T>(items: T[], total: number, page: number, pageSize: number): PaginatedResponse<T>;
+/** The `skip`/`take` an ORM wants, from the same clamped pair. */
+export declare function toOffset({ page, pageSize }: Pagination): {
+    skip: number;
+    take: number;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,UAAU;IACtD,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,6EAA6E;AAC7E,wBAAgB,eAAe,CAC7B,YAAY,EAAE,eAAe,EAC7B,QAAQ,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B,UAAU,CAYZ;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,iBAAiB,CAAC,CAAC,CAAC,CAEtB;AAED,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAEvF"}

package/dist/pagination.js

@@ -0,0 +1,26 @@
+// pagination.ts — one offset-pagination shape, everywhere.
+//
+// Forked three ways once: a re-typed clamp that dropped `totalPages`, and an
+// offset redone by hand in raw SQL. The response shape is the contract a client
+// codes against, so reshaping it per repo is a breaking change nobody declared.
+export const MAX_PAGE_SIZE = 100;
+export const DEFAULT_PAGE_SIZE = 20;
+/** `page` clamped to ≥1, `pageSize` clamped to 1–100. Never trust either. */
+export function parsePagination(searchParams, defaults) {
+    const rawPage = parseInt(searchParams.get('page') || '1', 10);
+    const rawSize = parseInt(searchParams.get('pageSize') || String(defaults?.pageSize ?? DEFAULT_PAGE_SIZE), 10);
+    return {
+        page: Number.isFinite(rawPage) ? Math.max(1, rawPage) : 1,
+        pageSize: Number.isFinite(rawSize)
+            ? Math.min(MAX_PAGE_SIZE, Math.max(1, rawSize))
+            : (defaults?.pageSize ?? DEFAULT_PAGE_SIZE),
+    };
+}
+export function paginatedResponse(items, total, page, pageSize) {
+    return { items, total, page, pageSize, totalPages: Math.ceil(total / pageSize) };
+}
+/** The `skip`/`take` an ORM wants, from the same clamped pair. */
+export function toOffset({ page, pageSize }) {
+    return { skip: (page - 1) * pageSize, take: pageSize };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,gFAAgF;AAahF,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AACjC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAC7B,YAA6B,EAC7B,QAAgC;IAEhC,MAAM,OAAO,GAAG,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,QAAQ,CACtB,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,QAAQ,IAAI,iBAAiB,CAAC,EAC/E,EAAE,CACH,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;YAChC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,IAAI,iBAAiB,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAU,EACV,KAAa,EACb,IAAY,EACZ,QAAgB;IAEhB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,EAAE,CAAC;AACnF,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAc;IACrD,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACzD,CAAC"}

package/dist/taxonomy.d.ts

@@ -0,0 +1,74 @@
+/** A metadata key a tag path declares. Only `select` keys become facets. */
+export interface MetadataKeyDefinition {
+    key: string;
+    label: string;
+    type: 'text' | 'date' | 'url' | 'select';
+    options?: string[];
+}
+/** The minimum a page must be for this module to classify it. */
+export interface FacetablePage {
+    title: string;
+    metadata?: unknown;
+}
+export interface FacetValue {
+    value: string;
+    count: number;
+}
+export interface Facet {
+    key: string;
+    label: string;
+    values: FacetValue[];
+}
+export type FacetFilters = Record<string, string>;
+export interface SharedFacet {
+    key: string;
+    value: string;
+}
+export interface RelatedRanking<T> {
+    pages: T[];
+    sharedFacet: SharedFacet | null;
+}
+/** State a category URL can carry. `href` receives this and owns the format. */
+export interface CategoryState {
+    sort?: string;
+    filters?: FacetFilters;
+    letter?: string;
+}
+export interface TaxonomyConfig {
+    /**
+     * The metadata keys a tag path declares, nearest-last or nearest-first — the
+     * order only matters for `label` collisions. Host-supplied because one repo
+     * resolves it down a nested tree and another down a flat trail.
+     */
+    getMetadataKeys: (tagPath: string) => MetadataKeyDefinition[];
+    /**
+     * The category URL contract. Every chip, letter, sort button and infobox row
+     * builds through this one function — a sort button that drops the active
+     * filters is the tell that a project grew a second one.
+     */
+    href?: (tagPath: string, state: CategoryState) => string;
+    /** Below this a category fits on a screen or two; above it, readers need an index. */
+    alphaIndexMinPages?: number;
+}
+/** Default: `/{tagPath}?sort=…&{facet}=…&letter=…`. Override for a prefixed mount. */
+export declare function defaultHref(tagPath: string, state: CategoryState): string;
+export declare const DEFAULT_ALPHA_INDEX_MIN_PAGES = 40;
+/** Bucket for titles that don't start with a letter (numerals, `$CAPER`). */
+export declare function firstLetter(title: string): string;
+/** Adding a filter already active removes it, so every chip is its own off-switch. */
+export declare function toggleFilter(filters: FacetFilters, key: string, value: string): FacetFilters;
+export interface Taxonomy {
+    /** The select-typed keys a tag path declares — its facetable axes. */
+    facetKeys: (tagPath: string) => MetadataKeyDefinition[];
+    /** Query params narrowed to facets this tag path actually declares. */
+    facetFilters: (tagPath: string, params: Record<string, string | string[] | undefined>) => FacetFilters;
+    filterPages: <T extends FacetablePage>(pages: T[], filters: FacetFilters, letter?: string) => T[];
+    buildFacets: <T extends FacetablePage>(tagPath: string, pages: T[], filters: FacetFilters, letter?: string) => Facet[];
+    alphaIndex: <T extends FacetablePage>(pages: T[], filters: FacetFilters) => FacetValue[];
+    /** Whether a set has outgrown a grid and needs the A–Z index. */
+    needsAlphaIndex: (pageCount: number) => boolean;
+    href: (tagPath: string, state: CategoryState) => string;
+    rankRelated: <T extends FacetablePage>(page: T, siblings: T[], tagPath: string, limit?: number) => RelatedRanking<T>;
+}
+export declare function createTaxonomy(config: TaxonomyConfig): Taxonomy;
+//# sourceMappingURL=taxonomy.d.ts.map

package/dist/taxonomy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taxonomy.d.ts","sourceRoot":"","sources":["../src/taxonomy.ts"],"names":[],"mappings":"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"}

package/dist/taxonomy.js

@@ -0,0 +1,156 @@
+// taxonomy.ts — the second axis of category browsing.
+//
+// A `tagPath` puts a page in exactly one place in a tree. The `select`-typed
+// metadata it already carries is a cross-cutting axis that is almost always
+// stored and never surfaced — the failure this module exists to prevent is a
+// 141-page category rendered as one flat grid while the data to split it sits
+// unread in a JSON column.
+//
+// Everything here is derived. Nothing is hand-curated, so nothing can go stale:
+// fix a page and it leaves the queue on the next revalidation.
+//
+// Two consumers proved the mechanism travels — one walks a nested tag tree, the
+// other a flat category list — so the tree itself is NOT in this module. Supply
+// `getMetadataKeys(tagPath)` and a `href` builder and the rest follows.
+/** Default: `/{tagPath}?sort=…&{facet}=…&letter=…`. Override for a prefixed mount. */
+export function defaultHref(tagPath, state) {
+    const params = new URLSearchParams();
+    if (state.sort)
+        params.set('sort', state.sort);
+    for (const [key, value] of Object.entries(state.filters ?? {}))
+        params.set(key, value);
+    if (state.letter)
+        params.set('letter', state.letter);
+    const query = params.toString();
+    return `/${tagPath}${query ? `?${query}` : ''}`;
+}
+export const DEFAULT_ALPHA_INDEX_MIN_PAGES = 40;
+const metaValue = (page, key) => (page.metadata?.[key] ?? '').trim();
+/** Bucket for titles that don't start with a letter (numerals, `$CAPER`). */
+export function firstLetter(title) {
+    const ch = title.trim()[0]?.toUpperCase() ?? '';
+    return ch >= 'A' && ch <= 'Z' ? ch : '#';
+}
+/** Adding a filter already active removes it, so every chip is its own off-switch. */
+export function toggleFilter(filters, key, value) {
+    const next = { ...filters };
+    if (next[key] === value)
+        delete next[key];
+    else
+        next[key] = value;
+    return next;
+}
+export function createTaxonomy(config) {
+    const href = config.href ?? defaultHref;
+    const minPages = config.alphaIndexMinPages ?? DEFAULT_ALPHA_INDEX_MIN_PAGES;
+    const facetKeys = (tagPath) => config.getMetadataKeys(tagPath).filter(k => k.type === 'select');
+    const matches = (page, filters, letter) => {
+        if (letter && firstLetter(page.title) !== letter)
+            return false;
+        return Object.entries(filters).every(([key, value]) => metaValue(page, key) === value);
+    };
+    const filterPages = (pages, filters, letter) => {
+        if (!Object.keys(filters).length && !letter)
+            return pages;
+        return pages.filter(p => matches(p, filters, letter));
+    };
+    return {
+        facetKeys,
+        href,
+        filterPages,
+        needsAlphaIndex: (pageCount) => pageCount >= minPages,
+        facetFilters(tagPath, params) {
+            const filters = {};
+            for (const key of facetKeys(tagPath)) {
+                const value = params[key.key];
+                if (typeof value === 'string' && value)
+                    filters[key.key] = value;
+            }
+            return filters;
+        },
+        /**
+         * Facet values with counts. Each facet is counted over the set narrowed by
+         * every *other* active filter, so its own options stay switchable rather
+         * than collapsing to the one already chosen.
+         *
+         * Values are read from the data, never from the declared `options`: a key
+         * that declares four and holds seven would otherwise hide three behind a
+         * bar claiming to cover everything. Render what is there and the drift
+         * becomes visible instead of silent.
+         */
+        buildFacets(tagPath, pages, filters, letter) {
+            return facetKeys(tagPath).flatMap(key => {
+                const others = Object.fromEntries(Object.entries(filters).filter(([k]) => k !== key.key));
+                const counts = new Map();
+                for (const page of filterPages(pages, others, letter)) {
+                    const value = metaValue(page, key.key);
+                    if (value)
+                        counts.set(value, (counts.get(value) ?? 0) + 1);
+                }
+                // A single-valued facet is no choice, so it stays hidden — unless it is
+                // the active one. An infobox row can set a filter the chips never
+                // offered, and without its chip the reader lands on a narrowed list
+                // with no way to widen it.
+                if (counts.size < 2 && !(key.key in filters))
+                    return [];
+                const values = [...counts]
+                    .map(([value, count]) => ({ value, count }))
+                    .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+                return [{ key: key.key, label: key.label.replace(/:$/, ''), values }];
+            });
+        },
+        /** A–Z buckets present in the set, `#` last. */
+        alphaIndex(pages, filters) {
+            const counts = new Map();
+            for (const page of filterPages(pages, filters)) {
+                const letter = firstLetter(page.title);
+                counts.set(letter, (counts.get(letter) ?? 0) + 1);
+            }
+            return [...counts]
+                .map(([value, count]) => ({ value, count }))
+                .sort((a, b) => a.value === '#' ? 1 : b.value === '#' ? -1 : a.value.localeCompare(b.value));
+        },
+        /**
+         * Siblings ranked by how many facet values they share with the page — a
+         * real relatedness signal. The behaviour this replaces (`pages.slice(0, 5)`
+         * under a *See also* heading) showed every page in a 141-page category the
+         * same five links. Ties keep the incoming order, so the tail degrades to
+         * the category's own sort rather than to nothing.
+         *
+         * The shared facet comes back as `{key, value}` rather than a label so the
+         * heading above the five can be the link into the whole filtered set, not
+         * a sentence explaining what "related" meant.
+         */
+        rankRelated(page, siblings, tagPath, limit = 5) {
+            const keys = facetKeys(tagPath);
+            if (!keys.length)
+                return { pages: siblings.slice(0, limit), sharedFacet: null };
+            const score = (other) => keys.reduce((n, k) => n +
+                (metaValue(page, k.key) && metaValue(other, k.key) === metaValue(page, k.key) ? 1 : 0), 0);
+            const ranked = siblings
+                .map((p, i) => ({ p, score: score(p), i }))
+                .sort((a, b) => b.score - a.score || a.i - b.i)
+                .slice(0, limit);
+            // Name the narrowest axis the page ACTUALLY SHARES with something in the
+            // list — a `category` with 15 options says more than a `status` with 4, so
+            // headline the narrower one, but only among the axes that are shared.
+            //
+            // Picking the narrowest axis the *page* carries, without checking whether
+            // any returned sibling matches on it, produces a heading that links to a
+            // set the list below it is not in: "More Classical pages in Nomenclature"
+            // over five pages that are not Classical. The heading is the link into the
+            // filtered set, so it has to name a filter that contains them.
+            const matched = ranked.filter(r => r.score > 0);
+            const narrowest = keys
+                .filter(k => metaValue(page, k.key) &&
+                matched.some(r => metaValue(r.p, k.key) === metaValue(page, k.key)))
+                .sort((a, b) => (b.options?.length ?? 0) - (a.options?.length ?? 0))[0];
+            const value = narrowest ? metaValue(page, narrowest.key) : '';
+            return {
+                pages: ranked.map(r => r.p),
+                sharedFacet: narrowest && value ? { key: narrowest.key, value } : null,
+            };
+        },
+    };
+}
+//# sourceMappingURL=taxonomy.js.map