docfy-core 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# docfy-core
+
+Document Model puro (normalização de spec OpenAPI + gerador de exemplos +
+transformer "Copy for AI") extraído do `docfy-ui`, sem dependências de
+React/DOM. Consumido por `docfy-ui` e `docfy-mcp`.
+
+## API
+
+```ts
+import { normalizeDocument, operationToAiText } from 'docfy-core';
+
+const document = await normalizeDocument(rawOpenApiSpec);
+const endpoint = document.tagGroups[0].endpoints[0];
+const aiText = operationToAiText(endpoint);
+```
+
+## Scripts
+
+- `npm run build` — compila para `dist/` (tipos + JS)
+- `npm test` — roda a suíte (vitest)
+- `npm run typecheck` — `tsc --noEmit`

package/dist/document-model/cap-depth.d.ts

@@ -0,0 +1,17 @@
+export interface CapDepthOptions {
+    maxDepth?: number;
+}
+/**
+ * Walks a dereferenced OpenAPI schema (or any object graph) and produces a
+ * JSON-safe copy: cycles become `"[Circular]"` and anything past `maxDepth`
+ * becomes `"[Object]"`/`"[Array]"`.
+ *
+ * Needed because `SwaggerParser.dereference()` resolves `$ref` into real
+ * object identity — a recursive DTO (`User.parent: User`) becomes an actual
+ * cycle, which `JSON.stringify` cannot serialize. Cycle detection uses the
+ * current ancestor chain, not a global "seen" set: the same dereferenced
+ * object can legitimately appear in multiple sibling branches (e.g.
+ * `createdBy: User` and `updatedBy: User`) without being circular — only
+ * an object appearing in its own chain of parents is a real cycle.
+ */
+export declare function capDepth(value: unknown, options?: CapDepthOptions): unknown;

package/dist/document-model/cap-depth.js

@@ -0,0 +1,41 @@
+const DEFAULT_MAX_DEPTH = 50;
+/**
+ * Walks a dereferenced OpenAPI schema (or any object graph) and produces a
+ * JSON-safe copy: cycles become `"[Circular]"` and anything past `maxDepth`
+ * becomes `"[Object]"`/`"[Array]"`.
+ *
+ * Needed because `SwaggerParser.dereference()` resolves `$ref` into real
+ * object identity — a recursive DTO (`User.parent: User`) becomes an actual
+ * cycle, which `JSON.stringify` cannot serialize. Cycle detection uses the
+ * current ancestor chain, not a global "seen" set: the same dereferenced
+ * object can legitimately appear in multiple sibling branches (e.g.
+ * `createdBy: User` and `updatedBy: User`) without being circular — only
+ * an object appearing in its own chain of parents is a real cycle.
+ */
+export function capDepth(value, options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const ancestors = new Set();
+    function walk(node, depth) {
+        if (node === null || typeof node !== 'object')
+            return node;
+        if (ancestors.has(node))
+            return '[Circular]';
+        if (depth >= maxDepth)
+            return Array.isArray(node) ? '[Array]' : '[Object]';
+        ancestors.add(node);
+        try {
+            if (Array.isArray(node)) {
+                return node.map((item) => walk(item, depth + 1));
+            }
+            const result = {};
+            for (const [key, val] of Object.entries(node)) {
+                result[key] = walk(val, depth + 1);
+            }
+            return result;
+        }
+        finally {
+            ancestors.delete(node);
+        }
+    }
+    return walk(value, 0);
+}

package/dist/document-model/example.d.ts

