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

package/dist/es/utils/resolver.js

@@ -0,0 +1,177 @@
+// 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.
+     * @param containingFilePath An optional source file path to use as the starting point for
+     * package resolution. When provided, TypeScript module resolution walks up from that file's
+     * directory, which allows transitive dependencies installed alongside the source file (e.g.
+     * in a sub-directory node_modules) to be found even when they are not reachable from the
+     * current working directory. The path is normalised to absolute before use;
+     * falls back to process.cwd() when omitted.
+     * @returns The resolved declaration AST.
+     */
+    static resolveTypeDeclarationAst(packageName, typeName, containingFilePath) {
+        // path.resolve normalises both absolute and relative paths to an absolute form so that
+        // TypeScript module resolution can correctly walk up the directory tree to node_modules.
+        const containingFile = containingFilePath
+            ? FileUtils.normalizeFilePath(FileUtils.resolvePath(containingFilePath))
+            : `${FileUtils.normalizeFilePath(FileUtils.getCurrentWorkingDirectory())}/__typeScriptToSchema__.ts`;
+        const resolveDir = FileUtils.getDirectoryPath(containingFile);
+        const cacheKey = `${resolveDir}::${packageName}::${typeName}`;
+        const moduleCacheKey = `${resolveDir}::${packageName}`;
+        const cachedDeclaration = Resolver._typeDeclarationCache[cacheKey];
+        if (cachedDeclaration !== undefined) {
+            return cachedDeclaration ?? undefined;
+        }
+        const compilerOptions = Resolver.getModuleResolutionCompilerOptions();
+        const resolvedModuleFileName = Resolver.resolvePackageEntryFile(packageName, containingFile, compilerOptions, moduleCacheKey);
+        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.
+     * @param cacheKey The cache key to use for the resolved module file cache.
+     * @returns The resolved entry file path.
+     * @internal
+     */
+    static resolvePackageEntryFile(packageName, containingFile, compilerOptions, cacheKey) {
+        const cachedResolvedModuleFile = Resolver._resolvedModuleFileCache[cacheKey];
+        if (cachedResolvedModuleFile !== undefined) {
+            return cachedResolvedModuleFile ?? undefined;
+        }
+        const resolvedModule = ts.resolveModuleName(packageName, containingFile, compilerOptions, ts.sys).resolvedModule;
+        const resolvedModuleFileName = resolvedModule?.resolvedFileName;
+        if (!resolvedModuleFileName) {
+            Resolver._resolvedModuleFileCache[cacheKey] = null;
+            return undefined;
+        }
+        Resolver._resolvedModuleFileCache[cacheKey] = 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 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 * @param containingFilePath An optional source file path to use as the starting point for\n\t * package resolution. When provided, TypeScript module resolution walks up from that file's\n\t * directory, which allows transitive dependencies installed alongside the source file (e.g.\n\t * in a sub-directory node_modules) to be found even when they are not reachable from the\n\t * current working directory. The path is normalised to absolute before use;\n\t * falls back to process.cwd() when omitted.\n\t * @returns The resolved declaration AST.\n\t */\n\tpublic static resolveTypeDeclarationAst(\n\t\tpackageName: string,\n\t\ttypeName: string,\n\t\tcontainingFilePath?: 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\t// path.resolve normalises both absolute and relative paths to an absolute form so that\n\t\t// TypeScript module resolution can correctly walk up the directory tree to node_modules.\n\t\tconst containingFile = containingFilePath\n\t\t\t? FileUtils.normalizeFilePath(FileUtils.resolvePath(containingFilePath))\n\t\t\t: `${FileUtils.normalizeFilePath(FileUtils.getCurrentWorkingDirectory())}/__typeScriptToSchema__.ts`;\n\t\tconst resolveDir = FileUtils.getDirectoryPath(containingFile);\n\t\tconst cacheKey = `${resolveDir}::${packageName}::${typeName}`;\n\t\tconst moduleCacheKey = `${resolveDir}::${packageName}`;\n\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 resolvedModuleFileName = Resolver.resolvePackageEntryFile(\n\t\t\tpackageName,\n\t\t\tcontainingFile,\n\t\t\tcompilerOptions,\n\t\t\tmoduleCacheKey\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 * @param cacheKey The cache key to use for the resolved module file cache.\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\tcacheKey: string\n\t): string | undefined {\n\t\tconst cachedResolvedModuleFile = Resolver._resolvedModuleFileCache[cacheKey];\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[cacheKey] = null;\n\t\t\treturn undefined;\n\t\t}\n\n\t\tResolver._resolvedModuleFileCache[cacheKey] = 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 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,319 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Is, ObjectHelper, StringHelper } from "@twin.org/core";
+import { FileUtils } from "./fileUtils.js";
+import { JsonSchemaBuilder } from "./jsonSchemaBuilder.js";
+import { Resolver } from "./resolver.js";
+import { EmbeddedSchemaMode } from "../models/embeddedSchemaMode.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;
+            }
+        }
+        for (const [generatedTitle, generatedSchema] of Object.entries(generatedSchemas)) {
+            this.inlineEmbeddedSchemas(context, generatedSchema, generatedTitle);
+        }
+        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));
+    }
+    /**
+     * Rewrite refs to @json-schema embedded local types into the current schema's $defs.
+     * @param context The generation context.
+     * @param schema The root schema to rewrite.
+     * @param rootTitle The title of the root schema.
+     */
+    inlineEmbeddedSchemas(context, schema, rootTitle) {
+        this.inlineEmbeddedSchemasInNode(context, schema, schema, rootTitle, new Set([rootTitle]));
+    }
+    /**
+     * Traverse a schema tree and move embedded local refs into the root schema's $defs.
+     * @param context The generation context.
+     * @param rootSchema The root schema document being rewritten.
+     * @param currentNode The current schema node.
+     * @param rootTitle The title of the root schema.
+     * @param ancestry Titles currently being expanded to avoid recursion cycles.
+     * @returns True if inline embedding changed this node or a descendant.
+     */
+    inlineEmbeddedSchemasInNode(context, rootSchema, currentNode, rootTitle, ancestry) {
+        let hasInlineReplacement = false;
+        if (Is.stringValue(currentNode.$ref)) {
+            const refId = currentNode.$ref;
+            const embeddedMode = context.embeddedSchemaModes?.[refId];
+            const embeddedSchema = this.findSchemaById(context, refId);
+            const defsKey = embeddedSchema
+                ? this.getEmbeddedDefinitionKey(embeddedSchema, refId)
+                : undefined;
+            if (embeddedMode &&
+                embeddedSchema &&
+                defsKey &&
+                defsKey !== rootTitle &&
+                !ancestry.has(defsKey)) {
+                const embeddedClone = this.createEmbeddedSchemaClone(context, embeddedSchema, embeddedMode);
+                this.inlineEmbeddedSchemasInNode(context, rootSchema, embeddedClone, rootTitle, new Set([...ancestry, defsKey]));
+                if (embeddedMode === EmbeddedSchemaMode.Defs) {
+                    rootSchema.$defs ??= {};
+                    rootSchema.$defs[defsKey] ??= embeddedClone;
+                    currentNode.$ref = `#/$defs/${defsKey}`;
+                }
+                else {
+                    this.replaceSchemaNode(currentNode, embeddedClone);
+                    hasInlineReplacement = true;
+                }
+            }
+        }
+        for (const value of Object.values(currentNode)) {
+            if (Is.array(value)) {
+                for (const item of value) {
+                    if (Is.object(item)) {
+                        hasInlineReplacement =
+                            this.inlineEmbeddedSchemasInNode(context, rootSchema, item, rootTitle, ancestry) ||
+                                hasInlineReplacement;
+                    }
+                }
+            }
+            else if (Is.object(value)) {
+                for (const nestedValue of Object.values(value)) {
+                    if (Is.object(nestedValue)) {
+                        hasInlineReplacement =
+                            this.inlineEmbeddedSchemasInNode(context, rootSchema, nestedValue, rootTitle, ancestry) || hasInlineReplacement;
+                    }
+                }
+            }
+        }
+        if (hasInlineReplacement) {
+            this.flattenInlineAllOfBranches(currentNode);
+        }
+        return hasInlineReplacement;
+    }
+    /**
+     * Flatten inline-expanded object allOf branches into the containing schema.
+     * @param schema The schema to flatten.
+     */
+    flattenInlineAllOfBranches(schema) {
+        if (!Is.array(schema.allOf) || schema.allOf.length === 0) {
+            return;
+        }
+        const remainingBranches = [];
+        const mergedProperties = {};
+        const mergedRequired = new Set((Is.array(schema.required) ? schema.required : []).filter((requiredKey) => Is.stringValue(requiredKey)));
+        let hasMergedBranch = false;
+        for (const branch of schema.allOf) {
+            if (this.canFlattenInlineAllOfBranch(branch)) {
+                hasMergedBranch = true;
+                schema.type ??= "object";
+                if (Is.object(branch.properties)) {
+                    Object.assign(mergedProperties, branch.properties);
+                }
+                if (Is.array(branch.required)) {
+                    for (const requiredKey of branch.required) {
+                        if (Is.stringValue(requiredKey)) {
+                            mergedRequired.add(requiredKey);
+                        }
+                    }
+                }
+            }
+            else {
+                remainingBranches.push(branch);
+            }
+        }
+        if (!hasMergedBranch) {
+            return;
+        }
+        if (Object.keys(mergedProperties).length > 0) {
+            schema.properties = Object.assign(schema.properties ?? {}, mergedProperties);
+        }
+        if (mergedRequired.size > 0) {
+            schema.required = [...mergedRequired];
+        }
+        if (remainingBranches.length > 0) {
+            schema.allOf = remainingBranches;
+        }
+        else {
+            delete schema.allOf;
+        }
+    }
+    /**
+     * Determine whether an allOf branch can be flattened into its parent after inline embedding.
+     * @param branch The allOf branch.
+     * @returns True if the branch is a plain object schema.
+     */
+    canFlattenInlineAllOfBranch(branch) {
+        return Boolean(!branch.$ref &&
+            !branch.allOf &&
+            !branch.anyOf &&
+            !branch.oneOf &&
+            !branch.items &&
+            (branch.type === "object" || Is.object(branch.properties) || Is.array(branch.required)));
+    }
+    /**
+     * Create a clone of an embedded schema suitable for defs or inline expansion.
+     * @param context The generation context.
+     * @param embeddedSchema The source schema.
+     * @param embeddedMode The embedding mode.
+     * @returns The cloned schema.
+     */
+    createEmbeddedSchemaClone(context, embeddedSchema, embeddedMode) {
+        let embeddedClone = ObjectHelper.clone(embeddedSchema);
+        if (embeddedMode === EmbeddedSchemaMode.Inline) {
+            embeddedClone = JsonSchemaBuilder.expandAllOfReferences(context, embeddedClone);
+            this.removeSchemaComments(embeddedClone);
+        }
+        delete embeddedClone.$schema;
+        delete embeddedClone.$id;
+        if (embeddedMode === EmbeddedSchemaMode.Inline) {
+            delete embeddedClone.title;
+        }
+        return embeddedClone;
+    }
+    /**
+     * Replace the contents of a schema node while keeping the same object reference.
+     * @param target The schema node to mutate.
+     * @param replacement The replacement content.
+     */
+    replaceSchemaNode(target, replacement) {
+        for (const key of Object.keys(target)) {
+            delete target[key];
+        }
+        Object.assign(target, replacement);
+    }
+    /**
+     * Find a generated schema by its canonical id across all loaded packages.
+     * @param context The generation context.
+     * @param schemaId The schema id to locate.
+     * @returns The schema when found.
+     */
+    findSchemaById(context, schemaId) {
+        return Object.values(context.schemas)
+            .flatMap(packageSchemas => Object.values(packageSchemas))
+            .find(schema => schema.$id === schemaId);
+    }
+    /**
+     * Resolve the local $defs key to use for an embedded schema.
+     * @param schema The embedded schema.
+     * @param schemaId The canonical schema id.
+     * @returns The local definition key.
+     */
+    getEmbeddedDefinitionKey(schema, schemaId) {
+        return schema.title ?? schemaId.split("/").pop() ?? schemaId;
+    }
+    /**
+     * Remove $comment fields from a schema tree.
+     * @param schema The schema tree to clean.
+     */
+    removeSchemaComments(schema) {
+        delete schema.$comment;
+        for (const value of Object.values(schema)) {
+            if (Is.array(value)) {
+                for (const item of value) {
+                    if (Is.object(item)) {
+                        this.removeSchemaComments(item);
+                    }
+                }
+            }
+            else if (Is.object(value)) {
+                for (const nestedValue of Object.values(value)) {
+                    if (Is.object(nestedValue)) {
+                        this.removeSchemaComments(nestedValue);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * 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