@zenera/rag 1.1.0

package/dist/schema/typescript.js

@@ -0,0 +1,246 @@
+import { isObject, refName } from "./schema.js";
+const KEYWORDS = new Set(['string', 'number', 'boolean', 'object', 'any', 'unknown', 'null']);
+export class Printer {
+    #types;
+    #tags = new Map();
+    #names = new Map();
+    constructor(types) {
+        this.#types = types;
+        this.#assignNames();
+        this.#findTags();
+    }
+    /** The TypeScript identifier a type id is printed as. */
+    identifier(id) {
+        return this.#names.get(id) ?? sanitize(id);
+    }
+    /** An inline type expression — what goes to the right of a colon. */
+    signature(schema, depth = 0) {
+        if (schema === true || schema === undefined) {
+            return 'unknown';
+        }
+        if (schema === false) {
+            return 'never';
+        }
+        if (!isObject(schema)) {
+            return 'unknown';
+        }
+        const ref = refName(schema);
+        if (ref !== undefined) {
+            return this.#types[ref] ? this.identifier(ref) : 'unknown';
+        }
+        if ('const' in schema) {
+            return literal(schema.const);
+        }
+        if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+            return schema.enum.map(literal).join(' | ');
+        }
+        for (const [key, join] of [
+            ['oneOf', ' | '],
+            ['anyOf', ' | '],
+            ['allOf', ' & '],
+        ]) {
+            const list = schema[key];
+            if (Array.isArray(list) && list.length > 0) {
+                const parts = list.map((s) => this.#wrap(s, depth));
+                return dedupe(parts).join(join);
+            }
+        }
+        const types = typesOf(schema);
+        if (types.length > 1) {
+            return dedupe(types.map((t) => this.#scalar(t, schema, depth))).join(' | ');
+        }
+        return this.#scalar(types[0], schema, depth);
+    }
+    /** A whole `export interface` / `export type` declaration for one id. */
+    declaration(id, options = {}) {
+        const schema = this.#types[id];
+        if (!schema) {
+            return '';
+        }
+        const name = this.identifier(id);
+        const comment = this.#comment(doc(schema), options, '');
+        const head = comment ? `${comment}\n` : '';
+        const properties = isObject(schema.properties) ? schema.properties : undefined;
+        if (!properties) {
+            return `${head}export type ${name} = ${this.signature(schema)};\n`;
+        }
+        return `${head}export interface ${name} ${this.#body(id, schema, options)}\n`;
+    }
+    // -----------------------------------------------------------------------
+    #body(id, schema, options) {
+        const properties = isObject(schema.properties) ? schema.properties : {};
+        const required = new Set(Array.isArray(schema.required) ? schema.required.filter(isString) : []);
+        const tag = this.#tags.get(id);
+        const lines = ['{'];
+        for (const [key, value] of Object.entries(properties)) {
+            if (options.only && !options.only.has(key)) {
+                continue;
+            }
+            const type = tag && tag.property === key ? literal(tag.value) : this.signature(value, 1);
+            lines.push(this.#comment(doc(value), options, '    '));
+            lines.push(`    ${property(key)}${required.has(key) ? '' : '?'}: ${type};`);
+        }
+        const extra = schema.additionalProperties;
+        if (extra !== undefined && extra !== false) {
+            lines.push(`    [key: string]: ${this.signature(extra, 1)};`);
+        }
+        lines.push('}');
+        // A `/** … */` line is emitted as '' when docs are off; dropping the
+        // blanks here keeps the two modes from differing by whitespace.
+        return lines.filter((line) => line !== '').join('\n');
+    }
+    /**
+     * The discriminated child rendered inline: `Cat` alone is the interface,
+     * but inside `type Pet = …` it is the branch, and the branch is what makes
+     * `if (pet.petType === 'cat')` narrow.
+     */
+    #wrap(schema, depth) {
+        return this.signature(schema, depth + 1);
+    }
+    #scalar(type, schema, depth) {
+        switch (type) {
+            case 'null':
+                return 'null';
+            case 'boolean':
+                return 'boolean';
+            case 'integer':
+            case 'number':
+                return 'number';
+            case 'string':
+                return 'string';
+            case 'array': {
+                const items = schema.prefixItems;
+                if (Array.isArray(items)) {
+                    return `[${items.map((s) => this.signature(s, depth + 1)).join(', ')}]`;
+                }
+                const inner = this.signature(schema.items, depth + 1);
+                return /[ |&]/.test(inner) ? `(${inner})[]` : `${inner}[]`;
+            }
+            case 'object':
+                return this.#inline(schema, depth);
+            default:
+                return schema.properties || schema.additionalProperties
+                    ? this.#inline(schema, depth)
+                    : 'unknown';
+        }
+    }
+    /** An object with no name of its own, printed where it stands. */
+    #inline(schema, depth) {
+        const properties = isObject(schema.properties) ? schema.properties : undefined;
+        if (!properties) {
+            const extra = schema.additionalProperties;
+            return extra === undefined || extra === true || extra === false
+                ? 'Record<string, unknown>'
+                : `Record<string, ${this.signature(extra, depth + 1)}>`;
+        }
+        // Past a few levels an inline object stops being readable and the
+        // graph has a named node for it anyway.
+        if (depth >= 3) {
+            return 'Record<string, unknown>';
+        }
+        const required = new Set(Array.isArray(schema.required) ? schema.required.filter(isString) : []);
+        const parts = Object.entries(properties).map(([key, value]) => `${property(key)}${required.has(key) ? '' : '?'}: ${this.signature(value, depth + 1)}`);
+        return parts.length > 0 ? `{ ${parts.join('; ')} }` : 'Record<string, unknown>';
+    }
+    #comment(text, options, indent) {
+        if (!options.docs || !text) {
+            return '';
+        }
+        const max = options.maxDoc ?? 200;
+        const one = text.replace(/\s+/g, ' ').trim();
+        const cut = one.length > max ? `${one.slice(0, max - 1)}…` : one;
+        return `${indent}/** ${cut.replace(/\*\//g, '*\u200b/')} */`;
+    }
+    /** Ids differ, identifiers may not; the second claimant is suffixed. */
+    #assignNames() {
+        const taken = new Set();
+        for (const id of Object.keys(this.#types)) {
+            let name = sanitize(id);
+            for (let n = 2; taken.has(name); n++) {
+                name = `${sanitize(id)}${n}`;
+            }
+            taken.add(name);
+            this.#names.set(id, name);
+        }
+    }
+    /**
+     * Both spellings of a discriminated union: the tag beside a `oneOf`, and
+     * the tag on a base type the children `allOf` into.
+     */
+    #findTags() {
+        for (const [id, schema] of Object.entries(this.#types)) {
+            const discriminator = schema.discriminator;
+            if (!isObject(discriminator) || typeof discriminator.propertyName !== 'string') {
+                continue;
+            }
+            const property = discriminator.propertyName;
+            const mapping = isObject(discriminator.mapping) ? discriminator.mapping : {};
+            for (const [value, target] of Object.entries(mapping)) {
+                const child = typeof target === 'string' ? tail(target) : undefined;
+                if (child && this.#types[child]) {
+                    this.#tags.set(child, { property, value });
+                }
+            }
+            for (const child of this.#children(id, schema)) {
+                if (!this.#tags.has(child)) {
+                    this.#tags.set(child, { property, value: child });
+                }
+            }
+        }
+    }
+    #children(id, schema) {
+        const branches = [schema.oneOf, schema.anyOf].filter(Array.isArray).flat();
+        const named = branches.map(refName).filter(isString);
+        if (named.length > 0) {
+            return named;
+        }
+        // The `allOf` idiom: the base declares the tag, the children point back.
+        return Object.entries(this.#types)
+            .filter(([, other]) => (Array.isArray(other.allOf) ? other.allOf : []).some((s) => refName(s) === id))
+            .map(([other]) => other);
+    }
+}
+// ---------------------------------------------------------------------------
+const isString = (v) => typeof v === 'string';
+function typesOf(schema) {
+    const type = schema.type;
+    if (Array.isArray(type)) {
+        return type.filter(isString);
+    }
+    return [isString(type) ? type : undefined];
+}
+function dedupe(parts) {
+    return [...new Set(parts)];
+}
+function literal(value) {
+    if (typeof value === 'string') {
+        return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+    }
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return 'unknown';
+}
+/** A key that is not a plain identifier has to be quoted. */
+export function property(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : `'${key.replace(/'/g, "\\'")}'`;
+}
+function doc(schema) {
+    if (!isObject(schema)) {
+        return '';
+    }
+    const description = schema.description ?? schema.title;
+    return isString(description) ? description : '';
+}
+function tail(pointer) {
+    return decodeURIComponent((pointer.split('/').pop() ?? '').replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+function sanitize(id) {
+    const cleaned = id.replace(/[^A-Za-z0-9_$]+/g, '_').replace(/^_+/, '');
+    const safe = /^[A-Za-z_$]/.test(cleaned) ? cleaned : `T${cleaned}`;
+    return KEYWORDS.has(safe) ? `${safe}_` : safe || 'Anonymous';
+}
+//# sourceMappingURL=typescript.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "@zenera/rag",
+    "version": "1.1.0",
+    "description": "Retrieval over API descriptions: openapi/swagger documents as a searchable graph.",
+    "keywords": [
+        "agents",
+        "ai-agents",
+        "llm",
+        "openapi",
+        "rag",
+        "vector-search"
+    ],
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "author": "Andrey Ryabov",
+    "homepage": "https://github.com/andreyryabov/ZeneraNeo#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/andreyryabov/ZeneraNeo.git",
+        "directory": "packages/rag"
+    },
+    "bugs": "https://github.com/andreyryabov/ZeneraNeo/issues",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./command": {
+            "types": "./dist/command.d.ts",
+            "default": "./dist/command.js"
+        },
+        "./tools": {
+            "types": "./dist/schema/tools.d.ts",
+            "default": "./dist/schema/tools.js"
+        }
+    },
+    "files": [
+        "dist",
+        "!dist/**/*.map"
+    ],
+    "engines": {
+        "node": ">=24"
+    },
+    "scripts": {
+        "build": "tsc -b",
+        "clean": "tsc -b --clean && rm -rf dist",
+        "prepack": "tsc -b"
+    },
+    "dependencies": {
+        "@apidevtools/swagger-parser": "^12.0.0",
+        "@lancedb/lancedb": "^0.38.0",
+        "graphology": "^0.26.0",
+        "@zenera/cli": "^1.1.0",
+        "@zenera/neo": "^1.1.0"
+    }
+}