@@ -0,0 +1,22 @@
+import type { JSONSchemaLike, ResponseInfo } from './types.js';
+export declare const STATUS_TEXT: Record<string, string>;
+/** Resolves `allOf`/`oneOf`/`anyOf` to a single concrete schema. Returns the variant count when a `oneOf`/`anyOf` union was found. */
+export declare function resolveUnion(schema: JSONSchemaLike | undefined): {
+    schema: JSONSchemaLike | undefined;
+    unionSize?: number;
+};
+/** Text used wherever a schema cycle is detected, instead of expanding it again. */
+export declare function circularMarker(schema: JSONSchemaLike): string;
+export interface SchemaExampleResult {
+    /** The flattened example, JSON.stringify-safe (cycles already capped). */
+    example: unknown;
+    json: string;
+    unionSizes: number[];
+}
+export declare function buildSchemaExample(schema: JSONSchemaLike | undefined): SchemaExampleResult | undefined;
+export declare function withUnionNotes(body: string, unionSizes: number[]): string;
+/**
+ * Primary 2xx response: smallest numeric 2xx code declared. Non-numeric
+ * statuses (e.g. "default") are not considered.
+ */
+export declare function pickPrimarySuccessResponse(responses: ResponseInfo[]): ResponseInfo | undefined;

package/dist/document-model/example.js

