@openapi-flow/core 0.3.10 → 0.3.12

package/dist/arguments/clarification/api-input-requirement-dialect.d.ts

@@ -0,0 +1,4 @@
+import type { ApiInputRequirement } from '../../types/api-clarification.js';
+import type { SchemaDialect } from '../../types/schema-dialect.js';
+/** A compiled projection declares its actual dialect; the source OAS version remains unchanged. */
+export declare function apiInputRequirementDialect(requirement: ApiInputRequirement): SchemaDialect;

package/dist/arguments/clarification/api-input-requirement-dialect.js

@@ -0,0 +1,8 @@
+/** A compiled projection declares its actual dialect; the source OAS version remains unchanged. */
+export function apiInputRequirementDialect(requirement) {
+    if (requirement.schemaDialect === 'draft-2020-12')
+        return 'draft-2020-12';
+    return requirement.openapiVersion.startsWith('3.0.')
+        ? 'openapi-3.0'
+        : 'draft-2020-12';
+}

package/dist/arguments/clarification/extraction/capture-api-input-answer-context.js

@@ -1,5 +1,6 @@
 import { apiInputAnswerContextSchema } from '../../../schemas/api-input-answer-extraction-schema.js';
 import { createOasValueValidator } from '../../../openapi/common/create-oas-value-validator.js';
+import { apiInputRequirementDialect } from '../api-input-requirement-dialect.js';
 /** Capture supplied pending contracts before any asynchronous model work. */
 export function captureApiInputAnswerContext(input) {
     apiInputAnswerContextSchema.parse(input);
@@ -9,9 +10,7 @@ export function captureApiInputAnswerContext(input) {
         if (ids.has(requirement.id))
             throw new Error(`Duplicate API input requirementId: ${requirement.id}`);
         ids.add(requirement.id);
-        createOasValueValidator(requirement.schema, requirement.openapiVersion.startsWith('3.0.')
-            ? 'openapi-3.0'
-            : 'draft-2020-12', `API input requirement ${requirement.id} ${requirement.targetPointer}`);
+        createOasValueValidator(requirement.schema, apiInputRequirementDialect(requirement), `API input requirement ${requirement.id} ${requirement.targetPointer}`);
     }
     return snapshot;
 }

package/dist/arguments/clarification/extraction/create-api-input-answer-extraction-record.js

@@ -1,19 +1,26 @@
 import { apiInputAnswerExtractionDecisionSchema } from '../../../schemas/api-input-answer-extraction-schema.js';
 import { captureApiInputAnswerContext } from './capture-api-input-answer-context.js';
