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

package/dist/types/utils/mappedTypeSchemaResolver.d.ts

@@ -0,0 +1,46 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+import * as ts from "typescript";
+import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaContext.js";
+/**
+ * Static mapped-type schema transformation helpers.
+ */
+export declare class MappedTypeSchemaResolver {
+    /**
+     * Resolve mapped type output keys, including remapped key names via `as`.
+     */
+    static resolveMappedTypePropertyEntries(context: ITypeScriptToSchemaContext, typeNode: ts.MappedTypeNode, mappedKeys: string[], mappedTypeParameterName: string): {
+        sourceKey: string;
+        mappedKey: string;
+    }[] | undefined;
+    /**
+     * Resolve a remapped mapped-type key expression for a concrete source key.
+     */
+    static resolveMappedTypeRemappedKey(context: ITypeScriptToSchemaContext, nameTypeNode: ts.TypeNode, sourceKey: string, mappedTypeParameterName: string): string | null | undefined;
+    /**
+     * Evaluate whether a concrete mapped key satisfies an `extends` condition.
+     */
+    static evaluateMappedKeyExtendsCondition(context: ITypeScriptToSchemaContext, sourceKey: string, extendsTypeNode: ts.TypeNode): boolean | undefined;
+    /**
+     * Build a conservative fallback schema for mapped types whose key remapping cannot be resolved.
+     */
+    static buildMappedTypeFallbackSchema(context: ITypeScriptToSchemaContext, typeNode: ts.MappedTypeNode, mappedKeys: string[], mappedTypeParameterName: string, sourceObjectSchema?: IJsonSchema): IJsonSchema;
+    /**
+     * Build fallback additionalProperties for unresolved mapped key remapping.
+     */
+    static buildMappedTypeFallbackAdditionalProperties(context: ITypeScriptToSchemaContext, typeNode: ts.MappedTypeNode, mappedKeys: string[], mappedTypeParameterName: string, sourceObjectSchema?: IJsonSchema): IJsonSchema | undefined;
+    /**
+     * Merge mapped property schemas when multiple source keys remap to the same output key.
+     */
+    static mergeMappedTypePropertySchemas(existingSchema: IJsonSchema, nextSchema: IJsonSchema): IJsonSchema;
+    /**
+     * Resolve required remapped keys from the source object's required key set.
+     */
+    static resolveMappedTypeSourceRequiredPropertyKeys(mappedEntries: {
+        sourceKey: string;
+        mappedKey: string;
+    }[], sourceObjectSchema: IJsonSchema): string[] | undefined;
+    /**
+     * Apply TypeScript intrinsic string remapping helpers to a key.
+     */
+    private static applyIntrinsicMappedTypeKeyRemap;
+}

package/dist/types/utils/objectTransformer.d.ts

@@ -0,0 +1,33 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+/**
+ * Applies common object-schema transformations used by the builder.
+ */
+export declare class ObjectTransformer {
+    /**
+     * Resolve a property schema from an object schema by property key.
+     * @param baseSchema The source object schema.
+     * @param propertyKey The property key to resolve.
+     * @returns The resolved property schema.
+     */
+    static resolvePropertySchemaFromObjectSchema(baseSchema: IJsonSchema, propertyKey: string): IJsonSchema | undefined;
+    /**
+     * Remove keys from an object schema.
+     * @param baseSchema The source object schema.
+     * @param omittedKeys The keys to remove.
+     * @returns The transformed object schema.
+     */
+    static omitKeysFromObjectSchema(baseSchema: IJsonSchema, omittedKeys: string[]): IJsonSchema;
+    /**
+     * Keep only keys from an object schema.
+     * @param baseSchema The source object schema.
+     * @param pickedKeys The keys to keep.
+     * @returns The transformed object schema.
+     */
+    static pickKeysFromObjectSchema(baseSchema: IJsonSchema, pickedKeys: string[]): IJsonSchema;
+    /**
+     * Normalize schema description whitespace while preserving intentional line breaks.
+     * @param schema The schema to normalize.
+     * @returns The normalized schema.
+     */
+    static normalizeSchemaDescriptions(schema: IJsonSchema): IJsonSchema;
+}

