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

package/dist/es/utils/resolver.js

@@ -0,0 +1,164 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import * as ts from "typescript";
+import { FileUtils } from "./fileUtils.js";
+/**
+ * Resolve TypeScript type declarations from package names.
+ */
+export class Resolver {
+    /**
+     * Cache for resolved package entry files.
+     * @internal
+     */
+    static _resolvedModuleFileCache = {};
+    /**
+     * Cache for parsed source files.
+     * @internal
+     */
+    static _sourceFileCache = {};
+    /**
+     * Cache for resolved type declarations.
+     * @internal
+     */
+    static _typeDeclarationCache = {};
+    /**
+     * Resolve a type declaration AST from a package and type name.
+     * @param packageName The package to inspect.
+     * @param typeName The type to resolve.
+     * @returns The resolved declaration AST.
+     */
+    static resolveTypeDeclarationAst(packageName, typeName) {
+        const cacheKey = `${packageName}::${typeName}`;
+        const cachedDeclaration = Resolver._typeDeclarationCache[cacheKey];
+        if (cachedDeclaration !== undefined) {
+            return cachedDeclaration ?? undefined;
+        }
+        const compilerOptions = Resolver.getModuleResolutionCompilerOptions();
+        const containingFile = `${FileUtils.normalizeFilePath(FileUtils.getCurrentWorkingDirectory())}/__typeScriptToSchema__.ts`;
+        const resolvedModuleFileName = Resolver.resolvePackageEntryFile(packageName, containingFile, compilerOptions);
+        if (!resolvedModuleFileName) {
+            Resolver._typeDeclarationCache[cacheKey] = null;
+            return undefined;
+        }
+        const declarationResult = Resolver.findTypeDeclarationInModuleGraph(resolvedModuleFileName, typeName, new Set(), compilerOptions);
+        Resolver._typeDeclarationCache[cacheKey] = declarationResult ?? null;
+        return declarationResult;
+    }
+    /**
+     * Resolve and cache the package entry file for a module name.
+     * @param packageName The package to resolve.
+     * @param containingFile The containing file for module resolution.
+     * @param compilerOptions Compiler options for module resolution.
+     * @returns The resolved entry file path.
+     * @internal
+     */
+    static resolvePackageEntryFile(packageName, containingFile, compilerOptions) {
+        const cachedResolvedModuleFile = Resolver._resolvedModuleFileCache[packageName];
+        if (cachedResolvedModuleFile !== undefined) {
+            return cachedResolvedModuleFile ?? undefined;
+        }
+        const resolvedModule = ts.resolveModuleName(packageName, containingFile, compilerOptions, ts.sys).resolvedModule;
+        const resolvedModuleFileName = resolvedModule?.resolvedFileName;
+        if (!resolvedModuleFileName) {
+            Resolver._resolvedModuleFileCache[packageName] = null;
+            return undefined;
+        }
+        Resolver._resolvedModuleFileCache[packageName] = resolvedModuleFileName;
+        return resolvedModuleFileName;
+    }
+    /**
+     * Resolve compiler options for module lookup.
+     * @returns The compiler options.
+     * @internal
+     */
+    static getModuleResolutionCompilerOptions() {
+        return {
+            module: ts.ModuleKind.NodeNext,
+            moduleResolution: ts.ModuleResolutionKind.NodeNext,
+            target: ts.ScriptTarget.ESNext,
+            skipLibCheck: true
+        };
+    }
+    /**
+     * Find a type declaration by walking a module's import/export graph.
+     * @param sourceFilePath The source file path to inspect.
+     * @param typeName The type name to find.
+     * @param visitedFiles The visited file set.
+     * @param compilerOptions Compiler options for module resolution.
+     * @returns The matched declaration with its source file.
+     * @internal
+     */
+    static findTypeDeclarationInModuleGraph(sourceFilePath, typeName, visitedFiles, compilerOptions) {
+        const absoluteSourcePath = FileUtils.normalizeFilePath(sourceFilePath);
+        if (visitedFiles.has(absoluteSourcePath)) {
+            return undefined;
+        }
+        visitedFiles.add(absoluteSourcePath);
+        const sourceFile = Resolver.getOrCreateSourceFile(sourceFilePath);
+        if (!sourceFile) {
+            return undefined;
+        }
+        for (const statement of sourceFile.statements) {
+            // interface IFoo { ... }  or  type Foo = ...  (the declaration we are searching for)
+            if ((ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) &&
+                statement.name.text === typeName) {
+                return {
+                    sourceFile,
+                    declaration: statement
+                };
+            }
+        }
+        const moduleSpecifiers = sourceFile.statements
+            // import { ... } from "..."  or  export { ... } from "..."  (re-export and import chains)
+            .filter(statement => ts.isExportDeclaration(statement) || ts.isImportDeclaration(statement))
+            .flatMap(statement => {
+            const moduleSpecifier = statement.moduleSpecifier;
+            // "./module.js"  (string literal module specifier)
+            return moduleSpecifier && ts.isStringLiteral(moduleSpecifier) ? [moduleSpecifier.text] : [];
+        });
+        for (const moduleSpecifier of moduleSpecifiers) {
+            const resolvedImportPath = Resolver.resolveModuleSpecifierFromFile(moduleSpecifier, sourceFilePath, compilerOptions);
+            if (resolvedImportPath) {
+                const declarationResult = Resolver.findTypeDeclarationInModuleGraph(resolvedImportPath, typeName, visitedFiles, compilerOptions);
+                if (declarationResult) {
+                    return declarationResult;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Read and cache a parsed source file.
+     * @param sourceFilePath The source file path.
+     * @returns The parsed source file.
+     * @internal
+     */
+    static getOrCreateSourceFile(sourceFilePath) {
+        const normalizedPath = FileUtils.normalizeFilePath(sourceFilePath);
+        const cachedSourceFile = Resolver._sourceFileCache[normalizedPath];
+        if (cachedSourceFile !== undefined) {
+            return cachedSourceFile ?? undefined;
+        }
+        const source = FileUtils.readFile(sourceFilePath);
+        if (!source) {
+            Resolver._sourceFileCache[normalizedPath] = null;
+            return undefined;
+        }
+        const sourceFile = ts.createSourceFile(sourceFilePath, source, ts.ScriptTarget.Latest, true);
+        Resolver._sourceFileCache[normalizedPath] = sourceFile;
+        return sourceFile;
+    }
+    /**
+     * Resolve a module specifier from a containing file.
+     * @param moduleSpecifier The module specifier text.
+     * @param containingFilePath The file containing the import/export.
+     * @param compilerOptions Compiler options for module resolution.
+     * @returns The resolved file path.
+     * @internal
+     */
+    static resolveModuleSpecifierFromFile(moduleSpecifier, containingFilePath, compilerOptions) {
+        return ts.resolveModuleName(moduleSpecifier, containingFilePath, compilerOptions, ts.sys)
+            .resolvedModule?.resolvedFileName;
+    }
+}
+//# sourceMappingURL=resolver.js.map

package/dist/es/utils/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../src/utils/resolver.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport * as ts from \"typescript\";\nimport { FileUtils } from \"./fileUtils.js\";\n\n/**\n * Resolve TypeScript type declarations from package names.\n */\nexport class Resolver {\n\t/**\n\t * Cache for resolved package entry files.\n\t * @internal\n\t */\n\tprivate static readonly _resolvedModuleFileCache: { [id: string]: string | null | undefined } =\n\t\t{};\n\n\t/**\n\t * Cache for parsed source files.\n\t * @internal\n\t */\n\tprivate static readonly _sourceFileCache: { [id: string]: ts.SourceFile | null | undefined } = {};\n\n\t/**\n\t * Cache for resolved type declarations.\n\t * @internal\n\t */\n\tprivate static readonly _typeDeclarationCache: {\n\t\t[id: string]:\n\t\t\t| {\n\t\t\t\t\tsourceFile: ts.SourceFile;\n\t\t\t\t\tdeclaration: ts.InterfaceDeclaration | ts.TypeAliasDeclaration;\n\t\t\t  }\n\t\t\t| null\n\t\t\t| undefined;\n\t} = {};\n\n\t/**\n\t * Resolve a type declaration AST from a package and type name.\n\t * @param packageName The package to inspect.\n\t * @param typeName The type to resolve.\n\t * @returns The resolved declaration AST.\n\t */\n\tpublic static resolveTypeDeclarationAst(\n\t\tpackageName: string,\n\t\ttypeName: string\n\t):\n\t\t| {\n\t\t\t\tsourceFile: ts.SourceFile;\n\t\t\t\tdeclaration: ts.InterfaceDeclaration | ts.TypeAliasDeclaration;\n\t\t  }\n\t\t| undefined {\n\t\tconst cacheKey = `${packageName}::${typeName}`;\n\t\tconst cachedDeclaration = Resolver._typeDeclarationCache[cacheKey];\n\t\tif (cachedDeclaration !== undefined) {\n\t\t\treturn cachedDeclaration ?? undefined;\n\t\t}\n\n\t\tconst compilerOptions = Resolver.getModuleResolutionCompilerOptions();\n\t\tconst containingFile = `${FileUtils.normalizeFilePath(FileUtils.getCurrentWorkingDirectory())}/__typeScriptToSchema__.ts`;\n\t\tconst resolvedModuleFileName = Resolver.resolvePackageEntryFile(\n\t\t\tpackageName,\n\t\t\tcontainingFile,\n\t\t\tcompilerOptions\n\t\t);\n\n\t\tif (!resolvedModuleFileName) {\n\t\t\tResolver._typeDeclarationCache[cacheKey] = null;\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst declarationResult = Resolver.findTypeDeclarationInModuleGraph(\n\t\t\tresolvedModuleFileName,\n\t\t\ttypeName,\n\t\t\tnew Set<string>(),\n\t\t\tcompilerOptions\n\t\t);\n\n\t\tResolver._typeDeclarationCache[cacheKey] = declarationResult ?? null;\n\t\treturn declarationResult;\n\t}\n\n\t/**\n\t * Resolve and cache the package entry file for a module name.\n\t * @param packageName The package to resolve.\n\t * @param containingFile The containing file for module resolution.\n\t * @param compilerOptions Compiler options for module resolution.\n\t * @returns The resolved entry file path.\n\t * @internal\n\t */\n\tprivate static resolvePackageEntryFile(\n\t\tpackageName: string,\n\t\tcontainingFile: string,\n\t\tcompilerOptions: ts.CompilerOptions\n\t): string | undefined {\n\t\tconst cachedResolvedModuleFile = Resolver._resolvedModuleFileCache[packageName];\n\t\tif (cachedResolvedModuleFile !== undefined) {\n\t\t\treturn cachedResolvedModuleFile ?? undefined;\n\t\t}\n\n\t\tconst resolvedModule = ts.resolveModuleName(\n\t\t\tpackageName,\n\t\t\tcontainingFile,\n\t\t\tcompilerOptions,\n\t\t\tts.sys\n\t\t).resolvedModule;\n\t\tconst resolvedModuleFileName = resolvedModule?.resolvedFileName;\n\t\tif (!resolvedModuleFileName) {\n\t\t\tResolver._resolvedModuleFileCache[packageName] = null;\n\t\t\treturn undefined;\n\t\t}\n\n\t\tResolver._resolvedModuleFileCache[packageName] = resolvedModuleFileName;\n\t\treturn resolvedModuleFileName;\n\t}\n\n\t/**\n\t * Resolve compiler options for module lookup.\n\t * @returns The compiler options.\n\t * @internal\n\t */\n\tprivate static getModuleResolutionCompilerOptions(): ts.CompilerOptions {\n\t\treturn {\n\t\t\tmodule: ts.ModuleKind.NodeNext,\n\t\t\tmoduleResolution: ts.ModuleResolutionKind.NodeNext,\n\t\t\ttarget: ts.ScriptTarget.ESNext,\n\t\t\tskipLibCheck: true\n\t\t};\n\t}\n\n\t/**\n\t * Find a type declaration by walking a module's import/export graph.\n\t * @param sourceFilePath The source file path to inspect.\n\t * @param typeName The type name to find.\n\t * @param visitedFiles The visited file set.\n\t * @param compilerOptions Compiler options for module resolution.\n\t * @returns The matched declaration with its source file.\n\t * @internal\n\t */\n\tprivate static findTypeDeclarationInModuleGraph(\n\t\tsourceFilePath: string,\n\t\ttypeName: string,\n\t\tvisitedFiles: Set<string>,\n\t\tcompilerOptions: ts.CompilerOptions\n\t):\n\t\t| {\n\t\t\t\tsourceFile: ts.SourceFile;\n\t\t\t\tdeclaration: ts.InterfaceDeclaration | ts.TypeAliasDeclaration;\n\t\t  }\n\t\t| undefined {\n\t\tconst absoluteSourcePath = FileUtils.normalizeFilePath(sourceFilePath);\n\t\tif (visitedFiles.has(absoluteSourcePath)) {\n\t\t\treturn undefined;\n\t\t}\n\t\tvisitedFiles.add(absoluteSourcePath);\n\n\t\tconst sourceFile = Resolver.getOrCreateSourceFile(sourceFilePath);\n\t\tif (!sourceFile) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tfor (const statement of sourceFile.statements) {\n\t\t\t// interface IFoo { ... }  or  type Foo = ...  (the declaration we are searching for)\n\t\t\tif (\n\t\t\t\t(ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) &&\n\t\t\t\tstatement.name.text === typeName\n\t\t\t) {\n\t\t\t\treturn {\n\t\t\t\t\tsourceFile,\n\t\t\t\t\tdeclaration: statement\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\tconst moduleSpecifiers = sourceFile.statements\n\t\t\t// import { ... } from \"...\"  or  export { ... } from \"...\"  (re-export and import chains)\n\t\t\t.filter(statement => ts.isExportDeclaration(statement) || ts.isImportDeclaration(statement))\n\t\t\t.flatMap(statement => {\n\t\t\t\tconst moduleSpecifier = statement.moduleSpecifier;\n\t\t\t\t// \"./module.js\"  (string literal module specifier)\n\t\t\t\treturn moduleSpecifier && ts.isStringLiteral(moduleSpecifier) ? [moduleSpecifier.text] : [];\n\t\t\t});\n\n\t\tfor (const moduleSpecifier of moduleSpecifiers) {\n\t\t\tconst resolvedImportPath = Resolver.resolveModuleSpecifierFromFile(\n\t\t\t\tmoduleSpecifier,\n\t\t\t\tsourceFilePath,\n\t\t\t\tcompilerOptions\n\t\t\t);\n\t\t\tif (resolvedImportPath) {\n\t\t\t\tconst declarationResult = Resolver.findTypeDeclarationInModuleGraph(\n\t\t\t\t\tresolvedImportPath,\n\t\t\t\t\ttypeName,\n\t\t\t\t\tvisitedFiles,\n\t\t\t\t\tcompilerOptions\n\t\t\t\t);\n\t\t\t\tif (declarationResult) {\n\t\t\t\t\treturn declarationResult;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Read and cache a parsed source file.\n\t * @param sourceFilePath The source file path.\n\t * @returns The parsed source file.\n\t * @internal\n\t */\n\tprivate static getOrCreateSourceFile(sourceFilePath: string): ts.SourceFile | undefined {\n\t\tconst normalizedPath = FileUtils.normalizeFilePath(sourceFilePath);\n\t\tconst cachedSourceFile = Resolver._sourceFileCache[normalizedPath];\n\t\tif (cachedSourceFile !== undefined) {\n\t\t\treturn cachedSourceFile ?? undefined;\n\t\t}\n\n\t\tconst source = FileUtils.readFile(sourceFilePath);\n\t\tif (!source) {\n\t\t\tResolver._sourceFileCache[normalizedPath] = null;\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst sourceFile = ts.createSourceFile(sourceFilePath, source, ts.ScriptTarget.Latest, true);\n\t\tResolver._sourceFileCache[normalizedPath] = sourceFile;\n\t\treturn sourceFile;\n\t}\n\n\t/**\n\t * Resolve a module specifier from a containing file.\n\t * @param moduleSpecifier The module specifier text.\n\t * @param containingFilePath The file containing the import/export.\n\t * @param compilerOptions Compiler options for module resolution.\n\t * @returns The resolved file path.\n\t * @internal\n\t */\n\tprivate static resolveModuleSpecifierFromFile(\n\t\tmoduleSpecifier: string,\n\t\tcontainingFilePath: string,\n\t\tcompilerOptions: ts.CompilerOptions\n\t): string | undefined {\n\t\treturn ts.resolveModuleName(moduleSpecifier, containingFilePath, compilerOptions, ts.sys)\n\t\t\t.resolvedModule?.resolvedFileName;\n\t}\n}\n"]}

package/dist/es/utils/templateLiteralPatternBuilder.js

@@ -0,0 +1,94 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Is } from "@twin.org/core";
+import * as ts from "typescript";
+/**
+ * Builds regex patterns for TypeScript template literal types.
+ */
+export class TemplateLiteralPatternBuilder {
+    /**
+     * Build a regular-expression pattern for a template literal type.
+     * @param typeNode The template literal type node.
+     * @returns The regex pattern, or undefined if a safe pattern cannot be derived.
+     */
+    static buildTemplateLiteralPattern(typeNode) {
+        // The head is the fixed prefix text before the first interpolation, e.g. "prefix-" in
+        // `prefix-${T}-suffix`
+        let templatePattern = `^${TemplateLiteralPatternBuilder.escapeRegexPattern(typeNode.head.text)}`;
+        // Each span is one ${T} interpolation plus the literal text that follows it
+        for (const templateSpan of typeNode.templateSpans) {
+            const spanPattern = TemplateLiteralPatternBuilder.buildTemplateLiteralSpanPattern(templateSpan.type);
+            if (!spanPattern) {
+                return undefined;
+            }
+            templatePattern += `${spanPattern}${TemplateLiteralPatternBuilder.escapeRegexPattern(templateSpan.literal.text)}`;
+        }
+        return `${templatePattern}$`;
+    }
+    /**
+     * Build a regex fragment for a template literal placeholder type.
+     * @param typeNode The placeholder type node.
+     * @returns The regex fragment, or undefined if unsupported.
+     * @internal
+     */
+    static buildTemplateLiteralSpanPattern(typeNode) {
+        // string  (string keyword lets any content through)
+        if (typeNode.kind === ts.SyntaxKind.StringKeyword) {
+            return ".*";
+        }
+        // MyAlias  (plain type reference with no type arguments is treated as open string)
+        if (ts.isTypeReferenceNode(typeNode) &&
+            ts.isIdentifier(typeNode.typeName) &&
+            (typeNode.typeArguments?.length ?? 0) === 0) {
+            return ".*";
+        }
+        // number  (number keyword matches optional sign, digits, and optional decimal)
+        if (typeNode.kind === ts.SyntaxKind.NumberKeyword) {
+            return "-?(?:0|[1-9]\\d*)(?:\\.\\d+)?";
+        }
+        // boolean  (boolean keyword matches the two literal words)
+        if (typeNode.kind === ts.SyntaxKind.BooleanKeyword) {
+            return "(?:true|false)";
+        }
+        // "hello" or 42 or true or false  (literal type node)
+        if (ts.isLiteralTypeNode(typeNode)) {
+            // "hello" or 42  (string or numeric literal)
+            if (ts.isStringLiteral(typeNode.literal) || ts.isNumericLiteral(typeNode.literal)) {
+                return TemplateLiteralPatternBuilder.escapeRegexPattern(typeNode.literal.text);
+            }
+            // true  (true keyword literal)
+            if (typeNode.literal.kind === ts.SyntaxKind.TrueKeyword) {
+                return "true";
+            }
+            // false  (false keyword literal)
+            if (typeNode.literal.kind === ts.SyntaxKind.FalseKeyword) {
+                return "false";
+            }
+        }
+        // "a" | "b" | "c"  (union of literal types)
+        if (ts.isUnionTypeNode(typeNode)) {
+            const unionPatterns = typeNode.types
+                .map(unionType => TemplateLiteralPatternBuilder.buildTemplateLiteralSpanPattern(unionType))
+                .filter((pattern) => Is.stringValue(pattern));
+            if (unionPatterns.length === typeNode.types.length) {
+                return `(?:${unionPatterns.join("|")})`;
+            }
+        }
+        // `prefix-${T}`  (nested template literal type, strip outer anchors)
+        if (ts.isTemplateLiteralTypeNode(typeNode)) {
+            const nestedPattern = TemplateLiteralPatternBuilder.buildTemplateLiteralPattern(typeNode);
+            return nestedPattern ? nestedPattern.replace(/^\^/, "").replace(/\$$/, "") : undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Escape regex metacharacters in a literal text fragment so it matches verbatim.
+     * @param value The text to escape.
+     * @returns The escaped regex text.
+     * @internal
+     */
+    static escapeRegexPattern(value) {
+        return value.replace(/[$()*+.?[\\\]^{|}-]/g, "\\$&");
+    }
+}
+//# sourceMappingURL=templateLiteralPatternBuilder.js.map

package/dist/es/utils/templateLiteralPatternBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templateLiteralPatternBuilder.js","sourceRoot":"","sources":["../../../src/utils/templateLiteralPatternBuilder.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is } from \"@twin.org/core\";\nimport * as ts from \"typescript\";\n\n/**\n * Builds regex patterns for TypeScript template literal types.\n */\nexport class TemplateLiteralPatternBuilder {\n\t/**\n\t * Build a regular-expression pattern for a template literal type.\n\t * @param typeNode The template literal type node.\n\t * @returns The regex pattern, or undefined if a safe pattern cannot be derived.\n\t */\n\tpublic static buildTemplateLiteralPattern(\n\t\ttypeNode: ts.TemplateLiteralTypeNode\n\t): string | undefined {\n\t\t// The head is the fixed prefix text before the first interpolation, e.g. \"prefix-\" in\n\t\t// `prefix-${T}-suffix`\n\t\tlet templatePattern = `^${TemplateLiteralPatternBuilder.escapeRegexPattern(typeNode.head.text)}`;\n\n\t\t// Each span is one ${T} interpolation plus the literal text that follows it\n\t\tfor (const templateSpan of typeNode.templateSpans) {\n\t\t\tconst spanPattern = TemplateLiteralPatternBuilder.buildTemplateLiteralSpanPattern(\n\t\t\t\ttemplateSpan.type\n\t\t\t);\n\t\t\tif (!spanPattern) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\ttemplatePattern += `${spanPattern}${TemplateLiteralPatternBuilder.escapeRegexPattern(templateSpan.literal.text)}`;\n\t\t}\n\n\t\treturn `${templatePattern}$`;\n\t}\n\n\t/**\n\t * Build a regex fragment for a template literal placeholder type.\n\t * @param typeNode The placeholder type node.\n\t * @returns The regex fragment, or undefined if unsupported.\n\t * @internal\n\t */\n\tprivate static buildTemplateLiteralSpanPattern(typeNode: ts.TypeNode): string | undefined {\n\t\t// string  (string keyword lets any content through)\n\t\tif (typeNode.kind === ts.SyntaxKind.StringKeyword) {\n\t\t\treturn \".*\";\n\t\t}\n\n\t\t// MyAlias  (plain type reference with no type arguments is treated as open string)\n\t\tif (\n\t\t\tts.isTypeReferenceNode(typeNode) &&\n\t\t\tts.isIdentifier(typeNode.typeName) &&\n\t\t\t(typeNode.typeArguments?.length ?? 0) === 0\n\t\t) {\n\t\t\treturn \".*\";\n\t\t}\n\n\t\t// number  (number keyword matches optional sign, digits, and optional decimal)\n\t\tif (typeNode.kind === ts.SyntaxKind.NumberKeyword) {\n\t\t\treturn \"-?(?:0|[1-9]\\\\d*)(?:\\\\.\\\\d+)?\";\n\t\t}\n\n\t\t// boolean  (boolean keyword matches the two literal words)\n\t\tif (typeNode.kind === ts.SyntaxKind.BooleanKeyword) {\n\t\t\treturn \"(?:true|false)\";\n\t\t}\n\n\t\t// \"hello\" or 42 or true or false  (literal type node)\n\t\tif (ts.isLiteralTypeNode(typeNode)) {\n\t\t\t// \"hello\" or 42  (string or numeric literal)\n\t\t\tif (ts.isStringLiteral(typeNode.literal) || ts.isNumericLiteral(typeNode.literal)) {\n\t\t\t\treturn TemplateLiteralPatternBuilder.escapeRegexPattern(typeNode.literal.text);\n\t\t\t}\n\n\t\t\t// true  (true keyword literal)\n\t\t\tif (typeNode.literal.kind === ts.SyntaxKind.TrueKeyword) {\n\t\t\t\treturn \"true\";\n\t\t\t}\n\n\t\t\t// false  (false keyword literal)\n\t\t\tif (typeNode.literal.kind === ts.SyntaxKind.FalseKeyword) {\n\t\t\t\treturn \"false\";\n\t\t\t}\n\t\t}\n\n\t\t// \"a\" | \"b\" | \"c\"  (union of literal types)\n\t\tif (ts.isUnionTypeNode(typeNode)) {\n\t\t\tconst unionPatterns = typeNode.types\n\t\t\t\t.map(unionType => TemplateLiteralPatternBuilder.buildTemplateLiteralSpanPattern(unionType))\n\t\t\t\t.filter((pattern): pattern is string => Is.stringValue(pattern));\n\n\t\t\tif (unionPatterns.length === typeNode.types.length) {\n\t\t\t\treturn `(?:${unionPatterns.join(\"|\")})`;\n\t\t\t}\n\t\t}\n\n\t\t// `prefix-${T}`  (nested template literal type, strip outer anchors)\n\t\tif (ts.isTemplateLiteralTypeNode(typeNode)) {\n\t\t\tconst nestedPattern = TemplateLiteralPatternBuilder.buildTemplateLiteralPattern(typeNode);\n\t\t\treturn nestedPattern ? nestedPattern.replace(/^\\^/, \"\").replace(/\\$$/, \"\") : undefined;\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Escape regex metacharacters in a literal text fragment so it matches verbatim.\n\t * @param value The text to escape.\n\t * @returns The escaped regex text.\n\t * @internal\n\t */\n\tprivate static escapeRegexPattern(value: string): string {\n\t\treturn value.replace(/[$()*+.?[\\\\\\]^{|}-]/g, \"\\\\$&\");\n\t}\n}\n"]}