-import { resolveApiInputAnswerSources } from './resolve-api-input-answer-sources.js';
+import { resolveApiInputAnswerInterpretations } from './resolve-api-input-answer-interpretations.js';
 export function createApiInputAnswerExtractionRecord(input) {
     const evidence = captureApiInputAnswerContext({
         reply: input.reply,
         requirements: input.requirements,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+        ...(input.selectOasEnums === undefined
+            ? {}
+            : { selectOasEnums: input.selectOasEnums }),
     });
     const decision = structuredClone(apiInputAnswerExtractionDecisionSchema.parse(input.decision));
-    const verification = resolveApiInputAnswerSources({
+    const verification = resolveApiInputAnswerInterpretations({
         ...evidence,
         selections: decision.answers.map((source) => ({
             requirementId: source.requirementId,
             sourceFormat: source.sourceFormat,
             sourceText: source.sourceText,
         })),
+        ...(decision.enumSelections === undefined
+            ? {}
+            : { enumSelections: decision.enumSelections }),
     });
     return {
         kind: 'model-extracted-api-input-answers',

package/dist/arguments/clarification/extraction/resolve-api-input-answer-interpretations.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveApiInputAnswerInterpretationsInput, ResolvedApiInputAnswerInterpretations } from '../../../types/api-input-enum-answers.js';
+/** Literal values and semantic intent have different sources and must never be conflated. */
+export declare function resolveApiInputAnswerInterpretations(input: ResolveApiInputAnswerInterpretationsInput): ResolvedApiInputAnswerInterpretations;

package/dist/arguments/clarification/extraction/resolve-api-input-answer-interpretations.js

@@ -0,0 +1,52 @@
+import { apiInputEnumAnswerSelectionsSchema } from '../../../schemas/api-input-enum-answer-selection-schema.js';
+import { captureApiInputAnswerContext } from './capture-api-input-answer-context.js';
+import { resolveApiInputAnswerSources } from './resolve-api-input-answer-sources.js';
+import { describeApiInputEnumAnswerChoices } from '../../enum/describe-api-input-enum-answer-choices.js';
+import { readApiInputLiteralSource } from '../../sources/read-api-input-literal-source.js';
+/** Literal values and semantic intent have different sources and must never be conflated. */
+export function resolveApiInputAnswerInterpretations(input) {
+    const context = captureApiInputAnswerContext({
+        reply: input.reply,
+        requirements: input.requirements,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+        ...(input.selectOasEnums === undefined
+            ? {}
+            : { selectOasEnums: input.selectOasEnums }),
+    });
+    const result = resolveApiInputAnswerSources({
+        reply: context.reply,
+        requirements: context.requirements,
+        selections: input.selections,
+    });
+    if (input.enumSelections === undefined)
+        return result;
+    const selections = apiInputEnumAnswerSelectionsSchema.parse(input.enumSelections);
+    if (context.selectOasEnums !== true)
+        throw new Error('API enum answer selection requires selectOasEnums: true in the original context');
+    const choices = describeApiInputEnumAnswerChoices(context);
+    const answered = new Set(result.answers.map((answer) => answer.requirementId));
+    result.enumSelections = selections.map((selection) => {
+        if (answered.has(selection.requirementId))
+            throw new Error(`Duplicate requirementId: ${selection.requirementId}`);
+        const candidate = choices
+            .find((choice) => choice.requirementId === selection.requirementId)
+            ?.candidates.find((item) => item.id === selection.candidateId);
+        if (!candidate)
+            throw new Error(`API enum answer ${selection.requirementId} has an unknown or stale OAS candidate: ${selection.candidateId}`);
+        const { occurrences } = readApiInputLiteralSource({
+            ...selection.intent,
+            text: context.reply,
+            label: `Enum answer intent ${selection.requirementId}`,
+        });
+        answered.add(selection.requirementId);
+        result.answers.push({
+            requirementId: selection.requirementId,
+            value: structuredClone(candidate.value),
+        });
+        return { ...selection, candidate: structuredClone(candidate), occurrences };
+    });
+    result.unansweredRequirementIds = context.requirements
+        .filter((item) => !answered.has(item.id))
+        .map((item) => item.id);
+    return result;
+}

package/dist/arguments/clarification/extraction/resolve-api-input-answer-sources.js

@@ -2,11 +2,13 @@ import { apiInputAnswerSourcesSchema } from '../../../schemas/api-input-answer-e
 import { captureApiInputAnswerContext } from './capture-api-input-answer-context.js';
 import { readApiInputLiteralSource } from '../../sources/read-api-input-literal-source.js';
 import { createOasValueValidator } from '../../../openapi/common/create-oas-value-validator.js';
+import { apiInputRequirementDialect } from '../api-input-requirement-dialect.js';
 /** Model-selected source text is the only value source, never a model-generated value. */
 export function resolveApiInputAnswerSources(input) {
     const context = captureApiInputAnswerContext({
         reply: input.reply,
         requirements: input.requirements,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
     });
     const selections = apiInputAnswerSourcesSchema.parse(input.selections);
     const answered = new Set();
@@ -24,9 +26,7 @@ export function resolveApiInputAnswerSources(input) {
             text: context.reply,
             label: `Answer ${requirement.id}`,
         });
-        const checked = createOasValueValidator(requirement.schema, requirement.openapiVersion.startsWith('3.0.')
-            ? 'openapi-3.0'
-            : 'draft-2020-12', `answer ${requirement.targetPointer}`).validate(value);
+        const checked = createOasValueValidator(requirement.schema, apiInputRequirementDialect(requirement), `answer ${requirement.targetPointer}`).validate(value);
         if (!checked.valid)
             throw new Error(`Answer ${requirement.id} violates its supplied OAS schema: ${checked.errors.map((error) => error.message).join('; ')}`);
         answered.add(requirement.id);

package/dist/arguments/clarification/extraction/resolve-api-input-source-selections.js

@@ -6,6 +6,7 @@ export function resolveApiInputSourceSelections(input) {
     const context = captureApiInputAnswerContext({
         reply: input.reply,
         requirements: input.requirements,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
     });
     const catalog = describeApiInputSources(context.reply);
     const selections = apiInputAnswerSelectionsSchema.parse(input.selections);

package/dist/arguments/clarification/extraction/validate-api-input-answer-analysis.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiInputAnswerAnalysisInput } from '../../../types/api-input-answer-extraction.js';
+/** Replay model choices against independently supplied original questions and reply. */
+export declare function validateApiInputAnswerAnalysis(input: ValidateApiInputAnswerAnalysisInput): void;

package/dist/arguments/clarification/extraction/validate-api-input-answer-analysis.js

@@ -0,0 +1,56 @@
+import { isDeepStrictEqual } from 'node:util';
+import { resolveApiInputAnswerInterpretations } from './resolve-api-input-answer-interpretations.js';
+import { validateApiInputAnswerExtractionRecord } from './validate-api-input-answer-extraction-record.js';
+/** Replay model choices against independently supplied original questions and reply. */
+export function validateApiInputAnswerAnalysis(input) {
+    const context = {
+        reply: input.reply,
+        requirements: input.requirements,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+        ...(input.selectOasEnums === undefined
+            ? {}
+            : { selectOasEnums: input.selectOasEnums }),
+    };
+    const { analysis } = input;
+    if (!Array.isArray(analysis.sources))
+        throw new Error('API input answer analysis.sources must be an array');
+    const resolved = resolveApiInputAnswerInterpretations({
+        ...context,
+        selections: analysis.sources.map((source) => ({
+            requirementId: source.requirementId,
+            sourceFormat: source.sourceFormat,
+            sourceText: source.sourceText,
+        })),
+        ...(analysis.enumSelections === undefined
+            ? {}
+            : {
+                enumSelections: analysis.enumSelections.map((selection) => ({
+                    requirementId: selection.requirementId,
+                    candidateId: selection.candidateId,
+                    intent: selection.intent,
+                    reason: selection.reason,
+                })),
+            }),
+    });
+    if (analysis.extraction !== undefined) {
+        validateApiInputAnswerExtractionRecord({
+            ...context,
+            record: analysis.extraction,
+        });
+        if (!isDeepStrictEqual(analysis.extraction.verification, resolved))
+            throw new Error('API input explanation differs from its code-resolved answer selection');
+    }
+    const status = !input.requirements.length
+        ? 'no-pending-inputs'
+        : input.reply === ''
+            ? 'empty-reply'
+            : 'extracted';
+    if (!isDeepStrictEqual(analysis, {
+        status,
+        ...resolved,
+        ...(analysis.extraction === undefined
+            ? {}
+            : { extraction: analysis.extraction }),
+    }))
+        throw new Error('API input analysis differs from its original reply, contracts or code-resolved values');
+}

package/dist/arguments/clarification/extraction/validate-api-input-answer-extraction-record.js

@@ -5,6 +5,10 @@ export function validateApiInputAnswerExtractionRecord(input) {
     const expected = createApiInputAnswerExtractionRecord({
         reply: input.reply,
         requirements: input.requirements,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+        ...(input.selectOasEnums === undefined
+            ? {}
+            : { selectOasEnums: input.selectOasEnums }),
         decision: input.record.decision,
     });
     if (!isDeepStrictEqual(expected, input.record))

package/dist/arguments/enum/describe-api-argument-enum-context.d.ts

@@ -0,0 +1,4 @@
+import type { ApiArgumentEnumContextInput } from '../../types/api-argument-enum.js';
+import type { ApiInputAnswerContext } from '../../types/api-input-answer-extraction.js';
+/** Derive real unanswered OAS enum questions, not a synthetic draft/edit plan. */
+export declare function describeApiArgumentEnumContext(input: ApiArgumentEnumContextInput): ApiInputAnswerContext;

package/dist/arguments/enum/describe-api-argument-enum-context.js

@@ -0,0 +1,41 @@
+import { describeApiLiteralGeneration } from '../generation/describe-api-literal-generation.js';
+import { inspectApiArgumentRequirements } from '../clarification/inspect-api-argument-requirements.js';
+import { describeApiInputEnumAnswerChoices } from './describe-api-input-enum-answer-choices.js';
+import { applyConfirmedApiInputs } from '../clarification/apply-confirmed-api-inputs.js';
+import { resolveApiLiteralProposalSources } from '../sources/resolve-api-literal-proposal-sources.js';
+import { expandRequestedEnumRequirements } from './expand-requested-enum-requirements.js';
+/** Derive real unanswered OAS enum questions, not a synthetic draft/edit plan. */
+export function describeApiArgumentEnumContext(input) {
+    const { input: snapshot, contract } = describeApiLiteralGeneration(input);
+    const proposal = contract.schema.parse(input.proposal);
+    resolveApiLiteralProposalSources({
+        callId: snapshot.callId,
+        values: proposal.values,
+        sources: input.literalSources,
+        messages: [{ id: 'scenario', text: snapshot.scenario }],
+    });
+    const values = applyConfirmedApiInputs({
+        ...snapshot,
+        values: proposal.values,
+    });
+    const inspected = inspectApiArgumentRequirements({
+        ...snapshot,
+        values,
+        requestedInputs: input.requestedInputs,
+    });
+    const context = {
+        reply: snapshot.scenario,
+        requirements: expandRequestedEnumRequirements({
+            ...input,
+            values,
+            requirements: inspected.requirements,
+        }),
+        selectOasEnums: true,
+        ...(snapshot.purpose === undefined ? {} : { purpose: snapshot.purpose }),
+    };
+    const ids = new Set(describeApiInputEnumAnswerChoices(context).map((choice) => choice.requirementId));
+    return {
+        ...context,
+        requirements: context.requirements.filter((item) => ids.has(item.id)),
+    };
+}

package/dist/arguments/enum/describe-api-input-enum-answer-choices.d.ts

@@ -0,0 +1,4 @@
+import type { ApiInputAnswerContext } from '../../types/api-input-answer-extraction.js';
+import type { ApiInputEnumAnswerChoice } from '../../types/api-input-enum-answers.js';
+/** Pending question contracts are the only value authority; defaults/examples are not candidates. */
+export declare function describeApiInputEnumAnswerChoices(input: ApiInputAnswerContext): ApiInputEnumAnswerChoice[];

package/dist/arguments/enum/describe-api-input-enum-answer-choices.js

@@ -0,0 +1,23 @@
+import { captureApiInputAnswerContext } from '../clarification/extraction/capture-api-input-answer-context.js';
+import { createOasValueValidator } from '../../openapi/common/create-oas-value-validator.js';
+import { createSchemaResourceContext } from '../../bindings/resources/create-schema-resource-context.js';
+import { listApiInputEnumCandidates } from './list-api-input-enum-candidates.js';
+import { apiInputRequirementDialect } from '../clarification/api-input-requirement-dialect.js';
+/** Pending question contracts are the only value authority; defaults/examples are not candidates. */
+export function describeApiInputEnumAnswerChoices(input) {
+    const context = captureApiInputAnswerContext(input);
+    if (context.selectOasEnums !== true)
+        return [];
+    return context.requirements.flatMap((requirement) => {
+        const normalized = createOasValueValidator(requirement.schema, apiInputRequirementDialect(requirement), `API enum answer ${requirement.id}`).schema;
+        const resources = createSchemaResourceContext(normalized);
+        const candidates = listApiInputEnumCandidates({
+            source: { kind: 'requirement', requirement },
+            schemas: [resources.reference(resources.root)],
+            resources,
+        });
+        return candidates.length
+            ? [{ requirementId: requirement.id, candidates }]
+            : [];
+    });
+}

package/dist/arguments/enum/expand-requested-enum-requirements.d.ts

@@ -0,0 +1,4 @@
+import type { ApiArgumentEnumRequirementsInput } from '../../types/api-argument-enum.js';
+import type { ApiInputRequirement } from '../../types/api-clarification.js';
+/** Missing containers need no fabricated value to expose their explicitly requested OAS descendants. */
+export declare function expandRequestedEnumRequirements(input: ApiArgumentEnumRequirementsInput): ApiInputRequirement[];

package/dist/arguments/enum/expand-requested-enum-requirements.js

@@ -0,0 +1,45 @@
+import { createHash } from 'node:crypto';
+import { requestBindingSchemas } from '../../bindings/request-binding-schema.js';
+import { unionBindingSchemas } from '../../bindings/combine-binding-schemas.js';
+import { hasPointer } from '../../bindings/json-pointer.js';
+/** Missing containers need no fabricated value to expose their explicitly requested OAS descendants. */
+export function expandRequestedEnumRequirements(input) {
+    const requirements = structuredClone(input.requirements);
+    const owned = [
+        ...input.bindings.map((binding) => binding.targetPointer),
+        ...(input.confirmedInputs === undefined
+            ? []
+            : input.confirmedInputs.map((value) => value.targetPointer)),
+    ];
+    for (const parent of input.requirements) {
+        if (parent.requestedInputs === undefined)
+            continue;
+        for (const targetPointer of parent.requestedInputs) {
+            if (requirements.some((item) => item.targetPointer === targetPointer) ||
+                hasPointer(input.values, targetPointer) ||
+                owned.some((pointer) => overlaps(pointer, targetPointer)))
+                continue;
+            const schemas = requestBindingSchemas(input, targetPointer);
+            if (!schemas.length)
+                throw new Error(`Requested enum input ${targetPointer} has no original OAS contract`);
+            const schema = unionBindingSchemas(schemas);
+            requirements.push({
+                ...parent,
+                kind: 'requested-input',
+                id: createHash('sha256')
+                    .update(JSON.stringify([parent.id, targetPointer, schema]))
+                    .digest('hex'),
+                targetPointer,
+                schema,
+                requestedInputs: [targetPointer],
+                message: `Provide scenario-requested value ${targetPointer} for ${input.operation.method} ${input.operation.path}.`,
+            });
+        }
+    }
+    return requirements;
+}
+function overlaps(left, right) {
+    return (left === right ||
+        left.startsWith(right + '/') ||
+        right.startsWith(left + '/'));
+}

package/dist/arguments/enum/list-api-input-enum-candidates.d.ts

@@ -0,0 +1,3 @@
+import type { ApiInputEnumCandidatesInput, ApiInputEnumCandidate } from '../../types/api-input-enum.js';
+/** Enumerate declared values only. A source resource retains references and all sibling assertions. */
+export declare function listApiInputEnumCandidates(input: ApiInputEnumCandidatesInput): ApiInputEnumCandidate[];

package/dist/arguments/enum/list-api-input-enum-candidates.js

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { createOasValueValidator } from '../../openapi/common/create-oas-value-validator.js';
+/** Enumerate declared values only. A source resource retains references and all sibling assertions. */
+export function listApiInputEnumCandidates(input) {
+    const material = input.source.kind === 'operation' ? input.source : input.source.requirement;
+    const operation = input.source.kind === 'operation'
+        ? input.source.operation.key
+        : input.source.requirement.operation;
+    if (!input.schemas.length)
+        throw new Error(`API enum ${material.callId}${material.targetPointer} has no original OAS target schema`);
+    const schema = input.schemas.length === 1 ? input.schemas[0] : { anyOf: input.schemas };
+    const validator = createOasValueValidator(input.resources.bundle(schema), 'draft-2020-12', `API enum ${material.callId}${material.targetPointer}`);
+    const identity = input.source.kind === 'operation'
+        ? JSON.stringify([
+            input.source.callId,
+            input.source.operation,
+            input.source.requestMediaType,
+            input.source.targetPointer,
+        ])
+        : JSON.stringify(['requirement', input.source.requirement]);
+    const candidates = [];
+    const active = new Set();
+    function visit(current, pointer) {
+        if (typeof current === 'boolean' || active.has(current))
+            return;
+        active.add(current);
+        try {
+            if (Array.isArray(current.enum))
+                current.enum.forEach((value, index) => {
+                    if (!validator.validate(value).valid)
+                        return;
+                    const schemaPointer = `${pointer}/enum/${index}`;
+                    candidates.push({
+                        id: createHash('sha256')
+                            .update(identity)
+                            .update(JSON.stringify([schemaPointer, value]))
+                            .digest('hex'),
+                        callId: material.callId,
+                        operation: structuredClone(operation),
+                        targetPointer: material.targetPointer,
+                        schemaPointer,
+                        value: structuredClone(value),
+                    });
+                });
+            if (typeof current.$ref === 'string') {
+                const resolved = input.resources.resolve(current);
+                if (typeof resolved !== 'boolean') {
+                    const reference = input.resources.reference(resolved);
+                    if (typeof reference === 'boolean' ||
+                        typeof reference.$ref !== 'string')
+                        throw new Error(`API enum ${material.callId}${material.targetPointer} has no original schema reference`);
+                    visit(resolved, decodeURIComponent(new URL(reference.$ref).hash.slice(1)));
+                }
+            }
+            for (const key of ['allOf', 'anyOf', 'oneOf']) {
+                const children = current[key];
+                if (Array.isArray(children))
+                    children.forEach((child, index) => {
+                        if (typeof child === 'boolean' ||
+                            (child !== null &&
+                                typeof child === 'object' &&
+                                !Array.isArray(child)))
+                            visit(child, `${pointer}/${key}/${index}`);
+                    });
+            }
+        }
+        finally {
+            active.delete(current);
+        }
+    }
+    input.schemas.forEach((item, index) => visit(item, `/${index}`));
+    return candidates.filter((candidate, index) => candidates.findIndex((item) => item.id === candidate.id) === index);
+}

package/dist/arguments/enum/resolve-api-argument-enum-interpretation.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveApiArgumentEnumInterpretationInput, ApiArgumentEnumResolution } from '../../types/api-argument-enum.js';
+/** Replay copied OAS values against independently supplied input; keep semantic evidence separate. */
+export declare function resolveApiArgumentEnumInterpretation(input: ResolveApiArgumentEnumInterpretationInput): ApiArgumentEnumResolution;

package/dist/arguments/enum/resolve-api-argument-enum-interpretation.js

@@ -0,0 +1,26 @@
+import { describeApiArgumentEnumContext } from './describe-api-argument-enum-context.js';
+import { validateApiInputAnswerAnalysis } from '../clarification/extraction/validate-api-input-answer-analysis.js';
+import { assignApiInputValue } from '../clarification/assign-api-input-value.js';
+import { inspectApiArgumentRequirements } from '../clarification/inspect-api-argument-requirements.js';
+import { applyConfirmedApiInputs } from '../clarification/apply-confirmed-api-inputs.js';
+/** Replay copied OAS values against independently supplied input; keep semantic evidence separate. */
+export function resolveApiArgumentEnumInterpretation(input) {
+    const context = describeApiArgumentEnumContext(input);
+    validateApiInputAnswerAnalysis({ ...context, analysis: input.analysis });
+    const values = applyConfirmedApiInputs({
+        ...input,
+        values: input.proposal.values,
+    });
+    for (const answer of input.analysis.answers) {
+        const requirement = context.requirements.find((item) => item.id === answer.requirementId);
+        if (!requirement)
+            throw new Error(`API enum answer ${answer.requirementId} has no current OAS requirement`);
+        assignApiInputValue(values, requirement.targetPointer, structuredClone(answer.value), input);
+    }
+    const inspected = inspectApiArgumentRequirements({ ...input, values });
+    return {
+        values,
+        unresolvedInputs: inspected.requirements.map((item) => item.targetPointer),
+        interpretation: structuredClone({ ...context, analysis: input.analysis }),
+    };
+}

package/dist/arguments/sources/resolve-api-literal-proposal-sources.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveApiLiteralProposalSourcesInput, VerifiedApiLiteralProposalSource } from '../../types/api-input-literal-source.js';
+/** The same source/coverage checks serve independent generation and draft editing. */
+export declare function resolveApiLiteralProposalSources(input: ResolveApiLiteralProposalSourcesInput): VerifiedApiLiteralProposalSource[];

package/dist/arguments/sources/resolve-api-literal-proposal-sources.js

@@ -0,0 +1,58 @@
+import { pointerTokens, pointerValue } from '../../bindings/json-pointer.js';
+import { verifyApiInputLiteralSource } from './verify-api-input-literal-source.js';
+/** The same source/coverage checks serve independent generation and draft editing. */
+export function resolveApiLiteralProposalSources(input) {
+    if (!input.callId?.trim() ||
+        !Array.isArray(input.sources) ||
+        !Array.isArray(input.messages))
+        throw new Error('Literal sources require callId, sources and original messages');
+    const sources = [];
+    for (const selection of input.sources) {
+        pointerTokens(selection.targetPointer);
+        const label = `API ${input.callId} literal ${selection.targetPointer}`;
+        if (sources.some((source) => overlaps(source.targetPointer, selection.targetPointer)))
+            throw new Error(`${label} has duplicate or overlapping literalSources`);
+        const message = input.messages.find((entry) => entry.id === selection.messageId);
+        if (!message)
+            throw new Error(`${label} cites unavailable user message ${selection.messageId}`);
+        const proposed = pointerValue(input.values, selection.targetPointer);
+        if (proposed === undefined)
+            throw new Error(`${label} source targets an absent proposed value`);
+        const parsed = verifyApiInputLiteralSource({
+            ...selection,
+            text: message.text,
+            label,
+            value: proposed,
+        });
+        sources.push({ ...selection, occurrences: parsed.occurrences });
+    }
+    function check(value, pointer) {
+        if (sources.some((source) => isAncestor(source.targetPointer, pointer)))
+            return;
+        if (value !== null &&
+            typeof value === 'object' &&
+            Object.keys(value).length) {
+            for (const [key, child] of Object.entries(value))
+                check(child, `${pointer}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`);
+            return;
+        }
+        throw new Error(`API ${input.callId} literal ${pointer} requires an exact user source in literalSources`);
+    }
+    for (const [root, value] of Object.entries(input.values)) {
+        if (root !== 'body' &&
+            value !== null &&
+            typeof value === 'object' &&
+            !Object.keys(value).length)
+            continue;
+        check(value, `/${root}`);
+    }
+    return sources;
+}
+function isAncestor(ancestor, pointer) {
+    return (ancestor === '' ||
+        pointer === ancestor ||
+        pointer.startsWith(`${ancestor}/`));
+}
+function overlaps(left, right) {
+    return isAncestor(left, right) || isAncestor(right, left);
+}

package/dist/draft/edits/api/describe-workflow-draft-api-enum-choices.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftApiEnumChoicesInput, WorkflowDraftApiEnumChoicesDescription } from '../../../types/workflow-draft-api-enum-selection.js';
+/** Only unresolved original-OAS inputs. Defaults/examples never become choices. */
+export declare function describeWorkflowDraftApiEnumChoices(input: WorkflowDraftApiEnumChoicesInput): WorkflowDraftApiEnumChoicesDescription;

package/dist/draft/edits/api/describe-workflow-draft-api-enum-choices.js

@@ -0,0 +1,70 @@
+import { resolveApiCallArgumentsContext } from './resolve-api-call-arguments-context.js';
+import { applyConfirmedApiInputs } from '../../../arguments/clarification/apply-confirmed-api-inputs.js';
+import { inspectApiArgumentRequirements } from '../../../arguments/clarification/inspect-api-argument-requirements.js';
+import { schemasAtPointer } from '../../../bindings/schema-at-pointer.js';
+import { hasPointer } from '../../../bindings/json-pointer.js';
+import { createSchemaResourceContext } from '../../../bindings/resources/create-schema-resource-context.js';
+import { listApiInputEnumCandidates } from '../../../arguments/enum/list-api-input-enum-candidates.js';
+/** Only unresolved original-OAS inputs. Defaults/examples never become choices. */
+export function describeWorkflowDraftApiEnumChoices(input) {
+    const { description, contract } = resolveApiCallArgumentsContext(input);
+    const values = applyConfirmedApiInputs({
+        callId: description.nodeId,
+        operation: description.operation,
+        requestMediaType: description.requestMediaType,
+        bindings: input.bindingPlan.bindings,
+        confirmedInputs: input.confirmedInputs,
+        values: contract.valuesSchema.parse(input.proposal.values),
+    });
+    const inspected = inspectApiArgumentRequirements({
+        callId: description.nodeId,
+        operation: description.operation,
+        requestMediaType: description.requestMediaType,
+        bindings: input.bindingPlan.bindings,
+        values,
+        requestedInputs: input.proposal.requestedInputs,
+    });
+    const targets = new Set(inspected.requirements.flatMap((requirement) => [
+        requirement.targetPointer,
+        ...(requirement.requestedInputs ?? []),
+    ]));
+    const candidates = [];
+    const choiceTargets = [];
+    const resources = createSchemaResourceContext(description.requestSchema);
+    for (const targetPointer of targets) {
+        if (hasPointer(values, targetPointer) ||
+            input.bindingPlan.bindings.some((binding) => overlaps(binding.targetPointer, targetPointer)) ||
+            (input.confirmedInputs ?? []).some((item) => overlaps(item.targetPointer, targetPointer)))
+            continue;
+        const schemas = schemasAtPointer(resources.root, targetPointer, resources);
+        const selected = listApiInputEnumCandidates({
+            source: {
+                kind: 'operation',
+                callId: description.nodeId,
+                operation: description.operation,
+                requestMediaType: description.requestMediaType,
+                targetPointer,
+            },
+            schemas,
+            resources,
+        });
+        if (selected.length) {
+            candidates.push(...selected);
+            const requirement = inspected.requirements.find((item) => item.targetPointer === targetPointer ||
+                item.requestedInputs?.includes(targetPointer));
+            choiceTargets.push({
+                targetPointer,
+                schema: resources.bundle(schemas.length === 1 ? schemas[0] : { anyOf: schemas }),
+                ...(requirement?.parameterDescription === undefined
+                    ? {}
+                    : { description: requirement.parameterDescription }),
+            });
+        }
+    }
+    return { candidates, targets: choiceTargets };
+}
+function overlaps(left, right) {
+    return (left === right ||
+        left.startsWith(right + '/') ||
+        right.startsWith(left + '/'));
+}