@aws-blocks/core 0.1.0

package/dist/scripts/extract-ts-types.js

@@ -0,0 +1,664 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Extract TypeScript type information from ApiNamespace method signatures.
+ *
+ * Uses `ts.createProgram` with a full type checker to extract both explicit
+ * and inferred types — including return types that have no annotation.
+ * Converts TS types to JSON Schema for the OpenRPC spec.
+ *
+ * Zod-validated methods still take priority in generate-spec.ts — this
+ * module provides the fallback for plain TS methods so they emit real
+ * types instead of { type: "unknown" }.
+ */
+import * as ts from 'typescript';
+import { dirname, resolve } from 'path';
+import { existsSync } from 'fs';
+/**
+ * Public so `generate-spec.ts` and any future emitter can share the same
+ * vocabulary. Spelt as a single token to avoid hyphenation surprises in
+ * JSDoc parsers.
+ */
+export const BLOCKS_SKIP_CODEGEN_TAG = 'blocksSkipCodegen';
+function hasKitSkipCodegenTag(node) {
+    for (const tag of ts.getJSDocTags(node)) {
+        if (tag.tagName.text === BLOCKS_SKIP_CODEGEN_TAG)
+            return true;
+    }
+    return false;
+}
+/**
+ * Pure-AST scan for method names tagged with `@blocksSkipCodegen` inside the
+ * `ApiNamespace(...)` calls of a TS source file. Returns a Set of method
+ * names (the OpenRPC emitter qualifies them by namespace later).
+ *
+ * Distinct from {@link extractMethodTypes} because that function builds a
+ * full `ts.Program` + type checker, and any failure inside type
+ * resolution (an imported module that doesn't typecheck, a third-party
+ * `.d.ts` mismatch) silently empties the returned Map. The skip set must
+ * survive those crashes, so this function uses only the parser.
+ */
+export function extractSkipCodegenMethods(sourcePath) {
+    const result = new Set();
+    const absPath = resolve(sourcePath);
+    const fileText = ts.sys.readFile(absPath);
+    if (!fileText)
+        return result;
+    const sourceFile = ts.createSourceFile(absPath, fileText, ts.ScriptTarget.ESNext, 
+    /*setParentNodes*/ true, ts.ScriptKind.TS);
+    function visitObjectLiteral(obj) {
+        for (const prop of obj.properties) {
+            if (ts.isMethodDeclaration(prop) &&
+                prop.name &&
+                ts.isIdentifier(prop.name) &&
+                hasKitSkipCodegenTag(prop)) {
+                result.add(prop.name.text);
+            }
+        }
+    }
+    function visit(node) {
+        if (ts.isNewExpression(node)) {
+            const callee = node.expression;
+            if (ts.isIdentifier(callee) && callee.text === 'ApiNamespace' && node.arguments && node.arguments.length >= 2) {
+                const handler = node.arguments[node.arguments.length - 1];
+                if (ts.isArrowFunction(handler) || ts.isFunctionExpression(handler)) {
+                    const body = handler.body;
+                    if (ts.isParenthesizedExpression(body) && ts.isObjectLiteralExpression(body.expression)) {
+                        visitObjectLiteral(body.expression);
+                    }
+                    else if (ts.isObjectLiteralExpression(body)) {
+                        visitObjectLiteral(body);
+                    }
+                    else if (ts.isBlock(body)) {
+                        for (const stmt of body.statements) {
+                            if (ts.isReturnStatement(stmt) && stmt.expression) {
+                                if (ts.isObjectLiteralExpression(stmt.expression)) {
+                                    visitObjectLiteral(stmt.expression);
+                                }
+                                else if (ts.isParenthesizedExpression(stmt.expression) &&
+                                    ts.isObjectLiteralExpression(stmt.expression.expression)) {
+                                    visitObjectLiteral(stmt.expression.expression);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return result;
+}
+// ── Main entry point ────────────────────────────────────────────────────────
+/**
+ * Parse a TypeScript source file with full type checking and extract type
+ * info for all methods inside `ApiNamespace(...)` calls.
+ *
+ * Uses `ts.createProgram` to resolve imports and infer return types.
+ * Falls back to AST-only parsing if program creation fails.
+ */
+export function extractMethodTypes(sourcePath) {
+    const result = new Map();
+    const absPath = resolve(sourcePath);
+    // Find tsconfig.json by walking up from the source file
+    const configPath = findTsConfig(dirname(absPath));
+    let program;
+    let checker;
+    let sourceFile;
+    if (configPath) {
+        const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+        const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, dirname(configPath));
+        // Only include our target file — the compiler resolves imports on demand.
+        // This is much faster than passing the full fileNames list from tsconfig.
+        const options = { ...parsed.options, skipLibCheck: true, skipDefaultLibCheck: true };
+        program = ts.createProgram([absPath], options);
+    }
+    else {
+        // No tsconfig — create a minimal program
+        program = ts.createProgram([absPath], {
+            target: ts.ScriptTarget.ESNext,
+            module: ts.ModuleKind.ESNext,
+            moduleResolution: ts.ModuleResolutionKind.Bundler,
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        });
+    }
+    checker = program.getTypeChecker();
+    sourceFile = program.getSourceFile(absPath);
+    if (!sourceFile)
+        return result;
+    // Find new ApiNamespace(scope, name, handler) and extract methods using the type checker
+    ts.forEachChild(sourceFile, function visit(node) {
+        if (ts.isNewExpression(node)) {
+            const fnName = node.expression;
+            if (ts.isIdentifier(fnName) && fnName.text === 'ApiNamespace' && node.arguments && node.arguments.length >= 2) {
+                const handlerArg = node.arguments[node.arguments.length - 1];
+                extractMethodsFromHandler(handlerArg, checker, sourceFile, result);
+            }
+        }
+        ts.forEachChild(node, visit);
+    });
+    // Second pass: resolve types for indirect ApiNamespace exports (e.g., auth.createApi()).
+    // The AST walk above only finds `new ApiNamespace(...)` in this file.
+    // For methods created by Building Block helpers in other files, use the type
+    // checker to resolve the call's return type and extract method signatures.
+    ts.forEachChild(sourceFile, (node) => {
+        if (!ts.isVariableStatement(node))
+            return;
+        for (const decl of node.declarationList.declarations) {
+            if (!decl.initializer || !ts.isIdentifier(decl.name))
+                continue;
+            // Skip if we already extracted methods for this via the AST walk
+            if (ts.isNewExpression(decl.initializer)) {
+                const callee = decl.initializer.expression;
+                if (ts.isIdentifier(callee) && callee.text === 'ApiNamespace')
+                    continue;
+            }
+            // Use the type checker to get the type of the initializer expression.
+            // For `auth.createApi()`, this resolves through the method's return type
+            // to the `AsyncAPI<T>` type that ApiNamespace returns.
+            const initType = checker.getTypeAtLocation(decl.initializer);
+            extractMethodsFromResolvedType(initType, checker, result);
+        }
+    });
+    return result;
+}
+// ── tsconfig discovery ──────────────────────────────────────────────────────
+function findTsConfig(dir) {
+    let current = dir;
+    for (let i = 0; i < 10; i++) {
+        const candidate = resolve(current, 'tsconfig.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return undefined;
+}
+// ── Handler extraction ──────────────────────────────────────────────────────
+function extractMethodsFromHandler(handlerNode, checker, sourceFile, result) {
+    let objectLiteral;
+    if (ts.isArrowFunction(handlerNode) || ts.isFunctionExpression(handlerNode)) {
+        const body = handlerNode.body;
+        if (ts.isParenthesizedExpression(body)) {
+            if (ts.isObjectLiteralExpression(body.expression)) {
+                objectLiteral = body.expression;
+            }
+        }
+        else if (ts.isObjectLiteralExpression(body)) {
+            objectLiteral = body;
+        }
+        else if (ts.isBlock(body)) {
+            for (const stmt of body.statements) {
+                if (ts.isReturnStatement(stmt) && stmt.expression) {
+                    if (ts.isObjectLiteralExpression(stmt.expression)) {
+                        objectLiteral = stmt.expression;
+                    }
+                    else if (ts.isParenthesizedExpression(stmt.expression) &&
+                        ts.isObjectLiteralExpression(stmt.expression.expression)) {
+                        objectLiteral = stmt.expression.expression;
+                    }
+                }
+            }
+        }
+    }
+    if (!objectLiteral)
+        return;
+    for (const prop of objectLiteral.properties) {
+        if (ts.isMethodDeclaration(prop) && prop.name && ts.isIdentifier(prop.name)) {
+            const methodName = prop.name.text;
+            const info = extractMethodTypeInfo(prop, checker, sourceFile);
+            if (info)
+                result.set(methodName, info);
+        }
+    }
+}
+function extractMethodTypeInfo(method, checker, sourceFile) {
+    const params = [];
+    for (const param of method.parameters) {
+        const name = ts.isIdentifier(param.name) ? param.name.text
+            : param.name.getText(sourceFile);
+        const required = !param.questionToken && !param.initializer;
+        // Use the type checker to get the resolved type (handles imported types, aliases, etc.)
+        const symbol = checker.getSymbolAtLocation(param.name);
+        let schema = { type: 'unknown' };
+        if (symbol) {
+            const paramType = checker.getTypeOfSymbolAtLocation(symbol, param);
+            schema = tsTypeToJsonSchema(paramType, checker);
+        }
+        else if (param.type) {
+            // Fallback to AST-based extraction
+            schema = typeNodeToJsonSchema(param.type, sourceFile);
+        }
+        params.push({ name, required, schema });
+    }
+    // Return type: use the type checker to get the inferred return type
+    let returnType = { type: 'unknown' };
+    let transferable;
+    const signature = checker.getSignatureFromDeclaration(method);
+    if (signature) {
+        let retType = checker.getReturnTypeOfSignature(signature);
+        // Unwrap Promise<T>
+        retType = unwrapPromise(retType, checker);
+        // Check if the return type is a transferable before converting to schema.
+        // Pass the syntactic return-type node so we can distinguish between
+        // `RealtimeChannel` (default `T = unknown` filled in) and
+        // `RealtimeChannel<unknown>` (explicit) — the resolved `ts.Type` looks
+        // identical for both, but only the latter should emit `typeArgs: [{}]`.
+        const retTypeNode = unwrapPromiseTypeNode(method.type);
+        transferable = detectTransferable(retType, checker, retTypeNode);
+        returnType = tsTypeToJsonSchema(retType, checker);
+    }
+    const skipCodegen = hasKitSkipCodegenTag(method) || undefined;
+    return { params, returnType, transferable, skipCodegen };
+}
+/**
+ * Walk a return-type AST node, unwrapping a single layer of `Promise<T>`,
+ * and return the inner `TypeReferenceNode` if any. Used to recover the
+ * syntactic type-arguments the customer wrote — `Promise<RealtimeChannel>`
+ * has no inner `<...>`, while `Promise<RealtimeChannel<X>>` does.
+ */
+function unwrapPromiseTypeNode(node) {
+    if (!node || !ts.isTypeReferenceNode(node))
+        return undefined;
+    const name = ts.isIdentifier(node.typeName) ? node.typeName.text : node.typeName.getText();
+    if (name === 'Promise' && node.typeArguments && node.typeArguments.length === 1) {
+        const inner = node.typeArguments[0];
+        return ts.isTypeReferenceNode(inner) ? inner : undefined;
+    }
+    return node;
+}
+// ── Type-checker-based extraction for indirect ApiNamespace calls ────────────
+/**
+ * Extract method type info from a resolved `ts.Type` (e.g., the return type
+ * of `auth.createApi()`). This handles the case where `ApiNamespace(...)` is
+ * called inside another module — the AST walk can't see it, but the type
+ * checker resolves the full return type including method signatures.
+ *
+ * The type is the `AsyncAPI<T>` wrapper returned by `ApiNamespace`, which is
+ * a mapped type where each property is `(...args: Args) => Promise<R>`.
+ * We also handle the case where the type is callable (the raw handler function
+ * before `AsyncAPI` wrapping) — we call-resolve it and inspect the result.
+ */
+function extractMethodsFromResolvedType(type, checker, result) {
+    // The runtime value of an ApiNamespace export is the handler function itself
+    // (with the marker symbol attached). Its TS type is `AsyncAPI<T>`, which is
+    // an object type with method-like properties. But it could also be typed as
+    // the handler function `(context: BlocksContext) => T`. Try both:
+    // 1. If the type has call signatures, resolve the return type (handler fn case)
+    // 2. Otherwise, treat it as the AsyncAPI<T> object directly
+    let methodsType = type;
+    // If the type is callable (handler function), resolve its return type
+    const callSigs = type.getCallSignatures();
+    if (callSigs.length > 0) {
+        const retType = checker.getReturnTypeOfSignature(callSigs[0]);
+        // The return type should be the object with method properties
+        if (retType.getProperties().length > 0) {
+            methodsType = retType;
+        }
+    }
+    const props = methodsType.getProperties();
+    if (props.length === 0)
+        return;
+    for (const prop of props) {
+        const propName = prop.getName();
+        // Skip internal symbols and the marker
+        if (propName.startsWith('_') || propName === 'Symbol(blocks:ApiNamespace)')
+            continue;
+        // Don't overwrite methods already found by the AST walk
+        if (result.has(propName))
+            continue;
+        const propType = checker.getTypeOfSymbol(prop);
+        const methodSigs = propType.getCallSignatures();
+        if (methodSigs.length === 0)
+            continue;
+        const sig = methodSigs[0];
+        // Extract params
+        const params = [];
+        for (const paramSymbol of sig.getParameters()) {
+            const paramType = checker.getTypeOfSymbol(paramSymbol);
+            const schema = tsTypeToJsonSchema(paramType, checker);
+            const paramDecl = paramSymbol.valueDeclaration;
+            const isOptional = paramDecl && ts.isParameter(paramDecl)
+                ? !!(paramDecl.questionToken || paramDecl.initializer)
+                : (paramSymbol.flags & ts.SymbolFlags.Optional) !== 0;
+            params.push({
+                name: paramSymbol.getName(),
+                required: !isOptional,
+                schema,
+            });
+        }
+        // Extract return type (unwrap Promise<T>)
+        let retType = checker.getReturnTypeOfSignature(sig);
+        retType = unwrapPromise(retType, checker);
+        // Check if the return type is a transferable before converting to schema
+        const transferable = detectTransferable(retType, checker);
+        const returnType = tsTypeToJsonSchema(retType, checker);
+        // JSDoc lives on the original method declaration, which we can reach
+        // via the symbol's `valueDeclaration` (the `MethodDeclaration` node in
+        // the BB-helper file that minted the AsyncAPI<T> shape).
+        let skipCodegen;
+        const declaration = prop.valueDeclaration;
+        if (declaration && hasKitSkipCodegenTag(declaration)) {
+            skipCodegen = true;
+        }
+        result.set(propName, { params, returnType, transferable, skipCodegen });
+    }
+}
+// ── Transferable detection ───────────────────────────────────────────────────
+/**
+ * Inspect a resolved ts.Type for the transferable protocol:
+ * - Has a method named `toJSON`
+ * - toJSON's return type has a property `__blocks` with a string LITERAL type
+ *
+ * If detected, extracts the blocks tag and resolves generic type arguments.
+ * Returns undefined if the type is not transferable.
+ *
+ * `syntacticNode` is the AST `TypeReferenceNode` the customer wrote (e.g.
+ * `RealtimeChannel<CursorPosition>`). It's passed in alongside the resolved
+ * `ts.Type` so we can tell the difference between an unwritten default
+ * (`RealtimeChannel`, where `T = unknown` is filled in by the checker) and
+ * an explicit `RealtimeChannel<unknown>`. The two look identical in the
+ * resolved `ts.Type`, but only the explicit form should emit a `[{}]` slot.
+ */
+function detectTransferable(type, checker, syntacticNode) {
+    // Step 1-2: Get properties of the type and find `toJSON`
+    const props = checker.getPropertiesOfType(type);
+    const toJsonSymbol = props.find(p => p.getName() === 'toJSON');
+    if (!toJsonSymbol)
+        return undefined;
+    // Step 3: Get the type of `toJSON`
+    const toJsonType = checker.getTypeOfSymbol(toJsonSymbol);
+    // Step 4: Get call signatures of the `toJSON` type
+    const callSignatures = toJsonType.getCallSignatures();
+    if (callSignatures.length === 0)
+        return undefined;
+    // Step 5: Get the return type of the first call signature
+    const returnType = checker.getReturnTypeOfSignature(callSignatures[0]);
+    // Step 6: Get properties of the return type, find `__blocks`
+    const returnProps = checker.getPropertiesOfType(returnType);
+    const blocksSymbol = returnProps.find(p => p.getName() === '__blocks');
+    if (!blocksSymbol)
+        return undefined;
+    // Step 7: Get the type of `__blocks`
+    const blocksType = checker.getTypeOfSymbol(blocksSymbol);
+    // Step 8: Check if it's a string literal type
+    if (!(blocksType.getFlags() & ts.TypeFlags.StringLiteral))
+        return undefined;
+    // Step 9: Extract the literal value as `blocksTag`
+    const blocksTag = blocksType.value;
+    // Step 10-11: For generic type arguments — only emit them when the
+    // customer actually wrote `<...>` in the source. If `syntacticNode` has
+    // no `typeArguments`, treat the type as non-generic (defaults filled in
+    // by the checker shouldn't appear in the spec).
+    const typeArgs = [];
+    const wroteTypeArgs = syntacticNode?.typeArguments && syntacticNode.typeArguments.length > 0;
+    if (wroteTypeArgs) {
+        const typeRef = type;
+        const resolvedArgs = typeRef.typeArguments ?? [];
+        for (const arg of resolvedArgs) {
+            // Explicit `unknown` / `any` → empty schema (matches Req 4.3).
+            const argFlags = arg.getFlags();
+            if (argFlags & ts.TypeFlags.Unknown || argFlags & ts.TypeFlags.Any) {
+                typeArgs.push({});
+            }
+            else {
+                typeArgs.push(tsTypeToJsonSchema(arg, checker));
+            }
+        }
+    }
+    return { blocksTag, typeArgs };
+}
+// ── ts.Type → JSON Schema conversion ────────────────────────────────────────
+/** Recursion guard to prevent infinite loops on recursive types. */
+const MAX_DEPTH = 6;
+/**
+ * Convert a resolved `ts.Type` to JSON Schema.
+ * This handles inferred types, imported types, type aliases, etc.
+ */
+function tsTypeToJsonSchema(type, checker, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return { type: 'object' };
+    const flags = type.getFlags();
+    // Primitives
+    if (flags & ts.TypeFlags.String)
+        return { type: 'string' };
+    if (flags & ts.TypeFlags.Number)
+        return { type: 'number' };
+    if (flags & ts.TypeFlags.Boolean)
+        return { type: 'boolean' };
+    if (flags & ts.TypeFlags.Null)
+        return { type: 'null' };
+    if (flags & ts.TypeFlags.Undefined)
+        return { type: 'null' };
+    if (flags & ts.TypeFlags.Void)
+        return { type: 'null' };
+    if (flags & ts.TypeFlags.Any)
+        return {};
+    if (flags & ts.TypeFlags.Unknown)
+        return { type: 'unknown' };
+    if (flags & ts.TypeFlags.Never)
+        return { type: 'unknown' };
+    // String/number/boolean literal
+    if (flags & ts.TypeFlags.StringLiteral) {
+        return { type: 'string', enum: [type.value] };
+    }
+    if (flags & ts.TypeFlags.NumberLiteral) {
+        return { type: 'number', enum: [type.value] };
+    }
+    if (flags & ts.TypeFlags.BooleanLiteral) {
+        // ts.TypeFlags doesn't expose the value directly; use the intrinsicName
+        const intrinsic = type.intrinsicName;
+        if (intrinsic === 'true')
+            return { type: 'boolean', enum: [true] };
+        if (intrinsic === 'false')
+            return { type: 'boolean', enum: [false] };
+        return { type: 'boolean' };
+    }
+    // Union type
+    if (type.isUnion()) {
+        return unionTypeToJsonSchema(type, checker, depth);
+    }
+    // Intersection type. Merge fixed properties from each arm and also
+    // preserve `additionalProperties` if any arm contributes an index
+    // signature (e.g. `{ username; password } & Record<string, string>`).
+    // This is how Cognito sign-up declares an open shape — without merging
+    // the index signature, native client codegen drops every key the
+    // type system can't statically enumerate (email, custom:*, etc.) and
+    // the wire format ends up missing them.
+    if (type.isIntersection()) {
+        const allProps = {};
+        const allRequired = [];
+        let additionalProps;
+        for (const member of type.types) {
+            const schema = tsTypeToJsonSchema(member, checker, depth + 1);
+            if (schema.properties) {
+                Object.assign(allProps, schema.properties);
+                if (schema.required)
+                    allRequired.push(...schema.required);
+            }
+            if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+                additionalProps = schema.additionalProperties;
+            }
+        }
+        if (Object.keys(allProps).length > 0) {
+            const schema = { type: 'object', properties: allProps };
+            if (allRequired.length > 0)
+                schema.required = allRequired;
+            if (additionalProps)
+                schema.additionalProperties = additionalProps;
+            return schema;
+        }
+        if (additionalProps) {
+            return { type: 'object', additionalProperties: additionalProps };
+        }
+        return { type: 'object' };
+    }
+    // Array type
+    if (checker.isArrayType(type)) {
+        const typeArgs = type.typeArguments;
+        if (typeArgs && typeArgs.length === 1) {
+            return { type: 'array', items: tsTypeToJsonSchema(typeArgs[0], checker, depth + 1) };
+        }
+        return { type: 'array' };
+    }
+    // Object type (interfaces, type literals, classes)
+    if (flags & ts.TypeFlags.Object) {
+        // Special-case built-in types that serialize to JSON primitives.
+        // Without this, Date emits as an object with getTime/toISOString/etc. properties.
+        const symbol = type.getSymbol();
+        const typeName = symbol?.getName();
+        if (typeName === 'Date')
+            return { type: 'string', format: 'date-time' };
+        if (typeName === 'RegExp')
+            return { type: 'string', format: 'regex' };
+        if (typeName === 'URL')
+            return { type: 'string', format: 'uri' };
+        if (typeName === 'Buffer' || typeName === 'ArrayBuffer' || typeName === 'Uint8Array')
+            return { type: 'string', format: 'binary' };
+        return objectTypeToJsonSchema(type, checker, depth);
+    }
+    return { type: 'unknown' };
+}
+function objectTypeToJsonSchema(type, checker, depth) {
+    const properties = {};
+    const required = [];
+    const props = checker.getPropertiesOfType(type);
+    // Index signatures (`Record<string, V>` or `{ [key: string]: V }`) carry
+    // the value type for any unnamed key. Capture once up front so we can
+    // emit `additionalProperties` on both the pure-map case (no fixed
+    // properties) and the mixed case (fixed properties + index sig).
+    const stringIndexType = checker.getIndexTypeOfType(type, ts.IndexKind.String);
+    const additionalProps = stringIndexType
+        ? tsTypeToJsonSchema(stringIndexType, checker, depth + 1)
+        : undefined;
+    if (props.length === 0 && additionalProps) {
+        return { type: 'object', additionalProperties: additionalProps };
+    }
+    if (props.length === 0)
+        return { type: 'object' };
+    for (const prop of props) {
+        // Skip internal/private properties
+        if (prop.name.startsWith('_'))
+            continue;
+        // Mapped-type properties (e.g. from `Partial<Record<K, V>>` and the
+        // per-variant intersections produced when unioning over an action
+        // payload map) are synthetic and have no `valueDeclaration`. Casting
+        // the `Symbol` to a `ts.Node` to satisfy `getTypeOfSymbolAtLocation`
+        // crashes inside the compiler's `isDeclaration` walk. `getTypeOfSymbol`
+        // resolves the property type without a location and works for both
+        // real and synthetic properties.
+        const propType = checker.getTypeOfSymbol(prop);
+        const propSchema = tsTypeToJsonSchema(propType, checker, depth + 1);
+        properties[prop.name] = propSchema;
+        const isOptional = (prop.flags & ts.SymbolFlags.Optional) !== 0;
+        if (!isOptional) {
+            required.push(prop.name);
+        }
+    }
+    const schema = { type: 'object', properties };
+    if (required.length > 0)
+        schema.required = required;
+    if (additionalProps)
+        schema.additionalProperties = additionalProps;
+    // Preserve the original type name for named types (interfaces, type aliases).
+    // This enables $ref extraction in generate-spec.ts and Phase 4 hydration detection.
+    const symbol = type.getSymbol() || type.aliasSymbol;
+    if (symbol) {
+        const name = symbol.getName();
+        // Skip anonymous/synthetic names
+        if (name && name !== '__type' && name !== '__object' && !name.startsWith('__')) {
+            schema.title = name;
+        }
+    }
+    return schema;
+}
+function unionTypeToJsonSchema(type, checker, depth) {
+    const members = type.types.map(t => tsTypeToJsonSchema(t, checker, depth + 1));
+    const nullish = members.filter(m => m.type === 'null');
+    const nonNullish = members.filter(m => m.type !== 'null');
+    // boolean is represented as true | false union in TS
+    if (nonNullish.length === 2 &&
+        nonNullish.every(m => m.type === 'boolean' && m.enum)) {
+        if (nullish.length > 0) {
+            return { oneOf: [{ type: 'boolean' }, { type: 'null' }] };
+        }
+        return { type: 'boolean' };
+    }
+    // T | null → oneOf [T, null]
+    if (nonNullish.length === 1 && nullish.length > 0) {
+        return { oneOf: [nonNullish[0], { type: 'null' }] };
+    }
+    // All same base type with enum values
+    const allEnums = nonNullish.every(m => m.enum);
+    if (allEnums && nonNullish.length > 0) {
+        const baseType = nonNullish[0].type;
+        if (nonNullish.every(m => m.type === baseType)) {
+            const enumValues = nonNullish.flatMap(m => m.enum || []);
+            const schema = { type: baseType, enum: enumValues };
+            if (nullish.length > 0) {
+                return { oneOf: [schema, { type: 'null' }] };
+            }
+            return schema;
+        }
+    }
+    // General union → oneOf
+    if (nonNullish.length > 1) {
+        const allMembers = nullish.length > 0 ? [...nonNullish, { type: 'null' }] : nonNullish;
+        return { oneOf: allMembers };
+    }
+    return members[0] || { type: 'unknown' };
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Unwrap Promise<T> → T. If the type is not a Promise, returns it unchanged.
+ */
+function unwrapPromise(type, checker) {
+    // Check if it's a Promise by looking at the symbol name
+    const symbol = type.getSymbol();
+    if (symbol && symbol.getName() === 'Promise') {
+        const typeArgs = type.typeArguments;
+        if (typeArgs && typeArgs.length === 1) {
+            return typeArgs[0];
+        }
+    }
+    return type;
+}
+// ── AST-only fallback (for explicit type annotations without checker) ───────
+function typeNodeToJsonSchema(typeNode, sourceFile) {
+    if (ts.isToken(typeNode)) {
+        switch (typeNode.kind) {
+            case ts.SyntaxKind.StringKeyword: return { type: 'string' };
+            case ts.SyntaxKind.NumberKeyword: return { type: 'number' };
+            case ts.SyntaxKind.BooleanKeyword: return { type: 'boolean' };
+            case ts.SyntaxKind.NullKeyword: return { type: 'null' };
+            case ts.SyntaxKind.VoidKeyword: return { type: 'null' };
+            case ts.SyntaxKind.AnyKeyword: return {};
+            default: return { type: 'unknown' };
+        }
+    }
+    if (ts.isTypeLiteralNode(typeNode)) {
+        const properties = {};
+        const required = [];
+        for (const member of typeNode.members) {
+            if (ts.isPropertySignature(member) && member.name) {
+                const propName = member.name.getText(sourceFile);
+                properties[propName] = member.type ? typeNodeToJsonSchema(member.type, sourceFile) : { type: 'unknown' };
+                if (!member.questionToken)
+                    required.push(propName);
+            }
+        }
+        const schema = { type: 'object', properties };
+        if (required.length > 0)
+            schema.required = required;
+        return schema;
+    }
+    if (ts.isArrayTypeNode(typeNode)) {
+        return { type: 'array', items: typeNodeToJsonSchema(typeNode.elementType, sourceFile) };
+    }
+    return { type: 'unknown' };
+}

package/dist/scripts/extract-ts-types.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=extract-ts-types.test.d.ts.map

package/dist/scripts/extract-ts-types.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-ts-types.test.d.ts","sourceRoot":"","sources":["../../src/scripts/extract-ts-types.test.ts"],"names":[],"mappings":""}