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

package/docs/reference/classes/MappedTypeSchemaResolver.md

@@ -0,0 +1,275 @@
+# Class: MappedTypeSchemaResolver
+
+Static mapped-type schema transformation helpers.
+
+## Constructors
+
+### Constructor
+
+> **new MappedTypeSchemaResolver**(): `MappedTypeSchemaResolver`
+
+#### Returns
+
+`MappedTypeSchemaResolver`
+
+## Methods
+
+### resolveMappedTypePropertyEntries() {#resolvemappedtypepropertyentries}
+
+> `static` **resolveMappedTypePropertyEntries**(`context`, `typeNode`, `mappedKeys`, `mappedTypeParameterName`): `object`[] \| `undefined`
+
+Resolve mapped type output keys, including remapped key names via `as`.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+The generation context.
+
+##### typeNode
+
+`MappedTypeNode`
+
+The mapped type node.
+
+##### mappedKeys
+
+`string`[]
+
+The resolved source keys from the mapped type constraint.
+
+##### mappedTypeParameterName
+
+`string`
+
+The mapped type parameter identifier.
+
+#### Returns
+
+`object`[] \| `undefined`
+
+The resolved source-to-output mapped key entries.
+
+***
+
+### resolveMappedTypeRemappedKey() {#resolvemappedtyperemappedkey}
+
+> `static` **resolveMappedTypeRemappedKey**(`context`, `nameTypeNode`, `sourceKey`, `mappedTypeParameterName`): `string` \| `null` \| `undefined`
+
+Resolve a remapped mapped-type key expression for a concrete source key.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+The generation context.
+
+##### nameTypeNode
+
+`TypeNode`
+
+The mapped type name remapping expression node.
+
+##### sourceKey
+
+`string`
+
+The concrete source key currently being evaluated.
+
+##### mappedTypeParameterName
+
+`string`
+
+The mapped type parameter identifier.
+
+#### Returns
+
+`string` \| `null` \| `undefined`
+
+The remapped key, null when excluded via never, or undefined when unresolved.
+
+***
+
+### evaluateMappedKeyExtendsCondition() {#evaluatemappedkeyextendscondition}
+
+> `static` **evaluateMappedKeyExtendsCondition**(`context`, `sourceKey`, `extendsTypeNode`): `boolean` \| `undefined`
+
+Evaluate whether a concrete mapped key satisfies an `extends` condition.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+The generation context.
+
+##### sourceKey
+
+`string`
+
+The concrete source key being evaluated.
+
+##### extendsTypeNode
+
+`TypeNode`
+
+The extends condition type node.
+
+#### Returns
+
+`boolean` \| `undefined`
+
+True when the key satisfies the condition, false when it does not, otherwise undefined.
+
+***
+
+### buildMappedTypeFallbackSchema() {#buildmappedtypefallbackschema}
+
+> `static` **buildMappedTypeFallbackSchema**(`context`, `typeNode`, `mappedKeys`, `mappedTypeParameterName`, `sourceObjectSchema?`): `IJsonSchema`
+
+Build a conservative fallback schema for mapped types whose key remapping cannot be resolved.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+The generation context.
+
+##### typeNode
+
+`MappedTypeNode`
+
+The mapped type node.
+
+##### mappedKeys
+
+`string`[]
+
+The resolved source keys from the mapped type constraint.
+
+##### mappedTypeParameterName
+
+`string`
+
+The mapped type parameter identifier.
+
+##### sourceObjectSchema?
+
+`IJsonSchema`
+
+The optional source object schema for property lookups.
+
+#### Returns
+
+`IJsonSchema`
+
+The fallback mapped type schema.
+
+***
+
+### buildMappedTypeFallbackAdditionalProperties() {#buildmappedtypefallbackadditionalproperties}
+
+> `static` **buildMappedTypeFallbackAdditionalProperties**(`context`, `typeNode`, `mappedKeys`, `mappedTypeParameterName`, `sourceObjectSchema?`): `IJsonSchema` \| `undefined`
+
+Build fallback additionalProperties for unresolved mapped key remapping.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+The generation context.
+
+##### typeNode
+
+`MappedTypeNode`
+
+The mapped type node.
+
+##### mappedKeys
+
+`string`[]
+
+The resolved source keys from the mapped type constraint.
+
+##### mappedTypeParameterName
+
+`string`
+
+The mapped type parameter identifier.
+
+##### sourceObjectSchema?
+
+`IJsonSchema`
+
+The optional source object schema for property lookups.
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+The fallback additionalProperties schema.
+
+***
+
+### mergeMappedTypePropertySchemas() {#mergemappedtypepropertyschemas}
+
+> `static` **mergeMappedTypePropertySchemas**(`existingSchema`, `nextSchema`): `IJsonSchema`
+
+Merge mapped property schemas when multiple source keys remap to the same output key.
+
+#### Parameters
+
+##### existingSchema
+
+`IJsonSchema`
+
+The existing schema already assigned to the mapped key.
+
+##### nextSchema
+
+`IJsonSchema`
+
+The next schema to merge into the mapped key.
+
+#### Returns
+
+`IJsonSchema`
+
+The merged schema.
+
+***
+
+### resolveMappedTypeSourceRequiredPropertyKeys() {#resolvemappedtypesourcerequiredpropertykeys}
+
+> `static` **resolveMappedTypeSourceRequiredPropertyKeys**(`mappedEntries`, `sourceObjectSchema`): `string`[] \| `undefined`
+
+Resolve required remapped keys from the source object's required key set.
+
+#### Parameters
+
+##### mappedEntries
+
+`object`[]
+
+The source-to-output mapped key entries.
+
+##### sourceObjectSchema
+
+`IJsonSchema`
+
+The source object schema containing required keys.
+
+#### Returns
+
+`string`[] \| `undefined`
+
+The required output keys.