@@ -0,0 +1,164 @@
+import { capDepth } from './cap-depth.js';
+export const STATUS_TEXT = {
+    '400': 'Bad Request',
+    '401': 'Unauthorized',
+    '403': 'Forbidden',
+    '404': 'Not Found',
+    '405': 'Method Not Allowed',
+    '409': 'Conflict',
+    '422': 'Unprocessable Entity',
+    '429': 'Too Many Requests',
+    '500': 'Internal Server Error',
+    '502': 'Bad Gateway',
+    '503': 'Service Unavailable',
+};
+/**
+ * Caches `schema` (with `allOf`) -> merged result by identity. Without this,
+ * every visit to the same `$ref`'d schema (e.g. a recursive `User.manager:
+ * User` where `User` itself uses `allOf`) would produce a freshly-allocated
+ * merged object, defeating the identity-based cycle detection in
+ * `flattenSchema`/`buildNode` below — they track "have I seen this object
+ * before" via a `Set`, which only works if the same input always resolves
+ * to the same output object.
+ */
+const mergeCache = new WeakMap();
+/**
+ * Shallow-merges an `allOf` composition into a single schema so downstream
+ * type/property resolution sees one object instead of an opaque array.
+ * `$ref`s are already dereferenced by `normalize.ts` by the time this runs,
+ * so each `allOf` entry is a real schema object, not a `$ref` string.
+ * Recurses so nested `allOf` (e.g. a `$ref`'d base schema that itself uses
+ * `allOf`) flattens fully; `oneOf`/`anyOf` inside a branch are left alone
+ * for `resolveUnion` to handle afterward.
+ */
+function mergeAllOf(schema) {
+    const branches = schema.allOf;
+    if (!branches || branches.length === 0)
+        return schema;
+    const cached = mergeCache.get(schema);
+    if (cached)
+        return cached;
+    const merged = { ...schema };
+    mergeCache.set(schema, merged);
+    delete merged.allOf;
+    let properties = { ...merged.properties };
+    let required = [...(merged.required ?? [])];
+    for (const branch of branches) {
+        const resolvedBranch = mergeAllOf(branch);
+        if (resolvedBranch.type && !merged.type)
+            merged.type = resolvedBranch.type;
+        if (resolvedBranch.properties) {
+            properties = { ...properties, ...resolvedBranch.properties };
+        }
+        if (Array.isArray(resolvedBranch.required)) {
+            required = [...required, ...resolvedBranch.required];
+        }
+    }
+    if (Object.keys(properties).length > 0) {
+        merged.properties = properties;
+        if (!merged.type)
+            merged.type = 'object';
+    }
+    if (required.length > 0)
+        merged.required = [...new Set(required)];
+    return merged;
+}
+/** Resolves `allOf`/`oneOf`/`anyOf` to a single concrete schema. Returns the variant count when a `oneOf`/`anyOf` union was found. */
+export function resolveUnion(schema) {
+    if (!schema)
+        return { schema: undefined };
+    const flattened = mergeAllOf(schema);
+    const union = flattened.oneOf ?? flattened.anyOf;
+    if (union && union.length > 0) {
+        // The chosen variant (e.g. `DigitalProduct`) may itself be an `allOf`
+        // composition — merge it too, otherwise it surfaces with no `type`/
+        // `properties` and falls back to the literal string "object".
+        return { schema: mergeAllOf(union[0]), unionSize: union.length };
+    }
+    return { schema: flattened };
+}
+/** Text used wherever a schema cycle is detected, instead of expanding it again. */
+export function circularMarker(schema) {
+    const title = typeof schema.title === 'string' ? schema.title : undefined;
+    return title ? `(circular reference to ${title})` : '(circular reference)';
+}
+/**
+ * Hard backstop against pathologically deep (but non-cyclic) schemas.
+ * Real cycles are caught immediately by ancestor tracking below — this
+ * only matters for the rare case of genuinely 20+ levels of distinct
+ * nesting.
+ */
+const MAX_DEPTH = 20;
+/**
+ * Flattens a JSON Schema into an example using TYPE NAMES as values
+ * ("name": "string"), never fake data — per the Copy for AI spec, section
+ * 3.2 step 3 ("chave: tipo, não valores fake"). Shared between the Copy
+ * for AI transformer and the code snippet generators so both render the
+ * exact same request/response body shape.
+ *
+ * `ancestors` tracks resolved schema objects currently on the recursion
+ * path (by identity, not a depth counter) — `SwaggerParser.dereference()`
+ * turns recursive DTOs (`User.parent: User`) into real object cycles, and
+ * a depth cap alone just unrolls the cycle N times before giving up,
+ * producing a huge wall of duplicated, useless nesting. Detecting the
+ * cycle the first time it repeats produces one concise marker instead.
+ */
+function flattenSchema(schema, depth, unionSizes, ancestors) {
+    if (!schema || depth > MAX_DEPTH)
+        return 'object';
+    const { schema: resolved, unionSize } = resolveUnion(schema);
+    if (unionSize)
+        unionSizes.push(unionSize);
+    if (!resolved)
+        return 'object';
+    if (ancestors.has(resolved))
+        return circularMarker(resolved);
+    const rawType = resolved.type;
+    const type = Array.isArray(rawType) ? rawType.find((t) => t !== 'null') ?? rawType[0] : rawType;
+    if (type === 'object' || resolved.properties) {
+        const props = resolved.properties ?? {};
+        ancestors.add(resolved);
+        const out = {};
+        for (const [key, propSchema] of Object.entries(props)) {
+            out[key] = flattenSchema(propSchema, depth + 1, unionSizes, ancestors);
+        }
+        ancestors.delete(resolved);
+        return out;
+    }
+    if (type === 'array') {
+        ancestors.add(resolved);
+        const item = flattenSchema(resolved.items, depth + 1, unionSizes, ancestors);
+        ancestors.delete(resolved);
+        return [item];
+    }
+    if (typeof type === 'string')
+        return type;
+    return 'object';
+}
+export function buildSchemaExample(schema) {
+    if (!schema)
+        return undefined;
+    const unionSizes = [];
+    const example = flattenSchema(schema, 0, unionSizes, new Set());
+    // Defense in depth: flattenSchema's own cycle detection should make this
+    // a no-op in practice, but capDepth stays as a second guard against any
+    // structure that's deep without being a detectable identity cycle.
+    const safe = capDepth(example, { maxDepth: 12 });
+    return { example: safe, json: JSON.stringify(safe, null, 2), unionSizes };
+}
+export function withUnionNotes(body, unionSizes) {
+    if (unionSizes.length === 0)
+        return body;
+    const notes = unionSizes.map((n) => `(one of ${n} possible shapes)`);
+    return `${body}\n${notes.join('\n')}`;
+}
+/**
+ * Primary 2xx response: smallest numeric 2xx code declared. Non-numeric
+ * statuses (e.g. "default") are not considered.
+ */
+export function pickPrimarySuccessResponse(responses) {
+    const numeric2xx = responses
+        .filter((r) => /^2\d\d$/.test(r.status))
+        .sort((a, b) => Number(a.status) - Number(b.status));
+    return numeric2xx[0];
+}