package/dist/types/utils/regEx.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Utility methods for pattern matching and regex construction.
+ */
+export declare class RegEx {
+    /**
+     * Determine whether a reference mapping pattern matches an external reference.
+     * @param pattern The mapping pattern.
+     * @param packageName The external package name.
+     * @param typeName The imported type name.
+     * @param schemaTitle The derived schema title.
+     * @returns True if matched.
+     */
+    static isReferencePatternMatch(pattern: string, packageName: string, typeName: string, schemaTitle: string): boolean;
+    /**
+     * Apply a reference mapping replacement to the first matching candidate.
+     * @param pattern The mapping pattern.
+     * @param replacement The replacement template.
+     * @param packageName The external package name.
+     * @param typeName The imported type name.
+     * @param schemaTitle The derived schema title.
+     * @returns The replaced value if a candidate matches.
+     */
+    static applyReferencePatternReplacement(pattern: string, replacement: string, packageName: string, typeName: string, schemaTitle: string): string | undefined;
+}

package/dist/types/utils/resolver.d.ts

@@ -0,0 +1,16 @@
+import * as ts from "typescript";
+/**
+ * Resolve TypeScript type declarations from package names.
+ */
+export declare class Resolver {
+    /**
+     * 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: string, typeName: string): {
+        sourceFile: ts.SourceFile;
+        declaration: ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
+    } | undefined;
+}

package/dist/types/utils/templateLiteralPatternBuilder.d.ts

@@ -0,0 +1,12 @@
+import * as ts from "typescript";
+/**
+ * Builds regex patterns for TypeScript template literal types.
+ */
+export declare 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: ts.TemplateLiteralTypeNode): string | undefined;
+}

package/dist/types/utils/typeScriptToSchema.d.ts

@@ -0,0 +1,31 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+import type { ITypeScriptToSchemaOptions } from "../models/ITypeScriptToSchemaOptions.js";
+/**
+ * Class for converting TypeScript types to JSON Schema.
+ */
+export declare 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.
+     */
+    generateSchema(namespace: string, packageName: string, schemas: {
+        [id: string]: {
+            [id: string]: IJsonSchema;
+        };
+    }, sourceFileOrTypeName: string, options?: ITypeScriptToSchemaOptions): Promise<{
+        [id: string]: IJsonSchema;
+    }>;
+    /**
+     * 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: string, fileName: string | undefined, packageName: string): boolean;
+}

package/dist/types/utils/utilityTypeSchemaMapper.d.ts

@@ -0,0 +1,92 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+import * as ts from "typescript";
+import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaContext.js";
+/**
+ * Static utility-type schema mapping helpers.
+ */
+export declare class UtilityTypeSchemaMapper {
+    /**
+     * Map Partial<T> to an object schema with no required properties.
+     * @param context The generation context.
+     * @param typeNode The Partial type reference.
+     * @param resolveUtilityBaseObjectSchema Callback to resolve base object schemas.
+     * @returns The mapped schema.
+     */
+    static mapPartialUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, resolveUtilityBaseObjectSchema: (context: ITypeScriptToSchemaContext, baseTypeNode: ts.TypeNode) => IJsonSchema | undefined): IJsonSchema | undefined;
+    /**
+     * Map Required<T> to an object schema with all properties required.
+     * @param context The generation context.
+     * @param typeNode The Required type reference.
+     * @param resolveUtilityBaseObjectSchema Callback to resolve base object schemas.
+     * @returns The mapped schema.
+     */
+    static mapRequiredUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, resolveUtilityBaseObjectSchema: (context: ITypeScriptToSchemaContext, baseTypeNode: ts.TypeNode) => IJsonSchema | undefined): IJsonSchema | undefined;
+    /**
+     * Map Pick<T, K> to an object schema with selected keys preserved.
+     */
+    static mapPickUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, resolveUtilityBaseObjectSchema: (context: ITypeScriptToSchemaContext, baseTypeNode: ts.TypeNode) => IJsonSchema | undefined, extractUtilityTypeKeys: (context: ITypeScriptToSchemaContext, keysNode: ts.TypeNode | undefined) => string[]): IJsonSchema | undefined;
+    /**
+     * Map Omit<T, K> to an object schema with selected keys removed.
+     */
+    static mapOmitUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, resolveUtilityBaseObjectSchema: (context: ITypeScriptToSchemaContext, baseTypeNode: ts.TypeNode) => IJsonSchema | undefined, extractUtilityTypeKeys: (context: ITypeScriptToSchemaContext, keysNode: ts.TypeNode | undefined) => string[]): IJsonSchema | undefined;
+    /**
+     * Map Exclude<T, U> to a schema that removes U members from T.
+     */
+    static mapExcludeUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, mapTypeNodeToSchema: (context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode) => IJsonSchema | undefined): IJsonSchema | undefined;
+    /**
+     * Map Extract<T, U> to a schema that keeps U members from T.
+     */
+    static mapExtractUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, mapTypeNodeToSchema: (context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode) => IJsonSchema | undefined): IJsonSchema | undefined;
+    /**
+     * Map NonNullable<T> by removing null and undefined branches from T.
+     */
+    static mapNonNullableUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, mapTypeNodeToSchema: (context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode) => IJsonSchema | undefined): IJsonSchema | undefined;
+    /**
+     * Map Record<K, V> to an object schema with key constraints where possible.
+     */
+    static mapRecordUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, mapTypeNodeToSchema: (context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode) => IJsonSchema | undefined): IJsonSchema | undefined;
+    /**
+     * Map JsonLdObject utility types using key-removal and optional key-addition rules.
+     */
+    static mapJsonLdObjectUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, options: {
+        keysToRemove: string[];
+        keyToAdd?: "id" | "@id" | "type" | "@type" | "@context";
+        isAddedKeyRequired?: boolean;
+    }, resolveUtilityBaseObjectSchema: (context: ITypeScriptToSchemaContext, baseTypeNode: ts.TypeNode) => IJsonSchema | undefined, mapTypeNodeToSchema: (context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode) => IJsonSchema | undefined): IJsonSchema | undefined;
+    /**
+     * Map ObjectOrArray<T> to a schema accepting T or T[].
+     */
+    static mapObjectOrArrayUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, mapTypeNodeToSchema: (context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode) => IJsonSchema | undefined): IJsonSchema | undefined;
+    /**
+     * Map SingleOccurrenceArray<T, U> to a non-empty array containing exactly one U.
+     */
+    static mapSingleOccurrenceArrayUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, mapTypeNodeToSchema: (context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode) => IJsonSchema | undefined): IJsonSchema | undefined;
+    /**
+     * Determine whether a type node represents null or undefined.
+     */
+    private static isNullOrUndefinedTypeNode;
+    /**
+     * Extract literal keys from a Record key type argument.
+     */
+    private static extractRecordLiteralKeys;
+    /**
+     * Resolve a default schema for JsonLdObject utility key additions when the type argument is omitted.
+     */
+    private static mapJsonLdObjectDefaultSchemaByKey;
+    /**
+     * Resolve default id schema for JsonLdObjectWithId when Id type argument is omitted.
+     */
+    private static mapJsonLdObjectWithIdDefaultIdSchema;
+    /**
+     * Resolve default type schema for JsonLdObjectWithType when Type argument is omitted.
+     */
+    private static mapJsonLdObjectWithTypeDefaultTypeSchema;
+    /**
+     * Resolve default context schema for JsonLdObjectWithContext when Context argument is omitted.
+     */
+    private static mapJsonLdObjectWithContextDefaultContextSchema;
+    /**
+     * Resolve default schema from either of two source keys, with fallback when both are absent.
+     */
+    private static mapJsonLdObjectDefaultEitherSchema;
+}

