@volter/twin-standard 1.0.0

package/dist/src/spec-ir-proto.d.ts

@@ -0,0 +1,80 @@
+import type { SpecIR } from './spec-ir.js';
+type ProtoField = {
+    name: string;
+    jsonName: string;
+    number: number;
+    type: string;
+    repeated: boolean;
+    map?: {
+        key: string;
+        value: string;
+    };
+    oneof?: string;
+};
+type ProtoMessage = {
+    fullName: string;
+    fields: ProtoField[];
+};
+type ProtoEnum = {
+    fullName: string;
+    values: string[];
+    numbers: Record<string, number>;
+};
+type ProtoRpc = {
+    name: string;
+    request: string;
+    response: string;
+    clientStreams: boolean;
+    serverStreams: boolean;
+};
+type ProtoService = {
+    fullName: string;
+    rpcs: ProtoRpc[];
+};
+export type ProtoFile = {
+    path: string;
+    pkg: string;
+    messages: ProtoMessage[];
+    enums: ProtoEnum[];
+    services: ProtoService[];
+};
+/** One `.proto` file's declarations. */
+export declare function parseProto(path: string, text: string): ProtoFile;
+/** The vendored tree (path → text) as data, so a spec patch corrects it as it corrects a JSON spec (derive-pack). */
+export type ProtoSpec = {
+    format: 'proto';
+    files: ProtoFile[];
+};
+export declare function readProtoFiles(files: Record<string, string>): ProtoSpec;
+/** The IR of the services the vendored files declare: every rpc of every service one operation. */
+export declare function fromProto(spec: ProtoSpec): SpecIR;
+/** A field as the kernel's protobuf codec reads it: its number, its JSON name, and its type resolved (a scalar's name, or
+ *  a message's or an enum's full name with its kind). */
+export type ProtoSchemaField = {
+    name: string;
+    json: string;
+    number: number;
+    type: string;
+    kind: 'scalar' | 'message' | 'enum';
+    repeated?: true;
+    map?: {
+        key: string;
+        value: string;
+        valueKind: 'scalar' | 'message' | 'enum';
+    };
+};
+/** The schema the derive writes for a proto unit (`src/generated/proto.gen.json`): every message's fields, every enum's
+ *  numbers, and each rpc's path, request and response, all by full name. */
+export type ProtoSchema = {
+    messages: Record<string, ProtoSchemaField[]>;
+    enums: Record<string, Record<string, number>>;
+    rpcs: Record<string, {
+        operation: string;
+        request: string;
+        response: string;
+        serverStreams?: true;
+        clientStreams?: true;
+    }>;
+};
+export declare function protoSchema(spec: ProtoSpec): ProtoSchema;
+export {};

package/dist/src/spec-ir-proto.js