package/dist/document-model/normalize.d.ts

@@ -0,0 +1,13 @@
+import type { DocumentModel } from './types.js';
+/**
+ * Normalizes a raw OpenAPI 3.0/3.1 spec (JSON or already-parsed object)
+ * into the in-memory Document Model consumed by the sidebar and detail
+ * panel. Dereferences all `$ref`s — see parser-spike.spec.ts for why
+ * @apidevtools/swagger-parser was chosen over the alternative considered.
+ *
+ * Note: dereferencing turns recursive schemas into real object cycles.
+ * This function does not break on that (cycles only matter at
+ * serialization time) — callers that JSON.stringify a schema from this
+ * model must run it through `capDepth()` first.
+ */
+export declare function normalizeDocument(rawSpec: unknown): Promise<DocumentModel>;

package/dist/document-model/normalize.js

@@ -0,0 +1,146 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
+const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+const DEFAULT_TAG = 'Default';
+const JSON_CONTENT_TYPE_PREFERENCE = ['application/json'];
+function pickContent(content) {
+    if (!content)
+        return undefined;
+    const keys = Object.keys(content);
+    if (keys.length === 0)
+        return undefined;
+    const preferred = JSON_CONTENT_TYPE_PREFERENCE.find((ct) => keys.includes(ct));
+    const contentType = preferred ?? keys[0];
+    return { contentType, schema: content[contentType]?.schema };
+}
+function buildParameters(rawParams) {
+    if (!rawParams)
+        return [];
+    return rawParams.map((p) => ({
+        name: p.name,
+        in: p.in,
+        required: Boolean(p.required),
+        schema: p.schema,
+        description: p.description,
+    }));
+}
+function buildRequestBody(rawRequestBody) {
+    if (!rawRequestBody)
+        return undefined;
+    const picked = pickContent(rawRequestBody.content);
+    if (!picked)
+        return undefined;
+    return {
+        required: Boolean(rawRequestBody.required),
+        contentType: picked.contentType,
+        schema: picked.schema,
+    };
+}
+function buildResponses(rawResponses) {
+    if (!rawResponses)
+        return [];
+    return Object.entries(rawResponses).map(([status, value]) => {
+        const picked = pickContent(value?.content);
+        return {
+            status,
+            description: value?.description,
+            contentType: picked?.contentType,
+            schema: picked?.schema,
+        };
+    });
+}
+/**
+ * Returns tag names in the order the sidebar should display them:
+ * 1. Tags declared in the top-level `tags` array, in that order.
+ * 2. Any tag used by an operation but not declared at top level, in the
+ *    order it's first encountered while walking `paths`.
+ * 3. A synthetic "Default" group, last, for operations with no tags at all.
+ */
+function getOrderedTagNames(spec) {
+    const declared = (spec.tags ?? []).map((t) => t.name);
+    const seen = new Set(declared);
+    const discovered = [];
+    let hasUntagged = false;
+    for (const pathItem of Object.values(spec.paths ?? {})) {
+        for (const method of HTTP_METHODS) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            const tags = operation.tags ?? [];
+            if (tags.length === 0) {
+                hasUntagged = true;
+                continue;
+            }
+            for (const tag of tags) {
+                if (!seen.has(tag)) {
+                    seen.add(tag);
+                    discovered.push(tag);
+                }
+            }
+        }
+    }
+    const ordered = [...declared, ...discovered];
+    if (hasUntagged)
+        ordered.push(DEFAULT_TAG);
+    return ordered;
+}
+function getTagDescription(spec, tagName) {
+    const declared = (spec.tags ?? []).find((t) => t.name === tagName);
+    return declared?.description;
+}
+/**
+ * Normalizes a raw OpenAPI 3.0/3.1 spec (JSON or already-parsed object)
+ * into the in-memory Document Model consumed by the sidebar and detail
+ * panel. Dereferences all `$ref`s — see parser-spike.spec.ts for why
+ * @apidevtools/swagger-parser was chosen over the alternative considered.
+ *
+ * Note: dereferencing turns recursive schemas into real object cycles.
+ * This function does not break on that (cycles only matter at
+ * serialization time) — callers that JSON.stringify a schema from this
+ * model must run it through `capDepth()` first.
+ */
+export async function normalizeDocument(rawSpec) {
+    const spec = (await SwaggerParser.dereference(rawSpec));
+    const endpointsByTag = new Map();
+    for (const tagName of getOrderedTagNames(spec)) {
+        endpointsByTag.set(tagName, []);
+    }
+    for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
+        for (const method of HTTP_METHODS) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            const tags = operation.tags?.length ? operation.tags : [DEFAULT_TAG];
+            const endpoint = {
+                method: method.toUpperCase(),
+                path,
+                operationId: operation.operationId,
+                summary: operation.summary,
+                description: operation.description,
+                tags,
+                parameters: buildParameters(operation.parameters),
+                requestBody: buildRequestBody(operation.requestBody),
+                responses: buildResponses(operation.responses),
+            };
+            for (const tag of tags) {
+                if (!endpointsByTag.has(tag))
+                    endpointsByTag.set(tag, []);
+                endpointsByTag.get(tag).push(endpoint);
+            }
+        }
+    }
+    const tagGroups = Array.from(endpointsByTag.entries())
+        .filter(([, endpoints]) => endpoints.length > 0)
+        .map(([name, endpoints]) => ({
+        name,
+        description: getTagDescription(spec, name),
+        endpoints,
+    }));
+    return {
+        info: {
+            title: spec.info?.title ?? '',
+            version: spec.info?.version ?? '',
+            description: spec.info?.description,
+        },
+        tagGroups,
+    };
+}

