@twin.org/tools-core 0.0.3-next.9 → 0.0.3

package/dist/es/utils/indexSignaturePatternResolver.js

@@ -0,0 +1,94 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import * as ts from "typescript";
+import { TemplateLiteralPatternBuilder } from "./templateLiteralPatternBuilder.js";
+/**
+ * Resolves regex patterns for index signature key types.
+ */
+export 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) {
+        // [key: string]: Value  (index signature, first parameter is the key)
+        const indexParameter = member.parameters[0];
+        if (!indexParameter?.type) {
+            return false;
+        }
+        // [key: string]: Value  or  [key: number]: Value  (string or numeric key)
+        return (indexParameter.type.kind === ts.SyntaxKind.StringKeyword ||
+            indexParameter.type.kind === ts.SyntaxKind.NumberKeyword);
+    }
+    /**
+     * 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, member, getTypeParameterBinding) {
+        const indexParameterType = member.parameters[0]?.type;
+        if (!indexParameterType) {
+            return undefined;
+        }
+        const resolvedTemplateType = IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(context, indexParameterType, new Set(), getTypeParameterBinding);
+        return resolvedTemplateType
+            ? TemplateLiteralPatternBuilder.buildTemplateLiteralPattern(resolvedTemplateType)
+            : undefined;
+    }
+    /**
+     * Resolve a template literal type node from a key-type expression.
+     * Handles parenthesised, readonly-wrapped, and type-aliased variants by recursing.
+     * A cycle guard via resolvingTypeNames prevents unbounded recursion on self-referential types.
+     * @param context The generation context.
+     * @param typeNode The key type node.
+     * @param resolvingTypeNames Type names currently being resolved.
+     * @param getTypeParameterBinding Callback for resolving generic bindings.
+     * @returns A template literal type node when resolvable.
+     * @internal
+     */
+    static resolveTemplateLiteralTypeNode(context, typeNode, resolvingTypeNames, getTypeParameterBinding) {
+        // `prefix-${T}` or `${K}`  (already a template literal type)
+        if (ts.isTemplateLiteralTypeNode(typeNode)) {
+            return typeNode;
+        }
+        // (KeyType)  (parenthesised type, unwrap and recurse)
+        if (ts.isParenthesizedTypeNode(typeNode)) {
+            return IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(context, typeNode.type, resolvingTypeNames, getTypeParameterBinding);
+        }
+        // readonly KeyType  (readonly-wrapped type operator, strip modifier and recurse)
+        if (ts.isTypeOperatorNode(typeNode) && typeNode.operator === ts.SyntaxKind.ReadonlyKeyword) {
+            return IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(context, typeNode.type, resolvingTypeNames, getTypeParameterBinding);
+        }
+        // MyKeyType  (named type reference, resolve via binding or type alias in source file)
+        if (ts.isTypeReferenceNode(typeNode)) {
+            // Namespace.TypeName  (qualified name) or TypeName  (plain identifier)
+            const typeName = ts.isIdentifier(typeNode.typeName)
+                ? typeNode.typeName.text
+                : typeNode.typeName.right.text;
+            if (resolvingTypeNames.has(typeName)) {
+                return undefined;
+            }
+            const typeParameterBinding = getTypeParameterBinding(context, typeName);
+            if (typeParameterBinding) {
+                return IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(context, typeParameterBinding, resolvingTypeNames, getTypeParameterBinding);
+            }
+            const sourceFile = context.activeSourceFile;
+            if (!sourceFile) {
+                return undefined;
+            }
+            // type MyKeyType = `prefix-${string}`  (look up a type alias in the active source file)
+            const typeAlias = sourceFile.statements.find((statement) => ts.isTypeAliasDeclaration(statement) && statement.name.text === typeName);
+            if (typeAlias) {
+                resolvingTypeNames.add(typeName);
+                const resolvedTemplateType = IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(context, typeAlias.type, resolvingTypeNames, getTypeParameterBinding);
+                resolvingTypeNames.delete(typeName);
+                return resolvedTemplateType;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=indexSignaturePatternResolver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"indexSignaturePatternResolver.js","sourceRoot":"","sources":["../../../src/utils/indexSignaturePatternResolver.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 { TemplateLiteralPatternBuilder } from \"./templateLiteralPatternBuilder.js\";\nimport type { ITypeScriptToSchemaContext } from \"../models/ITypeScriptToSchemaContext.js\";\n\n/**\n * Resolves regex patterns for index signature key types.\n */\nexport class IndexSignaturePatternResolver {\n\t/**\n\t * Determine whether an index signature can be represented as JSON object additionalProperties.\n\t * @param member The index signature declaration.\n\t * @returns True if supported.\n\t */\n\tpublic static isSupportedIndexSignature(member: ts.IndexSignatureDeclaration): boolean {\n\t\t// [key: string]: Value  (index signature, first parameter is the key)\n\t\tconst indexParameter = member.parameters[0];\n\t\tif (!indexParameter?.type) {\n\t\t\treturn false;\n\t\t}\n\n\t\t// [key: string]: Value  or  [key: number]: Value  (string or numeric key)\n\t\treturn (\n\t\t\tindexParameter.type.kind === ts.SyntaxKind.StringKeyword ||\n\t\t\tindexParameter.type.kind === ts.SyntaxKind.NumberKeyword\n\t\t);\n\t}\n\n\t/**\n\t * Extract a regex pattern for an index signature key type when representable.\n\t * @param context The generation context.\n\t * @param member The index signature declaration.\n\t * @param getTypeParameterBinding Callback for resolving generic bindings.\n\t * @returns The property-name pattern, if derivable.\n\t */\n\tpublic static extractIndexSignaturePattern(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\tmember: ts.IndexSignatureDeclaration,\n\t\tgetTypeParameterBinding: (\n\t\t\tcontext: ITypeScriptToSchemaContext,\n\t\t\ttypeName: string\n\t\t) => ts.TypeNode | null | undefined\n\t): string | undefined {\n\t\tconst indexParameterType = member.parameters[0]?.type;\n\t\tif (!indexParameterType) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst resolvedTemplateType = IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(\n\t\t\tcontext,\n\t\t\tindexParameterType,\n\t\t\tnew Set<string>(),\n\t\t\tgetTypeParameterBinding\n\t\t);\n\n\t\treturn resolvedTemplateType\n\t\t\t? TemplateLiteralPatternBuilder.buildTemplateLiteralPattern(resolvedTemplateType)\n\t\t\t: undefined;\n\t}\n\n\t/**\n\t * Resolve a template literal type node from a key-type expression.\n\t * Handles parenthesised, readonly-wrapped, and type-aliased variants by recursing.\n\t * A cycle guard via resolvingTypeNames prevents unbounded recursion on self-referential types.\n\t * @param context The generation context.\n\t * @param typeNode The key type node.\n\t * @param resolvingTypeNames Type names currently being resolved.\n\t * @param getTypeParameterBinding Callback for resolving generic bindings.\n\t * @returns A template literal type node when resolvable.\n\t * @internal\n\t */\n\tprivate static resolveTemplateLiteralTypeNode(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\ttypeNode: ts.TypeNode,\n\t\tresolvingTypeNames: Set<string>,\n\t\tgetTypeParameterBinding: (\n\t\t\tcontext: ITypeScriptToSchemaContext,\n\t\t\ttypeName: string\n\t\t) => ts.TypeNode | null | undefined\n\t): ts.TemplateLiteralTypeNode | undefined {\n\t\t// `prefix-${T}` or `${K}`  (already a template literal type)\n\t\tif (ts.isTemplateLiteralTypeNode(typeNode)) {\n\t\t\treturn typeNode;\n\t\t}\n\n\t\t// (KeyType)  (parenthesised type, unwrap and recurse)\n\t\tif (ts.isParenthesizedTypeNode(typeNode)) {\n\t\t\treturn IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(\n\t\t\t\tcontext,\n\t\t\t\ttypeNode.type,\n\t\t\t\tresolvingTypeNames,\n\t\t\t\tgetTypeParameterBinding\n\t\t\t);\n\t\t}\n\n\t\t// readonly KeyType  (readonly-wrapped type operator, strip modifier and recurse)\n\t\tif (ts.isTypeOperatorNode(typeNode) && typeNode.operator === ts.SyntaxKind.ReadonlyKeyword) {\n\t\t\treturn IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(\n\t\t\t\tcontext,\n\t\t\t\ttypeNode.type,\n\t\t\t\tresolvingTypeNames,\n\t\t\t\tgetTypeParameterBinding\n\t\t\t);\n\t\t}\n\n\t\t// MyKeyType  (named type reference, resolve via binding or type alias in source file)\n\t\tif (ts.isTypeReferenceNode(typeNode)) {\n\t\t\t// Namespace.TypeName  (qualified name) or TypeName  (plain identifier)\n\t\t\tconst typeName = ts.isIdentifier(typeNode.typeName)\n\t\t\t\t? typeNode.typeName.text\n\t\t\t\t: typeNode.typeName.right.text;\n\n\t\t\tif (resolvingTypeNames.has(typeName)) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst typeParameterBinding = getTypeParameterBinding(context, typeName);\n\t\t\tif (typeParameterBinding) {\n\t\t\t\treturn IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(\n\t\t\t\t\tcontext,\n\t\t\t\t\ttypeParameterBinding,\n\t\t\t\t\tresolvingTypeNames,\n\t\t\t\t\tgetTypeParameterBinding\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst sourceFile = context.activeSourceFile;\n\t\t\tif (!sourceFile) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\t// type MyKeyType = `prefix-${string}`  (look up a type alias in the active source file)\n\t\t\tconst typeAlias = sourceFile.statements.find(\n\t\t\t\t(statement): statement is ts.TypeAliasDeclaration =>\n\t\t\t\t\tts.isTypeAliasDeclaration(statement) && statement.name.text === typeName\n\t\t\t);\n\n\t\t\tif (typeAlias) {\n\t\t\t\tresolvingTypeNames.add(typeName);\n\t\t\t\tconst resolvedTemplateType = IndexSignaturePatternResolver.resolveTemplateLiteralTypeNode(\n\t\t\t\t\tcontext,\n\t\t\t\t\ttypeAlias.type,\n\t\t\t\t\tresolvingTypeNames,\n\t\t\t\t\tgetTypeParameterBinding\n\t\t\t\t);\n\t\t\t\tresolvingTypeNames.delete(typeName);\n\t\t\t\treturn resolvedTemplateType;\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n}\n"]}

package/dist/es/utils/intersectionSchemaMerger.js

@@ -0,0 +1,85 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Is, ObjectHelper } from "@twin.org/core";
+/**
+ * Merges compatible object intersections into a single JSON schema object.
+ */
+export 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, schemas, toInlineUtilityObjectSchema) {
+        const mergedProperties = {};
+        const mergedRequired = new Set();
+        const preservedRefs = new Set();
+        for (const schema of schemas) {
+            const isRefSchema = Is.stringValue(schema.$ref);
+            if (isRefSchema && schema.$ref) {
+                preservedRefs.add(schema.$ref);
+            }
+            const objectSchema = IntersectionSchemaMerger.resolveIntersectionObjectSchema(context, schema, toInlineUtilityObjectSchema);
+            if (!objectSchema) {
+                return undefined;
+            }
+            if (objectSchema.$ref ||
+                objectSchema.allOf ||
+                objectSchema.anyOf ||
+                objectSchema.oneOf ||
+                objectSchema.items) {
+                return undefined;
+            }
+            if (!isRefSchema) {
+                if (Is.object(objectSchema.properties)) {
+                    for (const [propertyName, propertySchema] of Object.entries(objectSchema.properties)) {
+                        mergedProperties[propertyName] = propertySchema;
+                    }
+                }
+                if (Is.array(objectSchema.required)) {
+                    for (const propertyName of objectSchema.required) {
+                        mergedRequired.add(propertyName);
+                    }
+                }
+            }
+        }
+        return {
+            type: "object",
+            properties: Object.keys(mergedProperties).length > 0 ? mergedProperties : undefined,
+            required: mergedRequired.size > 0 ? [...mergedRequired] : undefined,
+            allOf: preservedRefs.size > 0
+                ? [...preservedRefs].map(schemaRef => ({
+                    $ref: schemaRef
+                }))
+                : undefined
+        };
+    }
+    /**
+     * Resolve an intersection component to a plain object schema when possible.
+     * @param context The generation context.
+     * @param schema The mapped intersection component schema.
+     * @returns The resolved object schema.
+     * @internal
+     */
+    static resolveIntersectionObjectSchema(context, schema, toInlineUtilityObjectSchema) {
+        if (schema.type === "object" && Is.object(schema.properties)) {
+            return ObjectHelper.clone(schema);
+        }
+        if (schema.$ref) {
+            for (const packageSchemas of Object.values(context.schemas)) {
+                for (const referencedSchema of Object.values(packageSchemas)) {
+                    if (referencedSchema.$id === schema.$ref &&
+                        referencedSchema.type === "object" &&
+                        Is.object(referencedSchema.properties)) {
+                        return toInlineUtilityObjectSchema(referencedSchema);
+                    }
+                }
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=intersectionSchemaMerger.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"intersectionSchemaMerger.js","sourceRoot":"","sources":["../../../src/utils/intersectionSchemaMerger.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is, ObjectHelper } from \"@twin.org/core\";\nimport type { IJsonSchema } from \"@twin.org/tools-models\";\nimport type { ITypeScriptToSchemaContext } from \"../models/ITypeScriptToSchemaContext.js\";\n\n/**\n * Merges compatible object intersections into a single JSON schema object.\n */\nexport class IntersectionSchemaMerger {\n\t/**\n\t * Merge simple object intersection parts into a single object schema.\n\t * Supports local/known object refs by expanding them before merge.\n\t * @param context The generation context.\n\t * @param schemas The mapped intersection schemas.\n\t * @param toInlineUtilityObjectSchema Callback for converting referenced schemas to inline forms.\n\t * @returns The merged schema, or undefined when merge is not safe.\n\t */\n\tpublic static mergeIntersectionObjectSchemas(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\tschemas: IJsonSchema[],\n\t\ttoInlineUtilityObjectSchema: (schema: IJsonSchema) => IJsonSchema\n\t): IJsonSchema | undefined {\n\t\tconst mergedProperties: { [id: string]: IJsonSchema } = {};\n\t\tconst mergedRequired = new Set<string>();\n\t\tconst preservedRefs = new Set<string>();\n\n\t\tfor (const schema of schemas) {\n\t\t\tconst isRefSchema = Is.stringValue(schema.$ref);\n\t\t\tif (isRefSchema && schema.$ref) {\n\t\t\t\tpreservedRefs.add(schema.$ref);\n\t\t\t}\n\n\t\t\tconst objectSchema = IntersectionSchemaMerger.resolveIntersectionObjectSchema(\n\t\t\t\tcontext,\n\t\t\t\tschema,\n\t\t\t\ttoInlineUtilityObjectSchema\n\t\t\t);\n\t\t\tif (!objectSchema) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\t\t\tif (\n\t\t\t\tobjectSchema.$ref ||\n\t\t\t\tobjectSchema.allOf ||\n\t\t\t\tobjectSchema.anyOf ||\n\t\t\t\tobjectSchema.oneOf ||\n\t\t\t\tobjectSchema.items\n\t\t\t) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tif (!isRefSchema) {\n\t\t\t\tif (Is.object(objectSchema.properties)) {\n\t\t\t\t\tfor (const [propertyName, propertySchema] of Object.entries(objectSchema.properties)) {\n\t\t\t\t\t\tmergedProperties[propertyName] = propertySchema;\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tif (Is.array(objectSchema.required)) {\n\t\t\t\t\tfor (const propertyName of objectSchema.required) {\n\t\t\t\t\t\tmergedRequired.add(propertyName);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\ttype: \"object\",\n\t\t\tproperties: Object.keys(mergedProperties).length > 0 ? mergedProperties : undefined,\n\t\t\trequired: mergedRequired.size > 0 ? [...mergedRequired] : undefined,\n\t\t\tallOf:\n\t\t\t\tpreservedRefs.size > 0\n\t\t\t\t\t? [...preservedRefs].map(schemaRef => ({\n\t\t\t\t\t\t\t$ref: schemaRef\n\t\t\t\t\t\t}))\n\t\t\t\t\t: undefined\n\t\t};\n\t}\n\n\t/**\n\t * Resolve an intersection component to a plain object schema when possible.\n\t * @param context The generation context.\n\t * @param schema The mapped intersection component schema.\n\t * @returns The resolved object schema.\n\t * @internal\n\t */\n\tprivate static resolveIntersectionObjectSchema(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\tschema: IJsonSchema,\n\t\ttoInlineUtilityObjectSchema: (schema: IJsonSchema) => IJsonSchema\n\t): IJsonSchema | undefined {\n\t\tif (schema.type === \"object\" && Is.object(schema.properties)) {\n\t\t\treturn ObjectHelper.clone(schema);\n\t\t}\n\n\t\tif (schema.$ref) {\n\t\t\tfor (const packageSchemas of Object.values(context.schemas)) {\n\t\t\t\tfor (const referencedSchema of Object.values(packageSchemas)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\treferencedSchema.$id === schema.$ref &&\n\t\t\t\t\t\treferencedSchema.type === \"object\" &&\n\t\t\t\t\t\tIs.object(referencedSchema.properties)\n\t\t\t\t\t) {\n\t\t\t\t\t\treturn toInlineUtilityObjectSchema(referencedSchema);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n}\n"]}

package/dist/es/utils/jsDoc.js

@@ -0,0 +1,138 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Is } from "@twin.org/core";
+import * as ts from "typescript";
+/**
+ * General-purpose utility methods for working with JsDoc.
+ */
+export 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) {
+        // /** Description text */ (JSDoc block attached to a declaration)
+        const jsDocNodes = ts
+            .getJSDocCommentsAndTags(node)
+            .filter(commentOrTag => ts.isJSDoc(commentOrTag));
+        const description = jsDocNodes
+            .map(jsDocNode => ts.getTextOfJSDocComment(jsDocNode.comment)?.trim())
+            .find((value) => Boolean(value));
+        if (description) {
+            return description;
+        }
+        return 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) {
+        if (Is.string(jsDocTag.comment)) {
+            return jsDocTag.comment;
+        }
+        if (Is.array(jsDocTag.comment)) {
+            return jsDocTag.comment
+                .map(part => part.text)
+                .join("")
+                .trim();
+        }
+        return 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, tagName) {
+        const output = {};
+        for (const jsDocTag of ts.getJSDocTags(node)) {
+            if (jsDocTag.tagName.text === tagName) {
+                const commentText = JsDoc.getJSDocTagCommentText(jsDocTag);
+                if (commentText) {
+                    const separatorIndex = commentText.indexOf(":");
+                    if (separatorIndex > 0) {
+                        const key = commentText.slice(0, separatorIndex).trim();
+                        const value = commentText.slice(separatorIndex + 1).trim();
+                        if (key.length > 0) {
+                            output[key] = value;
+                        }
+                    }
+                }
+            }
+        }
+        return output;
+    }
+    /**
+     * 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, tagName) {
+        for (const jsDocTag of ts.getJSDocTags(node)) {
+            if (jsDocTag.tagName.text === tagName) {
+                const commentText = JsDoc.getJSDocTagCommentText(jsDocTag)?.trim();
+                if (commentText) {
+                    return commentText;
+                }
+            }
+        }
+        return 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, tagName) {
+        const results = [];
+        for (const jsDocTag of ts.getJSDocTags(node)) {
+            if (jsDocTag.tagName.text === tagName) {
+                const commentText = JsDoc.getJSDocTagCommentText(jsDocTag)?.trim();
+                if (commentText) {
+                    results.push(commentText);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * 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) {
+        const trimmedValue = value.trim();
+        if (trimmedValue.length === 0) {
+            return "";
+        }
+        const startsWithJsonToken = trimmedValue.startsWith("{") ||
+            trimmedValue.startsWith("[") ||
+            trimmedValue.startsWith('"') ||
+            trimmedValue === "true" ||
+            trimmedValue === "false" ||
+            trimmedValue === "null" ||
+            /^-?\d+(\.\d+)?$/u.test(trimmedValue);
+        if (!startsWithJsonToken) {
+            return trimmedValue;
+        }
+        try {
+            return JSON.parse(trimmedValue);
+        }
+        catch {
+            return trimmedValue;
+        }
+    }
+}
+//# sourceMappingURL=jsDoc.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsDoc.js","sourceRoot":"","sources":["../../../src/utils/jsDoc.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 * General-purpose utility methods for working with JsDoc.\n */\nexport class JsDoc {\n\t/**\n\t * Extract the JSDoc description comment for an AST node.\n\t * Only top-level JSDoc block comments are considered; inline tags are ignored.\n\t * @param node The node to inspect.\n\t * @returns The trimmed description text, or undefined when absent.\n\t */\n\tpublic static getNodeJsDocDescription(node: ts.Node): string | undefined {\n\t\t// /** Description text */ (JSDoc block attached to a declaration)\n\t\tconst jsDocNodes = ts\n\t\t\t.getJSDocCommentsAndTags(node)\n\t\t\t.filter(commentOrTag => ts.isJSDoc(commentOrTag));\n\t\tconst description = jsDocNodes\n\t\t\t.map(jsDocNode => ts.getTextOfJSDocComment(jsDocNode.comment)?.trim())\n\t\t\t.find((value): value is string => Boolean(value));\n\n\t\tif (description) {\n\t\t\treturn description;\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Convert a JSDoc tag's comment portion to a plain text string.\n\t * JSDoc tag comments may be plain strings or arrays of link/text parts.\n\t * @param jsDocTag The JSDoc tag.\n\t * @returns The comment text, or undefined when absent.\n\t */\n\tpublic static getJSDocTagCommentText(jsDocTag: ts.JSDocTag): string | undefined {\n\t\tif (Is.string(jsDocTag.comment)) {\n\t\t\treturn jsDocTag.comment;\n\t\t}\n\n\t\tif (Is.array(jsDocTag.comment)) {\n\t\t\treturn jsDocTag.comment\n\t\t\t\t.map(part => part.text)\n\t\t\t\t.join(\"\")\n\t\t\t\t.trim();\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Read all custom JSDoc tags matching a tag name from a node and convert them to key/value pairs.\n\t * Each matching tag's comment must be in the form \"key: value\"; entries that do not follow this\n\t * convention are silently skipped.\n\t * @param node The node to inspect.\n\t * @param tagName The tag name to filter by (e.g., 'json-schema').\n\t * @returns The extracted key/value pairs.\n\t */\n\tpublic static getNodeTags(node: ts.Node, tagName: string): { [id: string]: string } {\n\t\tconst output: { [id: string]: string } = {};\n\t\tfor (const jsDocTag of ts.getJSDocTags(node)) {\n\t\t\tif (jsDocTag.tagName.text === tagName) {\n\t\t\t\tconst commentText = JsDoc.getJSDocTagCommentText(jsDocTag);\n\t\t\t\tif (commentText) {\n\t\t\t\t\tconst separatorIndex = commentText.indexOf(\":\");\n\t\t\t\t\tif (separatorIndex > 0) {\n\t\t\t\t\t\tconst key = commentText.slice(0, separatorIndex).trim();\n\t\t\t\t\t\tconst value = commentText.slice(separatorIndex + 1).trim();\n\t\t\t\t\t\tif (key.length > 0) {\n\t\t\t\t\t\t\toutput[key] = value;\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}\n\n\t\treturn output;\n\t}\n\n\t/**\n\t * Read the plain comment text for the first matching JSDoc tag on a node.\n\t * @param node The node to inspect.\n\t * @param tagName The tag name to filter by (e.g., 'default').\n\t * @returns The trimmed comment text, or undefined when absent.\n\t */\n\tpublic static getNodeTagComment(node: ts.Node, tagName: string): string | undefined {\n\t\tfor (const jsDocTag of ts.getJSDocTags(node)) {\n\t\t\tif (jsDocTag.tagName.text === tagName) {\n\t\t\t\tconst commentText = JsDoc.getJSDocTagCommentText(jsDocTag)?.trim();\n\t\t\t\tif (commentText) {\n\t\t\t\t\treturn commentText;\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 the plain comment text for all matching JSDoc tags on a node.\n\t * @param node The node to inspect.\n\t * @param tagName The tag name to filter by (e.g., 'example').\n\t * @returns An array of trimmed comment texts for all matching tags.\n\t */\n\tpublic static getNodeTagComments(node: ts.Node, tagName: string): string[] {\n\t\tconst results: string[] = [];\n\t\tfor (const jsDocTag of ts.getJSDocTags(node)) {\n\t\t\tif (jsDocTag.tagName.text === tagName) {\n\t\t\t\tconst commentText = JsDoc.getJSDocTagCommentText(jsDocTag)?.trim();\n\t\t\t\tif (commentText) {\n\t\t\t\t\tresults.push(commentText);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn results;\n\t}\n\n\t/**\n\t * Parse a custom JSDoc tag value into JSON-compatible data.\n\t * Values that begin with a JSON token character (open brace, open bracket, double quote, true, false, null) or look like a\n\t * number are parsed with JSON.parse.  All other values are returned as plain strings.\n\t * @param value The raw value text.\n\t * @returns The parsed value.\n\t */\n\tpublic static parseTagValue(value: string): unknown {\n\t\tconst trimmedValue = value.trim();\n\t\tif (trimmedValue.length === 0) {\n\t\t\treturn \"\";\n\t\t}\n\n\t\tconst startsWithJsonToken =\n\t\t\ttrimmedValue.startsWith(\"{\") ||\n\t\t\ttrimmedValue.startsWith(\"[\") ||\n\t\t\ttrimmedValue.startsWith('\"') ||\n\t\t\ttrimmedValue === \"true\" ||\n\t\t\ttrimmedValue === \"false\" ||\n\t\t\ttrimmedValue === \"null\" ||\n\t\t\t/^-?\\d+(\\.\\d+)?$/u.test(trimmedValue);\n\n\t\tif (!startsWithJsonToken) {\n\t\t\treturn trimmedValue;\n\t\t}\n\n\t\ttry {\n\t\t\treturn JSON.parse(trimmedValue);\n\t\t} catch {\n\t\t\treturn trimmedValue;\n\t\t}\n\t}\n}\n"]}