package/dist/es/utils/typeScriptToSchema.js

@@ -0,0 +1,112 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Is, StringHelper } from "@twin.org/core";
+import { FileUtils } from "./fileUtils.js";
+import { JsonSchemaBuilder } from "./jsonSchemaBuilder.js";
+import { Resolver } from "./resolver.js";
+/**
+ * Class for converting TypeScript types to JSON Schema.
+ */
+export class TypeScriptToSchema {
+    /**
+     * Generates a JSON schema from a TypeScript source file or type name.
+     * @param namespace The schema namespace.
+     * @param packageName The package name.
+     * @param schemas The package schema map.
+     * @param sourceFileOrTypeName The source file to process or type name to resolve.
+     * @param options Additional generation options.
+     * @returns The generated JSON schemas indexed by title.
+     */
+    async generateSchema(namespace, packageName, schemas, sourceFileOrTypeName, options) {
+        const suppressPackageWarnings = (options?.suppressPackageWarnings ?? [])
+            .filter(packageNameToSkip => Is.stringValue(packageNameToSkip))
+            .map(packageNameToSkip => packageNameToSkip.toLowerCase());
+        const filteredOptions = {
+            ...options,
+            onDiagnostic: diagnostic => {
+                if (suppressPackageWarnings.some(packageToSkip => this.isDiagnosticFromPackage(diagnostic.path, diagnostic.fileName, packageToSkip))) {
+                    return;
+                }
+                options?.onDiagnostic?.(diagnostic);
+            }
+        };
+        const context = {
+            namespace,
+            packageName,
+            schemas,
+            options: filteredOptions
+        };
+        let generatedTitles = [];
+        context.schemas[context.packageName] ??= {};
+        const visitedFiles = [];
+        const sourceFiles = FileUtils.resolveSourceFiles(sourceFileOrTypeName);
+        if (sourceFiles.length > 0) {
+            for (const sourceFilePath of sourceFiles) {
+                const source = FileUtils.readFile(sourceFilePath);
+                if (source) {
+                    const parsedTitles = JsonSchemaBuilder.parseAllObjectSchemas(context, sourceFilePath, source, visitedFiles);
+                    for (const parsedTitle of parsedTitles) {
+                        if (!generatedTitles.includes(parsedTitle)) {
+                            generatedTitles.push(parsedTitle);
+                        }
+                    }
+                }
+            }
+        }
+        else if (this.isTypeNameInput(sourceFileOrTypeName)) {
+            const declarationResult = Resolver.resolveTypeDeclarationAst(context.packageName, sourceFileOrTypeName);
+            if (declarationResult) {
+                generatedTitles = JsonSchemaBuilder.parseAllObjectSchemas(context, declarationResult.sourceFile.fileName, declarationResult.sourceFile.getFullText(), visitedFiles);
+            }
+        }
+        else {
+            return {};
+        }
+        const generatedSchemas = {};
+        for (const generatedTitle of generatedTitles) {
+            const generatedSchema = context.schemas[context.packageName][generatedTitle];
+            if (generatedSchema) {
+                generatedSchemas[generatedTitle] = generatedSchema;
+            }
+        }
+        if (this.isTypeNameInput(sourceFileOrTypeName)) {
+            const requestedTitle = StringHelper.stripPrefix(sourceFileOrTypeName);
+            const requestedSchema = context.schemas[context.packageName][requestedTitle];
+            if (requestedSchema) {
+                generatedSchemas[requestedTitle] = requestedSchema;
+            }
+        }
+        return generatedSchemas;
+    }
+    /**
+     * Determine if a diagnostic originates from a specific package.
+     * @param path The schema or source path associated with the diagnostic.
+     * @param fileName The source filename associated with the diagnostic.
+     * @param packageName The package name to check, e.g. jose.
+     * @returns True if the diagnostic originated from the package.
+     */
+    isDiagnosticFromPackage(path, fileName, packageName) {
+        if (!Is.stringValue(packageName)) {
+            return false;
+        }
+        const sourcePaths = [fileName, path]
+            .filter((value) => Is.stringValue(value))
+            .map(value => value.replace(/\\/g, "/").toLowerCase());
+        const normalisedPackageName = packageName.toLowerCase();
+        const packagePath = `/node_modules/${normalisedPackageName}/`;
+        const packagePathNoTrailingSlash = `/node_modules/${normalisedPackageName}`;
+        return sourcePaths.some(sourcePath => sourcePath.includes(packagePath) || sourcePath.endsWith(packagePathNoTrailingSlash));
+    }
+    /**
+     * Determine whether an input value is a valid TypeScript type identifier.
+     * An identifier must start with a letter, underscore, or dollar sign and contain only
+     * alphanumerics, underscores, or dollar signs thereafter.
+     * @param value The value to inspect.
+     * @returns True if the value looks like a type name.
+     * @internal
+     */
+    isTypeNameInput(value) {
+        return /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(value);
+    }
+}
+//# sourceMappingURL=typeScriptToSchema.js.map

