@fungi.computer/forage 0.0.0-stage → 0.0.2

package/dist/schemas.js

@@ -0,0 +1,156 @@
+import { z } from "zod";
+const pathPattern = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/;
+const maximumCatalogOperations = 1_000;
+const maximumScore = 221;
+export const maximumDescriptionTypes = 20_000;
+export const maximumSampleEntries = 100;
+export const maximumSampleBytes = 4_000;
+export const maximumSampleDepth = 16;
+function jsonDepth(value, depth) {
+    if (depth > maximumSampleDepth)
+        return depth;
+    if (Array.isArray(value)) {
+        let maximum = depth;
+        for (const item of value) {
+            maximum = Math.max(maximum, jsonDepth(item, depth + 1));
+        }
+        return maximum;
+    }
+    if (value === null)
+        return depth;
+    const record = z.record(z.string(), z.json()).safeParse(value);
+    if (!record.success)
+        return depth;
+    let maximum = depth;
+    for (const item of Object.values(record.data)) {
+        maximum = Math.max(maximum, jsonDepth(item, depth + 1));
+    }
+    return maximum;
+}
+const sampleSchema = z
+    .record(z.string(), z.json())
+    .superRefine((value, context) => {
+    if (Object.keys(value).length > maximumSampleEntries) {
+        context.addIssue({
+            code: "custom",
+            message: "Sample exceeds the entry bound",
+        });
+    }
+    if (JSON.stringify(value).length > maximumSampleBytes) {
+        context.addIssue({
+            code: "custom",
+            message: "Sample exceeds the byte bound",
+        });
+    }
+    if (jsonDepth(value, 0) > maximumSampleDepth) {
+        context.addIssue({
+            code: "custom",
+            message: "Sample exceeds the depth bound",
+        });
+    }
+});
+/** Input accepted by the pure catalog search seam. */
+export const forageSearchInput = z.object({
+    query: z.string().max(200),
+    maxResults: z.number().int().min(1).max(50).default(50),
+});
+/** Input accepted by the pure catalog description seam. */
+export const forageDescribeInput = z.object({
+    path: z.string().max(160),
+    detail: z.enum(["index", "full"]).default("full"),
+    methods: z.array(z.string().max(80)).max(50).optional(),
+});
+/** Exhaustive listing request; cursor is scoped to one immutable catalog and filter. */
+export const forageListInput = z.object({
+    cursor: z.string().max(400).optional(),
+    limit: z.number().int().min(1).max(50).default(50),
+    namespace: z
+        .string()
+        .min(1)
+        .max(160)
+        .regex(/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/)
+        .optional(),
+});
+const peerSchema = z.object({
+    path: z.string().max(160),
+    capabilityNotes: z.string().max(500).optional(),
+});
+/** One ranked operation in a search response. */
+export const searchResultSchema = z.object({
+    path: z.string().max(160),
+    description: z.string().max(1000).optional(),
+    score: z.number().min(0).max(maximumScore),
+    matchReason: z.string().max(500).optional(),
+    sample: sampleSchema.optional(),
+    capabilityNotes: z.string().max(500).optional(),
+    peers: z.array(peerSchema).max(1000).optional(),
+});
+/** Bounded search response envelope. */
+export const searchOutputSchema = z.object({
+    results: z.array(searchResultSchema).max(50),
+    total: z.number().int().min(0).max(maximumCatalogOperations),
+    truncated: z.boolean(),
+    topScore: z.number().min(0).max(maximumScore),
+    margin: z.number().min(0).max(maximumScore),
+    catalogStamp: z
+        .string()
+        .length(16)
+        .regex(/^[0-9a-f]{16}$/),
+});
+/** One exhaustive page, using the exact search operation summary schema. */
+export const listOutputSchema = z.object({
+    results: z.array(searchResultSchema).max(50),
+    total: z.number().int().min(0).max(maximumCatalogOperations),
+    nextCursor: z.string().max(400).nullable(),
+    catalogStamp: z
+        .string()
+        .length(16)
+        .regex(/^[0-9a-f]{16}$/),
+});
+/** Deterministic description response. */
+export const describeOutputSchema = z.object({
+    path: z.string().max(160),
+    description: z.string().max(1000).optional(),
+    types: z.string().max(20000),
+    inputSchema: z
+        .json()
+        .refine((value) => JSON.stringify(value).length <= maximumDescriptionTypes &&
+        jsonDepth(value, 0) <= maximumSampleDepth, "Input schema exceeds the description bounds")
+        .optional(),
+    kind: z.enum(["module", "operation"]),
+    usage: z.string().max(300).optional(),
+});
+/** Closed failure vocabulary for malformed or absent catalog requests. */
+export const forageFailureSchema = z.object({
+    code: z.enum([
+        "empty_query",
+        "empty_catalog",
+        "unknown_target",
+        "duplicate_operation",
+        "invalid_input",
+    ]),
+    message: z.string().max(1000),
+});
+const jsonSchemaDescriber = z.object({
+    "~standard": z.object({
+        jsonSchema: z.object({
+            input: z.instanceof(Function),
+            output: z.instanceof(Function),
+        }),
+    }),
+});
+const jsonSchemaSource = z.custom((value) => jsonSchemaDescriber.safeParse(value).success, "Expected a Standard JSON Schema");
+/** A secret-free, callback-free operation descriptor. */
+export const operationSchema = z.object({
+    path: z.string().min(3).max(160).regex(pathPattern),
+    description: z.string().max(1000).optional(),
+    input: jsonSchemaSource,
+    output: jsonSchemaSource.optional(),
+    capabilityNotes: z.string().max(500).optional(),
+    instructions: z.string().max(1000).optional(),
+});
+/** Input used to construct one immutable catalog revision. */
+export const catalogInputSchema = z.object({
+    revision: z.string().min(1).max(160),
+    operations: z.array(operationSchema).max(maximumCatalogOperations),
+});

