@fungi.computer/forage 0.0.0-stage → 0.0.1

package/dist/rendering.js

@@ -0,0 +1,341 @@
+import { z } from "zod";
+import { ForageError } from "./errors.js";
+import { canonicalStringify, compareCodeUnits, isJsonObject, jsonValueSchema, } from "./normalization.js";
+import { maximumSampleBytes, maximumSampleDepth, maximumSampleEntries, } from "./schemas.js";
+const schemaNode = z.lazy(() => z.union([
+    z.boolean(),
+    z.looseObject({
+        $ref: z.string().optional(),
+        $defs: z.record(z.string(), schemaNode).optional(),
+        definitions: z.record(z.string(), schemaNode).optional(),
+        const: z.unknown().optional(),
+        enum: z.array(z.unknown()).optional(),
+        oneOf: z.array(schemaNode).optional(),
+        anyOf: z.array(schemaNode).optional(),
+        allOf: z.array(schemaNode).optional(),
+        type: z.union([z.string(), z.array(z.string())]).optional(),
+        properties: z.record(z.string(), schemaNode).optional(),
+        additionalProperties: schemaNode.optional(),
+        required: z.array(z.string()).optional(),
+        prefixItems: z.array(schemaNode).optional(),
+        items: z.union([schemaNode, z.array(schemaNode)]).optional(),
+        examples: z.array(z.unknown()).optional(),
+        default: z.unknown().optional(),
+    }),
+]));
+/**
+ * Facts already derived, per schema object and direction. A Standard JSON
+ * Schema describes an immutable schema, so its projection is a pure function
+ * of the object: compiling a catalog asks for the same projection several
+ * times per operation (size, fingerprint, sample, rendering), and a host that
+ * recompiles a catalog over the same installed schemas asks again on every
+ * compile. Projecting, validating, fingerprinting and sizing once per schema
+ * keeps catalog compilation proportional to what actually changed.
+ */
+const schemaFacts = new WeakMap();
+function factsFor(schema, io) {
+    let entry = schemaFacts.get(schema);
+    const cached = entry?.[io];
+    if (cached !== undefined)
+        return cached;
+    let node;
+    try {
+        node = schemaNode.parse(schema["~standard"].jsonSchema[io]({ target: "draft-2020-12" }));
+    }
+    catch {
+        throw new ForageError("invalid_input", "Schema cannot be projected to JSON Schema");
+    }
+    const json = jsonValueSchema.safeParse(node);
+    const facts = {
+        node,
+        json: json.success ? json.data : undefined,
+    };
+    if (entry === undefined) {
+        entry = {};
+        schemaFacts.set(schema, entry);
+    }
+    entry[io] = facts;
+    return facts;
+}
+function schemaFor(schema, io) {
+    return factsFor(schema, io).node;
+}
+function isNodeList(value) {
+    return Array.isArray(value);
+}
+/** Bounds the work and size of expanding shared `$defs` in one description. */
+const maximumReferenceExpansions = 256;
+const localReference = /^#\/(?:\$defs|definitions)\/([^/]+)$/u;
+/** Expand a local `$ref` in place; a recursive reference renders `unknown`. */
+function renderReference(reference, depth, refs) {
+    const name = localReference.exec(reference)?.[1];
+    if (name === undefined || refs.expanding.has(name))
+        return "unknown";
+    const target = refs.definitions[name];
+    if (target === undefined)
+        return "unknown";
+    refs.budget.expansions += 1;
+    if (refs.budget.expansions > maximumReferenceExpansions)
+        throw new ForageError("invalid_input", `Schema references expand more than ${String(maximumReferenceExpansions)} times; flatten its shared definitions`);
+    return renderNode(target, depth, {
+        definitions: refs.definitions,
+        expanding: new Set([...refs.expanding, name]),
+        budget: refs.budget,
+    });
+}
+/** Whether a node renders as a top-level TypeScript union. */
+function rendersUnion(node, refs) {
+    if (node === true || node === false)
+        return false;
+    if (node.$ref !== undefined) {
+        const name = localReference.exec(node.$ref)?.[1];
+        const target = name === undefined || refs.expanding.has(name)
+            ? undefined
+            : refs.definitions[name];
+        return (name !== undefined &&
+            target !== undefined &&
+            rendersUnion(target, {
+                definitions: refs.definitions,
+                expanding: new Set([...refs.expanding, name]),
+                budget: refs.budget,
+            }));
+    }
+    if (node.const !== undefined)
+        return false;
+    return ((node.enum !== undefined && node.enum.length > 1) ||
+        (node.oneOf !== undefined && node.oneOf.length > 1) ||
+        (node.anyOf !== undefined && node.anyOf.length > 1));
+}
+function renderNode(node, depth, refs) {
+    if (node === undefined || node === true || node === false || depth > 12) {
+        return "unknown";
+    }
+    if (node.$ref)
+        return renderReference(node.$ref, depth, refs);
+    if (node.const !== undefined)
+        return JSON.stringify(node.const);
+    if (node.enum)
+        return node.enum.map((value) => JSON.stringify(value)).join(" | ");
+    if (node.oneOf) {
+        return node.oneOf
+            .map((value) => renderNode(value, depth + 1, refs))
+            .join(" | ");
+    }
+    if (node.anyOf) {
+        return node.anyOf
+            .map((value) => renderNode(value, depth + 1, refs))
+            .join(" | ");
+    }
+    if (node.allOf) {
+        return node.allOf
+            .map((value) => {
+            const member = renderNode(value, depth + 1, refs);
+            // `&` binds tighter than `|`: keep a union member whole.
+            return rendersUnion(value, refs) ? `(${member})` : member;
+        })
+            .join(" & ");
+    }
+    if (node.type === "object" || node.properties) {
+        const properties = Object.entries(node.properties ?? {}).sort(([left], [right]) => compareCodeUnits(left, right));
+        if (properties.length === 0) {
+            const additional = node.additionalProperties;
+            if (additional === false)
+                return "Record<string, never>";
+            if (additional && additional !== true) {
+                return `Record<string, ${renderNode(additional, depth + 1, refs)}>`;
+            }
+            return "Record<string, unknown>";
+        }
+        const required = new Set(node.required ?? []);
+        const lines = properties.map(([key, value]) => {
+            const child = renderNode(value, depth + 1, refs);
+            const optional = required.has(key) ? "" : "?";
+            const safeKey = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+                ? key
+                : JSON.stringify(key);
+            return `${"  ".repeat(depth + 1)}${safeKey}${optional}: ${child};`;
+        });
+        return `{
+${lines.join("\n")}
+${"  ".repeat(depth)}}`;
+    }
+    if (node.type === "array") {
+        const items = node.items;
+        if (node.prefixItems && node.prefixItems.length > 0) {
+            const tuple = node.prefixItems.map((value) => renderNode(value, depth + 1, refs));
+            if (items !== undefined && items !== true && !isNodeList(items)) {
+                tuple.push(`...${renderNode(items, depth + 1, refs)}[]`);
+            }
+            return `[${tuple.join(", ")}]`;
+        }
+        if (items !== undefined && isNodeList(items))
+            return `[${items.map((value) => renderNode(value, depth + 1, refs)).join(", ")}][]`;
+        const item = renderNode(items, depth + 1, refs);
+        const compoundItem = items !== undefined &&
+            items !== true &&
+            items !== false &&
+            (items.oneOf !== undefined ||
+                items.anyOf !== undefined ||
+                items.allOf !== undefined);
+        return `${compoundItem ? `(${item})` : item}[]`;
+    }
+    switch (node.type) {
+        case "string":
+            return "string";
+        case "number":
+        case "integer":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        default:
+            return "unknown";
+    }
+}
+/** Render one schema's JSON Schema as deterministic TypeScript type text. */
+function renderSchemaType(schema, io = "input") {
+    const root = schemaFor(schema, io);
+    const definitions = root === true || root === false
+        ? {}
+        : { ...root.definitions, ...root.$defs };
+    return renderNode(root, 0, {
+        definitions,
+        expanding: new Set(),
+        budget: { expansions: 0 },
+    });
+}
+function safeTypeName(name) {
+    return name.replace(/[^A-Za-z0-9_$]/g, "_");
+}
+/** A quoted property tree also supports namespace segments that are TS keywords. */
+function renderEnvironment(path, input, output) {
+    let declaration = `(input: ${input}) => Promise<${output}>`;
+    for (const segment of path.split(".").reverse())
+        declaration = `{ [${JSON.stringify(segment)}]: ${declaration} }`;
+    return declaration;
+}
+/** Render a namespace index as a callable nested environment. */
+export function renderNamespaceIndex(operations) {
+    return operations.length === 0
+        ? ""
+        : `export declare const env: ${operations.map((operation) => operation.indexEnvironment).join(" & ")};`;
+}
+/** Render whole-operation schemas and their callable nested environment. */
+export function renderOperationTypes(operations) {
+    const types = operations.map((operation) => operation.types).join("\n\n");
+    return operations.length === 0
+        ? types
+        : `${types}\nexport declare const env: ${operations.map((operation) => operation.environment).join(" & ")};`;
+}
+/** Prepare all TypeScript descriptions for one operation at installation. */
+export function renderOperation(operation) {
+    const name = safeTypeName(operation.path.replace(/\./g, "$"));
+    const input = renderSchemaType(operation.input, "input");
+    const output = operation.output
+        ? renderSchemaType(operation.output, "output")
+        : "unknown";
+    return Object.freeze({
+        indexEnvironment: renderEnvironment(operation.path, input, output),
+        environment: renderEnvironment(operation.path, `${name}_Input`, `${name}_Output`),
+        types: `export type ${name}_Input = ${input};\nexport type ${name}_Output = ${output};`,
+    });
+}
+/** Derive sample arguments solely from input-schema examples and defaults. */
+export function deriveSample(schema) {
+    const node = schemaFor(schema, "input");
+    if (node === true || node === false || !node.properties) {
+        return undefined;
+    }
+    const properties = node.properties;
+    const sample = {};
+    let found = false;
+    const entries = Object.entries(properties).sort(([left], [right]) => compareCodeUnits(left, right));
+    for (const [key, value] of entries) {
+        if (value === true || value === false)
+            continue;
+        const property = value;
+        const examples = property.examples;
+        if (examples && examples.length > 0) {
+            const example = jsonValueSchema.safeParse(examples[0]);
+            if (example.success) {
+                sample[key] = example.data;
+                found = true;
+            }
+        }
+        else if (property.default !== undefined) {
+            const fallback = jsonValueSchema.safeParse(property.default);
+            if (fallback.success) {
+                sample[key] = fallback.data;
+                found = true;
+            }
+        }
+    }
+    return found ? sample : undefined;
+}
+/** Preserve validator constraints in the operation's Standard JSON Schema. */
+export function inputSchemaProjection(schema) {
+    const projection = factsFor(schema, "input").json;
+    if (projection === undefined) {
+        throw new ForageError("invalid_input", "Schema cannot be projected to JSON Schema");
+    }
+    return projection;
+}
+/** Produce a canonical schema representation used in peer identity and stamps. */
+export function schemaFingerprint(schema, io = "input") {
+    const facts = factsFor(schema, io);
+    facts.fingerprint ??= canonicalStringify(facts.json ?? null);
+    return facts.fingerprint;
+}
+function schemaDepth(value, depth) {
+    if (depth > maximumSampleDepth)
+        return depth;
+    if (Array.isArray(value)) {
+        let maximum = depth;
+        for (const item of value) {
+            maximum = Math.max(maximum, schemaDepth(item, depth + 1));
+        }
+        return maximum;
+    }
+    if (!isJsonObject(value))
+        return depth;
+    let maximum = depth;
+    for (const entry of Object.values(value)) {
+        maximum = Math.max(maximum, schemaDepth(entry, depth + 1));
+    }
+    return maximum;
+}
+/** Validate the bounded JSON projection before a catalog is installed. */
+export function schemaProjectionSize(schema, io) {
+    const facts = factsFor(schema, io);
+    facts.size ??= { bytes: measureProjection(schema, io, facts.json) };
+    return facts.size.bytes;
+}
+function measureProjection(schema, io, projection) {
+    if (!projection)
+        return undefined;
+    const encoded = JSON.stringify(projection);
+    if (encoded.length > 20_000 ||
+        schemaDepth(projection, 0) > maximumSampleDepth) {
+        return undefined;
+    }
+    if (io === "output")
+        return encoded.length;
+    const sample = deriveSample(schema);
+    if (!sample)
+        return encoded.length;
+    if (Object.keys(sample).length > maximumSampleEntries ||
+        schemaDepth(sample, 0) > maximumSampleDepth) {
+        return undefined;
+    }
+    let sampleText;
+    try {
+        sampleText = JSON.stringify(sample);
+    }
+    catch {
+        throw new ForageError("invalid_input", "Derived schema sample cannot be serialized");
+    }
+    if (!sampleText || sampleText.length > maximumSampleBytes)
+        return undefined;
+    return encoded.length + sampleText.length;
+}