package/docs/reference/classes/ObjectTransformer.md

@@ -0,0 +1,119 @@
+# Class: ObjectTransformer
+
+Applies common object-schema transformations used by the builder.
+
+## Constructors
+
+### Constructor
+
+> **new ObjectTransformer**(): `ObjectTransformer`
+
+#### Returns
+
+`ObjectTransformer`
+
+## Methods
+
+### resolvePropertySchemaFromObjectSchema() {#resolvepropertyschemafromobjectschema}
+
+> `static` **resolvePropertySchemaFromObjectSchema**(`baseSchema`, `propertyKey`): `IJsonSchema` \| `undefined`
+
+Resolve a property schema from an object schema by property key.
+
+#### Parameters
+
+##### baseSchema
+
+`IJsonSchema`
+
+The source object schema.
+
+##### propertyKey
+
+`string`
+
+The property key to resolve.
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+The resolved property schema.
+
+***
+
+### omitKeysFromObjectSchema() {#omitkeysfromobjectschema}
+
+> `static` **omitKeysFromObjectSchema**(`baseSchema`, `omittedKeys`): `IJsonSchema`
+
+Remove keys from an object schema.
+
+#### Parameters
+
+##### baseSchema
+
+`IJsonSchema`
+
+The source object schema.
+
+##### omittedKeys
+
+`string`[]
+
+The keys to remove.
+
+#### Returns
+
+`IJsonSchema`
+
+The transformed object schema.
+
+***
+
+### pickKeysFromObjectSchema() {#pickkeysfromobjectschema}
+
+> `static` **pickKeysFromObjectSchema**(`baseSchema`, `pickedKeys`): `IJsonSchema`
+
+Keep only keys from an object schema.
+
+#### Parameters
+
+##### baseSchema
+
+`IJsonSchema`
+
+The source object schema.
+
+##### pickedKeys
+
+`string`[]
+
+The keys to keep.
+
+#### Returns
+
+`IJsonSchema`
+
+The transformed object schema.
+
+***
+
+### normalizeSchemaDescriptions() {#normalizeschemadescriptions}
+
+> `static` **normalizeSchemaDescriptions**(`schema`): `IJsonSchema`
+
+Normalize schema description whitespace while preserving intentional line breaks.
+
+#### Parameters
+
+##### schema
+
+`IJsonSchema`
+
+The schema to normalize.
+
+#### Returns
+
+`IJsonSchema`
+
+The normalized schema.

package/docs/reference/classes/RegEx.md

@@ -0,0 +1,99 @@
+# Class: RegEx
+
+Utility methods for pattern matching and regex construction.
+
+## Constructors
+
+### Constructor
+
+> **new RegEx**(): `RegEx`
+
+#### Returns
+
+`RegEx`
+
+## Methods
+
+### isReferencePatternMatch() {#isreferencepatternmatch}
+
+> `static` **isReferencePatternMatch**(`pattern`, `packageName`, `typeName`, `schemaTitle`): `boolean`
+
+Determine whether a reference mapping pattern matches an external reference.
+
+#### Parameters
+
+##### pattern
+
+`string`
+
+The mapping pattern.
+
+##### packageName
+
+`string`
+
+The external package name.
+
+##### typeName
+
+`string`
+
+The imported type name.
+
+##### schemaTitle
+
+`string`
+
+The derived schema title.
+
+#### Returns
+
+`boolean`
+
+True if matched.
+
+***
+
+### applyReferencePatternReplacement() {#applyreferencepatternreplacement}
+
+> `static` **applyReferencePatternReplacement**(`pattern`, `replacement`, `packageName`, `typeName`, `schemaTitle`): `string` \| `undefined`
+
+Apply a reference mapping replacement to the first matching candidate.
+
+#### Parameters
+
+##### pattern
+
+`string`
+
+The mapping pattern.
+
+##### replacement
+
+`string`
+
+The replacement template.
+
+##### packageName
+
+`string`
+
+The external package name.
+
+##### typeName
+
+`string`
+
+The imported type name.
+
+##### schemaTitle
+
+`string`
+
+The derived schema title.
+
+#### Returns
+
+`string` \| `undefined`
+
+The replaced value if a candidate matches.