@@ -0,0 +1,339 @@
+// A Protocol Buffers service as the IR (spec-ir.ts): the spec of a vendor whose API is RPCs over HTTP rather than
+// REST paths (PlanetScale's psdb data plane, `psdb.v1alpha1.Database`, which @planetscale/database calls). The
+// `.proto` files are the vendor's published words, vendored under `spec/proto/` with every file they import.
+//
+// Connect's unary protocol (connectrpc.com/docs/protocol) addresses an rpc as `POST /<package>.<Service>/<Method>`
+// with the request message as its body in the proto3 JSON mapping (protobuf.dev/programming-guides/json): a field is
+// named by its lowerCamelCase JSON name, 64-bit integers are strings, bytes are base64, enums are their value names,
+// a map is an object, and a field holding its default value may be omitted. So each rpc is one operation: its request
+// message's fields are the body, and its response message is what it answers. A service's operations act on no
+// resource path, so each is an `action`; the response messages are the resources, as a spec that declares none yields
+// resources named after its response schemas.
+const SCALARS = {
+    double: 'number', float: 'number',
+    int32: 'integer', uint32: 'integer', sint32: 'integer', fixed32: 'integer', sfixed32: 'integer',
+    // proto3 JSON writes 64-bit integers as decimal strings
+    int64: 'string', uint64: 'string', sint64: 'string', fixed64: 'string', sfixed64: 'string',
+    bool: 'boolean', string: 'string', bytes: 'string',
+};
+/** protoc's JSON name: underscores dropped, the letter after each upper-cased. */
+const jsonNameOf = (name) => name.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+function tokens(text) {
+    // strings, comments and tokens in one pass: a `//` inside a string ("https://…") is the string's, not a comment
+    const all = text.match(/"(?:[^"\\]|\\.)*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/|[A-Za-z_][\w.]*|0[xX][0-9a-fA-F]+|\d+(?:\.\d+)?|[{}()<>;=,[\]-]/g) ?? [];
+    return all.filter((x) => !x.startsWith('//') && !x.startsWith('/*'));
+}
+/** One `.proto` file's declarations. */
+export function parseProto(path, text) {
+    const t = tokens(text);
+    let i = 0;
+    const file = { path, pkg: '', messages: [], enums: [], services: [] };
+    const expect = (tok) => { if (t[i] !== tok)
+        throw new Error(`spec-ir-proto: ${path}: expected "${tok}", found "${t[i]}"`); i++; };
+    // a statement ends at its `;`, or at the `}` closing a block that is its body (`extend X { … }`); braces inside
+    // brackets or an option's value (`[declaration = { … }]`, `option (x) = { … };`) do not end it
+    const skipStatement = () => {
+        let depth = 0;
+        while (i < t.length) {
+            const x = t[i++];
+            if (x === '{' || x === '[')
+                depth++;
+            else if (x === '}' || x === ']') {
+                depth--;
+                if (depth <= 0 && x === '}' && t[i] !== ';')
+                    return;
+            }
+            else if (x === ';' && depth <= 0)
+                return;
+        }
+    };
+    // a field's options, nested brackets and all (`[(google.api.field_behavior) = REQUIRED, (x) = { a: [1] }]`)
+    const skipOptions = () => { if (t[i] !== '[')
+        return; let depth = 0; do {
+        if (t[i] === '[')
+            depth++;
+        else if (t[i] === ']')
+            depth--;
+        i++;
+    } while (depth > 0 && i < t.length); };
+    const scope = () => file.pkg;
+    const parseEnum = (prefix) => {
+        const name = t[i++];
+        expect('{');
+        const values = [];
+        const numbers = {};
+        while (t[i] !== '}') {
+            if (t[i] === 'option' || t[i] === 'reserved') {
+                skipStatement();
+                continue;
+            }
+            const v = t[i++];
+            expect('=');
+            // a negative number is two tokens
+            const negative = t[i] === '-' ? (i++, true) : false;
+            numbers[v] = (negative ? -1 : 1) * Number(t[i++]);
+            skipOptions();
+            expect(';');
+            values.push(v);
+        }
+        i++;
+        file.enums.push({ fullName: `${prefix}.${name}`, values, numbers });
+    };
+    const parseField = (fields, oneof) => {
+        let repeated = false;
+        if (t[i] === 'repeated') {
+            repeated = true;
+            i++;
+        }
+        else if (t[i] === 'optional' || t[i] === 'required')
+            i++;
+        let type;
+        let map;
+        if (t[i] === 'map') {
+            i++;
+            expect('<');
+            const key = t[i++];
+            expect(',');
+            const value = t[i++];
+            expect('>');
+            map = { key, value };
+            type = value;
+        }
+        else
+            type = t[i++];
+        const name = t[i++];
+        expect('=');
+        const number = Number(t[i++]);
+        let jsonName = jsonNameOf(name);
+        if (t[i] === '[') {
+            // a declared json_name overrides the derived one
+            const end = t.indexOf(']', i);
+            const at = t.slice(i, end).indexOf('json_name');
+            if (at >= 0)
+                jsonName = JSON.parse(t[i + at + 2]);
+            i = end + 1;
+        }
+        expect(';');
+        fields.push({ name, jsonName, number, type, repeated, ...(map ? { map } : {}), ...(oneof ? { oneof } : {}) });
+    };
+    const parseMessage = (prefix) => {
+        const name = t[i++];
+        const fullName = `${prefix}.${name}`;
+        expect('{');
+        const fields = [];
+        while (t[i] !== '}') {
+            const x = t[i];
+            if (x === 'message') {
+                i++;
+                parseMessage(fullName);
+            }
+            else if (x === 'enum') {
+                i++;
+                parseEnum(fullName);
+            }
+            else if (x === 'oneof') {
+                i++;
+                const group = t[i++];
+                expect('{');
+                while (t[i] !== '}') {
+                    if (t[i] === 'option') {
+                        skipStatement();
+                        continue;
+                    }
+                    parseField(fields, group);
+                }
+                i++;
+            }
+            else if (x === 'option' || x === 'reserved' || x === 'extensions' || x === 'extend')
+                skipStatement();
+            else if (x === ';')
+                i++;
+            else
+                parseField(fields);
+        }
+        i++;
+        file.messages.push({ fullName, fields });
+    };
+    while (i < t.length) {
+        const x = t[i++];
+        if (x === 'package') {
+            file.pkg = t[i++];
+            expect(';');
+        }
+        else if (x === 'message')
+            parseMessage(scope());
+        else if (x === 'enum')
+            parseEnum(scope());
+        else if (x === 'service') {
+            const name = t[i++];
+            expect('{');
+            const rpcs = [];
+            while (t[i] !== '}') {
+                if (t[i] !== 'rpc') {
+                    skipStatement();
+                    continue;
+                }
+                i++;
+                const rpc = t[i++];
+                expect('(');
+                const clientStreams = t[i] === 'stream' ? (i++, true) : false;
+                const request = t[i++];
+                expect(')');
+                expect('returns');
+                expect('(');
+                const serverStreams = t[i] === 'stream' ? (i++, true) : false;
+                const response = t[i++];
+                expect(')');
+                if (t[i] === '{') {
+                    let depth = 0;
+                    do {
+                        if (t[i] === '{')
+                            depth++;
+                        else if (t[i] === '}')
+                            depth--;
+                        i++;
+                    } while (depth > 0);
+                }
+                else
+                    expect(';');
+                rpcs.push({ name: rpc, request, response, clientStreams, serverStreams });
+            }
+            i++;
+            file.services.push({ fullName: `${file.pkg}.${name}`, rpcs });
+        }
+        else if (x === 'syntax' || x === 'import' || x === 'option' || x === 'edition' || x === 'extend')
+            skipStatement(); // an `extend` adds options, never a wire type
+        else if (x === ';')
+            continue;
+        else
+            throw new Error(`spec-ir-proto: ${path}: unexpected "${x}"`);
+    }
+    return file;
+}
+export function readProtoFiles(files) {
+    return { format: 'proto', files: Object.entries(files).sort(([a], [b]) => a.localeCompare(b)).map(([path, text]) => parseProto(path, text)) };
+}
+/** The IR of the services the vendored files declare: every rpc of every service one operation. */
+export function fromProto(spec) {
+    const parsed = spec.files;
+    const messages = new Map(parsed.flatMap((f) => f.messages.map((m) => [m.fullName, m])));
+    const enums = new Map(parsed.flatMap((f) => f.enums.map((e) => [e.fullName, e])));
+    // a type name as written resolves from the innermost scope outward (protobuf's scoping rule)
+    const resolve = (name, scopeName) => {
+        if (name.startsWith('.'))
+            return name.slice(1);
+        const parts = scopeName.split('.');
+        for (let n = parts.length; n >= 0; n--) {
+            const candidate = [...parts.slice(0, n), name].filter(Boolean).join('.');
+            if (messages.has(candidate) || enums.has(candidate))
+                return candidate;
+        }
+        return undefined;
+    };
+    const short = (fullName) => fullName.split('.').pop();
+    const typeOf = (f, scopeName) => {
+        if (f.map)
+            return { type: 'object' };
+        if (f.repeated)
+            return { type: 'array' };
+        if (SCALARS[f.type])
+            return { type: SCALARS[f.type] };
+        const full = resolve(f.type, scopeName);
+        if (full && enums.has(full))
+            return { type: 'string', enum: enums.get(full).values };
+        if (!full)
+            throw new Error(`spec-ir-proto: ${scopeName}: type ${f.type} is not declared in the vendored files`);
+        return { type: short(full) };
+    };
+    const services = parsed.flatMap((f) => f.services);
+    if (!services.length)
+        throw new Error('spec-ir-proto: the vendored files declare no service');
+    const operations = [];
+    const answered = new Set();
+    for (const svc of services) {
+        const pkg = svc.fullName.split('.').slice(0, -1).join('.');
+        for (const rpc of svc.rpcs) {
+            const request = resolve(rpc.request, pkg);
+            const response = resolve(rpc.response, pkg);
+            if (!request || !response)
+                throw new Error(`spec-ir-proto: ${svc.fullName}.${rpc.name}: an argument type is not declared`);
+            answered.add(response);
+            const body = messages.get(request).fields
+                .map((f) => ({ name: f.jsonName, type: typeOf(f, request).type, required: false }))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            operations.push({
+                id: rpc.name,
+                method: 'post',
+                path: `/${svc.fullName}/${rpc.name}`,
+                pathParams: [],
+                query: [],
+                body,
+                bodyEncoding: 'json',
+                successStatus: 200,
+                ...(rpc.serverStreams ? { streams: true } : {}),
+                answers: { resource: short(response), list: false },
+                class: 'action',
+            });
+        }
+    }
+    // proto3 JSON may omit any field holding its default, so none is required; a message field may be null
+    const resources = [...answered].sort().map((full) => {
+        const m = messages.get(full);
+        const fields = m.fields.map((f) => {
+            const t = typeOf(f, full);
+            return { name: f.jsonName, type: t.type, nullable: !SCALARS[f.type] && !t.enum && !f.repeated && !f.map, ...(t.enum ? { enum: t.enum } : {}) };
+        });
+        return {
+            name: short(full),
+            schema: short(full),
+            fields,
+            stateCandidates: fields.filter((f) => f.enum && f.enum.length > 1).map((f) => ({ field: f.name, values: f.enum })),
+            expandable: [],
+        };
+    });
+    return { format: 'proto', version: services.map((s) => s.fullName).join(', '), resources, operations };
+}
+export function protoSchema(spec) {
+    const parsed = spec.files;
+    const messages = new Map(parsed.flatMap((f) => f.messages.map((m) => [m.fullName, m])));
+    const enums = new Map(parsed.flatMap((f) => f.enums.map((e) => [e.fullName, e])));
+    const resolve = (name, scopeName) => {
+        if (name.startsWith('.'))
+            return name.slice(1);
+        const parts = scopeName.split('.');
+        for (let n = parts.length; n >= 0; n--) {
+            const candidate = [...parts.slice(0, n), name].filter(Boolean).join('.');
+            if (messages.has(candidate) || enums.has(candidate))
+                return candidate;
+        }
+        return undefined;
+    };
+    const kindOf = (type, scopeName) => {
+        if (SCALARS[type])
+            return { type, kind: 'scalar' };
+        const full = resolve(type, scopeName);
+        if (!full)
+            throw new Error(`spec-ir-proto: ${scopeName}: type ${type} is not declared in the vendored files`);
+        return { type: full, kind: enums.has(full) ? 'enum' : 'message' };
+    };
+    const out = { messages: {}, enums: {}, rpcs: {} };
+    for (const [full, m] of messages) {
+        out.messages[full] = m.fields.map((f) => {
+            const t = kindOf(f.type, full);
+            const map = f.map ? (() => { const v = kindOf(f.map.value, full); return { key: f.map.key, value: v.type, valueKind: v.kind }; })() : undefined;
+            return { name: f.name, json: f.jsonName, number: f.number, type: t.type, kind: t.kind, ...(f.repeated ? { repeated: true } : {}), ...(map ? { map } : {}) };
+        });
+    }
+    for (const [full, e] of enums)
+        out.enums[full] = e.numbers;
+    for (const svc of parsed.flatMap((f) => f.services)) {
+        const pkg = svc.fullName.split('.').slice(0, -1).join('.');
+        // an rpc's message type the tree does not declare is a spec that cannot be served, named, never an undefined schema
+        const resolved = (type) => { const r = resolve(type, pkg); if (!r)
+            throw new Error(`proto: ${svc.fullName} names message ${type}, which no file of the tree declares`); return r; };
+        for (const rpc of svc.rpcs) {
+            out.rpcs[`/${svc.fullName}/${rpc.name}`] = { operation: rpc.name, request: resolved(rpc.request), response: resolved(rpc.response), ...(rpc.serverStreams ? { serverStreams: true } : {}), ...(rpc.clientStreams ? { clientStreams: true } : {}) };
+        }
+    }
+    return out;
+}