package/dist/schemas.d.ts

@@ -0,0 +1,231 @@
+import { z } from "zod";
+export declare const maximumDescriptionTypes = 20000;
+export declare const maximumSampleEntries = 100;
+export declare const maximumSampleBytes = 4000;
+export declare const maximumSampleDepth = 16;
+/** Input accepted by the pure catalog search seam. */
+export declare const forageSearchInput: z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** Input accepted by the pure catalog description seam. */
+export declare const forageDescribeInput: z.ZodObject<{
+    path: z.ZodString;
+    detail: z.ZodDefault<z.ZodEnum<{
+        index: "index";
+        full: "full";
+    }>>;
+    methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Exhaustive listing request; cursor is scoped to one immutable catalog and filter. */
+export declare const forageListInput: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    namespace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** One ranked operation in a search response. */
+export declare const searchResultSchema: z.ZodObject<{
+    path: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    score: z.ZodNumber;
+    matchReason: z.ZodOptional<z.ZodString>;
+    sample: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    capabilityNotes: z.ZodOptional<z.ZodString>;
+    peers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        capabilityNotes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Bounded search response envelope. */
+export declare const searchOutputSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        score: z.ZodNumber;
+        matchReason: z.ZodOptional<z.ZodString>;
+        sample: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        capabilityNotes: z.ZodOptional<z.ZodString>;
+        peers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            capabilityNotes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    topScore: z.ZodNumber;
+    margin: z.ZodNumber;
+    catalogStamp: z.ZodString;
+}, z.core.$strip>;
+/** One exhaustive page, using the exact search operation summary schema. */
+export declare const listOutputSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        score: z.ZodNumber;
+        matchReason: z.ZodOptional<z.ZodString>;
+        sample: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        capabilityNotes: z.ZodOptional<z.ZodString>;
+        peers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            capabilityNotes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    nextCursor: z.ZodNullable<z.ZodString>;
+    catalogStamp: z.ZodString;
+}, z.core.$strip>;
+/** Deterministic description response. */
+export declare const describeOutputSchema: z.ZodObject<{
+    path: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    types: z.ZodString;
+    inputSchema: z.ZodOptional<z.ZodJSONSchema>;
+    kind: z.ZodEnum<{
+        module: "module";
+        operation: "operation";
+    }>;
+    usage: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Closed failure vocabulary for malformed or absent catalog requests. */
+export declare const forageFailureSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        empty_query: "empty_query";
+        empty_catalog: "empty_catalog";
+        unknown_target: "unknown_target";
+        duplicate_operation: "duplicate_operation";
+        invalid_input: "invalid_input";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+/** Options Forage passes when it asks a schema for its JSON Schema. */
+export type JsonSchemaTarget = Readonly<{
+    target: "draft-2020-12";
+}>;
+/**
+ * Any schema that describes itself through Standard JSON Schema: Zod 4
+ * schemas natively, and Effect schemas through Mycelium. Forage only renders
+ * descriptions; validation stays with the schema's owner.
+ */
+export type JsonSchemaSource = Readonly<{
+    "~standard": Readonly<{
+        jsonSchema: Readonly<{
+            /** JSON Schema of the value the operation accepts. */
+            input: (options: JsonSchemaTarget) => object;
+            /** JSON Schema of the value the operation returns. */
+            output: (options: JsonSchemaTarget) => object;
+        }>;
+    }>;
+}>;
+/** A secret-free, callback-free operation descriptor. */
+export declare const operationSchema: z.ZodObject<{
+    path: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    input: z.ZodCustom<Readonly<{
+        "~standard": Readonly<{
+            jsonSchema: Readonly<{
+                /** JSON Schema of the value the operation accepts. */
+                input: (options: JsonSchemaTarget) => object;
+                /** JSON Schema of the value the operation returns. */
+                output: (options: JsonSchemaTarget) => object;
+            }>;
+        }>;
+    }>, Readonly<{
+        "~standard": Readonly<{
+            jsonSchema: Readonly<{
+                /** JSON Schema of the value the operation accepts. */
+                input: (options: JsonSchemaTarget) => object;
+                /** JSON Schema of the value the operation returns. */
+                output: (options: JsonSchemaTarget) => object;
+            }>;
+        }>;
+    }>>;
+    output: z.ZodOptional<z.ZodCustom<Readonly<{
+        "~standard": Readonly<{
+            jsonSchema: Readonly<{
+                /** JSON Schema of the value the operation accepts. */
+                input: (options: JsonSchemaTarget) => object;
+                /** JSON Schema of the value the operation returns. */
+                output: (options: JsonSchemaTarget) => object;
+            }>;
+        }>;
+    }>, Readonly<{
+        "~standard": Readonly<{
+            jsonSchema: Readonly<{
+                /** JSON Schema of the value the operation accepts. */
+                input: (options: JsonSchemaTarget) => object;
+                /** JSON Schema of the value the operation returns. */
+                output: (options: JsonSchemaTarget) => object;
+            }>;
+        }>;
+    }>>>;
+    capabilityNotes: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Input used to construct one immutable catalog revision. */
+export declare const catalogInputSchema: z.ZodObject<{
+    revision: z.ZodString;
+    operations: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input: z.ZodCustom<Readonly<{
+            "~standard": Readonly<{
+                jsonSchema: Readonly<{
+                    /** JSON Schema of the value the operation accepts. */
+                    input: (options: JsonSchemaTarget) => object;
+                    /** JSON Schema of the value the operation returns. */
+                    output: (options: JsonSchemaTarget) => object;
+                }>;
+            }>;
+        }>, Readonly<{
+            "~standard": Readonly<{
+                jsonSchema: Readonly<{
+                    /** JSON Schema of the value the operation accepts. */
+                    input: (options: JsonSchemaTarget) => object;
+                    /** JSON Schema of the value the operation returns. */
+                    output: (options: JsonSchemaTarget) => object;
+                }>;
+            }>;
+        }>>;
+        output: z.ZodOptional<z.ZodCustom<Readonly<{
+            "~standard": Readonly<{
+                jsonSchema: Readonly<{
+                    /** JSON Schema of the value the operation accepts. */
+                    input: (options: JsonSchemaTarget) => object;
+                    /** JSON Schema of the value the operation returns. */
+                    output: (options: JsonSchemaTarget) => object;
+                }>;
+            }>;
+        }>, Readonly<{
+            "~standard": Readonly<{
+                jsonSchema: Readonly<{
+                    /** JSON Schema of the value the operation accepts. */
+                    input: (options: JsonSchemaTarget) => object;
+                    /** JSON Schema of the value the operation returns. */
+                    output: (options: JsonSchemaTarget) => object;
+                }>;
+            }>;
+        }>>>;
+        capabilityNotes: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Parsed search request type. */
+export type ForageSearchInput = z.input<typeof forageSearchInput>;
+/** Exhaustive listing request type. */
+export type ForageListInput = z.input<typeof forageListInput>;
+/** Exhaustive page response type. */
+export type ListOutput = z.infer<typeof listOutputSchema>;
+/** Parsed description request type. */
+export type ForageDescribeInput = z.input<typeof forageDescribeInput>;
+/** One ranked search result type. */
+export type SearchResult = z.infer<typeof searchResultSchema>;
+/** Search response envelope type. */
+export type SearchOutput = z.infer<typeof searchOutputSchema>;
+/** Description response type. */
+export type DescribeOutput = z.infer<typeof describeOutputSchema>;
+/** Typed failure value type. */
+export type ForageFailure = z.infer<typeof forageFailureSchema>;
+/** Catalog operation descriptor type. */
+export type Operation = z.infer<typeof operationSchema>;
+/** Catalog construction input type. */
+export type CatalogInput = z.input<typeof catalogInputSchema>;