package/dist/document-model/types.d.ts

@@ -0,0 +1,49 @@
+/** Loosely-typed JSON Schema node — we don't re-implement a schema type system, just pass it through. */
+export type JSONSchemaLike = Record<string, unknown>;
+export interface ParameterInfo {
+    name: string;
+    in: 'query' | 'path' | 'header' | 'cookie';
+    required: boolean;
+    schema: JSONSchemaLike | undefined;
+    description: string | undefined;
+}
+export interface RequestBodyInfo {
+    required: boolean;
+    /** The content type actually selected (application/json preferred, else first available). */
+    contentType: string;
+    schema: JSONSchemaLike | undefined;
+}
+export interface ResponseInfo {
+    /** "200", "404", "default", etc. */
+    status: string;
+    description: string | undefined;
+    contentType: string | undefined;
+    schema: JSONSchemaLike | undefined;
+}
+export interface Endpoint {
+    method: string;
+    path: string;
+    operationId: string | undefined;
+    summary: string | undefined;
+    description: string | undefined;
+    tags: string[];
+    parameters: ParameterInfo[];
+    requestBody: RequestBodyInfo | undefined;
+    responses: ResponseInfo[];
+}
+export interface TagGroup {
+    name: string;
+    description: string | undefined;
+    endpoints: Endpoint[];
+}
+export interface DocumentModel {
+    info: {
+        title: string;
+        version: string;
+        description: string | undefined;
+    };
+    /** Tags in declared order (from the top-level `tags` array), then any
+     * tags used by operations but not declared, in first-appearance order.
+     * Operations with no tags fall into a synthetic "Default" group, last. */
+    tagGroups: TagGroup[];
+}

package/dist/document-model/types.js

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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { normalizeDocument } from './document-model/normalize.js';
+export { STATUS_TEXT, buildSchemaExample, circularMarker, pickPrimarySuccessResponse, resolveUnion, withUnionNotes, } from './document-model/example.js';
+export type { SchemaExampleResult } from './document-model/example.js';
+export { capDepth } from './document-model/cap-depth.js';
+export type { CapDepthOptions } from './document-model/cap-depth.js';
+export { operationToAiText } from './transformers/copy-for-ai.js';
+export type { DocumentModel, Endpoint, JSONSchemaLike, ParameterInfo, RequestBodyInfo, ResponseInfo, TagGroup, } from './document-model/types';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { normalizeDocument } from './document-model/normalize.js';
+export { STATUS_TEXT, buildSchemaExample, circularMarker, pickPrimarySuccessResponse, resolveUnion, withUnionNotes, } from './document-model/example.js';
+export { capDepth } from './document-model/cap-depth.js';
+export { operationToAiText } from './transformers/copy-for-ai.js';