package/docs/reference/classes/Resolver.md

@@ -0,0 +1,52 @@
+# Class: Resolver
+
+Resolve TypeScript type declarations from package names.
+
+## Constructors
+
+### Constructor
+
+> **new Resolver**(): `Resolver`
+
+#### Returns
+
+`Resolver`
+
+## Methods
+
+### resolveTypeDeclarationAst() {#resolvetypedeclarationast}
+
+> `static` **resolveTypeDeclarationAst**(`packageName`, `typeName`, `containingFilePath?`): \{ `sourceFile`: `SourceFile`; `declaration`: `InterfaceDeclaration` \| `TypeAliasDeclaration`; \} \| `undefined`
+
+Resolve a type declaration AST from a package and type name.
+
+#### Parameters
+
+##### packageName
+
+`string`
+
+The package to inspect.
+
+##### typeName
+
+`string`
+
+The type to resolve.
+
+##### containingFilePath?
+
+`string`
+
+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
+
+\{ `sourceFile`: `SourceFile`; `declaration`: `InterfaceDeclaration` \| `TypeAliasDeclaration`; \} \| `undefined`
+
+The resolved declaration AST.

package/docs/reference/classes/TemplateLiteralPatternBuilder.md

@@ -0,0 +1,35 @@
+# Class: TemplateLiteralPatternBuilder
+
+Builds regex patterns for TypeScript template literal types.
+
+## Constructors
+
+### Constructor
+
+> **new TemplateLiteralPatternBuilder**(): `TemplateLiteralPatternBuilder`
+
+#### Returns
+
+`TemplateLiteralPatternBuilder`
+
+## Methods
+
+### buildTemplateLiteralPattern() {#buildtemplateliteralpattern}
+
+> `static` **buildTemplateLiteralPattern**(`typeNode`): `string` \| `undefined`
+
+Build a regular-expression pattern for a template literal type.
+
+#### Parameters
+
+##### typeNode
+
+`TemplateLiteralTypeNode`
+
+The template literal type node.
+
+#### Returns
+
+`string` \| `undefined`
+
+The regex pattern, or undefined if a safe pattern cannot be derived.

package/docs/reference/classes/TypeScriptToSchema.md

@@ -0,0 +1,91 @@
+# Class: TypeScriptToSchema
+
+Class for converting TypeScript types to JSON Schema.
+
+## Constructors
+
+### Constructor
+
+> **new TypeScriptToSchema**(): `TypeScriptToSchema`
+
+#### Returns
+
+`TypeScriptToSchema`
+
+## Methods
+
+### generateSchema() {#generateschema}
+
+> **generateSchema**(`namespace`, `packageName`, `schemas`, `sourceFileOrTypeName`, `options?`): `Promise`\<\{\[`id`: `string`\]: `IJsonSchema`; \}\>
+
+Generates a JSON schema from a TypeScript source file or type name.
+
+#### Parameters
+
+##### namespace
+
+`string`
+
+The schema namespace.
+
+##### packageName
+
+`string`
+
+The package name.
+
+##### schemas
+
+The package schema map.
+
+##### sourceFileOrTypeName
+
+`string`
+
+The source file to process or type name to resolve.
+
+##### options?
+
+[`ITypeScriptToSchemaOptions`](../interfaces/ITypeScriptToSchemaOptions.md)
+
+Additional generation options.
+
+#### Returns
+
+`Promise`\<\{\[`id`: `string`\]: `IJsonSchema`; \}\>
+
+The generated JSON schemas indexed by title.
+
+***
+
+### isDiagnosticFromPackage() {#isdiagnosticfrompackage}
+
+> **isDiagnosticFromPackage**(`path`, `fileName`, `packageName`): `boolean`
+
+Determine if a diagnostic originates from a specific package.
+
+#### Parameters
+
+##### path
+
+`string`
+
+The schema or source path associated with the diagnostic.
+
+##### fileName
+
+`string` \| `undefined`
+
+The source filename associated with the diagnostic.
+
+##### packageName
+
+`string`
+
+The package name to check, e.g. jose.
+
+#### Returns
+
+`boolean`
+
+True if the diagnostic originated from the package.