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

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,52 @@
+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.
+     */
+    static mapImportTypeNodeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.ImportTypeNode): IJsonSchema | undefined;
+    /**
+     * Map a type query node (typeof expr) to schema by resolving the referenced variable.
+     */
+    static mapTypeQueryNodeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.TypeQueryNode): IJsonSchema;
+    /**
+     * Resolve import-type references to local or external schema ids.
+     */
+    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.
+     */
+    private static resolveConstObjectProperty;
+    /**
+     * Find a variable declaration by traversing import and export chains.
+     */
+    private static findVariableDeclarationInModuleGraph;
+    /**
+     * Find an imported symbol reference by local identifier name.
+     */
+    private static findImportedValueReference;
+    /**
+     * Resolve an import declaration module specifier to a source file.
+     */
+    private static resolveImportDeclarationSourceFile;
+    /**
+     * Extract a const-object property value from a declaration initializer.
+     */
+    private static extractConstObjectPropertyFromDeclarationInitializer;
+    /**
+     * Extract a const-object property value from a declaration type annotation.
+     */
+    private static extractConstObjectPropertyFromDeclarationType;
+    /**
+     * Extract a literal value from a type node when possible.
+     */
+    private static extractLiteralValueFromTypeNode;
+    /**
+     * Extract a referenced type name from an import type qualifier.
+     */
+    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,46 @@
+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;
+    /**
+     * Parse a custom JSDoc tag value into JSON-compatible data.
+     * Values that begin with a JSON token character ({, [, ", 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;
+}