package/dist/transformers/copy-for-ai.d.ts

@@ -0,0 +1,11 @@
+import type { Endpoint } from '../document-model/types.js';
+/**
+ * Transforms a normalized Endpoint into the plain-text, LLM-ready
+ * representation behind the "Copy for AI" button. Pure function, no I/O —
+ * runs entirely client-side in well under 5ms.
+ *
+ * Section order: Endpoint → Purpose → Request → Parameters → Validation →
+ * Success Response → Error Responses. Empty sections are omitted, and
+ * sections are separated by a blank line for scannability.
+ */
+export declare function operationToAiText(endpoint: Endpoint): string;

package/dist/transformers/copy-for-ai.js

@@ -0,0 +1,138 @@
+import { STATUS_TEXT, buildSchemaExample, pickPrimarySuccessResponse, resolveUnion, withUnionNotes, } from '../document-model/example.js';
+function truncateToSentences(text, maxSentences) {
+    const sentences = text.trim().split(/(?<=[.!?])\s+/).filter(Boolean);
+    return sentences.slice(0, maxSentences).join(' ');
+}
+function buildPurpose(endpoint) {
+    if (endpoint.summary)
+        return endpoint.summary;
+    if (endpoint.description)
+        return truncateToSentences(endpoint.description, 2);
+    return undefined;
+}
+/**
+ * Extracts explicit validation rules from a request body schema:
+ * format, minLength/maxLength, minimum/maximum, pattern, enum.
+ *
+ * Deliberate decision: `required` does NOT produce its own line. The
+ * worked example in section 3.3 shows zero "X is required" lines for a
+ * register endpoint where email/password are almost certainly required —
+ * presence is already conveyed by the field simply appearing in the
+ * Request example, so a separate "required" line would be redundant
+ * noise for the AI consumer. Reproduced exactly against that example.
+ *
+ * `ancestors` tracks resolved schema objects on the current recursion
+ * path by identity — dereferenced schemas can be real object cycles
+ * (recursive DTOs). Unlike a plain depth cap (which used to unroll the
+ * cycle ~10 times, producing duplicated "parent.parent...x10 email must
+ * be valid" lines), stopping the moment a schema repeats means a
+ * recursive property contributes at most one pass of rules — its own
+ * rules already cover what the cycle would otherwise repeat.
+ */
+function extractValidationRules(schema, prefix = '', ancestors = new Set()) {
+    const { schema: resolved } = resolveUnion(schema);
+    if (!resolved)
+        return [];
+    if (ancestors.has(resolved))
+        return [];
+    const properties = resolved.properties ?? {};
+    const rules = [];
+    ancestors.add(resolved);
+    for (const [key, rawPropSchema] of Object.entries(properties)) {
+        const name = prefix ? `${prefix}.${key}` : key;
+        const { schema: prop } = resolveUnion(rawPropSchema);
+        if (!prop)
+            continue;
+        if (prop.format)
+            rules.push(`${name} must be valid`);
+        if (prop.minLength !== undefined)
+            rules.push(`${name} min length ${prop.minLength}`);
+        if (prop.maxLength !== undefined)
+            rules.push(`${name} max length ${prop.maxLength}`);
+        if (prop.minimum !== undefined)
+            rules.push(`${name} min ${prop.minimum}`);
+        if (prop.maximum !== undefined)
+            rules.push(`${name} max ${prop.maximum}`);
+        if (prop.pattern)
+            rules.push(`${name} must match pattern ${prop.pattern}`);
+        if (Array.isArray(prop.enum))
+            rules.push(`${name} must be one of: ${prop.enum.join(', ')}`);
+        if (prop.type === 'object' && prop.properties) {
+            rules.push(...extractValidationRules(prop, name, ancestors));
+        }
+    }
+    ancestors.delete(resolved);
+    return rules;
+}
+const PARAM_GROUP_LABELS = {
+    path: 'Path Parameters',
+    query: 'Query Parameters',
+    header: 'Headers',
+};
+/** Same grouping/order/labels as the visual `ParametersSection` — cookie params stay out of scope for both. */
+const PARAM_GROUP_ORDER = ['path', 'query', 'header'];
+function formatParameterLine(param) {
+    const requirement = param.required ? 'required' : 'optional';
+    const type = typeof param.schema?.type === 'string' ? param.schema.type : 'unknown';
+    const description = param.description ? ` — ${param.description}` : '';
+    return `- ${param.name} (${requirement}): ${type}${description}`;
+}
+/** Groups parameters into Path/Query/Headers sub-sections, each with an explicit required/optional per line. */
+function buildParametersBlock(parameters) {
+    const groups = PARAM_GROUP_ORDER.map((kind) => ({
+        kind,
+        items: parameters.filter((p) => p.in === kind),
+    })).filter((g) => g.items.length > 0);
+    if (groups.length === 0)
+        return undefined;
+    const body = groups
+        .map((g) => `${PARAM_GROUP_LABELS[g.kind]}:\n${g.items.map(formatParameterLine).join('\n')}`)
+        .join('\n');
+    return `Parameters:\n${body}`;
+}
+function buildErrorResponseLines(responses) {
+    return responses
+        .filter((r) => /^[45]\d\d$/.test(r.status))
+        .map((r) => `${r.status} ${r.description || STATUS_TEXT[r.status] || ''}`.trim());
+}
+/**
+ * Transforms a normalized Endpoint into the plain-text, LLM-ready
+ * representation behind the "Copy for AI" button. Pure function, no I/O —
+ * runs entirely client-side in well under 5ms.
+ *
+ * Section order: Endpoint → Purpose → Request → Parameters → Validation →
+ * Success Response → Error Responses. Empty sections are omitted, and
+ * sections are separated by a blank line for scannability.
+ */
+export function operationToAiText(endpoint) {
+    const sections = [];
+    sections.push(`Endpoint: ${endpoint.method} ${endpoint.path}`);
+    const purpose = buildPurpose(endpoint);
+    if (purpose)
+        sections.push(`Purpose:\n${purpose}`);
+    if (endpoint.requestBody?.schema) {
+        const result = buildSchemaExample(endpoint.requestBody.schema);
+        if (result)
+            sections.push(withUnionNotes(`Request:\n${result.json}`, result.unionSizes));
+    }
+    const parametersBlock = buildParametersBlock(endpoint.parameters);
+    if (parametersBlock)
+        sections.push(parametersBlock);
+    if (endpoint.requestBody?.schema) {
+        const rules = extractValidationRules(endpoint.requestBody.schema);
+        if (rules.length > 0) {
+            sections.push(`Validation:\n${rules.map((r) => `- ${r}`).join('\n')}`);
+        }
+    }
+    const success = pickPrimarySuccessResponse(endpoint.responses);
+    if (success) {
+        const result = buildSchemaExample(success.schema);
+        const body = result ? withUnionNotes(result.json, result.unionSizes) : (success.description || 'No content');
+        sections.push(`Success Response (${success.status}):\n${body}`);
+    }
+    const errorLines = buildErrorResponseLines(endpoint.responses);
+    if (errorLines.length > 0) {
+        sections.push(`Error Responses:\n${errorLines.join('\n')}`);
+    }
+    return sections.join('\n\n');
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "docfy-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pure OpenAPI document-model + Copy-for-AI transformer shared by docfy-ui and docfy-mcp",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "Marvin Rocha",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MarvinRF/docfy-core.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.16.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}