/**
 * @license
 * Copyright (c) 2025 Handsoncode. All rights reserved.
 */
/**
 * Builders for the objects the metadata API returns: [[FunctionListEntry]] from `getAvailableFunctions` and
 * [[FunctionDetails]] from `getFunctionDetails`.
 *
 * No single place holds those objects ready to be returned, which is what these builders are for. The catalogue
 * ([[FUNCTION_DOCS]]) stores only the authored English prose — category, description, parameter names and
 * descriptions, documentation link, examples — and knows nothing about the language a caller asks for, about how
 * many arguments the plugin actually implements, or about functions with no entry at all. So each returned object
 * is assembled from three sources:
 *
 * - the **catalogue entry** ([[FunctionDoc]]), for everything an author wrote;
 * - the **implementation** (`implementedFunctions`), for the argument count, per-argument optionality and
 *   `repeatLastArgs` — the implementation is the authority where the two disagree;
 * - the **active translation package**, for the localized name.
 *
 * The custom-function builders cover the third case: a user-registered function has no catalogue entry, so it is
 * described from its implementation alone, and every authored field is omitted rather than filled with a
 * placeholder.
 */
import { FunctionMetadata, FunctionArgument } from '../plugin/FunctionPlugin';
import { FunctionDoc, FunctionListEntry, FunctionDetails } from './FunctionDescription';
/** Resolves a function's display name: the translation for the active language, or the canonical id as fallback. */
declare type TranslateName = (canonicalName: string) => string | undefined;
/** The structural subset of `FunctionMetadata` the builders read (so callers/tests need not supply `method`). */
export declare type StructuralMetadata = Pick<FunctionMetadata, 'parameters' | 'repeatLastArgs'>;
/**
 * Returns whether a parameter may be omitted: it declares `optionalArg`, or it has a `defaultValue`.
 *
 * @param {FunctionArgument | undefined} arg - the structural argument metadata, or `undefined`
 */
export declare function isParameterOptional(arg: FunctionArgument | undefined): boolean;
/**
 * Normalizes a declared `repeatLastArgs` into the value the public [[FunctionDetails.repeatLastArgs]] may carry: a
 * non-negative integer no larger than the number of parameters. Shared by both details builders, so the built-in and
 * the custom path can never report the field under different rules.
 *
 * The two rules have different provenance: the first mirrors the evaluator, the second normalizes a declaration the
 * evaluator cannot honour sensibly.
 * - Only a positive integer means anything. `FunctionPlugin.buildMetadataForEachArgumentValue` gates the repeat on
 *   `Number.isInteger(repeatLastArgs) && repeatLastArgs > 0`, so for `undefined`, `0`, a negative, a fraction, `NaN`
 *   or `Infinity` the evaluator repeats nothing and the function has a fixed arity. Reporting `0` for all of those
 *   describes what actually runs instead of echoing a value the interpreter ignores. (`Math.min` alone would not do:
 *   `Math.min(NaN, 2)` is `NaN` and `Math.min(-1, 2)` is `-1`.)
 * - A valid count is clamped to the parameter count. This is a repair of a malformed declaration for reporting
 *   purposes, not a claim about how the evaluator treats it: a count above the parameter count makes
 *   `buildMetadataForEachArgumentValue`'s `slice(length - repeatLastArgs)` index negative, so the parameter list
 *   doubles on every pass and the function ends up accepting an erratic set of arities that no `repeatLastArgs`
 *   value describes. Since the field cannot be reported faithfully at all in that case, it carries the largest
 *   meaningful count rather than rendering "the last N of M parameters repeat" with N > M.
 *
 * @param {number | undefined} repeatLastArgs - the value declared in `implementedFunctions`, if any
 * @param {number} parameterCount - the number of parameters the function declares
 */
export declare function clampRepeatLastArgs(repeatLastArgs: number | undefined, parameterCount: number): number;
/**
 * Builds a Tier-1 list entry by joining the catalogue doc with the translation on the canonical id.
 *
 * @param {string} canonicalName - the language-independent function id
 * @param {FunctionDoc} doc - the function's authored catalogue entry
 * @param {TranslateName} translate - per-id translation lookup
 * @param {string | undefined} aliasOf - the alias target's id when `canonicalName` is an alias, else `undefined`
 */
export declare function buildFunctionListEntry(canonicalName: string, doc: FunctionDoc, translate: TranslateName, aliasOf?: string): FunctionListEntry;
/**
 * Builds a Tier-2 details object: the list fields plus the parameter list (name, description, optionality) and
 * `repeatLastArgs` (how many trailing parameters repeat, normalized by [[clampRepeatLastArgs]]). The caller renders
 * the syntax string from these.
 * `documentationUrl` and `examples` come from the catalogue doc, which authors both for every entry, as it does the
 * parameter descriptions. A custom function has none of them; see [[buildCustomFunctionDetails]].
 *
 * The parameter list always has one entry per implemented argument, so it describes what the evaluator actually
 * accepts even when the catalogue entry has drifted out of step with the signature; see
 * [[buildDocumentedParameters]] for what such an entry still contributes.
 *
 * @param {string} canonicalName - the language-independent function id
 * @param {FunctionDoc} doc - the function's authored catalogue entry
 * @param {StructuralMetadata} metadata - structural metadata from `implementedFunctions`
 * @param {TranslateName} translate - per-id translation lookup
 * @param {string | undefined} aliasOf - the alias target's id when `canonicalName` is an alias, else `undefined`
 */
export declare function buildFunctionDetails(canonicalName: string, doc: FunctionDoc, metadata: StructuralMetadata, translate: TranslateName, aliasOf?: string): FunctionDetails;
/**
 * Builds a Tier-1 list entry for a custom (user-registered) function, which ships no catalogue doc. The name is the
 * only authored information: `category` is reported as `'Custom'` and there is no `shortDescription`.
 *
 * @param {string} canonicalName - the language-independent function id
 * @param {TranslateName} translate - per-id translation lookup
 * @param {string | undefined} aliasOf - the alias target's id when `canonicalName` is an alias, else `undefined`
 */
export declare function buildCustomFunctionListEntry(canonicalName: string, translate: TranslateName, aliasOf?: string): FunctionListEntry;
/**
 * Builds Tier-2 details for a custom (user-registered) function from its structural metadata alone (no catalogue
 * doc): the `'Custom'` category, positional parameter names (`Arg1`, `Arg2`, ...), per-parameter optionality, and
 * `repeatLastArgs` (normalized by [[clampRepeatLastArgs]], exactly as on the built-in path). The authored fields —
 * `shortDescription`, `documentationUrl` and `examples` — have no source here, so they are omitted.
 *
 * @param {string} canonicalName - the language-independent function id
 * @param {StructuralMetadata} metadata - structural metadata from `implementedFunctions`
 * @param {TranslateName} translate - per-id translation lookup
 * @param {string | undefined} aliasOf - the alias target's id when `canonicalName` is an alias, else `undefined`
 */
export declare function buildCustomFunctionDetails(canonicalName: string, metadata: StructuralMetadata, translate: TranslateName, aliasOf?: string): FunctionDetails;
export {};