@twin.org/tools-core 0.0.3-next.3 → 0.0.3-next.31

package/dist/types/models/ITypeScriptToSchemaContext.d.ts

@@ -0,0 +1,71 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+import type * as ts from "typescript";
+import type { EmbeddedSchemaMode } from "./embeddedSchemaMode.js";
+import type { ITypeScriptToSchemaOptions } from "./ITypeScriptToSchemaOptions.js";
+/**
+ * Context for TypeScript to JSON schema generation.
+ */
+export interface ITypeScriptToSchemaContext {
+    /**
+     * The namespace for generated schema ids.
+     */
+    namespace: string;
+    /**
+     * The package name for generated schema ids.
+     */
+    packageName: string;
+    /**
+     * The schema cache indexed by package and title.
+     */
+    schemas: {
+        [id: string]: {
+            [id: string]: IJsonSchema;
+        };
+    };
+    /**
+     * The currently active source file being mapped.
+     */
+    activeSourceFile?: ts.SourceFile;
+    /**
+     * The currently active enclosing object (interface/type) being mapped.
+     */
+    activeEnclosingObjectName?: string;
+    /**
+     * The first disallowed type encountered while mapping the active enclosing object.
+     */
+    activeDisallowedType?: {
+        disallowedTypeName: string;
+        propertyName: string;
+        enclosingObjectName: string;
+    };
+    /**
+     * Type names currently being resolved to avoid recursive local-type expansion loops.
+     */
+    resolvingTypeNames?: Set<string>;
+    /**
+     * Utility type names currently being processed to avoid infinite recursion cycles
+     * when encountering complex combinations of indexed access types, keyof, and utility types.
+     */
+    resolvingUtilityTypes?: Set<string>;
+    /**
+     * Imported utility base schemas currently being resolved to avoid recursive re-entry
+     * while parsing module graphs for utility type application.
+     */
+    resolvingImportedObjectSchemas?: Set<string>;
+    /**
+     * Generic type parameter bindings active for the current mapping scope.
+     */
+    typeParameterBindings?: {
+        [id: string]: ts.TypeNode | null;
+    };
+    /**
+     * Schema ids marked with @json-schema embedded and their embedding mode.
+     */
+    embeddedSchemaModes?: {
+        [id: string]: EmbeddedSchemaMode;
+    };
+    /**
+     * Optional schema generation options.
+     */
+    options?: ITypeScriptToSchemaOptions;
+}

package/dist/types/models/ITypeScriptToSchemaDiagnostics.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Diagnostic payload for non-fatal schema generation issues.
+ */
+export interface ITypeScriptToSchemaDiagnostics {
+    /**
+     * Stable diagnostic code identifying the issue type.
+     */
+    code: string;
+    /**
+     * Additional structured metadata related to the diagnostic.
+     */
+    properties?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Schema path where the issue was detected.
+     */
+    path: string;
+    /**
+     * Source file where the diagnostic originated, if available.
+     */
+    fileName?: string;
+    /**
+     * One-based source line number, when available.
+     */
+    line?: number;
+    /**
+     * One-based source column number, when available.
+     */
+    column?: number;
+}

package/dist/types/models/ITypeScriptToSchemaOptions.d.ts

@@ -0,0 +1,22 @@
+import type { ITypeScriptToSchemaDiagnostics } from "./ITypeScriptToSchemaDiagnostics.js";
+/**
+ * Options for TypeScript to JSON schema generation.
+ */
+export interface ITypeScriptToSchemaOptions {
+    /**
+     * Mapping of package ids, type ids, wildcard patterns, or regex patterns to schema id prefixes
+     * or replacement templates for referenced schemas.
+     */
+    externalReferences?: {
+        [id: string]: string;
+    };
+    /**
+     * Optional diagnostic callback for non-fatal generation issues.
+     * @param diagnostic The diagnostic details for the generation issue.
+     */
+    onDiagnostic?: (diagnostic: ITypeScriptToSchemaDiagnostics) => void;
+    /**
+     * Package names where diagnostics should be suppressed, e.g. jose.
+     */
+    suppressPackageWarnings?: string[];
+}

package/dist/types/models/embeddedSchemaMode.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The available embedded schema modes.
+ */
+export declare const EmbeddedSchemaMode: {
+    /**
+     * Referenced schemas are added to the "defs" section of the root schema.
+     */
+    readonly Defs: "defs";
+    /**
+     * Referenced schemas are inlined into the referencing schema.
+     */
+    readonly Inline: "inline";
+};
+/**
+ * The embedded schema mode value type.
+ */
+export type EmbeddedSchemaMode = (typeof EmbeddedSchemaMode)[keyof typeof EmbeddedSchemaMode];

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

