/**
 * JSDoc rendering for JSON Schema.
 *
 * Pure schema-to-string primitives used to describe tools to an LLM.
 * Input is a JSON Schema node (however produced — Zod, hand-written, etc.);
 * output is either a compact inline TS-like type string or a set of
 * JSDoc `@param` / `@returns` lines with dotted-path expansion for nested
 * objects that carry per-field descriptions.
 *
 * This module knows nothing about tool metadata, AsyncFunction, or the
 * rest of the library — it is a renderer, nothing more.
 */
export type Schema = Record<string, unknown>;
export type JsDocTag = 'param' | 'returns' | 'property';
/**
 * Pull a human-readable description from a JSON Schema node.
 *
 * Falls back to the non-null variant of an `anyOf`/`oneOf` union, so
 * `z.x().describe(...).nullable()` — which Zod emits as
 * `{anyOf: [{…, description}, {type: 'null'}]}` — still surfaces its
 * description.
 */
export declare function getInlineDescription(schema: Schema): string | undefined;
/**
 * Convert a JSON Schema to a compact TS-like type string.
 * e.g. `{type: "object", properties: {name: {type: "string"}, id: {type: "number"}}}`
 *   → `"{ name: string, id: number }"`
 *
 * Unions (`anyOf`/`oneOf`) render as `A | B`. Per-field descriptions are NOT
 * emitted here — JSDoc's inline type grammar has no slot for them. Nested
 * field descriptions are surfaced separately via `expandDottedLines`.
 */
export declare function jsonSchemaToTypeString(schema: Schema): string;
/**
 * Render a `@param` tag as a header line plus any dotted expansion lines.
 *
 * Header:   ` * @param {Type} name - desc`  (or `[name]` when optional)
 * Expanded: ` * @param {Type} name.field - desc` for each nested property.
 *
 * When `refs` is provided and the schema (possibly wrapped in array/nullable)
 * matches a registered typedef, the header collapses to `{TypedefName}` and
 * no dotted expansion is emitted.
 */
export declare function renderParam(name: string, schema: Schema, optional: boolean, refs?: Map<string, string>): string[];
/**
 * Render a `@returns` tag. Unlike `@param`, the header carries no label —
 * JSDoc convention is `@returns {Type} description`. Expansion still uses
 * a synthetic `returns` prefix so sub-fields are addressable.
 *
 * `schema` may be undefined when the caller has a description but no schema;
 * in that case the returned line is just `@returns DESC`.
 *
 * When `refs` contains the schema, the tag collapses to `{TypedefName}` and
 * no dotted expansion is emitted. In practice `collectTypedefs` always
 * promotes object return schemas so this is the expected path for objects.
 */
export declare function renderReturns(schema: Schema | undefined, desc: string, refs?: Map<string, string>): string[];
export interface Typedef {
    name: string;
    schema: Schema;
}
export interface TypedefSource {
    /** Top-level schemas for each named parameter. */
    paramSchemas: Schema[];
    /** Return schema, if any. */
    returnSchema?: Schema;
}
export interface TypedefContext {
    typedefs: Typedef[];
    /** structural hash → typedef name */
    refs: Map<string, string>;
}
/**
 * Collect object shapes worth promoting to `@typedef` blocks.
 *
 * Promotion rule: a shape is promoted when ANY of:
 *   1. It appears structurally ≥2 times across the tool set (dedup win).
 *   2. It is (reachable from) a return schema (dotted `@returns.field` is
 *      non-standard JSDoc, whereas typedefs are).
 *   3. Its dotted expansion would produce ≥ SINGLE_USE_PROMOTE_THRESHOLD
 *      lines — at which point the typedef form is shorter than repeating
 *      the `prefix.` on every line.
 *
 * Returns the typedef list (in first-encounter order) and a hash→name lookup
 * map for use during rendering.
 */
export declare function collectTypedefs(sources: TypedefSource[]): TypedefContext;
/**
 * Render a `@typedef {Object} name` block with one `@property` line per field.
 *
 * Fields whose schema matches another typedef collapse to `{RefName}`; other
 * nested object fields still dot-expand (`field.subfield`), which is canonical
 * JSDoc for nested properties inside a typedef.
 */
export declare function renderTypedef(name: string, schema: Schema, refs?: Map<string, string>): string[];
//# sourceMappingURL=jsdoc.d.ts.map