specli 0.0.11 → 0.0.13

package/dist/cli/naming.js

@@ -0,0 +1,191 @@
+import { pluralize } from "./pluralize.js";
+import { kebabCase } from "./strings.js";
+const GENERIC_TAGS = new Set(["default", "defaults", "api"]);
+function getPathSegments(path) {
+    return path
+        .split("/")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function getPathArgs(path) {
+    const args = [];
+    const re = /\{([^}]+)\}/g;
+    while (true) {
+        const match = re.exec(path);
+        if (!match)
+            break;
+        // biome-ignore lint/style/noNonNullAssertion: unknown
+        args.push(match[1]);
+    }
+    return args;
+}
+function pickResourceFromTags(tags) {
+    if (!tags.length)
+        return undefined;
+    const first = tags[0]?.trim();
+    if (!first)
+        return undefined;
+    if (GENERIC_TAGS.has(first.toLowerCase()))
+        return undefined;
+    return first;
+}
+function splitOperationId(operationId) {
+    const trimmed = operationId.trim();
+    if (!trimmed)
+        return {};
+    // Prefer dot-notation when present: Contacts.List
+    if (trimmed.includes(".")) {
+        const [prefix, ...rest] = trimmed.split(".");
+        return { prefix, suffix: rest.join(".") };
+    }
+    // Try separators: Contacts_List, Contacts__List
+    if (trimmed.includes("__")) {
+        const [prefix, ...rest] = trimmed.split("__");
+        return { prefix, suffix: rest.join("__") };
+    }
+    if (trimmed.includes("_")) {
+        const [prefix, ...rest] = trimmed.split("_");
+        return { prefix, suffix: rest.join("_") };
+    }
+    return { suffix: trimmed };
+}
+function inferStyle(op) {
+    // Path-based RPC convention (common in gRPC-ish HTTP gateways)
+    // - POST /Contacts.List
+    // - POST /Contacts/Service.List
+    if (op.path.includes("."))
+        return "rpc";
+    // operationId dot-notation alone is not enough to call it RPC; many REST APIs
+    // have dotted ids. We treat dotted operationId as a weak signal.
+    if (op.operationId?.includes(".") && op.method === "POST")
+        return "rpc";
+    return "rest";
+}
+function inferResource(op) {
+    const tag = pickResourceFromTags(op.tags);
+    if (tag)
+        return pluralize(kebabCase(tag));
+    if (op.operationId) {
+        const { prefix } = splitOperationId(op.operationId);
+        if (prefix) {
+            const fromId = kebabCase(prefix);
+            if (fromId === "ping")
+                return "ping";
+            return pluralize(fromId);
+        }
+    }
+    const segments = getPathSegments(op.path);
+    let first = segments[0] ?? "api";
+    // If first segment is rpc-ish, like Contacts.List, split it.
+    // biome-ignore lint/style/noNonNullAssertion: split always returns at least one element
+    first = first.includes(".") ? first.split(".")[0] : first;
+    // Singletons like /ping generally shouldn't become `pings`.
+    if (first.toLowerCase() === "ping")
+        return "ping";
+    // Strip path params if they appear in first segment (rare)
+    const cleaned = first.replace(/^\{.+\}$/, "");
+    return pluralize(kebabCase(cleaned || "api"));
+}
+function canonicalizeAction(action) {
+    const a = kebabCase(action);
+    // Common RPC verbs -> REST canonical verbs
+    if (a === "retrieve" || a === "read")
+        return "get";
+    if (a === "list" || a === "search")
+        return "list";
+    if (a === "create")
+        return "create";
+    if (a === "update" || a === "patch")
+        return "update";
+    if (a === "delete" || a === "remove")
+        return "delete";
+    return a;
+}
+function inferRestAction(op) {
+    // If operationId is present and looks intentional, prefer it.
+    // This helps with singleton endpoints like GET /ping (Ping.Get) vs collections.
+    if (op.operationId) {
+        const { suffix } = splitOperationId(op.operationId);
+        if (suffix) {
+            const fromId = canonicalizeAction(suffix);
+            if (fromId === "get" ||
+                fromId === "list" ||
+                fromId === "create" ||
+                fromId === "update" ||
+                fromId === "delete") {
+                return fromId;
+            }
+        }
+    }
+    const method = op.method.toUpperCase();
+    const args = getPathArgs(op.path);
+    const hasId = args.length > 0;
+    if (method === "GET" && !hasId)
+        return "list";
+    if (method === "POST" && !hasId)
+        return "create";
+    if (method === "GET" && hasId)
+        return "get";
+    if ((method === "PUT" || method === "PATCH") && hasId)
+        return "update";
+    if (method === "DELETE" && hasId)
+        return "delete";
+    return kebabCase(method);
+}
+function inferRpcAction(op) {
+    // Prefer operationId suffix: Contacts.List -> list
+    if (op.operationId) {
+        const { suffix } = splitOperationId(op.operationId);
+        if (suffix)
+            return canonicalizeAction(suffix);
+    }
+    // Else take last segment and split by '.'
+    const segments = getPathSegments(op.path);
+    const last = segments[segments.length - 1] ?? "";
+    if (last.includes(".")) {
+        const part = last.split(".").pop() ?? last;
+        return canonicalizeAction(part);
+    }
+    return kebabCase(op.method);
+}
+export function planOperation(op) {
+    const style = inferStyle(op);
+    const resource = inferResource(op);
+    const action = style === "rpc" ? inferRpcAction(op) : inferRestAction(op);
+    return {
+        ...op,
+        key: op.key,
+        style,
+        resource,
+        action,
+        canonicalAction: action,
+        pathArgs: getPathArgs(op.path).map((a) => kebabCase(a)),
+    };
+}
+export function planOperations(ops) {
+    const planned = ops.map(planOperation);
+    // Stable collision handling: if resource+action repeats, add a suffix.
+    const counts = new Map();
+    for (const op of planned) {
+        const key = `${op.resource}:${op.action}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const seen = new Map();
+    return planned.map((op) => {
+        const key = `${op.resource}:${op.action}`;
+        const total = counts.get(key) ?? 0;
+        if (total <= 1)
+            return op;
+        const idx = (seen.get(key) ?? 0) + 1;
+        seen.set(key, idx);
+        const suffix = op.operationId
+            ? kebabCase(op.operationId)
+            : kebabCase(`${op.method}-${op.path}`);
+        const disambiguatedAction = `${op.action}-${suffix}-${idx}`;
+        return {
+            ...op,
+            action: disambiguatedAction,
+            aliasOf: `${op.resource} ${op.canonicalAction}`,
+        };
+    });
+}

package/dist/cli/naming.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/naming.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import { planOperation } from "./naming.js";
+describe("planOperation", () => {
+    test("REST: GET /contacts -> contacts list", () => {
+        const op = {
+            key: "GET /contacts",
+            method: "GET",
+            path: "/contacts",
+            operationId: "Contacts.List",
+            tags: ["Contacts"],
+            parameters: [],
+        };
+        const planned = planOperation(op);
+        expect(planned.style).toBe("rest");
+        expect(planned.resource).toBe("contacts");
+        expect(planned.action).toBe("list");
+        expect(planned.pathArgs).toEqual([]);
+    });
+    test("REST: singleton /ping stays ping and prefers operationId action", () => {
+        const op = {
+            key: "GET /ping",
+            method: "GET",
+            path: "/ping",
+            operationId: "Ping.Get",
+            tags: [],
+            parameters: [],
+        };
+        const planned = planOperation(op);
+        expect(planned.style).toBe("rest");
+        expect(planned.resource).toBe("ping");
+        expect(planned.action).toBe("get");
+    });
+    test("REST: singular path pluralizes to contacts", () => {
+        const op = {
+            key: "GET /contact/{id}",
+            method: "GET",
+            path: "/contact/{id}",
+            tags: [],
+            parameters: [],
+        };
+        const planned = planOperation(op);
+        expect(planned.style).toBe("rest");
+        expect(planned.resource).toBe("contacts");
+        expect(planned.action).toBe("get");
+        expect(planned.pathArgs).toEqual(["id"]);
+    });
+    test("RPC: POST /Contacts.List -> contacts list", () => {
+        const op = {
+            key: "POST /Contacts.List",
+            method: "POST",
+            path: "/Contacts.List",
+            operationId: "Contacts.List",
+            tags: [],
+            parameters: [],
+        };
+        const planned = planOperation(op);
+        expect(planned.style).toBe("rpc");
+        expect(planned.resource).toBe("contacts");
+        expect(planned.action).toBe("list");
+    });
+    test("RPC: Retrieve canonicalizes to get", () => {
+        const op = {
+            key: "POST /Contacts.Retrieve",
+            method: "POST",
+            path: "/Contacts.Retrieve",
+            operationId: "Contacts.Retrieve",
+            tags: [],
+            parameters: [],
+        };
+        const planned = planOperation(op);
+        expect(planned.style).toBe("rpc");
+        expect(planned.resource).toBe("contacts");
+        expect(planned.action).toBe("get");
+    });
+});

package/dist/{src/cli → cli}/operations.d.ts

@@ -1,3 +1,2 @@
 import type { NormalizedOperation, OpenApiDoc } from "./types.js";
 export declare function indexOperations(doc: OpenApiDoc): NormalizedOperation[];
-//# sourceMappingURL=operations.d.ts.map

package/dist/cli/operations.js

@@ -0,0 +1,100 @@
+function operationKey(method, path) {
+    return `${method.toUpperCase()} ${path}`;
+}
+const HTTP_METHODS = [
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "options",
+    "head",
+    "trace",
+];
+function normalizeParam(p) {
+    if (!p || typeof p !== "object")
+        return undefined;
+    const loc = p.in;
+    const name = p.name;
+    if (loc !== "path" &&
+        loc !== "query" &&
+        loc !== "header" &&
+        loc !== "cookie") {
+        return undefined;
+    }
+    if (!name)
+        return undefined;
+    return {
+        in: loc,
+        name,
+        required: Boolean(p.required || loc === "path"),
+        description: p.description,
+        schema: p.schema,
+    };
+}
+function mergeParameters(pathParams, opParams) {
+    const merged = new Map();
+    for (const p of pathParams ?? []) {
+        const normalized = normalizeParam(p);
+        if (!normalized)
+            continue;
+        merged.set(`${normalized.in}:${normalized.name}`, normalized);
+    }
+    for (const p of opParams ?? []) {
+        const normalized = normalizeParam(p);
+        if (!normalized)
+            continue;
+        merged.set(`${normalized.in}:${normalized.name}`, normalized);
+    }
+    return [...merged.values()];
+}
+function normalizeRequestBody(rb) {
+    if (!rb)
+        return undefined;
+    const content = rb.content ?? {};
+    const contentTypes = Object.keys(content);
+    const schemasByContentType = {};
+    for (const contentType of contentTypes) {
+        schemasByContentType[contentType] = content[contentType]?.schema;
+    }
+    return {
+        required: Boolean(rb.required),
+        contentTypes,
+        schemasByContentType,
+    };
+}
+export function indexOperations(doc) {
+    const out = [];
+    const paths = doc.paths ?? {};
+    for (const [path, rawPathItem] of Object.entries(paths)) {
+        if (!rawPathItem || typeof rawPathItem !== "object")
+            continue;
+        const pathItem = rawPathItem;
+        for (const method of HTTP_METHODS) {
+            const op = pathItem[method];
+            if (!op)
+                continue;
+            const parameters = mergeParameters(pathItem.parameters, op.parameters);
+            const normalizedMethod = method.toUpperCase();
+            out.push({
+                key: operationKey(normalizedMethod, path),
+                method: normalizedMethod,
+                path,
+                operationId: op.operationId,
+                tags: op.tags ?? [],
+                summary: op.summary,
+                description: op.description,
+                deprecated: op.deprecated,
+                security: (op.security ?? doc.security),
+                parameters,
+                requestBody: normalizeRequestBody(op.requestBody),
+            });
+        }
+    }
+    out.sort((a, b) => {
+        if (a.path !== b.path)
+            return a.path.localeCompare(b.path);
+        return a.method.localeCompare(b.method);
+    });
+    return out;
+}

package/dist/cli/operations.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/operations.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { indexOperations } from "./operations.js";
+describe("indexOperations", () => {
+    test("indexes basic operations", () => {
+        const doc = {
+            openapi: "3.0.3",
+            paths: {
+                "/contacts": {
+                    get: {
+                        operationId: "Contacts.List",
+                        tags: ["Contacts"],
+                        parameters: [
+                            {
+                                in: "query",
+                                name: "limit",
+                                schema: { type: "integer" },
+                            },
+                        ],
+                    },
+                },
+                "/contacts/{id}": {
+                    get: {
+                        operationId: "Contacts.Get",
+                        tags: ["Contacts"],
+                        parameters: [
+                            {
+                                in: "path",
+                                name: "id",
+                                required: true,
+                                schema: { type: "string" },
+                            },
+                        ],
+                    },
+                },
+            },
+        };
+        const ops = indexOperations(doc);
+        expect(ops).toHaveLength(2);
+        expect(ops[0]?.key).toBe("GET /contacts");
+        expect(ops[0]?.path).toBe("/contacts");
+        expect(ops[0]?.method).toBe("GET");
+        expect(ops[0]?.parameters).toHaveLength(1);
+        expect(ops[0]?.parameters[0]?.in).toBe("query");
+        expect(ops[1]?.key).toBe("GET /contacts/{id}");
+        expect(ops[1]?.path).toBe("/contacts/{id}");
+        expect(ops[1]?.method).toBe("GET");
+        expect(ops[1]?.parameters).toHaveLength(1);
+        expect(ops[1]?.parameters[0]?.in).toBe("path");
+        expect(ops[1]?.parameters[0]?.required).toBe(true);
+    });
+});

package/dist/{src/cli → cli}/params.d.ts

@@ -16,4 +16,3 @@ export type ParamSpec = {
     schema?: import("./types.js").JsonSchema;
 };
 export declare function deriveParamSpecs(op: NormalizedOperation): ParamSpec[];
-//# sourceMappingURL=params.d.ts.map

package/dist/cli/params.js

@@ -0,0 +1,36 @@
+import { getSchemaEnumStrings, getSchemaFormat, getSchemaType, } from "./schema-shape.js";
+import { kebabCase } from "./strings.js";
+export function deriveParamSpecs(op) {
+    const out = [];
+    for (const p of op.parameters) {
+        const flag = `--${kebabCase(p.name)}`;
+        const type = getSchemaType(p.schema);
+        const schemaObj = p.schema && typeof p.schema === "object"
+            ? p.schema
+            : undefined;
+        const itemsSchema = schemaObj && type === "array" && typeof schemaObj.items === "object"
+            ? schemaObj.items
+            : undefined;
+        out.push({
+            kind: p.in === "path" ? "positional" : "flag",
+            in: p.in,
+            name: p.name,
+            flag,
+            required: p.required,
+            description: p.description,
+            type,
+            format: getSchemaFormat(p.schema),
+            enum: getSchemaEnumStrings(p.schema),
+            itemType: type === "array" ? getSchemaType(itemsSchema) : undefined,
+            itemFormat: type === "array" ? getSchemaFormat(itemsSchema) : undefined,
+            itemEnum: type === "array" ? getSchemaEnumStrings(itemsSchema) : undefined,
+            schema: schemaObj,
+        });
+    }
+    out.sort((a, b) => {
+        if (a.in !== b.in)
+            return a.in.localeCompare(b.in);
+        return a.name.localeCompare(b.name);
+    });
+    return out;
+}

package/dist/cli/params.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/params.test.js

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { deriveParamSpecs } from "./params.js";
+describe("deriveParamSpecs", () => {
+    test("derives basic types + flags", () => {
+        const op = {
+            key: "GET /contacts",
+            method: "GET",
+            path: "/contacts",
+            tags: [],
+            parameters: [
+                {
+                    in: "query",
+                    name: "limit",
+                    required: false,
+                    schema: {
+                        type: "integer",
+                        format: "int32",
+                        enum: ["1", "2"],
+                    },
+                },
+                {
+                    in: "header",
+                    name: "X-Request-Id",
+                    required: false,
+                    schema: { type: "string" },
+                },
+            ],
+        };
+        const specs = deriveParamSpecs(op);
+        expect(specs).toHaveLength(2);
+        const limit = specs.find((p) => p.name === "limit");
+        expect(limit?.kind).toBe("flag");
+        expect(limit?.flag).toBe("--limit");
+        expect(limit?.type).toBe("integer");
+        expect(limit?.format).toBe("int32");
+        expect(limit?.enum).toEqual(["1", "2"]);
+        const reqId = specs.find((p) => p.name === "X-Request-Id");
+        expect(reqId?.kind).toBe("flag");
+        expect(reqId?.flag).toBe("--x-request-id");
+        expect(reqId?.type).toBe("string");
+    });
+    test("derives array item types", () => {
+        const op = {
+            key: "GET /things",
+            method: "GET",
+            path: "/things",
+            tags: [],
+            parameters: [
+                {
+                    in: "query",
+                    name: "ids",
+                    required: false,
+                    schema: { type: "array", items: { type: "integer" } },
+                },
+            ],
+        };
+        const specs = deriveParamSpecs(op);
+        expect(specs).toHaveLength(1);
+        expect(specs[0]?.type).toBe("array");
+        expect(specs[0]?.itemType).toBe("integer");
+    });
+});

package/dist/{src/cli → cli}/pluralize.d.ts

@@ -1,2 +1 @@
 export declare function pluralize(word: string): string;
-//# sourceMappingURL=pluralize.d.ts.map

package/dist/cli/pluralize.js

@@ -0,0 +1,38 @@
+const IRREGULAR = {
+    person: "people",
+    man: "men",
+    woman: "women",
+    child: "children",
+    tooth: "teeth",
+    foot: "feet",
+    mouse: "mice",
+    goose: "geese",
+};
+const UNCOUNTABLE = new Set([
+    "metadata",
+    "information",
+    "equipment",
+    "money",
+    "series",
+    "species",
+]);
+export function pluralize(word) {
+    const w = word.trim();
+    if (!w)
+        return w;
+    const lower = w.toLowerCase();
+    if (UNCOUNTABLE.has(lower))
+        return lower;
+    if (IRREGULAR[lower])
+        return IRREGULAR[lower];
+    // already plural-ish
+    if (lower.endsWith("s"))
+        return lower;
+    if (/[bcdfghjklmnpqrstvwxyz]y$/.test(lower)) {
+        return lower.replace(/y$/, "ies");
+    }
+    if (/(ch|sh|x|z)$/.test(lower)) {
+        return `${lower}es`;
+    }
+    return `${lower}s`;
+}

package/dist/{src/cli → cli}/positional.d.ts

@@ -16,4 +16,3 @@ export type FlagsIndex = {
 };
 export declare function derivePositionals(action: ActionShapeForCli): PositionalArg[];
 export declare function deriveFlags(action: ActionShapeForCli): FlagsIndex;
-//# sourceMappingURL=positional.d.ts.map

package/dist/cli/positional.js

@@ -0,0 +1,35 @@
+export function derivePositionals(action) {
+    const byName = new Map();
+    // Use pathArgs order; match metadata from params when available.
+    for (const name of action.pathArgs) {
+        const p = action.params.find((x) => x.in === "path" && x.name === name);
+        byName.set(name, {
+            name,
+            required: true,
+            description: p?.description,
+            type: p?.type ?? "unknown",
+            format: p?.format,
+            enum: p?.enum,
+        });
+    }
+    return [...byName.values()];
+}
+export function deriveFlags(action) {
+    return {
+        flags: action.params
+            .filter((p) => p.kind === "flag")
+            .map((p) => ({
+            in: p.in,
+            name: p.name,
+            flag: p.flag,
+            required: p.required,
+            description: p.description,
+            type: p.type,
+            format: p.format,
+            enum: p.enum,
+            itemType: p.itemType,
+            itemFormat: p.itemFormat,
+            itemEnum: p.itemEnum,
+        })),
+    };
+}

package/dist/cli/positional.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/positional.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { deriveFlags, derivePositionals } from "./positional.js";
+describe("derivePositionals", () => {
+    test("returns ordered positionals from pathArgs", () => {
+        const action = {
+            pathArgs: ["id"],
+            params: [
+                {
+                    kind: "positional",
+                    in: "path",
+                    name: "id",
+                    flag: "--id",
+                    required: true,
+                    type: "string",
+                },
+            ],
+        };
+        const pos = derivePositionals(action);
+        expect(pos).toEqual([
+            {
+                name: "id",
+                required: true,
+                type: "string",
+                format: undefined,
+                enum: undefined,
+                description: undefined,
+            },
+        ]);
+    });
+});
+describe("deriveFlags", () => {
+    test("returns only flag params", () => {
+        const action = {
+            pathArgs: [],
+            params: [
+                {
+                    kind: "flag",
+                    in: "query",
+                    name: "limit",
+                    flag: "--limit",
+                    required: false,
+                    type: "integer",
+                },
+            ],
+        };
+        const flags = deriveFlags(action);
+        expect(flags.flags).toEqual([
+            {
+                in: "query",
+                name: "limit",
+                flag: "--limit",
+                required: false,
+                description: undefined,
+                type: "integer",
+                format: undefined,
+                enum: undefined,
+            },
+        ]);
+    });
+});