toolcraft-openapi 0.0.27 → 0.0.34

package/dist/mock/forgeyard.js

@@ -0,0 +1,452 @@
+export const FORGEYARD_BASE_URL = "https://api.forgeyard.invalid";
+export const FORGEYARD_RESOURCES = [
+    "artifacts",
+    "audits",
+    "automations",
+    "branches",
+    "builds",
+    "checks",
+    "changes",
+    "comments",
+    "commits",
+    "deployments",
+    "discussions",
+    "environments",
+    "events",
+    "files",
+    "hooks",
+    "identities",
+    "integrations",
+    "invitations",
+    "jobs",
+    "keys",
+    "labels",
+    "licenses",
+    "members",
+    "milestones",
+    "notifications",
+    "organizations",
+    "packages",
+    "pages",
+    "permissions",
+    "pipelines",
+    "policies",
+    "projects",
+    "releases",
+    "repositories",
+    "reviews",
+    "runners",
+    "secrets",
+    "sessions",
+    "settings",
+    "snapshots",
+    "statuses",
+    "tags",
+    "teams",
+    "templates",
+    "tokens",
+    "topics",
+    "variables",
+    "webhooks",
+    "workflows",
+    "workspaces",
+    "approvals",
+    "archives",
+    "attestations",
+    "billing-accounts",
+    "codespaces",
+    "dependencies",
+    "exports",
+    "imports",
+    "mirrors",
+    "rulesets",
+    "security-alerts",
+    "service-accounts",
+    "signatures",
+    "sponsors"
+];
+const stringSchema = { type: "string" };
+const identifierParameter = {
+    name: "id",
+    in: "path",
+    required: true,
+    description: "Stable Forgeyard resource identifier.",
+    schema: stringSchema
+};
+const queryParameter = {
+    name: "query",
+    in: "query",
+    description: "Search query.",
+    schema: stringSchema
+};
+const bodySchema = {
+    type: "object",
+    required: ["name"],
+    properties: {
+        name: { type: "string", description: "Display name." },
+        active: { type: "boolean", description: "Whether the resource is active." },
+        labels: { type: "array", items: { type: "string" }, description: "Labels to attach." }
+    }
+};
+const successResponse = {
+    description: "Successful Forgeyard response.",
+    content: {
+        "application/json": {
+            schema: { type: "object" },
+            example: { ok: true }
+        }
+    }
+};
+export function createForgeyardSpec() {
+    const paths = {};
+    for (const resource of FORGEYARD_RESOURCES) {
+        const tag = resource;
+        const singular = singularize(resource);
+        const collectionPath = `/v1/${resource}`;
+        const resourcePath = `${collectionPath}/{id}`;
+        const searchPath = `${collectionPath}/search`;
+        const archivePath = `${collectionPath}/{id}/archive`;
+        paths[collectionPath] = {
+            get: operation(tag, `list ${resource}`, `List ${resource}.`, [queryParameter]),
+            post: operation(tag, `create ${singular}`, `Create a ${singular}.`, [], true)
+        };
+        paths[resourcePath] = {
+            get: operation(tag, `view ${singular}`, `View a ${singular}.`, [identifierParameter]),
+            put: operation(tag, `replace ${singular}`, `Replace a ${singular}.`, [identifierParameter], true),
+            patch: operation(tag, `update ${singular}`, `Update a ${singular}.`, [identifierParameter], true),
+            delete: operation(tag, `delete ${singular}`, `Delete a ${singular}.`, [identifierParameter])
+        };
+        paths[searchPath] = {
+            get: operation(tag, `search ${resource}`, `Search ${resource}.`, [queryParameter])
+        };
+        paths[archivePath] = {
+            post: operation(tag, `archive ${singular}`, `Archive a ${singular}.`, [identifierParameter], true)
+        };
+    }
+    paths["/v1/compatibility/quotes"] = {
+        get: operation("compatibility", "listQuotes", "List compatibility quotes.", [])
+    };
+    paths["/v1/compatibility/symbols"] = {
+        get: operation("compatibility", "listSymbols", "List compatibility symbols.", [])
+    };
+    paths["/v1/compatibility/representation"] = {
+        get: {
+            ...operation("compatibility", "get compatibility representation", "Negotiate a wildcard JSON representation.", [
+                {
+                    name: "x-forgeyard-tenant",
+                    in: "header",
+                    required: true,
+                    schema: { type: "string" }
+                }
+            ]),
+            responses: {
+                "200": {
+                    description: "Successful wildcard response.",
+                    content: {
+                        "*/*": {
+                            schema: { type: "object" },
+                            example: { ok: true }
+                        }
+                    }
+                }
+            }
+        }
+    };
+    paths["/v1/compatibility/jobs"] = {
+        post: {
+            tags: ["compatibility"],
+            summary: "Create a compatibility job without operationId.",
+            requestBody: {
+                required: true,
+                content: {
+                    "application/json": {
+                        schema: {
+                            type: "object",
+                            required: ["configuration"],
+                            properties: {
+                                configuration: {
+                                    type: "object",
+                                    properties: {
+                                        retries: { type: "integer" },
+                                        matrix: { type: "array", items: { type: "object" } }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            responses: { "200": successResponse }
+        }
+    };
+    paths["/v1/compatibility/jobs/{id}"] = {
+        put: {
+            ...operation("compatibility", "PUT /v1/compatibility/jobs/{id}", "Update a compatibility job without an explicit operationId.", [identifierParameter], true),
+            operationId: undefined
+        }
+    };
+    paths["/v1/compatibility/jobs/{id}/settings"] = {
+        put: {
+            ...operation("compatibility", "PUT /v1/compatibility/jobs/{id}/settings", "Update compatibility job settings without an explicit operationId.", [identifierParameter], true),
+            operationId: undefined
+        }
+    };
+    paths["/v1/compatibility/dictionary"] = {
+        post: {
+            tags: ["compatibility"],
+            operationId: "create compatibility dictionary",
+            summary: "Create a free-form compatibility dictionary.",
+            requestBody: {
+                required: true,
+                content: {
+                    "application/json": {
+                        schema: { type: "object", additionalProperties: true }
+                    }
+                }
+            },
+            responses: { "200": successResponse }
+        }
+    };
+    paths["/v1/compatibility/report"] = {
+        get: {
+            tags: ["compatibility"],
+            operationId: "export compatibility report",
+            responses: {
+                "200": {
+                    description: "Text report.",
+                    content: { "text/plain": { schema: { type: "string" }, example: "forgeyard report" } }
+                }
+            }
+        }
+    };
+    paths["/v1/compatibility/archive"] = {
+        get: {
+            tags: ["compatibility"],
+            operationId: "download compatibility archive",
+            responses: {
+                "200": {
+                    description: "Binary archive.",
+                    content: {
+                        "application/octet-stream": {
+                            schema: { type: "string", format: "binary" }
+                        }
+                    }
+                }
+            }
+        }
+    };
+    paths["/v1/compatibility/manifest"] = {
+        post: {
+            tags: ["compatibility"],
+            operationId: "import compatibility manifest",
+            requestBody: {
+                required: true,
+                content: {
+                    "text/xml": {
+                        schema: { type: "object", properties: { name: { type: "string" } } }
+                    }
+                }
+            },
+            responses: { "200": successResponse }
+        }
+    };
+    paths["/v1/compatibility/bundle"] = {
+        post: {
+            tags: ["compatibility"],
+            operationId: "upload compatibility bundle",
+            requestBody: {
+                required: true,
+                content: {
+                    "application/zip": {
+                        schema: { type: "string", format: "binary" }
+                    }
+                }
+            },
+            responses: { "200": successResponse }
+        }
+    };
+    paths["/v1/compatibility/attachment"] = {
+        post: {
+            tags: ["compatibility"],
+            operationId: "upload compatibility attachment",
+            requestBody: {
+                required: true,
+                content: {
+                    "multipart/form-data": {
+                        schema: {
+                            type: "object",
+                            required: ["file", "description"],
+                            properties: {
+                                file: { type: "string", format: "binary" },
+                                description: { type: "string" },
+                                placement: { type: "integer" }
+                            }
+                        }
+                    }
+                }
+            },
+            responses: { "200": successResponse }
+        }
+    };
+    paths["/v1/compatibility/token"] = {
+        post: {
+            tags: ["compatibility"],
+            operationId: "create compatibility token",
+            requestBody: {
+                required: true,
+                content: {
+                    "application/x-www-form-urlencoded": {
+                        schema: {
+                            type: "object",
+                            required: ["username"],
+                            properties: { username: { type: "string" }, scopes: { type: "array", items: { type: "string" } } }
+                        }
+                    }
+                }
+            },
+            responses: { "200": successResponse }
+        }
+    };
+    paths["/v1/compatibility/filter"] = {
+        get: {
+            ...operation("compatibility", "filter compatibility", "Filter compatibility data.", [
+                {
+                    name: "filter",
+                    in: "query",
+                    style: "deepObject",
+                    explode: true,
+                    schema: { type: "object", properties: { owner: { type: "string" }, active: { type: "boolean" } } }
+                }
+            ])
+        }
+    };
+    paths["/v1/compatibility/batches/{ids}"] = {
+        get: operation("compatibility", "view compatibility batch", "View a compatibility batch.", [
+            { name: "ids", in: "path", required: true, schema: { type: "array", items: { type: "string" } } }
+        ])
+    };
+    paths["/v1/compatibility/punctuation"] = {
+        get: operation("Product [identifier]", "view punctuation compatibility", "Test safe generated nouns.", [])
+    };
+    paths["/v1/compatibility/referenced/{id}"] = {
+        get: operation("compatibility", "view referenced compatibility", "Source for a cross-path reference.", [identifierParameter])
+    };
+    paths["/v1/compatibility/referenced/{id}/details"] = {
+        get: operation("compatibility", "view referenced compatibility details", "Use a cross-path parameter reference.", [
+            { $ref: "#/paths/~1v1~1compatibility~1referenced~1%7Bid%7D/get/parameters/0" }
+        ])
+    };
+    paths["/v1/compatibility/operation-server"] = {
+        get: {
+            ...operation("compatibility", "view operation server compatibility", "Use a fixed operation-level server.", []),
+            servers: [{ url: "https://api.forgeyard.invalid" }]
+        }
+    };
+    paths["/v1/compatibility/explicit-authorization"] = {
+        post: {
+            ...operation("compatibility", "create explicit authorization compatibility", "Use an explicit authorization header.", [
+                { name: "Authorization", in: "header", required: true, schema: { type: "string" } }
+            ]),
+            security: []
+        }
+    };
+    paths["/v1/compatibility/get-body"] = {
+        get: {
+            tags: ["compatibility"],
+            operationId: "search compatibility with body",
+            requestBody: {
+                required: true,
+                content: {
+                    "application/json": {
+                        schema: {
+                            type: "object",
+                            required: ["query"],
+                            properties: { query: { type: "string" } }
+                        }
+                    }
+                }
+            },
+            responses: { "200": successResponse }
+        }
+    };
+    paths["/v1/compatibility/composed-query"] = {
+        get: operation("compatibility", "search composed compatibility", "Use equivalent composed query schemas.", [
+            {
+                name: "regions",
+                in: "query",
+                schema: {
+                    oneOf: [
+                        { type: "array", items: { type: "string", format: "country-code-2" } },
+                        { type: "array", items: { type: "string", format: "negated-country-code-2" } }
+                    ]
+                }
+            }
+        ])
+    };
+    paths["/v1/compatibility/bracketed-array"] = {
+        get: operation("compatibility", "search bracketed compatibility", "Use bracketed array query serialization.", [
+            { name: "expand", in: "query", style: "deepObject", explode: true, schema: { type: "array", items: { type: "string" } } }
+        ])
+    };
+    paths["/v1/compatibility/deep-union"] = {
+        get: operation("compatibility", "search union compatibility", "Use a deep-object query union.", [
+            {
+                name: "created",
+                in: "query",
+                style: "deepObject",
+                explode: true,
+                schema: { anyOf: [{ type: "object", properties: { gt: { type: "integer" } } }, { type: "integer" }] }
+            }
+        ])
+    };
+    paths["/v1/maps/{id}/attachments"] = {
+        post: {
+            tags: ["attachments"],
+            parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+            responses: { "201": successResponse }
+        }
+    };
+    paths["/v1/spots/{id}/attachments"] = {
+        post: {
+            tags: ["attachments"],
+            parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+            responses: { "201": successResponse }
+        }
+    };
+    return {
+        openapi: "3.0.3",
+        info: {
+            title: "Forgeyard API",
+            version: "1.0.0"
+        },
+        paths
+    };
+}
+function operation(tag, operationId, summary, parameters, requestBody = false) {
+    return {
+        tags: [tag],
+        operationId,
+        summary,
+        ...(parameters.length === 0 ? {} : { parameters }),
+        ...(requestBody
+            ? {
+                requestBody: {
+                    required: true,
+                    content: {
+                        "application/json": { schema: bodySchema }
+                    }
+                }
+            }
+            : {}),
+        responses: { "200": successResponse }
+    };
+}
+function singularize(resource) {
+    if (resource.endsWith("ies")) {
+        return `${resource.slice(0, -3)}y`;
+    }
+    if (resource.endsWith("ses")) {
+        return resource.slice(0, -2);
+    }
+    return resource.endsWith("s") ? resource.slice(0, -1) : resource;
+}

package/dist/mock.d.ts

@@ -1,2 +1,3 @@
 export { mockFetch } from "./mock/fetch.js";
+export { createForgeyardSpec, FORGEYARD_BASE_URL, FORGEYARD_RESOURCES } from "./mock/forgeyard.js";
 export type { MockFetchHandle, MockFetchOptions, MockFetchFixtures, MockFixtureEntry, OnUnmocked, RequestRecord } from "./mock/fetch.js";

package/dist/mock.js

@@ -1 +1,2 @@
 export { mockFetch } from "./mock/fetch.js";
+export { createForgeyardSpec, FORGEYARD_BASE_URL, FORGEYARD_RESOURCES } from "./mock/forgeyard.js";

package/dist/naming.d.ts

@@ -1,4 +1,4 @@
-export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
 type MethodDefaults = {
     collection: string;
     resource: string;
@@ -10,9 +10,12 @@ export declare const METHOD_DEFAULTS: Partial<Record<HttpMethod, MethodDefaults>
 export declare function deriveNoun(operation: {
     tags?: string[];
 }, path: string, operationId: string): string;
+export declare function normalizeNoun(value: string): string;
 export declare function deriveVerb(method: HttpMethod, path: string, operation: {
     operationId?: string;
 }, operationId: string, noun: string): string;
+export declare function deriveDisambiguatedVerb(operationId: string, noun: string): string;
+export declare function derivePathDisambiguatedVerb(method: HttpMethod, path: string, noun: string, verb: string, includeTemplateQualifiers?: boolean, includeParentQualifiers?: boolean): string;
 export declare function normalizeParamName(name: string): string;
 export declare function toPascalCase(value: string): string;
 export declare function toCamelCase(value: string): string;

package/dist/naming.js

@@ -10,18 +10,19 @@ export const METHOD_DEFAULTS = {
         resource: "view",
         genericVerbs: ["get", "list", "view"],
         preferOperationIdWhenPathTailIsGeneric: true
-    }
+    },
+    head: { collection: "check", resource: "check" },
+    options: { collection: "options", resource: "options" }
 };
 export function deriveNoun(operation, path, operationId) {
     const noun = operation.tags?.[0];
     if (typeof noun !== "string" || noun.length === 0) {
-        const fallbackNoun = deriveNounFromPath(path);
-        if (fallbackNoun === undefined) {
-            throw new UserError(`Operation ${JSON.stringify(operationId)} must define tags[0] or a static resource segment in the path to derive a command noun.`);
-        }
-        return fallbackNoun;
+        return normalizeNoun(deriveNounFromPath(path) ?? operationId);
     }
-    return toKebabCase(noun);
+    return normalizeNoun(noun);
+}
+export function normalizeNoun(value) {
+    return toKebabCase([...value].map((character) => (isNounWordCharacter(character) ? character : " ")).join(""));
 }
 export function deriveVerb(method, path, operation, operationId, noun) {
     const segments = splitPathSegments(path);
@@ -49,8 +50,51 @@ export function deriveVerb(method, path, operation, operationId, noun) {
     if (derived !== undefined) {
         return derived;
     }
+    const fallback = deriveVerbFromPath(method, segments, noun);
+    if (fallback !== undefined) {
+        return fallback;
+    }
     throw new UserError(`Operation ${JSON.stringify(operationId)} is missing an operationId, so toolcraft-openapi cannot derive a stable command verb.`);
 }
+function deriveVerbFromPath(method, segments, noun) {
+    const action = method === "post" ? "create" : method === "put" || method === "patch" ? "update" : undefined;
+    if (action === undefined) {
+        return undefined;
+    }
+    const staticSegments = segments
+        .filter((segment) => !isPathTemplateSegment(segment) && segment !== "api" && !isVersionWord(segment))
+        .map((segment) => toKebabCase(segment));
+    const nounIndex = staticSegments.indexOf(noun);
+    const qualifiers = nounIndex === -1 ? staticSegments.slice(1) : staticSegments.slice(nounIndex + 1);
+    return qualifiers.length === 0 ? action : `${action}-${qualifiers.join("-")}`;
+}
+export function deriveDisambiguatedVerb(operationId, noun) {
+    const words = trimLeadingWords(splitWords(operationId).filter((word) => !isVersionWord(word)), splitWords(noun));
+    const withoutGenericVerb = stripLeadingGenericVerb(words, ["create", "delete", "get", "list", "patch", "post", "put", "remove", "update", "view"]);
+    const candidate = withoutGenericVerb.length === 0 ? words : withoutGenericVerb;
+    return candidate.map(normalizeNoun).filter((word) => word.length > 0).join("-");
+}
+export function derivePathDisambiguatedVerb(method, path, noun, verb, includeTemplateQualifiers = false, includeParentQualifiers = false) {
+    const segments = splitPathSegments(path);
+    const nounIndex = segments.findIndex((segment) => toKebabCase(segment) === noun);
+    const relevantSegments = includeParentQualifiers || nounIndex === -1 ? segments : segments.slice(nounIndex + 1);
+    const staticQualifiers = relevantSegments
+        .flatMap(readStaticPathSegmentWords)
+        .filter((word) => word !== "api" && !isVersionWord(word));
+    const templateQualifiers = relevantSegments.flatMap(readPathTemplateWords);
+    const qualifiers = includeTemplateQualifiers
+        ? [...staticQualifiers, ...templateQualifiers]
+        : staticQualifiers.length > 0
+            ? staticQualifiers
+            : templateQualifiers;
+    if (qualifiers.length === 0) {
+        return verb;
+    }
+    const defaultVerb = METHOD_DEFAULTS[method]?.resource ??
+        METHOD_DEFAULTS[method]?.collection ??
+        (method === "post" ? "create" : method === "put" || method === "patch" ? "update" : verb);
+    return `${defaultVerb}-${qualifiers.join("-")}`;
+}
 export function normalizeParamName(name) {
     return toCamelCase(name);
 }
@@ -97,9 +141,51 @@ function deriveNounFromPath(path) {
         .map((segment) => toKebabCase(segment))
         .find((segment) => segment.length > 0);
 }
+function isNounWordCharacter(character) {
+    return ((character >= "a" && character <= "z") ||
+        (character >= "A" && character <= "Z") ||
+        (character >= "0" && character <= "9") ||
+        character === "-" ||
+        character === "_");
+}
 function isPathTemplateSegment(segment) {
     return segment !== undefined && segment.startsWith("{") && segment.endsWith("}");
 }
+function readStaticPathSegmentWords(segment) {
+    let depth = 0;
+    let staticText = "";
+    for (const character of segment) {
+        if (character === "{") {
+            depth += 1;
+            staticText += " ";
+            continue;
+        }
+        if (character === "}") {
+            depth = Math.max(0, depth - 1);
+            staticText += " ";
+            continue;
+        }
+        staticText += depth === 0 ? character : " ";
+    }
+    return splitWords(staticText.replaceAll(":", " "));
+}
+function readPathTemplateWords(segment) {
+    let depth = 0;
+    let templateText = "";
+    for (const character of segment) {
+        if (character === "{") {
+            depth += 1;
+            continue;
+        }
+        if (character === "}") {
+            depth = Math.max(0, depth - 1);
+            templateText += " ";
+            continue;
+        }
+        templateText += depth > 0 ? character : " ";
+    }
+    return splitWords(templateText.replaceAll(":", " "));
+}
 function deriveVerbFromOperationId(method, operationId, noun, defaults) {
     const words = normalizeOperationIdWords(method, operationId, noun);
     if (words === undefined) {