@twin.org/tools-core 0.0.3-next.2 → 0.0.3-next.21

package/dist/types/utils/jsonSchemaBuilder.d.ts

@@ -0,0 +1,747 @@
+import { type IJsonSchema } from "@twin.org/tools-models";
+import * as ts from "typescript";
+import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaContext.js";
+/**
+ * Builder for composing JSON schema fragments from TypeScript AST nodes.
+ */
+export declare class JsonSchemaBuilder {
+    /**
+     * The JSON Schema version used.
+     */
+    static readonly SCHEMA_VERSION = "https://json-schema.org/draft/2020-12/schema";
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Dictionary of TypeScript utility type names to their schema mapping handlers.
+     */
+    private static readonly _utilityTypeHandlers;
+    /**
+     * Parse all object declarations from a source file.
+     * @param context The generation context.
+     * @param sourceFilePath The source file path.
+     * @param source The TypeScript source.
+     * @param visitedFiles The list of visited source files.
+     * @returns The generated schema titles.
+     */
+    static parseAllObjectSchemas(context: ITypeScriptToSchemaContext, sourceFilePath: string, source: string, visitedFiles: string[]): string[];
+    /**
+     * Apply @json-schema tags from JSDoc to a schema object.
+     * @param schema The schema to expand.
+     * @param node The node to inspect for tags.
+     * @throws GeneralError Thrown when a tag key is not supported by IJsonSchema.
+     */
+    static applyJsonSchemaTags(schema: Partial<IJsonSchema>, node: ts.Node): void;
+    /**
+     * Validate that a @json-schema constraint key is compatible with the given schema type,
+     * and that the raw value is valid for the constraint.
+     * @param schemaKey The mapped schema key being applied.
+     * @param schemaType The type already set on the schema, if any.
+     * @param rawValue The raw string value from the JSDoc tag.
+     * @throws GeneralError Thrown when the constraint is not valid for the schema type.
+     * @throws GeneralError Thrown when the format value is not a recognised JSON Schema format.
+     */
+    static validateJsonSchemaTagConstraint(schemaKey: string, schemaType: string | string[] | undefined, rawValue: string): void;
+    /**
+     * Determine whether a mapped @json-schema tag key is supported.
+     * @param key The mapped schema key.
+     * @returns True if the key is supported.
+     */
+    static isAllowedJsonSchemaTagKey(key: string): boolean;
+    /**
+     * Build the base schema with common properties.
+     * @param namespace The namespace for generated schema id.
+     * @param title The schema title.
+     * @param statement The type statement node.
+     * @returns The base schema to be expanded.
+     */
+    static buildBaseSchema(namespace: string, title: string, statement: ts.Node): Partial<IJsonSchema>;
+    /**
+     * Add enum information to a schema.
+     * @param schema The schema to expand.
+     * @param entries The enum entries.
+     */
+    static buildEnumSchema(schema: Partial<IJsonSchema>, entries: {
+        value: string | number;
+        description?: string;
+    }[]): void;
+    /**
+     * Build an object schema from interface or type literal members.
+     * @param context The generation context.
+     * @param schema The schema to expand.
+     * @param members The members to process.
+     */
+    static buildObjectSchema(context: ITypeScriptToSchemaContext, schema: Partial<IJsonSchema>, members: ts.NodeArray<ts.TypeElement>): void;
+    /**
+     * Build property schemas and required list from type members.
+     * @param context The generation context.
+     * @param members The members to process.
+     * @returns The object property schema map and required list.
+     */
+    static buildObjectMembersSchema(context: ITypeScriptToSchemaContext, members: ts.NodeArray<ts.TypeElement>): {
+        properties: {
+            [key: string]: IJsonSchema;
+        };
+        required: string[];
+        patternProperties?: {
+            [pattern: string]: IJsonSchema;
+        };
+        additionalProperties?: IJsonSchema;
+        propertyNames?: IJsonSchema;
+    };
+    /**
+     * Build an object schema from a type literal node.
+     * @param context The generation context.
+     * @param typeNode The type literal node.
+     * @returns The object schema.
+     */
+    static buildTypeLiteralSchema(context: ITypeScriptToSchemaContext, typeNode: ts.TypeLiteralNode): IJsonSchema;
+    /**
+     * Merge pattern property schemas by pattern, deduplicating equivalent branches.
+     * @param patternPropertySchemas Pattern and schema entries to merge.
+     * @returns Merged patternProperties map.
+     */
+    static mergePatternPropertySchemas(patternPropertySchemas: {
+        pattern: string;
+        schema: IJsonSchema;
+    }[]): {
+        [pattern: string]: IJsonSchema;
+    } | undefined;
+    /**
+     * Map a property type node to schema.
+     * @param context The generation context.
+     * @param typeNode The member type node.
+     * @returns The mapped member schema.
+     */
+    static mapMemberTypeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode): IJsonSchema | undefined;
+    /**
+     * Map TypeScript type nodes to JSON schema.
+     * @param context The generation context.
+     * @param typeNode The node to process.
+     * @returns The mapped schema.
+     */
+    static mapTypeNodeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode): IJsonSchema | undefined;
+    /**
+     * Determine whether a union of primitive keyword branches is pairwise disjoint.
+     * @param unionTypeNode The union node being mapped.
+     * @param unionTypeNodes The original union branch type nodes.
+     * @param unionSchemas The mapped union branch schemas.
+     * @returns True if every branch is a primitive keyword schema and no branches overlap.
+     */
+    static isDisjointPrimitiveKeywordUnion(unionTypeNode: ts.UnionTypeNode, unionTypeNodes: ts.NodeArray<ts.TypeNode>, unionSchemas: IJsonSchema[]): boolean;
+    /**
+     * Determine whether a union of schemas represents mutually exclusive object branches.
+     * @param context The generation context.
+     * @param unionTypeNodes The union branch type nodes for cross-checking with the mapped schemas.
+     * @param unionSchemas The mapped union branch schemas.
+     * @returns True if each branch is an object schema with a unique required key set.
+     */
+    static isNeverDiscriminatedObjectUnion(context: ITypeScriptToSchemaContext, unionTypeNodes: ts.NodeArray<ts.TypeNode>, unionSchemas: IJsonSchema[]): boolean;
+    /**
+     * Determine whether object union branches are discriminated by a shared required literal tag.
+     * @param context The generation context.
+     * @param unionSchemas The mapped union branch schemas.
+     * @returns True if the union can be safely represented as oneOf.
+     */
+    static isLiteralTagDiscriminatedObjectUnion(context: ITypeScriptToSchemaContext, unionSchemas: IJsonSchema[]): boolean;
+    /**
+     * Resolve branch members that can encode never-based discriminators.
+     * @param context The generation context.
+     * @param unionTypeNode The union branch type node.
+     * @returns Type members for the branch when resolvable.
+     */
+    static resolveNeverDiscriminatorMembers(context: ITypeScriptToSchemaContext, unionTypeNode: ts.TypeNode): ts.NodeArray<ts.TypeElement> | undefined;
+    /**
+     * Resolve a local $ref schema to its stored schema definition.
+     * @param context The generation context.
+     * @param schema The schema that may contain a local reference.
+     * @returns The resolved schema when available.
+     */
+    static resolveLocalSchemaReference(context: ITypeScriptToSchemaContext, schema: IJsonSchema): IJsonSchema | undefined;
+    /**
+     * Resolve a property value from a const object declaration in an imported source file.
+     * @param context The generation context.
+     * @param objectName The name of the const object.
+     * @param propertyName The name of the property to resolve.
+     * @returns The resolved string or number value, or undefined if unresolvable.
+     */
+    static resolveConstObjectProperty(context: ITypeScriptToSchemaContext, objectName: string, propertyName: string): string | number | undefined;
+    /**
+     * Find a variable declaration by traversing import and export chains.
+     * @param sourceFilePath The source file path to start from.
+     * @param variableName The variable declaration name to find.
+     * @param visitedFiles The file set already visited.
+     * @returns The variable declaration when found.
+     */
+    static findVariableDeclarationInModuleGraph(sourceFilePath: string, variableName: string, visitedFiles: Set<string>): ts.VariableDeclaration | undefined;
+    /**
+     * Find an imported symbol reference by local identifier name.
+     * @param sourceFile The source file to inspect.
+     * @param localName The local identifier name.
+     * @returns The module specifier and imported symbol name.
+     */
+    static findImportedValueReference(sourceFile: ts.SourceFile, localName: string): {
+        moduleSpecifier: string;
+        importedName: string;
+    } | undefined;
+    /**
+     * Resolve an import declaration module specifier to a source file.
+     * @param containingSourceFilePath The containing source file path.
+     * @param moduleSpecifier The module specifier text.
+     * @returns The resolved source file path.
+     */
+    static resolveImportDeclarationSourceFile(containingSourceFilePath: string, moduleSpecifier: string): string | undefined;
+    /**
+     * Extract a const-object property value from a declaration initializer.
+     * @param objectDeclaration The variable declaration.
+     * @param propertyName The property to resolve.
+     * @returns The resolved value.
+     */
+    static extractConstObjectPropertyFromDeclarationInitializer(objectDeclaration: ts.VariableDeclaration, propertyName: string): string | number | undefined;
+    /**
+     * Extract a const-object property value from a declaration type annotation.
+     * @param declarationTypeNode The declaration type annotation.
+     * @param propertyName The property to resolve.
+     * @returns The resolved value.
+     */
+    static extractConstObjectPropertyFromDeclarationType(declarationTypeNode: ts.TypeNode, propertyName: string): string | number | undefined;
+    /**
+     * Extract a literal value from a type node when possible.
+     * @param typeNode The type node.
+     * @returns The literal value.
+     */
+    static extractLiteralValueFromTypeNode(typeNode: ts.TypeNode): string | number | undefined;
+    /**
+     * Extract a referenced type name from an import type qualifier.
+     * @param qualifier The import type qualifier.
+     * @returns The resolved type name.
+     */
+    static extractImportTypeName(qualifier: ts.EntityName | undefined): string | undefined;
+    /**
+     * Resolve import-type references to local or external schema ids.
+     * @param context The generation context.
+     * @param moduleSpecifier The import module specifier.
+     * @param typeName The imported type name.
+     * @param title The derived schema title.
+     * @returns The resolved schema id.
+     */
+    static resolveImportTypeReferenceSchemaId(context: ITypeScriptToSchemaContext, moduleSpecifier: string, typeName: string, title: string): string | undefined;
+    /**
+     * Infer a primitive JSON schema from a literal expression.
+     * @param context The generation context.
+     * @param expr The expression to inspect.
+     * @param asConst Whether to produce exact const schemas matching an as-const assertion.
+     * @returns The inferred schema.
+     */
+    static inferSchemaFromExpression(context: ITypeScriptToSchemaContext, expr: ts.Expression, asConst?: boolean): IJsonSchema;
+    /**
+     * Infer an object schema from an object literal expression, using const or widened types.
+     * @param context The generation context.
+     * @param expr The object literal expression.
+     * @param asConst Whether property value schemas should be exact const types.
+     * @returns The inferred object schema.
+     */
+    static inferObjectLiteralSchema(context: ITypeScriptToSchemaContext, expr: ts.ObjectLiteralExpression, asConst: boolean): IJsonSchema;
+    /**
+     * Infer an array schema from an array literal expression.
+     * For as-const arrays a fixed-length tuple schema is produced; otherwise a plain array schema.
+     * @param context The generation context.
+     * @param expr The array literal expression.
+     * @param asConst Whether to produce a const-exact tuple schema.
+     * @returns The inferred array schema.
+     */
+    static inferArrayLiteralSchema(context: ITypeScriptToSchemaContext, expr: ts.ArrayLiteralExpression, asConst: boolean): IJsonSchema;
+    /**
+     * Map conditional type nodes (e.g. T extends U ? X : Y) to schema.
+     * @param context The generation context.
+     * @param typeNode The conditional type node.
+     * @returns The mapped schema.
+     */
+    static mapConditionalTypeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.ConditionalTypeNode): IJsonSchema | undefined;
+    /**
+     * Map indexed access type nodes (e.g. T["id"]) to schema.
+     * @param context The generation context.
+     * @param typeNode The indexed access type node.
+     * @returns The mapped schema.
+     */
+    static mapIndexedAccessTypeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.IndexedAccessTypeNode): IJsonSchema | undefined;
+    /**
+     * Map template literal type nodes to string schemas.
+     * @param context The generation context.
+     * @param typeNode The template literal type node.
+     * @returns The mapped schema.
+     */
+    static mapTemplateLiteralTypeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.TemplateLiteralTypeNode): IJsonSchema;
+    /**
+     * Map mapped type nodes to object schemas.
+     * @param context The generation context.
+     * @param typeNode The mapped type node.
+     * @returns The mapped schema.
+     */
+    static mapMappedTypeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.MappedTypeNode): IJsonSchema | undefined;
+    /**
+     * Determine whether a mapped type value uses indexed access with the mapped key parameter.
+     * @param typeNode The mapped type node.
+     * @param mappedTypeParameterName The mapped type parameter name.
+     * @returns True if the value shape is based on source indexed access.
+     */
+    static isMappedTypeIndexedValueByTypeParameter(typeNode: ts.MappedTypeNode, mappedTypeParameterName: string): boolean;
+    /**
+     * Check whether a type node is allowed for schema generation.
+     * @param context The generation context.
+     * @param typeNode The type node to inspect.
+     * @param propertyName The optional property name when the type is a property type.
+     * @param enclosingObjectName The optional enclosing object name when the type is a property type.
+     * @returns True when the type is allowed.
+     */
+    static checkTypeNodeAllowed(context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode, propertyName?: string, enclosingObjectName?: string): boolean;
+    /**
+     * Determine whether a property type should be treated as a function and skipped.
+     * @param typeNode The property type node.
+     * @returns True if the property type is function-like.
+     */
+    static isFunctionPropertyType(typeNode: ts.TypeNode): boolean;
+    /**
+     * Determine whether a type node represents symbol or unique symbol.
+     * @param typeNode The type node to inspect.
+     * @returns True when the type is symbol or unique symbol.
+     */
+    static isSymbolTypeNode(typeNode: ts.TypeNode): boolean;
+    /**
+     * Determine whether a computed property expression references a symbol.
+     * Covers well-known symbols (Symbol.iterator, etc.) and const variables
+     * declared with a unique symbol type annotation.
+     * @param context The generation context.
+     * @param expression The computed property expression.
+     * @returns True when the key is symbol-based.
+     */
+    static isSymbolKeyedComputedExpression(context: ITypeScriptToSchemaContext, expression: ts.Expression): boolean;
+    /**
+     * Extract a property name from TypeScript property syntax.
+     * Computed names are resolved when they evaluate to concrete literals.
+     * @param context The generation context.
+     * @param propertyName The property name node.
+     * @returns The normalized property name.
+     */
+    static extractPropertyName(context: ITypeScriptToSchemaContext, propertyName: ts.PropertyName): string | undefined;
+    /**
+     * Find a variable declaration by name in a source file.
+     * @param sourceFile The source file to search.
+     * @param variableName The variable name.
+     * @returns The declaration if found.
+     */
+    static findVariableDeclaration(sourceFile: ts.SourceFile | undefined, variableName: string): ts.VariableDeclaration | undefined;
+    /**
+     * Resolve a schema for an imported identifier used in a type query.
+     * @param context The generation context.
+     * @param localName The local imported symbol name.
+     * @returns The mapped schema if resolvable.
+     */
+    static resolveImportedTypeQuerySchema(context: ITypeScriptToSchemaContext, localName: string): IJsonSchema | undefined;
+    /**
+     * Resolve computed property name expressions when they can be evaluated to concrete keys.
+     * @param context The generation context.
+     * @param expression The computed property expression.
+     * @param resolvingIdentifiers Identifier names currently being resolved.
+     * @returns The resolved property key.
+     */
+    static resolveComputedPropertyNameExpression(context: ITypeScriptToSchemaContext, expression: ts.Expression, resolvingIdentifiers: Set<string>): string | undefined;
+    /**
+     * Find a local const variable declaration in the active source file.
+     * @param context The generation context.
+     * @param variableName The variable name.
+     * @returns The declaration when found.
+     */
+    static findConstVariableDeclaration(context: ITypeScriptToSchemaContext, variableName: string): ts.VariableDeclaration | undefined;
+    /**
+     * Resolve a property value from a local const object declaration.
+     * @param context The generation context.
+     * @param objectName The const object name.
+     * @param propertyName The property to resolve.
+     * @returns The resolved value when available.
+     */
+    static resolveLocalConstObjectProperty(context: ITypeScriptToSchemaContext, objectName: string, propertyName: string): string | number | undefined;
+    /**
+     * Map a tuple type node to schema.
+     * @param context The generation context.
+     * @param tupleTypeNode The tuple type node.
+     * @returns The mapped tuple schema.
+     */
+    static mapTupleTypeToSchema(context: ITypeScriptToSchemaContext, tupleTypeNode: ts.TupleTypeNode): IJsonSchema | undefined;
+    /**
+     * Extract schema for a tuple rest element.
+     * @param context The generation context.
+     * @param restElementType The rest element type.
+     * @returns The mapped rest element schema.
+     */
+    static extractRestElementSchema(context: ITypeScriptToSchemaContext, restElementType: ts.TypeNode): IJsonSchema | undefined;
+    /**
+     * Find an existing schema id by title in known package schemas.
+     * @param context The generation context.
+     * @param schemaTitle The schema title to find.
+     * @returns The existing schema id if found.
+     */
+    static findExistingSchemaIdByTitle(context: ITypeScriptToSchemaContext, schemaTitle: string): string | undefined;
+    /**
+     * Apply interface inheritance (`extends`) as `allOf` references.
+     * @param context The generation context.
+     * @param schema The schema to expand.
+     * @param declaration The interface declaration.
+     */
+    static applyInterfaceExtendsSchema(context: ITypeScriptToSchemaContext, schema: Partial<IJsonSchema>, declaration: ts.InterfaceDeclaration): void;
+    /**
+     * Map Partial<T> to an object schema with no required properties.
+     * @param context The generation context.
+     * @param typeNode The Partial type reference.
+     * @returns The mapped schema.
+     */
+    static mapPartialUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map Required<T> to an object schema with all properties required.
+     * @param context The generation context.
+     * @param typeNode The Required type reference.
+     * @returns The mapped schema.
+     */
+    static mapRequiredUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map Pick<T, K> to an object schema with selected keys preserved.
+     * @param context The generation context.
+     * @param typeNode The Pick type reference.
+     * @returns The mapped schema.
+     */
+    static mapPickUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map Omit<T, K> to an object schema with selected keys removed.
+     * @param context The generation context.
+     * @param typeNode The Omit type reference.
+     * @returns The mapped schema.
+     */
+    static mapOmitUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map Exclude<T, U> to a schema that removes U members from T.
+     * @param context The generation context.
+     * @param typeNode The Exclude type reference.
+     * @returns The mapped schema.
+     */
+    static mapExcludeUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map Extract<T, U> to a schema that keeps U members from T.
+     * @param context The generation context.
+     * @param typeNode The Extract type reference.
+     * @returns The mapped schema.
+     */
+    static mapExtractUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map NonNullable<T> by removing null and undefined branches from T.
+     * @param context The generation context.
+     * @param typeNode The NonNullable type reference.
+     * @returns The mapped schema.
+     */
+    static mapNonNullableUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map Record<K, V> to an object schema with key constraints where possible.
+     * @param context The generation context.
+     * @param typeNode The Record type reference.
+     * @returns The mapped schema.
+     */
+    static mapRecordUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Determine whether a type node represents null or undefined.
+     * @param typeNode The type node.
+     * @returns True if the node is null or undefined.
+     */
+    static isNullOrUndefinedTypeNode(typeNode: ts.TypeNode): boolean;
+    /**
+     * Extract literal keys from a Record key type argument.
+     * @param keyTypeNode The key type argument node.
+     * @returns The extracted literal keys.
+     */
+    static extractRecordLiteralKeys(keyTypeNode: ts.TypeNode): string[];
+    /**
+     * Map JsonLdObject utility types using key-removal and optional key-addition rules.
+     * @param context The generation context.
+     * @param typeNode The JsonLdObject utility type reference.
+     * @param options Mapping options.
+     * @param options.keysToRemove Keys to remove from the base schema.
+     * @param options.keyToAdd Optional key to add to the base schema.
+     * @param options.isAddedKeyRequired Whether the added key should be required.
+     * @returns The mapped schema.
+     */
+    static mapJsonLdObjectUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, options: {
+        keysToRemove: string[];
+        keyToAdd?: "id" | "@id" | "type" | "@type" | "@context";
+        isAddedKeyRequired?: boolean;
+    }): IJsonSchema | undefined;
+    /**
+     * Resolve a default schema for JsonLdObject utility key additions when the type argument is omitted.
+     * @param baseSchema The base object schema.
+     * @param keyToAdd The key being added by the utility.
+     * @returns The resolved schema.
+     */
+    static mapJsonLdObjectDefaultSchemaByKey(baseSchema: IJsonSchema, keyToAdd: "id" | "@id" | "type" | "@type" | "@context"): IJsonSchema;
+    /**
+     * Resolve default id schema for JsonLdObjectWithId when Id type argument is omitted.
+     * @param baseSchema The base object schema.
+     * @returns The resolved id schema.
+     */
+    static mapJsonLdObjectWithIdDefaultIdSchema(baseSchema: IJsonSchema): IJsonSchema;
+    /**
+     * Resolve default type schema for JsonLdObjectWithType when Type argument is omitted.
+     * @param baseSchema The base object schema.
+     * @returns The resolved type schema.
+     */
+    static mapJsonLdObjectWithTypeDefaultTypeSchema(baseSchema: IJsonSchema): IJsonSchema;
+    /**
+     * Resolve default context schema for JsonLdObjectWithContext when Context argument is omitted.
+     * @param baseSchema The base object schema.
+     * @returns The resolved context schema.
+     */
+    static mapJsonLdObjectWithContextDefaultContextSchema(baseSchema: IJsonSchema): IJsonSchema;
+    /**
+     * Resolve default schema from either of two source keys, with fallback when both are absent.
+     * @param baseSchema The base object schema.
+     * @param firstKey The primary key to resolve.
+     * @param secondKey The secondary key to resolve.
+     * @param fallbackSchema The fallback schema.
+     * @returns The resolved schema.
+     */
+    static mapJsonLdObjectDefaultEitherSchema(baseSchema: IJsonSchema, firstKey: string, secondKey: string, fallbackSchema: IJsonSchema): IJsonSchema;
+    /**
+     * Map ObjectOrArray<T> to a schema accepting T or T[].
+     * @param context The generation context.
+     * @param typeNode The ObjectOrArray type reference.
+     * @returns The mapped schema.
+     */
+    static mapObjectOrArrayUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map SingleOccurrenceArray<T, U> to a non-empty array containing exactly one U.
+     * @param context The generation context.
+     * @param typeNode The SingleOccurrenceArray type reference.
+     * @returns The mapped schema.
+     */
+    static mapSingleOccurrenceArrayUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Add a comment to schemas inlined for utility type transformations.
+     * @param schema The schema to annotate.
+     * @param baseTypeDescription The utility base type description.
+     * @returns The annotated schema.
+     */
+    static annotateUtilityInlineSchema(schema: IJsonSchema, baseTypeDescription: string): IJsonSchema;
+    /**
+     * Resolve a utility base type node to an object schema.
+     * @param context The generation context.
+     * @param baseTypeNode The utility base type node.
+     * @returns The resolved object schema.
+     * @throws GeneralError when a named type reference cannot be resolved to a schema.
+     */
+    static resolveUtilityBaseObjectSchema(context: ITypeScriptToSchemaContext, baseTypeNode: ts.TypeNode): IJsonSchema | undefined;
+    /**
+     * Resolve a mapped utility schema to an object schema when possible.
+     * @param context The generation context.
+     * @param mappedSchema The mapped schema.
+     * @returns The resolved object schema.
+     */
+    static resolveMappedUtilityBaseObjectSchema(context: ITypeScriptToSchemaContext, mappedSchema: IJsonSchema): IJsonSchema | undefined;
+    /**
+     * Expand allOf references in a schema by inlining referenced schemas.
+     * This handles inheritance cases where a type extends another type.
+     * When applying utility operations (Omit, Pick) to types with allOf inheritance,
+     * the referenced schemas must be expanded so properties are available for omit/pick.
+     * @param context The generation context.
+     * @param schema The schema potentially containing allOf with references.
+     * @param currentSchemaTitle The title of the current schema being processed, used for $comment annotations.
+     * @returns The schema with expanded references merged into properties.
+     */
+    static expandAllOfReferences(context: ITypeScriptToSchemaContext, schema: IJsonSchema, currentSchemaTitle?: string): IJsonSchema;
+    /**
+     * Attempt to load an external schema by title from imported module declarations.
+     * @param context The generation context.
+     * @param schemaTitle The schema title.
+     * @returns The loaded schema.
+     */
+    static tryLoadExternalSchemaByTitle(context: ITypeScriptToSchemaContext, schemaTitle: string): IJsonSchema | undefined;
+    /**
+     * Resolve an object schema for utility type application.
+     * @param context The generation context.
+     * @param typeName The referenced type name.
+     * @returns The resolved object schema.
+     */
+    static resolveObjectTypeSchemaForUtility(context: ITypeScriptToSchemaContext, typeName: string): IJsonSchema | undefined;
+    /**
+     * Find an imported type reference from the active source file by local or exported symbol name.
+     * @param context The generation context.
+     * @param typeName The local or exported type name to find.
+     * @returns The module specifier and exported candidate type name when found.
+     */
+    static findImportedTypeReference(context: ITypeScriptToSchemaContext, typeName: string): {
+        moduleSpecifier: string;
+        candidateTypeName: string;
+    } | undefined;
+    /**
+     * Resolve an imported object schema for utility type application.
+     * @param context The generation context.
+     * @param moduleSpecifier The module where the type is imported from.
+     * @param candidateTypeName The exported candidate type name.
+     * @param title The stripped title of the requested type.
+     * @returns The resolved object schema.
+     */
+    static resolveImportedObjectTypeSchemaForUtility(context: ITypeScriptToSchemaContext, moduleSpecifier: string, candidateTypeName: string, title: string): IJsonSchema | undefined;
+    /**
+     * Map a local interface or type alias declaration to an object schema.
+     * @param context The generation context.
+     * @param typeName The referenced type name.
+     * @returns The mapped schema.
+     */
+    static mapObjectTypeFromLocalDeclaration(context: ITypeScriptToSchemaContext, typeName: string): IJsonSchema | undefined;
+    /**
+     * Extract string literal keys from a utility type key argument (e.g. Pick or Omit).
+     * @param context The generation context.
+     * @param keysTypeNode The keys type node.
+     * @returns The extracted keys.
+     */
+    static extractUtilityTypeKeys(context: ITypeScriptToSchemaContext, keysTypeNode: ts.TypeNode | undefined): string[];
+    /**
+     * Extract property keys from an indexed access index type.
+     * @param context The generation context.
+     * @param indexTypeNode The index type node.
+     * @returns The extracted keys.
+     */
+    static extractIndexedAccessKeys(context: ITypeScriptToSchemaContext, indexTypeNode: ts.TypeNode): string[];
+    /**
+     * Extract keys for a mapped type constraint.
+     * @param context The generation context.
+     * @param constraintTypeNode The mapped type constraint.
+     * @returns The extracted keys.
+     */
+    static extractMappedTypeKeys(context: ITypeScriptToSchemaContext, constraintTypeNode: ts.TypeNode | undefined): string[];
+    /**
+     * Resolve a referenced type node from a local type alias declaration.
+     * @param context The generation context.
+     * @param typeNode The type reference node.
+     * @returns The referenced type node, if found locally.
+     */
+    static resolveReferencedTypeNodeFromLocalDeclaration(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): ts.TypeNode | undefined;
+    /**
+     * Create a nested mapping context with generic parameters bound.
+     * @param context The current generation context.
+     * @param typeParameters The generic type parameters for the declaration.
+     * @param typeArguments Explicit type arguments, when provided.
+     * @returns The scoped mapping context.
+     */
+    static withTypeParameterBindings(context: ITypeScriptToSchemaContext, typeParameters: ts.NodeArray<ts.TypeParameterDeclaration> | undefined, typeArguments?: ts.NodeArray<ts.TypeNode>): ITypeScriptToSchemaContext;
+    /**
+     * Get a bound generic type parameter for the current mapping scope.
+     * @param context The current generation context.
+     * @param typeName The type name to resolve.
+     * @returns The bound type node, null for unresolved generic parameters, or undefined when not generic.
+     */
+    static getTypeParameterBinding(context: ITypeScriptToSchemaContext, typeName: string): ts.TypeNode | null | undefined;
+    /**
+     * Determine whether a mapped type is a homomorphic source-preserving form.
+     * @param typeNode The mapped type node.
+     * @returns True if the mapped type mirrors an existing object shape.
+     */
+    static isHomomorphicMappedType(typeNode: ts.MappedTypeNode): boolean;
+    /**
+     * Resolve a source object schema for a mapped type when one exists.
+     * @param context The generation context.
+     * @param typeNode The mapped type node.
+     * @returns The resolved source object schema.
+     */
+    static resolveMappedTypeSourceObjectSchema(context: ITypeScriptToSchemaContext, typeNode: ts.MappedTypeNode): IJsonSchema | undefined;
+    /**
+     * Map a single mapped-type property schema.
+     * @param context The generation context.
+     * @param typeNode The mapped type node.
+     * @param sourcePropertyKey The original property key from the source object, used for lookup when the mapped type is homomorphic.
+     * @param mappedTypeParameterName The mapped type parameter name.
+     * @param sourceObjectSchema The optional source object schema.
+     * @returns The mapped property schema.
+     */
+    static mapMappedTypePropertySchema(context: ITypeScriptToSchemaContext, typeNode: ts.MappedTypeNode, sourcePropertyKey: string, mappedTypeParameterName: string, sourceObjectSchema?: IJsonSchema): IJsonSchema | undefined;
+    /**
+     * Resolve a concrete property schema for an indexed access object type and key.
+     * @param context The generation context.
+     * @param objectTypeNode The source object type node.
+     * @param propertyKey The property key to resolve.
+     * @param sourceObjectSchema The optional pre-resolved source object schema.
+     * @returns The resolved property schema.
+     */
+    static resolveIndexedPropertySchema(context: ITypeScriptToSchemaContext, objectTypeNode: ts.TypeNode, propertyKey: string, sourceObjectSchema?: IJsonSchema): IJsonSchema | undefined;
+    /**
+     * Determine whether a type node is a reference to the mapped type parameter.
+     * @param typeNode The type node.
+     * @param mappedTypeParameterName The mapped type parameter name.
+     * @returns True if the node references the mapped parameter.
+     */
+    static isMappedTypeParameterReference(typeNode: ts.TypeNode, mappedTypeParameterName: string): boolean;
+    /**
+     * Apply mapped-type optionality to a schema cloned from a source object.
+     * @param schema The mapped schema.
+     * @param optionalToken The mapped type optional token.
+     */
+    static applyMappedTypeOptionality(schema: IJsonSchema, optionalToken: ts.QuestionToken | ts.PlusToken | ts.MinusToken | undefined): void;
+    /**
+     * Apply mapped-type required keys for generated property sets.
+     * @param schema The mapped schema.
+     * @param propertyKeys The generated property keys.
+     * @param optionalToken The mapped type optional token.
+     */
+    static applyMappedTypeRequiredKeys(schema: IJsonSchema, propertyKeys: string[], optionalToken: ts.QuestionToken | ts.PlusToken | ts.MinusToken | undefined): void;
+    /**
+     * Extract key names from a keyof operand where possible.
+     * @param context The generation context.
+     * @param keysOperandNode The operand used with keyof.
+     * @returns The extracted keys.
+     */
+    static extractKeyofTypeKeys(context: ITypeScriptToSchemaContext, keysOperandNode: ts.TypeNode): string[];
+    /**
+     * Determine whether a keyof operand is a generic type parameter reference.
+     * @param context The generation context.
+     * @param keysOperandNode The operand used with keyof.
+     * @returns True if the operand is a generic parameter.
+     */
+    static isGenericKeyofOperand(context: ITypeScriptToSchemaContext, keysOperandNode: ts.TypeNode): boolean;
+    /**
+     * Resolve a schema id for an external imported type reference.
+     * @param context The generation context.
+     * @param typeNode The type reference node.
+     * @param typeName The referenced type name.
+     * @returns The resolved schema id.
+     */
+    static resolveExternalTypeReferenceSchemaId(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, typeName: string): string | undefined;
+    /**
+     * Resolve a mapped schema target for an imported reference.
+     * @param context The generation context.
+     * @param packageName The referenced package or module specifier.
+     * @param typeName The imported type name.
+     * @returns The mapped schema id and optional namespace if one matches.
+     */
+    static resolveReferenceMappingTarget(context: ITypeScriptToSchemaContext, packageName: string, typeName: string): {
+        schemaId: string;
+        namespace?: string;
+    } | undefined;
+    /**
+     * Find a module specifier for a referenced type in the active source file imports.
+     * @param sourceFile The active source file.
+     * @param typeNode The referenced type node.
+     * @param typeName The referenced type name.
+     * @returns The module specifier.
+     */
+    static findImportedModuleSpecifier(sourceFile: ts.SourceFile, typeNode: ts.TypeReferenceNode, typeName: string): string | undefined;
+    /**
+     * Map custom tag key names to JSON schema property names.
+     * @param key The raw tag key.
+     * @returns The schema key.
+     */
+    static mapJsonSchemaTagKey(key: string): string;
+    /**
+     * Extract the inner type node from a named or rest tuple element.
+     * Named tuple members and rest elements both wrap an inner type node; this unwraps them.
+     * Plain type nodes are returned as-is.
+     * @param element The tuple element.
+     * @returns The inner type node.
+     */
+    static extractTupleElementType(element: ts.TypeNode): ts.TypeNode | undefined;
+}