@@ -0,0 +1,13 @@
+/**
+ * Shared constants for TypeScript to JSON schema generation.
+ */
+export declare class Constants {
+    /**
+     * Utility type names currently unsupported and mapped to open schemas with diagnostics.
+     */
+    static readonly UNSUPPORTED_UTILITY_TYPE_NAMES: string[];
+    /**
+     * Native typed-array and binary type names mapped to JSON number arrays.
+     */
+    static readonly ARRAY_NUMBER_TYPE_NAMES: string[];
+}

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

@@ -0,0 +1,17 @@
+import type * as ts from "typescript";
+import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaContext.js";
+/**
+ * Emits non-fatal diagnostics during schema mapping.
+ */
+export declare class DiagnosticReporter {
+    /**
+     * Emit an optional non-fatal schema generation diagnostic.
+     * @param context The generation context.
+     * @param node The related AST node.
+     * @param code The diagnostic code.
+     * @param properties The values to substitute into the localised message.
+     */
+    static report(context: ITypeScriptToSchemaContext, node: ts.Node, code: string, properties?: {
+        [key: string]: unknown;
+    }): void;
+}

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

@@ -0,0 +1,16 @@
+import * as ts from "typescript";
+/**
+ * Validates whether a type node is allowed for schema generation.
+ */
+export declare class DisallowedTypeGuard {
+    /**
+     * Type names that are not supported for JSON schema generation.
+     */
+    private static readonly _DISALLOWED_TYPE_NAMES;
+    /**
+     * Resolve a disallowed type name from a type node.
+     * @param typeNode The type node to inspect.
+     * @returns The disallowed type name, if found.
+     */
+    static getDisallowedTypeName(typeNode: ts.TypeNode): string | undefined;
+}

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