package/dist/search.d.ts

@@ -0,0 +1,17 @@
+import { type Operation, type SearchOutput } from "./schemas.js";
+import { type RenderedOperation } from "./rendering.js";
+import type { JsonValue } from "./normalization.js";
+/** Private installation-time projection used by the pure ranking function. */
+export type PreparedOperation = Operation & {
+    readonly fingerprint: string;
+    readonly inputSchema: JsonValue;
+    readonly sample: Record<string, JsonValue> | undefined;
+    readonly rendered: RenderedOperation;
+};
+/** Prepare schema-derived search metadata once for an immutable catalog revision. */
+export declare function prepareOperation(operation: Operation): PreparedOperation;
+/** Identify every model-visible part of the catalog, including schemas. */
+declare function catalogStamp(operations: readonly PreparedOperation[]): string;
+/** Pure deterministic ranking over one immutable operation snapshot. */
+export declare function searchCatalog(operations: readonly PreparedOperation[], query: string, maxResults: number | undefined, stamp: string): SearchOutput;
+export { catalogStamp };

package/dist/search.js

@@ -0,0 +1,258 @@
+import { searchOutputSchema, } from "./schemas.js";
+import { canonicalStringify, compareCodeUnits, hashString64, isStopword, normalizeQuery, operationMethod, operationNamespace, stemVariants, tokenize, } from "./normalization.js";
+import { deriveSample, inputSchemaProjection, renderOperation, schemaFingerprint, } from "./rendering.js";
+import { ForageError } from "./errors.js";
+/** Prepare schema-derived search metadata once for an immutable catalog revision. */
+export function prepareOperation(operation) {
+    return Object.freeze({
+        ...operation,
+        fingerprint: schemaFingerprint(operation.input),
+        inputSchema: inputSchemaProjection(operation.input),
+        sample: deriveSample(operation.input),
+        rendered: renderOperation(operation),
+    });
+}
+const matchWeight = {
+    exact: 14,
+    startsWith: 9,
+    phrase: 6,
+    token: 4,
+    prefix: 2,
+    substring: 2,
+    includes: 1,
+};
+function fieldWeight(field) {
+    switch (field) {
+        case "path":
+            return 12;
+        case "namespace":
+            return 8;
+        case "method":
+            return 10;
+        case "description":
+            return 5;
+        default:
+            return 5;
+    }
+}
+/** Identify every model-visible part of the catalog, including schemas. */
+function catalogStamp(operations) {
+    const lines = [...operations]
+        .sort((left, right) => compareCodeUnits(left.path, right.path))
+        .map((operation) => canonicalStringify([
+        operation.path,
+        operation.description ?? null,
+        operation.capabilityNotes ?? null,
+        operation.instructions ?? null,
+        operation.fingerprint,
+        operation.output === undefined
+            ? null
+            : schemaFingerprint(operation.output, "output"),
+    ]));
+    return hashString64(lines.join("\n"));
+}
+function scoreLevel(value, term) {
+    if (value === term)
+        return "exact";
+    if (value.startsWith(term))
+        return "startsWith";
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`\\b${escaped}\\b`).test(value))
+        return "phrase";
+    const parts = tokenize(value);
+    if (parts.some((part) => part === term))
+        return "token";
+    if (parts.some((part) => part.startsWith(term)))
+        return "prefix";
+    if (parts.some((part) => part.includes(term)))
+        return "substring";
+    if (value.includes(term))
+        return "includes";
+    return "none";
+}
+function scoreField(rawValue, field, queryTokens) {
+    const value = normalizeQuery(rawValue);
+    let bestLevel = "none";
+    let bestScore = 0;
+    let matchedTokens = [];
+    for (const token of queryTokens) {
+        const terms = [token, ...stemVariants(token)];
+        let selected = "none";
+        for (const term of terms) {
+            const level = scoreLevel(value, term);
+            if (level !== "none") {
+                selected = level;
+                break;
+            }
+        }
+        if (selected === "none")
+            continue;
+        const score = matchWeight[selected] * fieldWeight(field);
+        if (score > bestScore) {
+            bestLevel = selected;
+            bestScore = score;
+            matchedTokens = [token];
+        }
+        else if (score === bestScore && !matchedTokens.includes(token)) {
+            matchedTokens.push(token);
+        }
+    }
+    return { level: bestLevel, score: bestScore, matchedTokens };
+}
+function tokenMatches(value, token) {
+    const normalized = normalizeQuery(value);
+    return [token, ...stemVariants(token)].some((term) => normalized.includes(term));
+}
+function matchReason(fields) {
+    const parts = [];
+    for (const [field, scored] of fields) {
+        if (scored.level === "none")
+            continue;
+        const tokens = scored.matchedTokens
+            .slice(0, 4)
+            .map((token) => token.slice(0, 20));
+        parts.push(`${field}:${scored.level}(${tokens.join(" ")})`);
+    }
+    return parts.length > 0 ? parts.join("; ") : undefined;
+}
+function checkedSearchOutput(output) {
+    const parsed = searchOutputSchema.safeParse(output);
+    if (!parsed.success) {
+        throw new ForageError("invalid_input", "Search output exceeded its bounds");
+    }
+    return parsed.data;
+}
+function clusterKey(operation) {
+    return [
+        operationMethod(operation.path),
+        (operation.description ?? "").trim().toLowerCase().replace(/\s+/g, " "),
+        operation.fingerprint,
+    ].join("\u0000");
+}
+function emptyResult(stamp) {
+    return checkedSearchOutput({
+        results: [],
+        total: 0,
+        truncated: false,
+        topScore: 0,
+        margin: 0,
+        catalogStamp: stamp,
+    });
+}
+function scoreCandidate(operation, normalizedQuery, queryTokens, coverageTokens, threshold) {
+    const namespace = operationNamespace(operation.path);
+    const method = operationMethod(operation.path);
+    const description = operation.description ?? "";
+    const fields = [operation.path, namespace, method, description];
+    const pathScore = scoreField(operation.path, "path", queryTokens);
+    const namespaceScore = scoreField(namespace, "namespace", queryTokens);
+    const methodScore = scoreField(method, "method", queryTokens);
+    const descriptionScore = scoreField(description, "description", queryTokens);
+    const matched = coverageTokens.filter((token) => fields.some((field) => tokenMatches(field, token))).length;
+    const coverage = matched / coverageTokens.length;
+    const phraseMatch = normalizeQuery(`${operation.path} ${description}`).includes(normalizedQuery);
+    if (coverage < threshold && !phraseMatch)
+        return undefined;
+    const baseScore = Math.max(pathScore.score, namespaceScore.score, methodScore.score, descriptionScore.score);
+    if (baseScore === 0)
+        return undefined;
+    let bonus = matched === coverageTokens.length ? 25 : coverage * 10;
+    const firstToken = coverageTokens[0];
+    if (firstToken && fields.some((field) => tokenMatches(field, firstToken))) {
+        bonus += 8;
+    }
+    if (pathScore.level === "exact" || methodScore.level === "exact")
+        bonus += 20;
+    const result = {
+        path: operation.path,
+        score: baseScore + bonus,
+    };
+    if (description)
+        result.description = description;
+    const reason = matchReason([
+        ["method", methodScore],
+        ["description", descriptionScore],
+        ["path", pathScore],
+        ["namespace", namespaceScore],
+    ]);
+    if (reason)
+        result.matchReason = reason;
+    if (operation.sample)
+        result.sample = operation.sample;
+    if (operation.capabilityNotes)
+        result.capabilityNotes = operation.capabilityNotes;
+    return {
+        result,
+        cluster: clusterKey(operation),
+        pathScore: pathScore.score,
+    };
+}
+function mergeCandidateClusters(candidates) {
+    const grouped = new Map();
+    for (const candidate of candidates) {
+        const group = grouped.get(candidate.cluster) ?? [];
+        group.push(candidate);
+        grouped.set(candidate.cluster, group);
+    }
+    const merged = [];
+    for (const group of grouped.values()) {
+        const sorted = [...group].sort((left, right) => right.pathScore - left.pathScore ||
+            right.result.score - left.result.score ||
+            compareCodeUnits(left.result.path, right.result.path));
+        const survivor = sorted[0];
+        if (!survivor)
+            continue;
+        const peers = [];
+        const peerCandidates = sorted
+            .slice(1)
+            .sort((left, right) => compareCodeUnits(left.result.path, right.result.path));
+        for (const candidate of peerCandidates) {
+            const peer = {
+                path: candidate.result.path,
+            };
+            if (candidate.result.capabilityNotes) {
+                peer.capabilityNotes = candidate.result.capabilityNotes;
+            }
+            peers.push(peer);
+        }
+        const mergedResult = {
+            ...survivor.result,
+            score: Math.max(...sorted.map((candidate) => candidate.result.score)),
+        };
+        if (peers.length > 0)
+            mergedResult.peers = peers;
+        merged.push(mergedResult);
+    }
+    return merged.sort((left, right) => right.score - left.score || compareCodeUnits(left.path, right.path));
+}
+function checkedRankedOutput(merged, resultLimit, stamp) {
+    const bounded = merged.slice(0, resultLimit);
+    const top = bounded[0];
+    const second = bounded[1];
+    return checkedSearchOutput({
+        results: bounded,
+        total: merged.length,
+        truncated: merged.length > resultLimit,
+        topScore: top?.score ?? 0,
+        margin: top && second ? top.score - second.score : 0,
+        catalogStamp: stamp,
+    });
+}
+/** Pure deterministic ranking over one immutable operation snapshot. */
+export function searchCatalog(operations, query, maxResults = 50, stamp) {
+    const resultLimit = Math.min(50, Math.max(1, Math.floor(maxResults)));
+    const normalizedQuery = normalizeQuery(query);
+    const queryTokens = tokenize(normalizedQuery);
+    const coverageTokens = queryTokens.filter((token) => !isStopword(token));
+    if (coverageTokens.length === 0)
+        return emptyResult(stamp);
+    const threshold = coverageTokens.length <= 2 ? 1 : 0.6;
+    const candidates = [];
+    for (const operation of operations) {
+        const candidate = scoreCandidate(operation, normalizedQuery, queryTokens, coverageTokens, threshold);
+        if (candidate)
+            candidates.push(candidate);
+    }
+    return checkedRankedOutput(mergeCandidateClusters(candidates), resultLimit, stamp);
+}
+export { catalogStamp };

package/docs/api/README.md

@@ -0,0 +1,15 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/forage**
+
+---
+
+# @fungi.computer/forage
+
+## Modules
+
+| Module                                      | Description |
+| ------------------------------------------- | ----------- |
+| [index](index.md)                           | -           |
+| [json-schema-subset](json-schema-subset.md) | -           |
+| [openapi](openapi.md)                       | -           |