@zenera/rag 1.1.0

package/dist/schema/graph.js

@@ -0,0 +1,320 @@
+import { MultiDirectedGraph } from 'graphology';
+import { isObject, refName } from "./schema.js";
+import { methodTypeOf, } from "./spec.js";
+import { Printer } from "./typescript.js";
+export const methodId = (operationId) => `Method:${operationId}`;
+export const typeId = (name) => `Type:${name}`;
+export const propertyId = (parent, name) => `Property:${parent}.${name}`;
+export const paramId = (operationId, name) => `Property:${operationId}#${name}`;
+/** How deep an anonymous object is given a name of its own before giving up. */
+const MAX_SYNTHESIS_DEPTH = 4;
+export function buildGraph(corpus) {
+    return new Builder(corpus).run();
+}
+class Builder {
+    #corpus;
+    #graph = new MultiDirectedGraph();
+    #types;
+    /** property node -> the schema it was built from, for signatures at the end */
+    #schemas = new Map();
+    /** synthesized type -> how many levels of anonymity it sat under */
+    #depths = new Map();
+    #source;
+    #queue = [];
+    #expanded = new Set();
+    constructor(corpus) {
+        this.#corpus = corpus;
+        this.#types = { ...corpus.types };
+        this.#source = { ...corpus.typeSource };
+        this.#queue.push(...Object.keys(corpus.types));
+    }
+    run() {
+        for (const operation of this.#corpus.operations) {
+            this.#operation(operation);
+        }
+        while (this.#queue.length > 0) {
+            this.#expand(this.#queue.pop());
+        }
+        this.#signatures();
+        propagate(this.#graph);
+        return { graph: this.#graph, types: this.#types };
+    }
+    // -----------------------------------------------------------------------
+    // Operations
+    // -----------------------------------------------------------------------
+    #operation(op) {
+        const id = methodId(op.operationId);
+        this.#graph.mergeNode(id, {
+            ...blank(),
+            kind: 'method',
+            name: op.operationId,
+            doc: op.summary || op.description,
+            methodType: methodTypeOf(op.method),
+            httpMethod: op.method.toUpperCase(),
+            path: op.path,
+            source: op.source,
+        });
+        for (const param of op.params) {
+            const node = paramId(op.operationId, param.name);
+            this.#graph.mergeNode(node, {
+                ...blank(),
+                kind: 'property',
+                name: param.name,
+                parent: op.operationId,
+                doc: param.doc,
+                source: op.source,
+                required: param.required,
+            });
+            this.#schemas.set(node, param.schema);
+            this.#edge(id, node, { relation: 'HAS_PARAM', status: 0, in: param.in });
+            const target = this.#resolve(param.schema, `${op.operationId}_${param.name}`, 1, op.source);
+            if (target) {
+                this.#edge(node, typeId(target), edge('OF_TYPE'));
+            }
+        }
+        if (op.requestBody) {
+            const target = this.#resolve(op.requestBody.schema, `${op.operationId}Request`, 0, op.source);
+            if (target) {
+                this.#edge(id, typeId(target), edge('TAKES_INPUT'));
+            }
+        }
+        const many = op.responses.length > 1;
+        for (const response of op.responses) {
+            const preferred = many
+                ? `${op.operationId}Response${response.status}`
+                : `${op.operationId}Response`;
+            const target = this.#resolve(response.schema, preferred, 0, op.source);
+            if (target) {
+                this.#edge(id, typeId(target), {
+                    relation: 'RETURNS_OUTPUT',
+                    status: response.status,
+                    in: '',
+                });
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Types
+    // -----------------------------------------------------------------------
+    /**
+     * The type id a schema stands for, inventing one where the document did
+     * not bother. An array is unwrapped first: `returns User[]` and
+     * `returns User` are the same edge as far as reaching `User` goes, and
+     * keeping a `UsersResponse` wrapper in between costs a hop and says nothing.
+     */
+    #resolve(schema, preferred, depth, source) {
+        if (!isObject(schema)) {
+            return undefined;
+        }
+        const ref = refName(schema);
+        if (ref !== undefined) {
+            return this.#types[ref] ? ref : undefined;
+        }
+        if (schema.type === 'array' || schema.items !== undefined) {
+            return this.#resolve(schema.items, preferred, depth, source);
+        }
+        if (!worthNaming(schema) || depth >= MAX_SYNTHESIS_DEPTH) {
+            return undefined;
+        }
+        return this.#synthesize(preferred, schema, depth, source);
+    }
+    #synthesize(preferred, schema, depth, source) {
+        let name = preferred;
+        for (let n = 2; this.#types[name]; n++) {
+            name = `${preferred}${n}`;
+        }
+        this.#types[name] = schema;
+        this.#source[name] = source;
+        this.#depths.set(name, depth);
+        this.#queue.push(name);
+        return name;
+    }
+    #expand(name) {
+        if (this.#expanded.has(name)) {
+            return;
+        }
+        this.#expanded.add(name);
+        const schema = this.#types[name];
+        if (!schema) {
+            return;
+        }
+        const id = typeId(name);
+        const depth = this.#depths.get(name) ?? 0;
+        const source = this.#source[name] ?? '';
+        this.#graph.mergeNode(id, {
+            ...blank(),
+            kind: 'type',
+            name,
+            doc: docOf(schema),
+            source,
+        });
+        for (const key of ['allOf', 'anyOf', 'oneOf']) {
+            const list = schema[key];
+            if (!Array.isArray(list)) {
+                continue;
+            }
+            for (const member of list) {
+                const target = refName(member);
+                if (target && this.#types[target]) {
+                    this.#edge(id, typeId(target), edge('COMPOSES'));
+                }
+            }
+        }
+        const items = this.#resolve(schema.items, `${name}Item`, depth + 1, source);
+        if (items) {
+            this.#edge(id, typeId(items), edge('ITEM_OF'));
+        }
+        const { properties, required } = flatten(schema, this.#types);
+        for (const [key, value] of Object.entries(properties)) {
+            const node = propertyId(name, key);
+            this.#graph.mergeNode(node, {
+                ...blank(),
+                kind: 'property',
+                name: key,
+                parent: name,
+                doc: docOf(value),
+                source,
+                required: required.has(key),
+            });
+            this.#schemas.set(node, value);
+            this.#edge(id, node, edge('HAS_PROPERTY'));
+            const target = this.#resolve(value, `${name}_${capital(key)}`, depth + 1, source);
+            if (target) {
+                this.#edge(node, typeId(target), edge('OF_TYPE'));
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    #edge(from, to, attrs) {
+        if (!this.#graph.hasNode(to)) {
+            this.#graph.addNode(to, { ...blank(), kind: 'type', name: to.slice(5) });
+        }
+        this.#graph.addDirectedEdge(from, to, attrs);
+    }
+    /** One printer over the settled corpus, so every signature agrees. */
+    #signatures() {
+        const printer = new Printer(this.#types);
+        for (const [node, schema] of this.#schemas) {
+            if (this.#graph.hasNode(node)) {
+                this.#graph.setNodeAttribute(node, 'signature', printer.signature(schema));
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Direction
+// ---------------------------------------------------------------------------
+/**
+ * Which side of a call a node lives on. Seeded from the operations — a request
+ * body is an input, a response is an output — and then pushed down through
+ * composition until it stops. A DTO used both ways comes out `both`, which is
+ * the honest answer and the reason this is a closure rather than a flag set at
+ * the point of use.
+ */
+export function propagate(graph) {
+    const inputs = new Set();
+    const outputs = new Set();
+    graph.forEachDirectedEdge((_edge, attrs, _source, target) => {
+        if (attrs.relation === 'TAKES_INPUT' || attrs.relation === 'HAS_PARAM') {
+            inputs.add(target);
+        }
+        else if (attrs.relation === 'RETURNS_OUTPUT') {
+            outputs.add(target);
+        }
+    });
+    const DOWN = new Set(['HAS_PROPERTY', 'OF_TYPE', 'COMPOSES', 'ITEM_OF']);
+    for (const [seeds, mark] of [
+        [inputs, 'input'],
+        [outputs, 'output'],
+    ]) {
+        const seen = new Set();
+        const stack = [...seeds];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (seen.has(node) || !graph.hasNode(node)) {
+                continue;
+            }
+            seen.add(node);
+            const was = graph.getNodeAttribute(node, 'direction');
+            graph.setNodeAttribute(node, 'direction', was === 'none' || was === mark ? mark : 'both');
+            graph.forEachOutEdge(node, (_e, attrs, _s, target) => {
+                if (DOWN.has(attrs.relation)) {
+                    stack.push(target);
+                }
+            });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+function blank() {
+    return {
+        kind: 'type',
+        name: '',
+        parent: '',
+        doc: '',
+        direction: 'none',
+        methodType: 'n/a',
+        httpMethod: '',
+        path: '',
+        source: '',
+        signature: '',
+        required: false,
+    };
+}
+function edge(relation) {
+    return { relation, status: 0, in: '' };
+}
+/** Worth a node of its own: it has fields, or it is a choice between things. */
+function worthNaming(schema) {
+    return (isObject(schema.properties) ||
+        Array.isArray(schema.allOf) ||
+        Array.isArray(schema.oneOf) ||
+        Array.isArray(schema.anyOf));
+}
+/**
+ * The properties a type actually has. `allOf` with an inline member is how
+ * most documents spell inheritance, and leaving those fields off the type that
+ * declares them would hide them from every search.
+ */
+function flatten(schema, types, seen = new Set()) {
+    const properties = {};
+    const required = new Set();
+    if (seen.has(schema)) {
+        return { properties, required };
+    }
+    seen.add(schema);
+    if (isObject(schema.properties)) {
+        Object.assign(properties, schema.properties);
+    }
+    if (Array.isArray(schema.required)) {
+        for (const key of schema.required) {
+            if (typeof key === 'string') {
+                required.add(key);
+            }
+        }
+    }
+    for (const member of Array.isArray(schema.allOf) ? schema.allOf : []) {
+        // A named member is a node in its own right, reached by COMPOSES.
+        if (!isObject(member) || refName(member) !== undefined) {
+            continue;
+        }
+        const inner = flatten(member, types, seen);
+        Object.assign(properties, inner.properties);
+        for (const key of inner.required) {
+            required.add(key);
+        }
+    }
+    return { properties, required };
+}
+function docOf(schema) {
+    if (!isObject(schema)) {
+        return '';
+    }
+    const description = schema.description ?? schema.title;
+    return typeof description === 'string' ? description.trim() : '';
+}
+function capital(key) {
+    const cleaned = key.replace(/[^A-Za-z0-9]+/g, '_');
+    return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
+//# sourceMappingURL=graph.js.map

package/dist/schema/hydrate.d.ts

@@ -0,0 +1,19 @@
+import { type Schema } from './schema.ts';
+import type { Operation } from './spec.ts';
+import type { Subgraph } from './subgraph.ts';
+export interface HydrateOptions {
+    docs?: boolean;
+    maxDoc?: number;
+    /** narrow each interface to the properties the search actually matched */
+    onlyHits?: boolean;
+}
+export declare function toTypeScript(sub: Subgraph, schemas: Readonly<Record<string, Schema>>, options?: HydrateOptions): string;
+/**
+ * The other half of the job: when the task is to *call* the API rather than to
+ * type its payloads, a valid document beats a declaration file.
+ */
+export declare function toOpenApi(sub: Subgraph, schemas: Readonly<Record<string, Schema>>, operations: readonly Operation[], info?: {
+    title: string;
+    version: string;
+}): Record<string, unknown>;
+//# sourceMappingURL=hydrate.d.ts.map

package/dist/schema/hydrate.js

@@ -0,0 +1,182 @@
+import { refsIn } from "./schema.js";
+import { Printer, property } from "./typescript.js";
+export function toTypeScript(sub, schemas, options = {}) {
+    const printer = new Printer(schemas);
+    const wanted = closure(typeNames(sub), schemas);
+    const only = options.onlyHits ? hitProperties(sub) : undefined;
+    const blocks = [];
+    const operations = sub.nodes.filter((n) => n.kind === 'method');
+    if (operations.length > 0) {
+        blocks.push(operations.map((m) => routeComment(m)).join('\n'));
+    }
+    const printed = new Set([...wanted].map((name) => printer.identifier(name)));
+    for (const method of operations) {
+        const block = params(sub, method, printer, printed, options);
+        if (block) {
+            blocks.push(block);
+        }
+    }
+    for (const name of [...wanted].sort()) {
+        blocks.push(printer.declaration(name, {
+            docs: options.docs,
+            maxDoc: options.maxDoc,
+            only: only?.get(name),
+        }));
+    }
+    return blocks.filter(Boolean).join('\n');
+}
+/**
+ * The other half of the job: when the task is to *call* the API rather than to
+ * type its payloads, a valid document beats a declaration file.
+ */
+export function toOpenApi(sub, schemas, operations, info = { title: 'Selection', version: '0' }) {
+    const names = new Set(sub.nodes.filter((n) => n.kind === 'method').map((n) => n.attributes.name));
+    const chosen = operations.filter((op) => names.has(op.operationId));
+    const wanted = closure(typeNames(sub), schemas);
+    const paths = {};
+    for (const op of chosen) {
+        for (const name of [
+            ...op.params.flatMap((p) => refsIn(p.schema)),
+            ...refsIn(op.requestBody?.schema),
+            ...op.responses.flatMap((r) => refsIn(r.schema)),
+        ]) {
+            wanted.add(name);
+        }
+        (paths[op.path] ??= {})[op.method] = {
+            operationId: op.operationId,
+            ...(op.summary ? { summary: op.summary } : {}),
+            ...(op.description ? { description: op.description } : {}),
+            ...(op.params.length > 0
+                ? {
+                    parameters: op.params.map((p) => ({
+                        name: p.name,
+                        in: p.in,
+                        required: p.required,
+                        ...(p.doc ? { description: p.doc } : {}),
+                        schema: p.schema,
+                    })),
+                }
+                : {}),
+            ...(op.requestBody
+                ? {
+                    requestBody: {
+                        required: op.requestBody.required,
+                        content: { 'application/json': { schema: op.requestBody.schema } },
+                    },
+                }
+                : {}),
+            responses: Object.fromEntries(op.responses.map((r) => [
+                String(r.status),
+                {
+                    description: r.doc || 'Success',
+                    content: { 'application/json': { schema: r.schema } },
+                },
+            ])),
+        };
+    }
+    // Everything was rewritten to `#/$defs/<id>` at load; a standalone document
+    // has to point at where the schemas are about to be written instead.
+    const components = Object.fromEntries([...closure(wanted, schemas)].sort().map((name) => [name, rebase(schemas[name])]));
+    return {
+        openapi: '3.1.0',
+        info,
+        paths: rebase(paths),
+        components: { schemas: components },
+    };
+}
+// ---------------------------------------------------------------------------
+function typeNames(sub) {
+    return new Set(sub.nodes.filter((n) => n.kind === 'type').map((n) => n.attributes.name));
+}
+/** Every name reachable from the selection, so nothing printed dangles. */
+function closure(names, schemas) {
+    const out = new Set();
+    const stack = [...names];
+    while (stack.length > 0) {
+        const name = stack.pop();
+        if (out.has(name) || !schemas[name]) {
+            continue;
+        }
+        out.add(name);
+        stack.push(...refsIn(schemas[name]));
+    }
+    return out;
+}
+function hitProperties(sub) {
+    const out = new Map();
+    for (const node of sub.nodes) {
+        if (node.kind !== 'property' || !node.hit || !node.attributes.parent) {
+            continue;
+        }
+        const set = out.get(node.attributes.parent) ?? new Set();
+        set.add(node.attributes.name);
+        out.set(node.attributes.parent, set);
+    }
+    return out;
+}
+function routeComment(method) {
+    const a = method.attributes;
+    return `// ${a.httpMethod} ${a.path}${a.doc ? `  — ${a.doc.replace(/\s+/g, ' ')}` : ''}`;
+}
+/** The parameters of one operation, as something a caller can hold. */
+function params(sub, method, printer, printed, options) {
+    const owned = sub.edges
+        .filter((e) => e.source === method.id && e.relation === 'HAS_PARAM')
+        .map((e) => ({ edge: e, node: sub.nodes.find((n) => n.id === e.target) }))
+        .filter((p) => !!p.node);
+    if (owned.length === 0) {
+        return '';
+    }
+    const lines = [`export interface ${printer.identifier(`${method.attributes.name}Params`)} {`];
+    for (const { edge, node } of owned) {
+        const a = node.attributes;
+        const note = [edge.in, a.doc].filter(Boolean).join(' — ');
+        if (options.docs && note) {
+            lines.push(`    /** ${note.replace(/\s+/g, ' ')} */`);
+        }
+        lines.push(`    ${property(a.name)}${a.required ? '' : '?'}: ${resolvable(a.signature, printed)};`);
+    }
+    lines.push('}\n');
+    return lines.join('\n');
+}
+const BUILTIN = new Set([
+    'string',
+    'number',
+    'boolean',
+    'null',
+    'unknown',
+    'never',
+    'Record',
+    'true',
+    'false',
+]);
+/**
+ * Signatures were computed against the whole corpus, so one may name a type
+ * this selection does not print. `unknown` is a worse answer than the name and
+ * a far better one than a file that will not compile.
+ */
+function resolvable(signature, printed) {
+    if (!signature) {
+        return 'unknown';
+    }
+    const names = signature.replace(/'[^']*'/g, '').match(/[A-Za-z_$][A-Za-z0-9_$]*/g) ?? [];
+    return names.every((name) => BUILTIN.has(name) || printed.has(name)) ? signature : 'unknown';
+}
+/** `#/$defs/X` back to `#/components/schemas/X`. */
+function rebase(value) {
+    if (Array.isArray(value)) {
+        return value.map(rebase);
+    }
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    const out = {};
+    for (const [key, inner] of Object.entries(value)) {
+        out[key] =
+            key === '$ref' && typeof inner === 'string'
+                ? inner.replace(/^#\/\$defs\//, '#/components/schemas/')
+                : rebase(inner);
+    }
+    return out;
+}
+//# sourceMappingURL=hydrate.js.map

package/dist/schema/render.d.ts

@@ -0,0 +1,11 @@
+import type { Subgraph } from './subgraph.ts';
+export type RenderFormat = 'text' | 'mermaid' | 'mermaid-flowchart';
+export interface RenderOptions {
+    docs?: boolean;
+    maxDoc?: number;
+}
+export declare function render(sub: Subgraph, format: RenderFormat, options?: RenderOptions): string;
+export declare function toText(sub: Subgraph, options?: RenderOptions): string;
+export declare function toMermaid(sub: Subgraph, options?: RenderOptions): string;
+export declare function toFlowchart(sub: Subgraph, options?: RenderOptions): string;
+//# sourceMappingURL=render.d.ts.map