specli 0.0.1

package/src/cli/naming.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+import { planOperation } from "./naming.ts";
+import type { NormalizedOperation } from "./types.ts";
+
+describe("planOperation", () => {
+	test("REST: GET /contacts -> contacts list", () => {
+		const op: NormalizedOperation = {
+			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: NormalizedOperation = {
+			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: NormalizedOperation = {
+			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: NormalizedOperation = {
+			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: NormalizedOperation = {
+			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/src/cli/naming.ts

@@ -0,0 +1,224 @@
+import { pluralize } from "./pluralize.ts";
+import { kebabCase } from "./strings.ts";
+import type { NormalizedOperation } from "./types.ts";
+
+export type PlannedOperation = NormalizedOperation & {
+	resource: string;
+	action: string;
+	pathArgs: string[];
+	style: "rest" | "rpc";
+	canonicalAction: string;
+	aliasOf?: string;
+};
+
+const GENERIC_TAGS = new Set(["default", "defaults", "api"]);
+
+function getPathSegments(path: string): string[] {
+	return path
+		.split("/")
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+function getPathArgs(path: string): string[] {
+	const args: string[] = [];
+	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: string[]): string | undefined {
+	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: string): {
+	prefix?: string;
+	suffix?: string;
+} {
+	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: NormalizedOperation): "rest" | "rpc" {
+	// 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: NormalizedOperation): string {
+	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: string): string {
+	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: NormalizedOperation): string {
+	// 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: NormalizedOperation): string {
+	// 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: NormalizedOperation): PlannedOperation {
+	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: NormalizedOperation[]): PlannedOperation[] {
+	const planned = ops.map(planOperation);
+
+	// Stable collision handling: if resource+action repeats, add a suffix.
+	const counts = new Map<string, number>();
+	for (const op of planned) {
+		const key = `${op.resource}:${op.action}`;
+		counts.set(key, (counts.get(key) ?? 0) + 1);
+	}
+
+	const seen = new Map<string, number>();
+	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/src/cli/operations.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+
+import { indexOperations } from "./operations.ts";
+import type { OpenApiDoc } from "./types.ts";
+
+describe("indexOperations", () => {
+	test("indexes basic operations", () => {
+		const doc: OpenApiDoc = {
+			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/src/cli/operations.ts

@@ -0,0 +1,152 @@
+import type {
+	NormalizedOperation,
+	NormalizedParameter,
+	NormalizedRequestBody,
+	OpenApiDoc,
+} from "./types.ts";
+
+function operationKey(method: string, path: string): string {
+	return `${method.toUpperCase()} ${path}`;
+}
+
+const HTTP_METHODS = [
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete",
+	"options",
+	"head",
+	"trace",
+] as const;
+
+type RawParameter = {
+	in?: string;
+	name?: string;
+	required?: boolean;
+	description?: string;
+	schema?: unknown;
+};
+
+type RawRequestBody = {
+	required?: boolean;
+	content?: Record<string, { schema?: unknown } | undefined>;
+};
+
+type RawOperation = {
+	operationId?: string;
+	tags?: string[];
+	summary?: string;
+	description?: string;
+	deprecated?: boolean;
+	security?: OpenApiDoc["security"];
+	parameters?: RawParameter[];
+	requestBody?: RawRequestBody;
+};
+
+type RawPathItem = {
+	parameters?: RawParameter[];
+} & Partial<Record<(typeof HTTP_METHODS)[number], RawOperation>>;
+
+function normalizeParam(p: RawParameter): NormalizedParameter | undefined {
+	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: RawParameter[] | undefined,
+	opParams: RawParameter[] | undefined,
+): NormalizedParameter[] {
+	const merged = new Map<string, NormalizedParameter>();
+
+	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: RawRequestBody | undefined,
+): NormalizedRequestBody | undefined {
+	if (!rb) return undefined;
+
+	const content = rb.content ?? {};
+	const contentTypes = Object.keys(content);
+	const schemasByContentType: Record<string, unknown | undefined> = {};
+
+	for (const contentType of contentTypes) {
+		schemasByContentType[contentType] = content[contentType]?.schema;
+	}
+
+	return {
+		required: Boolean(rb.required),
+		contentTypes,
+		schemasByContentType,
+	};
+}
+
+export function indexOperations(doc: OpenApiDoc): NormalizedOperation[] {
+	const out: NormalizedOperation[] = [];
+	const paths = doc.paths ?? {};
+
+	for (const [path, rawPathItem] of Object.entries(paths)) {
+		if (!rawPathItem || typeof rawPathItem !== "object") continue;
+
+		const pathItem = rawPathItem as 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) as OpenApiDoc["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/src/cli/params.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+
+import { deriveParamSpecs } from "./params.ts";
+import type { NormalizedOperation } from "./types.ts";
+
+describe("deriveParamSpecs", () => {
+	test("derives basic types + flags", () => {
+		const op: NormalizedOperation = {
+			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: NormalizedOperation = {
+			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/src/cli/params.ts

@@ -0,0 +1,71 @@
+import {
+	getSchemaEnumStrings,
+	getSchemaFormat,
+	getSchemaType,
+} from "./schema-shape.ts";
+import { kebabCase } from "./strings.ts";
+import type { NormalizedOperation, NormalizedParameter } from "./types.ts";
+
+export type ParamType = import("./schema-shape.ts").ParamType;
+
+export type ParamSpec = {
+	kind: "positional" | "flag";
+	in: NormalizedParameter["in"];
+	name: string;
+	flag: string;
+	required: boolean;
+	description?: string;
+	type: ParamType;
+	format?: string;
+	enum?: string[];
+
+	// Arrays
+	itemType?: ParamType;
+	itemFormat?: string;
+	itemEnum?: string[];
+
+	// Original schema for Ajv validation and future advanced flag expansion.
+	schema?: import("./types.ts").JsonSchema;
+};
+
+export function deriveParamSpecs(op: NormalizedOperation): ParamSpec[] {
+	const out: ParamSpec[] = [];
+
+	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 as import("./types.ts").JsonSchema)
+				: undefined;
+
+		const itemsSchema =
+			schemaObj && type === "array" && typeof schemaObj.items === "object"
+				? (schemaObj.items as unknown)
+				: 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/src/cli/pluralize.ts

@@ -0,0 +1,41 @@
+const IRREGULAR: Record<string, string> = {
+	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: string): string {
+	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`;
+}