package/docs/changelog.md

@@ -1,5 +1,180 @@
 # Changelog
 
+## [0.0.3-next.21](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.20...tools-core-v0.0.3-next.21) (2026-03-20)
+
+
+### Features
+
+* add jsdoc tag validation ([971b8d3](https://github.com/twinfoundation/tools/commit/971b8d3817d40467bfd7549c99af602f0c590299))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tools-models bumped from 0.0.3-next.20 to 0.0.3-next.21
+
+## [0.0.3-next.20](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.19...tools-core-v0.0.3-next.20) (2026-03-20)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tools-models bumped from 0.0.3-next.19 to 0.0.3-next.20
+
+## [0.0.3-next.19](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.18...tools-core-v0.0.3-next.19) (2026-03-19)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tools-models bumped from 0.0.3-next.18 to 0.0.3-next.19
+
+## [0.0.3-next.18](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.17...tools-core-v0.0.3-next.18) (2026-03-19)
+
+
+### Features
+
+* add jsdoc default value to schema ([7886a84](https://github.com/twinfoundation/tools/commit/7886a84961e692d2054f223e2e99205a654b76a6))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tools-models bumped from 0.0.3-next.17 to 0.0.3-next.18
+
+## [0.0.3-next.17](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.16...tools-core-v0.0.3-next.17) (2026-03-19)
+
+
+### Features
+
+* improve discriminated unions ([9c36ea7](https://github.com/twinfoundation/tools/commit/9c36ea7283230089ff19085ddc4b4c30a4e3f8a2))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tools-models bumped from 0.0.3-next.16 to 0.0.3-next.17
+
+## [0.0.3-next.16](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.15...tools-core-v0.0.3-next.16) (2026-03-19)
+
+
+### Features
+
+* ts to schema ([#86](https://github.com/twinfoundation/tools/issues/86)) ([ffebda5](https://github.com/twinfoundation/tools/commit/ffebda5f14ab5ec734bf37c9fb70a7ec3d4012c3))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tools-models bumped from 0.0.3-next.15 to 0.0.3-next.16
+
+## [0.0.3-next.15](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.14...tools-core-v0.0.3-next.15) (2026-03-10)
+
+
+### Features
+
+* use jsdoc tags for json-ld markup ([1ea872e](https://github.com/twinfoundation/tools/commit/1ea872e07a1cc0e94178158a57383d64008e02e3))
+
+## [0.0.3-next.14](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.13...tools-core-v0.0.3-next.14) (2026-03-06)
+
+
+### Bug Fixes
+
+* improve schema output ([9e53cbe](https://github.com/twinfoundation/tools/commit/9e53cbe26e6272323d72c65e277b7d24521fdbba))
+
+## [0.0.3-next.13](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.12...tools-core-v0.0.3-next.13) (2026-03-05)
+
+
+### Bug Fixes
+
+* work for schema generator spread defect ([1a705ff](https://github.com/twinfoundation/tools/commit/1a705ffc74b353f652e74ea43454164a2f6740bf))
+
+## [0.0.3-next.12](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.11...tools-core-v0.0.3-next.12) (2026-02-27)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+## [0.0.3-next.11](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.10...tools-core-v0.0.3-next.11) (2026-02-25)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+## [0.0.3-next.10](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.9...tools-core-v0.0.3-next.10) (2026-02-25)
+
+
+### Features
+
+* remove additionalProperties ([f9b5d81](https://github.com/twinfoundation/tools/commit/f9b5d81e952468f9579593cb979f2b84db6f0dfa))
+
+## [0.0.3-next.9](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.8...tools-core-v0.0.3-next.9) (2026-02-24)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+## [0.0.3-next.8](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.7...tools-core-v0.0.3-next.8) (2026-02-23)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+## [0.0.3-next.7](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.6...tools-core-v0.0.3-next.7) (2026-02-04)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+## [0.0.3-next.6](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.5...tools-core-v0.0.3-next.6) (2026-01-28)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+## [0.0.3-next.5](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.4...tools-core-v0.0.3-next.5) (2026-01-06)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+## [0.0.3-next.4](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.3...tools-core-v0.0.3-next.4) (2026-01-05)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
+## [0.0.3-next.3](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.2...tools-core-v0.0.3-next.3) (2025-11-11)
+
+
+### Miscellaneous Chores
+
+* **tools-core:** Synchronize repo versions
+
 ## [0.0.3-next.2](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.1...tools-core-v0.0.3-next.2) (2025-11-11)
 
 
@@ -93,4 +268,4 @@
 
 * add support for auto expand types ([dd1e10a](https://github.com/twinfoundation/tools/commit/dd1e10a5b2fea6f80890ff6f3971f48e239cb4c1))
 
-## @twin.org/tools-core - Changelog
+## Changelog

package/docs/examples.md

@@ -1 +1,87 @@
-# @twin.org/tools-core - Examples
+# Tools Core Examples
+
+This package provides the lower-level building blocks used by the CLI applications. The most common entry point is `TypeScriptToSchema`, which parses TypeScript declarations and returns JSON Schema documents keyed by title.
+
+## Generate Schemas From TypeScript
+
+```ts
+import type { IJsonSchema } from '@twin.org/tools-models';
+import { TypeScriptToSchema } from '@twin.org/tools-core';
+
+const converter = new TypeScriptToSchema();
+const packageSchemas: { [id: string]: { [id: string]: IJsonSchema } } = {};
+
+const generatedSchemas = await converter.generateSchema(
+  'https://schema.example.com/demo/',
+  '@example/demo-package',
+  packageSchemas,
+  './dist/types/models.d.ts'
+);
+
+console.log(Object.keys(generatedSchemas));
+```
+
+When you already know the exported type you want, pass the type name instead of a file path. The helper resolves the declaration and returns the generated schema for that type together with any dependent schemas.
+
+```ts
+import type { IJsonSchema } from '@twin.org/tools-models';
+import { TypeScriptToSchema } from '@twin.org/tools-core';
+
+const converter = new TypeScriptToSchema();
+const packageSchemas: { [id: string]: { [id: string]: IJsonSchema } } = {};
+
+const generatedSchemas = await converter.generateSchema(
+  'https://schema.example.com/demo/',
+  '@example/demo-package',
+  packageSchemas,
+  'DemoRequest'
+);
+
+const requestSchema = generatedSchemas.DemoRequest;
+```
+
+## Transform Generated Object Schemas
+
+`TypeScriptSchemaObjectTransformer` helps when you need to adapt object schemas produced by the builder for utility types such as `Pick` and `Omit`, or when you want cleaner description text before serialising the result.
+
+```ts
+import type { IJsonSchema } from '@twin.org/tools-models';
+import { TypeScriptSchemaObjectTransformer } from '@twin.org/tools-core';
+
+const transformer = new TypeScriptSchemaObjectTransformer();
+
+const personSchema: IJsonSchema = {
+  title: 'Person',
+  type: 'object',
+  properties: {
+    id: { type: 'string' },
+    name: { type: 'string' },
+    email: { type: 'string', format: 'email' }
+  },
+  required: ['id', 'name', 'email']
+};
+
+const publicPersonSchema = transformer.omitKeysFromObjectSchema(personSchema, ['email']);
+const personSummarySchema = transformer.pickKeysFromObjectSchema(personSchema, ['id', 'name']);
+```
+
+If your schema descriptions come from multiline source comments, `normalizeSchemaDescriptions` removes duplicated whitespace while keeping intentional line breaks intact.
+
+```ts
+import type { IJsonSchema } from '@twin.org/tools-models';
+import { TypeScriptSchemaObjectTransformer } from '@twin.org/tools-core';
+
+const transformer = new TypeScriptSchemaObjectTransformer();
+
+const schemaWithDescription: IJsonSchema = {
+  type: 'object',
+  properties: {
+    status: {
+      type: 'string',
+      description: 'Current   status.\n\n  Used in responses.'
+    }
+  }
+};
+
+const normalisedSchema = transformer.normalizeSchemaDescriptions(schemaWithDescription);
+```

package/docs/reference/classes/Constants.md

@@ -0,0 +1,29 @@
+# Class: Constants
+
+Shared constants for TypeScript to JSON schema generation.
+
+## Constructors
+
+### Constructor
+
+> **new Constants**(): `Constants`
+
+#### Returns
+
+`Constants`
+
+## Properties
+
+### UNSUPPORTED\_UTILITY\_TYPE\_NAMES {#unsupported_utility_type_names}
+
+> `readonly` `static` **UNSUPPORTED\_UTILITY\_TYPE\_NAMES**: `string`[]
+
+Utility type names currently unsupported and mapped to open schemas with diagnostics.
+
+***
+
+### ARRAY\_NUMBER\_TYPE\_NAMES {#array_number_type_names}
+
+> `readonly` `static` **ARRAY\_NUMBER\_TYPE\_NAMES**: `string`[]
+
+Native typed-array and binary type names mapped to JSON number arrays.

package/docs/reference/classes/DiagnosticReporter.md

@@ -0,0 +1,49 @@
+# Class: DiagnosticReporter
+
+Emits non-fatal diagnostics during schema mapping.
+
+## Constructors
+
+### Constructor
+
+> **new DiagnosticReporter**(): `DiagnosticReporter`
+
+#### Returns
+
+`DiagnosticReporter`
+
+## Methods
+
+### report() {#report}
+
+> `static` **report**(`context`, `node`, `code`, `properties?`): `void`
+
+Emit an optional non-fatal schema generation diagnostic.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+The generation context.
+
+##### node
+
+`Node`
+
+The related AST node.
+
+##### code
+
+`string`
+
+The diagnostic code.
+
+##### properties?
+
+The values to substitute into the localised message.
+
+#### Returns
+
+`void`

package/docs/reference/classes/DisallowedTypeGuard.md

@@ -0,0 +1,35 @@
+# Class: DisallowedTypeGuard
+
+Validates whether a type node is allowed for schema generation.
+
+## Constructors
+
+### Constructor
+
+> **new DisallowedTypeGuard**(): `DisallowedTypeGuard`
+
+#### Returns
+
+`DisallowedTypeGuard`
+
+## Methods
+
+### getDisallowedTypeName() {#getdisallowedtypename}
+
+> `static` **getDisallowedTypeName**(`typeNode`): `string` \| `undefined`
+
+Resolve a disallowed type name from a type node.
+
+#### Parameters
+
+##### typeNode
+
+`TypeNode`
+
+The type node to inspect.
+
+#### Returns
+
+`string` \| `undefined`
+
+The disallowed type name, if found.