@@ -0,0 +1,42 @@
+import * as ts from "typescript";
+/**
+ * Utility methods for extracting enum values from TypeScript AST nodes.
+ *
+ * Handles three distinct patterns used to define enumerable sets of values:
+ * - Native enum declarations: `enum Color { Red = "red" }`
+ * - Const-object-with-matching-type patterns: `const Foo = { A: "a" } as const` paired with a type alias named identically to the const
+ */
+export declare class Enum {
+    /**
+     * Extract enum values from a const-and-type pair where a const object and a type alias share the
+     * same name.  The const object is located first because its members may carry JSDoc descriptions
+     * that would be lost if the type alias were processed in isolation.
+     * @param name The name to search for.
+     * @param sourceFile The source file to search.
+     * @returns The extracted enum entries or undefined when the pattern is not present.
+     */
+    static extractEnumValuesFromConstAndType(name: string, sourceFile: ts.SourceFile): {
+        value: string | number;
+        description?: string;
+    }[] | undefined;
+    /**
+     * Extract enum entries from a const object literal.
+     * Only properties whose initializer is a string or numeric literal are included.
+     * @param objLiteral The object literal expression.
+     * @returns The extracted enum entries.
+     */
+    static extractEnumEntriesFromConstObject(objLiteral: ts.ObjectLiteralExpression): {
+        value: string | number;
+        description?: string;
+    }[];
+    /**
+     * Extract enum values from a native TypeScript enum declaration.
+     * Numeric members without an explicit initializer are auto-incremented from the previous value.
+     * @param declaration The enum declaration.
+     * @returns The extracted enum entries.
+     */
+    static extractEnumValuesFromEnumDeclaration(declaration: ts.EnumDeclaration): {
+        value: string | number;
+        description?: string;
+    }[];
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Utility helpers for TypeScript file and directory paths.
+ */
+export declare class FileUtils {
+    /**
+     * Does the file exist.
+     * @param filePath The file path.
+     * @returns True if the file exists.
+     */
+    static fileExists(filePath: string): boolean;
+    /**
+     * Read the file.
+     * @param filePath The file path.
+     * @returns The file contents.
+     */
+    static readFile(filePath: string): string;
+    /**
+     * Resolve a path.
+     * @param filePath The file path.
+     * @returns The resolved path.
+     */
+    static resolvePath(filePath: string): string;
+    /**
+     * Get the current working directory.
+     * @returns The current working directory.
+     */
+    static getCurrentWorkingDirectory(): string;
+    /**
+     * Normalize path separators for consistent comparisons.
+     * @param filePath The file path.
+     * @returns The normalized file path.
+     */
+    static normalizeFilePath(filePath: string): string;
+    /**
+     * Get the directory portion of a file path.
+     * @param filePath The file path.
+     * @returns The directory path.
+     */
+    static getDirectoryPath(filePath: string): string;
+    /**
+     * Resolve a relative path against a base directory.
+     * @param baseDirectory The base directory.
+     * @param relativePath The relative path.
+     * @returns The resolved path.
+     */
+    static resolveRelativePath(baseDirectory: string, relativePath: string): string;
+    /**
+     * Resolve a local import specifier to a TypeScript source file path.
+     * @param sourceFilePath The importing source file path.
+     * @param importPath The import specifier.
+     * @returns The resolved source file path.
+     */
+    static resolveImportSourceFilePath(sourceFilePath: string, importPath: string): string | undefined;
+    /**
+     * Determine if the provided path includes glob pattern tokens.
+     * @param sourceFileOrGlob The direct source file path or glob pattern.
+     * @returns True if the value is a glob pattern.
+     */
+    static isGlobPattern(sourceFileOrGlob: string): boolean;
+    /**
+     * Resolve source files from a direct path or a glob pattern.
+     * @param sourceFileOrGlob The direct source file path or glob pattern.
+     * @returns The resolved source file paths.
+     */
+    static resolveSourceFiles(sourceFileOrGlob: string): string[];
+}

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

@@ -0,0 +1,87 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+import * as ts from "typescript";
+import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaContext.js";
+/**
+ * Static helpers for import type and type query schema resolution.
+ */
+export declare class ImportTypeQuerySchemaResolver {
+    /**
+     * Map import type nodes (e.g. import("pkg").Type) to schema references.
+     * @param context The generation context.
+     * @param typeNode The import type node.
+     * @returns The mapped schema.
+     */
+    static mapImportTypeNodeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.ImportTypeNode): IJsonSchema | undefined;
+    /**
+     * Map a type query node (typeof expr) to schema by resolving the referenced variable.
+     * @param context The generation context.
+     * @param typeNode The type query node.
+     * @returns The mapped schema.
+     */
+    static mapTypeQueryNodeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.TypeQueryNode): IJsonSchema;
+    /**
+     * 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 stripped schema title.
+     * @returns The resolved schema id.
+     */
+    static resolveImportTypeReferenceSchemaId(context: ITypeScriptToSchemaContext, moduleSpecifier: string, typeName: string, title: string): string | undefined;
+    /**
+     * Resolve a property value from a const object declaration in an imported source file.
+     * @param context The generation context.
+     * @param objectName The imported object symbol name.
+     * @param propertyName The property name to resolve from the object.
+     * @returns The resolved literal property value.
+     */
+    private static resolveConstObjectProperty;
+    /**
+     * Find a variable declaration by traversing import and export chains.
+     * @param sourceFilePath The source file path to inspect.
+     * @param variableName The variable name to find.
+     * @param visitedFiles The set of visited files to prevent recursion cycles.
+     * @returns The matched variable declaration.
+     */
+    private static findVariableDeclarationInModuleGraph;
+    /**
+     * Find an imported symbol reference by local identifier name.
+     * @param sourceFile The active source file.
+     * @param localName The local identifier name.
+     * @returns The imported symbol reference.
+     */
+    private static findImportedValueReference;
+    /**
+     * Resolve an import declaration module specifier to a source file.
+     * @param containingSourceFilePath The path of the file containing the import declaration.
+     * @param moduleSpecifier The module specifier to resolve.
+     * @returns The resolved source file path.
+     */
+    private static resolveImportDeclarationSourceFile;
+    /**
+     * Extract a const-object property value from a declaration initializer.
+     * @param objectDeclaration The variable declaration containing the object initializer.
+     * @param propertyName The property name to resolve.
+     * @returns The extracted literal property value.
+     */
+    private static extractConstObjectPropertyFromDeclarationInitializer;
+    /**
+     * Extract a const-object property value from a declaration type annotation.
+     * @param declarationTypeNode The declaration type node to inspect.
+     * @param propertyName The property name to resolve.
+     * @returns The extracted literal property value.
+     */
+    private static extractConstObjectPropertyFromDeclarationType;
+    /**
+     * Extract a literal value from a type node when possible.
+     * @param typeNode The type node to inspect.
+     * @returns The extracted literal value.
+     */
+    private static extractLiteralValueFromTypeNode;
+    /**
+     * Extract a referenced type name from an import type qualifier.
+     * @param qualifier The import type qualifier.
+     * @returns The extracted type name.
+     */
+    private static extractImportTypeName;
+}

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