package/dist/es/utils/typeScriptToSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeScriptToSchema.js","sourceRoot":"","sources":["../../../src/utils/typeScriptToSchema.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is, StringHelper } from \"@twin.org/core\";\nimport type { IJsonSchema } from \"@twin.org/tools-models\";\nimport { FileUtils } from \"./fileUtils.js\";\nimport { JsonSchemaBuilder } from \"./jsonSchemaBuilder.js\";\nimport { Resolver } from \"./resolver.js\";\nimport type { ITypeScriptToSchemaContext } from \"../models/ITypeScriptToSchemaContext.js\";\nimport type { ITypeScriptToSchemaOptions } from \"../models/ITypeScriptToSchemaOptions.js\";\n\n/**\n * Class for converting TypeScript types to JSON Schema.\n */\nexport class TypeScriptToSchema {\n\t/**\n\t * Generates a JSON schema from a TypeScript source file or type name.\n\t * @param namespace The schema namespace.\n\t * @param packageName The package name.\n\t * @param schemas The package schema map.\n\t * @param sourceFileOrTypeName The source file to process or type name to resolve.\n\t * @param options Additional generation options.\n\t * @returns The generated JSON schemas indexed by title.\n\t */\n\tpublic async generateSchema(\n\t\tnamespace: string,\n\t\tpackageName: string,\n\t\tschemas: { [id: string]: { [id: string]: IJsonSchema } },\n\t\tsourceFileOrTypeName: string,\n\t\toptions?: ITypeScriptToSchemaOptions\n\t): Promise<{ [id: string]: IJsonSchema }> {\n\t\tconst suppressPackageWarnings = (options?.suppressPackageWarnings ?? [])\n\t\t\t.filter(packageNameToSkip => Is.stringValue(packageNameToSkip))\n\t\t\t.map(packageNameToSkip => packageNameToSkip.toLowerCase());\n\t\tconst filteredOptions: ITypeScriptToSchemaOptions = {\n\t\t\t...options,\n\t\t\tonDiagnostic: diagnostic => {\n\t\t\t\tif (\n\t\t\t\t\tsuppressPackageWarnings.some(packageToSkip =>\n\t\t\t\t\t\tthis.isDiagnosticFromPackage(diagnostic.path, diagnostic.fileName, packageToSkip)\n\t\t\t\t\t)\n\t\t\t\t) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\toptions?.onDiagnostic?.(diagnostic);\n\t\t\t}\n\t\t};\n\n\t\tconst context: ITypeScriptToSchemaContext = {\n\t\t\tnamespace,\n\t\t\tpackageName,\n\t\t\tschemas,\n\t\t\toptions: filteredOptions\n\t\t};\n\n\t\tlet generatedTitles: string[] = [];\n\t\tcontext.schemas[context.packageName] ??= {};\n\t\tconst visitedFiles: string[] = [];\n\t\tconst sourceFiles = FileUtils.resolveSourceFiles(sourceFileOrTypeName);\n\n\t\tif (sourceFiles.length > 0) {\n\t\t\tfor (const sourceFilePath of sourceFiles) {\n\t\t\t\tconst source = FileUtils.readFile(sourceFilePath);\n\t\t\t\tif (source) {\n\t\t\t\t\tconst parsedTitles = JsonSchemaBuilder.parseAllObjectSchemas(\n\t\t\t\t\t\tcontext,\n\t\t\t\t\t\tsourceFilePath,\n\t\t\t\t\t\tsource,\n\t\t\t\t\t\tvisitedFiles\n\t\t\t\t\t);\n\t\t\t\t\tfor (const parsedTitle of parsedTitles) {\n\t\t\t\t\t\tif (!generatedTitles.includes(parsedTitle)) {\n\t\t\t\t\t\t\tgeneratedTitles.push(parsedTitle);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (this.isTypeNameInput(sourceFileOrTypeName)) {\n\t\t\tconst declarationResult = Resolver.resolveTypeDeclarationAst(\n\t\t\t\tcontext.packageName,\n\t\t\t\tsourceFileOrTypeName\n\t\t\t);\n\t\t\tif (declarationResult) {\n\t\t\t\tgeneratedTitles = JsonSchemaBuilder.parseAllObjectSchemas(\n\t\t\t\t\tcontext,\n\t\t\t\t\tdeclarationResult.sourceFile.fileName,\n\t\t\t\t\tdeclarationResult.sourceFile.getFullText(),\n\t\t\t\t\tvisitedFiles\n\t\t\t\t);\n\t\t\t}\n\t\t} else {\n\t\t\treturn {};\n\t\t}\n\n\t\tconst generatedSchemas: { [id: string]: IJsonSchema } = {};\n\t\tfor (const generatedTitle of generatedTitles) {\n\t\t\tconst generatedSchema = context.schemas[context.packageName][generatedTitle];\n\t\t\tif (generatedSchema) {\n\t\t\t\tgeneratedSchemas[generatedTitle] = generatedSchema;\n\t\t\t}\n\t\t}\n\n\t\tif (this.isTypeNameInput(sourceFileOrTypeName)) {\n\t\t\tconst requestedTitle = StringHelper.stripPrefix(sourceFileOrTypeName);\n\t\t\tconst requestedSchema = context.schemas[context.packageName][requestedTitle];\n\t\t\tif (requestedSchema) {\n\t\t\t\tgeneratedSchemas[requestedTitle] = requestedSchema;\n\t\t\t}\n\t\t}\n\n\t\treturn generatedSchemas;\n\t}\n\n\t/**\n\t * Determine if a diagnostic originates from a specific package.\n\t * @param path The schema or source path associated with the diagnostic.\n\t * @param fileName The source filename associated with the diagnostic.\n\t * @param packageName The package name to check, e.g. jose.\n\t * @returns True if the diagnostic originated from the package.\n\t */\n\tpublic isDiagnosticFromPackage(\n\t\tpath: string,\n\t\tfileName: string | undefined,\n\t\tpackageName: string\n\t): boolean {\n\t\tif (!Is.stringValue(packageName)) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst sourcePaths = [fileName, path]\n\t\t\t.filter((value): value is string => Is.stringValue(value))\n\t\t\t.map(value => value.replace(/\\\\/g, \"/\").toLowerCase());\n\t\tconst normalisedPackageName = packageName.toLowerCase();\n\t\tconst packagePath = `/node_modules/${normalisedPackageName}/`;\n\t\tconst packagePathNoTrailingSlash = `/node_modules/${normalisedPackageName}`;\n\n\t\treturn sourcePaths.some(\n\t\t\tsourcePath =>\n\t\t\t\tsourcePath.includes(packagePath) || sourcePath.endsWith(packagePathNoTrailingSlash)\n\t\t);\n\t}\n\n\t/**\n\t * Determine whether an input value is a valid TypeScript type identifier.\n\t * An identifier must start with a letter, underscore, or dollar sign and contain only\n\t * alphanumerics, underscores, or dollar signs thereafter.\n\t * @param value The value to inspect.\n\t * @returns True if the value looks like a type name.\n\t * @internal\n\t */\n\tprivate isTypeNameInput(value: string): boolean {\n\t\treturn /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(value);\n\t}\n}\n"]}