package/dist/src/spec-ir.d.ts

@@ -0,0 +1,104 @@
+type Json = any;
+export type OperationClass = 'create' | 'retrieve' | 'list' | 'update' | 'delete' | 'action' | 'computed' | 'non-resource';
+export declare const CRUD_CLASSES: ReadonlySet<OperationClass>;
+/** A parameter or body field: its name, type and whether it is required, and the numeric bounds the spec states
+ *  (`minimum`, `maximum`), which a strict body (the manifest's `body.strict`, `ctx.fields`) refuses outside of. */
+export type IrParam = {
+    name: string;
+    type: string;
+    required: boolean;
+    minimum?: number;
+    maximum?: number;
+};
+export type IrOperation = {
+    /** The spec's operationId, or the `method_path` slug when the spec has none. */
+    id: string;
+    method: string;
+    path: string;
+    /** Query values that tell this operation from another at the same method and path (a spec key
+     *  such as `/responses?beta=true`); `null`: the key present with any value (S3's UploadPart, `uploadId`). */
+    discriminator?: Record<string, string | null>;
+    /** request headers that name the operation (AWS JSON's X-Amz-Target), for a wire whose operations share a path;
+     *  `null`: the header present with any value (S3's CopyObject, `x-amz-copy-source`) */
+    headers?: Record<string, string | null>;
+    pathParams: string[];
+    /** The spec's own grouping of the operation, where it has one (a client-derived spec: the client library that makes
+     *  the call), which names the family file its handler is written in; absent, the family is the path's (the grade's
+     *  interim rule) */
+    family?: string;
+    /** The path the operation's own server puts before it, when its path item or operation names a server of its own
+     *  (OpenAPI's path-level `servers`: Upstash's /auditlogs at https://api.upstash.com, beside the document's /v2) */
+    basePath?: string;
+    query: IrParam[];
+    /** Top-level body fields; `bodyEncoding` says how the vendor reads them. */
+    body: IrParam[];
+    bodyEncoding: 'json' | 'form' | 'multipart' | 'xml' | 'none';
+    /** A form-encoded operation's number and boolean fields, by bracket path (formScalarsOf). */
+    scalars?: Record<string, 'integer' | 'number' | 'boolean'>;
+    successStatus: number;
+    /** the success is documented with no content at all (a 200 with nothing in it) */
+    emptySuccess?: true;
+    /** The success answer may be a server-sent event stream (`text/event-stream`). */
+    streams?: boolean;
+    /** The resource the success answer is (or lists), when it is one: the first of a union, whose
+     *  other members are `alternatives` (a deleted form, or the kinds of a polymorphic answer); `key`
+     *  when the answer is an envelope holding it under that property (`{ ok, channel: {...} }`). */
+    /** `extends`: fields the answer adds to its resource (GitHub's ruleset-version-with-state: allOf ruleset-version and `state`). */
+    answers?: {
+        resource: string;
+        list: boolean;
+        alternatives?: string[];
+        key?: string;
+        extends?: string[];
+    };
+    /** The credential scopes any one of which lets a caller make this call, from the spec's security. */
+    scopes?: string[];
+    /** The security schemes any one of which the call is made with (the spec's security, each requirement's scheme
+     *  names); absent when the call takes none. `anonymous` when a requirement is empty (`{}`: the call may also go
+     *  without). */
+    credentials?: string[];
+    /** The resource the operation acts on: the one at its path. */
+    resource?: string;
+    class: OperationClass;
+};
+export type IrStateCandidate = {
+    field: string;
+    values: string[];
+};
+export type IrResource = {
+    name: string;
+    /** The component schema that defines it. */
+    schema: string;
+    /** `discriminator`: a union's field each alternative gives one value (which alternative it is). */
+    fields: Array<{
+        name: string;
+        type: string;
+        nullable: boolean;
+        required?: boolean;
+        enum?: string[];
+        discriminator?: boolean;
+    }>;
+    /** Top-level enum fields with more than one value. The manifest rules on each. */
+    stateCandidates: IrStateCandidate[];
+    /** Fields holding another resource's id that a caller may ask to receive embedded. */
+    expandable: string[];
+};
+export type SpecIR = {
+    format: 'openapi' | 'smithy' | 'proto' | 'client';
+    version: string;
+    /** The path the vendor's server URL puts before every operation path (`/v1` for OpenAI), when any. */
+    basePath?: string;
+    /** The path parameters whose values span segments: Smithy's greedy labels (`{Key+}`), which the path keeps as the label. */
+    spanning?: string[];
+    resources: IrResource[];
+    operations: IrOperation[];
+};
+export declare function slug(method: string, path: string): string;
+export declare function fromOpenAPI(spec: Json): SpecIR;
+/** A Swagger 2.0 document as the OpenAPI 3 shape `fromOpenAPI` reads: definitions become component
+ *  schemas, formData and body parameters a request body, response schemas JSON content, and
+ *  host + basePath the server. Nothing vendor-specific. */
+export declare function fromSwagger2(doc: Json): SpecIR;
+/** An AWS service's Smithy JSON model as the IR (`service` names the service shape when the model holds several). */
+export declare function fromSmithy(model: Json, service?: string): SpecIR;
+export {};