@@ -0,0 +1,21 @@
+import * as ts from "typescript";
+import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaContext.js";
+/**
+ * Resolves regex patterns for index signature key types.
+ */
+export declare class IndexSignaturePatternResolver {
+    /**
+     * Determine whether an index signature can be represented as JSON object additionalProperties.
+     * @param member The index signature declaration.
+     * @returns True if supported.
+     */
+    static isSupportedIndexSignature(member: ts.IndexSignatureDeclaration): boolean;
+    /**
+     * Extract a regex pattern for an index signature key type when representable.
+     * @param context The generation context.
+     * @param member The index signature declaration.
+     * @param getTypeParameterBinding Callback for resolving generic bindings.
+     * @returns The property-name pattern, if derivable.
+     */
+    static extractIndexSignaturePattern(context: ITypeScriptToSchemaContext, member: ts.IndexSignatureDeclaration, getTypeParameterBinding: (context: ITypeScriptToSchemaContext, typeName: string) => ts.TypeNode | null | undefined): string | undefined;
+}

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

@@ -0,0 +1,16 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaContext.js";
+/**
+ * Merges compatible object intersections into a single JSON schema object.
+ */
+export declare class IntersectionSchemaMerger {
+    /**
+     * Merge simple object intersection parts into a single object schema.
+     * Supports local/known object refs by expanding them before merge.
+     * @param context The generation context.
+     * @param schemas The mapped intersection schemas.
+     * @param toInlineUtilityObjectSchema Callback for converting referenced schemas to inline forms.
+     * @returns The merged schema, or undefined when merge is not safe.
+     */
+    static mergeIntersectionObjectSchemas(context: ITypeScriptToSchemaContext, schemas: IJsonSchema[], toInlineUtilityObjectSchema: (schema: IJsonSchema) => IJsonSchema): IJsonSchema | undefined;
+}

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

@@ -0,0 +1,53 @@
+import * as ts from "typescript";
+/**
+ * General-purpose utility methods for working with JsDoc.
+ */
+export declare class JsDoc {
+    /**
+     * Extract the JSDoc description comment for an AST node.
+     * Only top-level JSDoc block comments are considered; inline tags are ignored.
+     * @param node The node to inspect.
+     * @returns The trimmed description text, or undefined when absent.
+     */
+    static getNodeJsDocDescription(node: ts.Node): string | undefined;
+    /**
+     * Convert a JSDoc tag's comment portion to a plain text string.
+     * JSDoc tag comments may be plain strings or arrays of link/text parts.
+     * @param jsDocTag The JSDoc tag.
+     * @returns The comment text, or undefined when absent.
+     */
+    static getJSDocTagCommentText(jsDocTag: ts.JSDocTag): string | undefined;
+    /**
+     * Read all custom JSDoc tags matching a tag name from a node and convert them to key/value pairs.
+     * Each matching tag's comment must be in the form "key: value"; entries that do not follow this
+     * convention are silently skipped.
+     * @param node The node to inspect.
+     * @param tagName The tag name to filter by (e.g., 'json-schema').
+     * @returns The extracted key/value pairs.
+     */
+    static getNodeTags(node: ts.Node, tagName: string): {
+        [id: string]: string;
+    };
+    /**
+     * Read the plain comment text for the first matching JSDoc tag on a node.
+     * @param node The node to inspect.
+     * @param tagName The tag name to filter by (e.g., 'default').
+     * @returns The trimmed comment text, or undefined when absent.
+     */
+    static getNodeTagComment(node: ts.Node, tagName: string): string | undefined;
+    /**
+     * Read the plain comment text for all matching JSDoc tags on a node.
+     * @param node The node to inspect.
+     * @param tagName The tag name to filter by (e.g., 'example').
+     * @returns An array of trimmed comment texts for all matching tags.
+     */
+    static getNodeTagComments(node: ts.Node, tagName: string): string[];
+    /**
+     * Parse a custom JSDoc tag value into JSON-compatible data.
+     * Values that begin with a JSON token character (open brace, open bracket, double quote, true, false, null) or look like a
+     * number are parsed with JSON.parse.  All other values are returned as plain strings.
+     * @param value The raw value text.
+     * @returns The parsed value.
+     */
+    static parseTagValue(value: string): unknown;
+}