specli 0.0.11 → 0.0.13

package/src/cli/naming.ts

@@ -1,224 +0,0 @@
-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.ts

@@ -1,152 +0,0 @@
-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.ts

@@ -1,71 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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`;
-}

package/src/cli/positional.ts

@@ -1,75 +0,0 @@
-import type { ParamSpec } from "./params.ts";
-
-export type ActionShapeForCli = {
-	pathArgs: string[];
-	params: ParamSpec[];
-};
-
-export type PositionalArg = {
-	name: string;
-	required: boolean;
-	description?: string;
-	type: import("./schema-shape.ts").ParamType;
-	format?: string;
-	enum?: string[];
-};
-
-export type FlagsIndex = {
-	flags: Array<
-		Pick<
-			import("./params.ts").ParamSpec,
-			| "in"
-			| "name"
-			| "flag"
-			| "required"
-			| "description"
-			| "type"
-			| "format"
-			| "enum"
-			| "itemType"
-			| "itemFormat"
-			| "itemEnum"
-		>
-	>;
-};
-
-export function derivePositionals(action: ActionShapeForCli): PositionalArg[] {
-	const byName = new Map<string, PositionalArg>();
-
-	// Use pathArgs order; match metadata from params when available.
-	for (const name of action.pathArgs) {
-		const p = action.params.find(
-			(x: ParamSpec) => 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: ActionShapeForCli): FlagsIndex {
-	return {
-		flags: action.params
-			.filter((p: ParamSpec) => p.kind === "flag")
-			.map((p: ParamSpec) => ({
-				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/src/cli/request-body.ts

@@ -1,94 +0,0 @@
-import {
-	getSchemaEnumStrings,
-	getSchemaFormat,
-	getSchemaType,
-} from "./schema-shape.ts";
-import type {
-	JsonSchema,
-	NormalizedOperation,
-	NormalizedRequestBody,
-} from "./types.ts";
-import { isJsonSchema } from "./types.ts";
-
-export type RequestBodyContent = {
-	contentType: string;
-	required: boolean;
-	schemaType: import("./schema-shape.ts").ParamType;
-	schemaFormat?: string;
-	schemaEnum?: string[];
-};
-
-export type RequestBodyInfo = {
-	required: boolean;
-	content: RequestBodyContent[];
-	// Convenience flags for later arg generation.
-	hasJson: boolean;
-	hasFormUrlEncoded: boolean;
-	hasMultipart: boolean;
-
-	// Phase 1 planning: supported generic body inputs.
-	bodyFlags: string[];
-	preferredContentType?: string;
-
-	// Original JSON Schema (for expanded flags + validation)
-	preferredSchema?: JsonSchema;
-};
-
-function getRequestBody(
-	op: NormalizedOperation,
-): NormalizedRequestBody | undefined {
-	return op.requestBody;
-}
-
-export function deriveRequestBodyInfo(
-	op: NormalizedOperation,
-): RequestBodyInfo | undefined {
-	const rb = getRequestBody(op);
-	if (!rb) return undefined;
-
-	const content: RequestBodyContent[] = [];
-	for (const contentType of rb.contentTypes) {
-		const schema = rb.schemasByContentType[contentType];
-		content.push({
-			contentType,
-			required: rb.required,
-			schemaType: getSchemaType(schema),
-			schemaFormat: getSchemaFormat(schema),
-			schemaEnum: getSchemaEnumStrings(schema),
-		});
-	}
-
-	content.sort((a, b) => a.contentType.localeCompare(b.contentType));
-
-	const hasJson = content.some((c) => c.contentType.includes("json"));
-	const hasFormUrlEncoded = content.some(
-		(c) => c.contentType === "application/x-www-form-urlencoded",
-	);
-	const hasMultipart = content.some((c) =>
-		c.contentType.startsWith("multipart/"),
-	);
-
-	const bodyFlags = ["--data", "--file"]; // always available when requestBody exists
-
-	const preferredContentType =
-		content.find((c) => c.contentType === "application/json")?.contentType ??
-		content.find((c) => c.contentType.includes("json"))?.contentType ??
-		content[0]?.contentType;
-
-	const preferredSchema = preferredContentType
-		? rb.schemasByContentType[preferredContentType]
-		: undefined;
-
-	return {
-		required: rb.required,
-		content,
-		hasJson,
-		hasFormUrlEncoded,
-		hasMultipart,
-		bodyFlags,
-		preferredContentType,
-		preferredSchema: isJsonSchema(preferredSchema)
-			? preferredSchema
-			: undefined,
-	};
-}

package/src/cli/runtime/argv.ts

@@ -1,14 +0,0 @@
-export function getArgValue(argv: string[], key: string): string | undefined {
-	for (let i = 0; i < argv.length; i++) {
-		const a = argv[i];
-		if (!a) continue;
-
-		if (a === key) return argv[i + 1];
-		if (a.startsWith(`${key}=`)) return a.slice(key.length + 1);
-	}
-	return undefined;
-}
-
-export function hasAnyArg(argv: string[], names: string[]): boolean {
-	return argv.some((a) => a && names.includes(a));
-}