@tsonic/cli 0.0.61 → 0.0.62

package/dist/commands/library-bindings-augment.js

@@ -1,6 +1,6 @@
-import { readFileSync, readdirSync, writeFileSync, existsSync } from "node:fs";
-import { basename, join, resolve, posix } from "node:path";
-import { buildModuleDependencyGraph } from "@tsonic/frontend";
+import { copyFileSync, existsSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve, posix } from "node:path";
+import { buildModuleDependencyGraph, } from "@tsonic/frontend";
 import * as ts from "typescript";
 const renderDiagnostics = (diags) => {
     return diags
@@ -15,8 +15,30 @@ const renderDiagnostics = (diags) => {
 const escapeRegExp = (text) => {
     return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 };
+const typePrinter = ts.createPrinter({ removeComments: true });
+const printTypeNodeText = (node, sourceFile) => {
+    return typePrinter
+        .printNode(ts.EmitHint.Unspecified, node, sourceFile)
+        .trim();
+};
+const ensureUndefinedInType = (typeText) => {
+    const trimmed = typeText.trim();
+    if (/\bundefined\b/.test(trimmed))
+        return trimmed;
+    return `${trimmed} | undefined`;
+};
 const normalizeModuleFileKey = (filePath) => {
-    return posix.normalize(filePath).replace(/^(\.\/)+/, "").replace(/^\/+/, "");
+    return posix
+        .normalize(filePath)
+        .replace(/^(\.\/)+/, "")
+        .replace(/^\/+/, "");
+};
+const getPropertyNameText = (name) => {
+    if (ts.isIdentifier(name))
+        return name.text;
+    if (ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    return undefined;
 };
 const stripExistingSection = (text, startMarker, endMarker) => {
     const start = text.indexOf(startMarker);
@@ -35,7 +57,9 @@ const upsertSectionAfterImports = (text, startMarker, endMarker, body) => {
     while (insertAt < lines.length) {
         const line = lines[insertAt] ?? "";
         const trimmed = line.trim();
-        if (trimmed === "" || trimmed.startsWith("//") || trimmed.startsWith("import ")) {
+        if (trimmed === "" ||
+            trimmed.startsWith("//") ||
+            trimmed.startsWith("import ")) {
             insertAt += 1;
             continue;
         }
@@ -103,7 +127,10 @@ const applyWrappersToBaseType = (baseType, wrappers) => {
 };
 const patchInternalIndexWithMemberOverrides = (internalIndexDtsPath, overrides) => {
     if (!existsSync(internalIndexDtsPath)) {
-        return { ok: false, error: `Internal index not found at ${internalIndexDtsPath}` };
+        return {
+            ok: false,
+            error: `Internal index not found at ${internalIndexDtsPath}`,
+        };
     }
     const original = readFileSync(internalIndexDtsPath, "utf-8");
     // Collect wrapper imports (dedupe + validate no alias conflicts).
@@ -112,7 +139,8 @@ const patchInternalIndexWithMemberOverrides = (internalIndexDtsPath, overrides)
         for (const w of o.wrappers) {
             const existing = wrapperByAlias.get(w.aliasName);
             if (existing) {
-                if (existing.source !== w.source || existing.importedName !== w.importedName) {
+                if (existing.source !== w.source ||
+                    existing.importedName !== w.importedName) {
                     return {
                         ok: false,
                         error: `Conflicting wrapper import alias '${w.aliasName}' while augmenting ${internalIndexDtsPath}.\n` +
@@ -173,30 +201,239 @@ const patchInternalIndexWithMemberOverrides = (internalIndexDtsPath, overrides)
         for (const o of list.sort((a, b) => a.memberName.localeCompare(b.memberName))) {
             const propRe = new RegExp(String.raw `(^\s*(?:readonly\s+)?${escapeRegExp(o.memberName)}\s*:\s*)([^;]+)(;)`, "m");
             const propMatch = propRe.exec(body);
-            if (!propMatch) {
+            if (propMatch) {
+                const baseType = (o.replaceWithSourceType ? o.sourceTypeText : undefined) ??
+                    propMatch[2] ??
+                    "";
+                let nextType = applyWrappersToBaseType(baseType, o.wrappers);
+                if (o.isOptional)
+                    nextType = ensureUndefinedInType(nextType);
+                body = body.replace(propRe, `$1${nextType}$3`);
+                continue;
+            }
+            const getterRe = new RegExp(String.raw `(^\s*get\s+${escapeRegExp(o.memberName)}\s*\(\)\s*:\s*)([^;]+)(;)`, "m");
+            const setterRe = new RegExp(String.raw `(^\s*set\s+${escapeRegExp(o.memberName)}\s*\(\s*value\s*:\s*)([^)]+)(\)\s*;)`, "m");
+            const getterMatch = getterRe.exec(body);
+            const setterMatch = setterRe.exec(body);
+            if (!getterMatch && !setterMatch) {
                 return {
                     ok: false,
                     error: `Failed to locate property '${o.memberName}' on '${ifaceName}' in ${internalIndexDtsPath}.\n` +
-                        `This property was annotated with extension wrappers in TS source and should exist in CLR metadata.`,
+                        `This property was declared in TS source and should exist in CLR metadata.`,
                 };
             }
-            const baseType = propMatch[2] ?? "";
-            const wrappedType = applyWrappersToBaseType(baseType, o.wrappers);
-            body = body.replace(propRe, `$1${wrappedType}$3`);
+            if (getterMatch) {
+                const baseType = (o.replaceWithSourceType ? o.sourceTypeText : undefined) ??
+                    getterMatch[2] ??
+                    "";
+                let nextType = applyWrappersToBaseType(baseType, o.wrappers);
+                if (o.isOptional)
+                    nextType = ensureUndefinedInType(nextType);
+                body = body.replace(getterRe, `$1${nextType}$3`);
+            }
+            if (setterMatch) {
+                const baseType = (o.replaceWithSourceType ? o.sourceTypeText : undefined) ??
+                    setterMatch[2] ??
+                    "";
+                let nextType = applyWrappersToBaseType(baseType, o.wrappers);
+                if (o.isOptional)
+                    nextType = ensureUndefinedInType(nextType);
+                body = body.replace(setterRe, `$1${nextType}$3`);
+            }
         }
         const patchedBlock = head + body + tail;
-        next = next.slice(0, match.index) + patchedBlock + next.slice(match.index + block.length);
+        next =
+            next.slice(0, match.index) +
+                patchedBlock +
+                next.slice(match.index + block.length);
+    }
+    if (next !== original) {
+        writeFileSync(internalIndexDtsPath, next, "utf-8");
+    }
+    return { ok: true, value: undefined };
+};
+const patchInternalIndexBrandMarkersOptional = (internalIndexDtsPath, typeNames) => {
+    if (!existsSync(internalIndexDtsPath)) {
+        return {
+            ok: false,
+            error: `Internal index not found at ${internalIndexDtsPath}`,
+        };
+    }
+    const original = readFileSync(internalIndexDtsPath, "utf-8");
+    let next = original;
+    for (const typeName of Array.from(new Set(typeNames)).sort((a, b) => a.localeCompare(b))) {
+        const ifaceName = `${typeName}$instance`;
+        const ifaceRe = new RegExp(String.raw `export\s+interface\s+${escapeRegExp(ifaceName)}\b[^{]*\{[\s\S]*?^\}`, "m");
+        const match = ifaceRe.exec(next);
+        if (!match || match.index === undefined)
+            continue;
+        const block = match[0];
+        const open = block.indexOf("{");
+        const close = block.lastIndexOf("}");
+        if (open < 0 || close < 0 || close <= open)
+            continue;
+        const head = block.slice(0, open + 1);
+        let body = block.slice(open + 1, close);
+        const tail = block.slice(close);
+        const brandRe = /(^\s*readonly\s+__tsonic_type_[A-Za-z0-9_]+)\s*:\s*never\s*;/m;
+        if (!brandRe.test(body))
+            continue;
+        body = body.replace(brandRe, "$1?: never;");
+        const patchedBlock = head + body + tail;
+        next =
+            next.slice(0, match.index) +
+                patchedBlock +
+                next.slice(match.index + block.length);
     }
     if (next !== original) {
         writeFileSync(internalIndexDtsPath, next, "utf-8");
     }
     return { ok: true, value: undefined };
 };
+const splitTopLevelTypeArgs = (text) => {
+    const parts = [];
+    let depthAngle = 0;
+    let depthParen = 0;
+    let depthBrace = 0;
+    let depthBracket = 0;
+    let start = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        const ch = text[i];
+        if (ch === "<")
+            depthAngle += 1;
+        else if (ch === ">")
+            depthAngle = Math.max(0, depthAngle - 1);
+        else if (ch === "(")
+            depthParen += 1;
+        else if (ch === ")")
+            depthParen = Math.max(0, depthParen - 1);
+        else if (ch === "{")
+            depthBrace += 1;
+        else if (ch === "}")
+            depthBrace = Math.max(0, depthBrace - 1);
+        else if (ch === "[")
+            depthBracket += 1;
+        else if (ch === "]")
+            depthBracket = Math.max(0, depthBracket - 1);
+        else if (ch === "," &&
+            depthAngle === 0 &&
+            depthParen === 0 &&
+            depthBrace === 0 &&
+            depthBracket === 0) {
+            parts.push(text.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    parts.push(text.slice(start).trim());
+    return parts.filter((p) => p.length > 0);
+};
+const expandUnionsDeep = (typeText) => {
+    const unionPrefixRe = /Union_\d+</g;
+    let result = typeText;
+    // Iterate until no more Union_N< patterns remain
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        unionPrefixRe.lastIndex = 0;
+        const prefixMatch = unionPrefixRe.exec(result);
+        if (!prefixMatch)
+            break;
+        // Find the matching > for the < at the end of the prefix
+        const openAngle = prefixMatch.index + prefixMatch[0].length - 1;
+        let depth = 1;
+        let closeAngle = -1;
+        for (let i = openAngle + 1; i < result.length; i += 1) {
+            const ch = result[i];
+            if (ch === "<")
+                depth += 1;
+            else if (ch === ">") {
+                depth -= 1;
+                if (depth === 0) {
+                    closeAngle = i;
+                    break;
+                }
+            }
+        }
+        if (closeAngle < 0)
+            break;
+        const inner = result.slice(openAngle + 1, closeAngle);
+        const args = splitTopLevelTypeArgs(inner);
+        if (args.length < 2)
+            break;
+        const expanded = `(${args.join(" | ")})`;
+        result =
+            result.slice(0, prefixMatch.index) +
+                expanded +
+                result.slice(closeAngle + 1);
+    }
+    return result;
+};
+const patchFacadeWithSourceFunctionSignatures = (facadeDtsPath, signaturesByName) => {
+    if (!existsSync(facadeDtsPath)) {
+        return {
+            ok: false,
+            error: `Facade declaration file not found at ${facadeDtsPath}`,
+        };
+    }
+    const original = readFileSync(facadeDtsPath, "utf-8");
+    let next = original;
+    for (const [name, signatures] of Array.from(signaturesByName.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+        if (signatures.length === 0)
+            continue;
+        const fnRe = new RegExp(String.raw `^(export\s+declare\s+function\s+${escapeRegExp(name)}(?:<[\s\S]*?>)?\s*\([\s\S]*?\)\s*:\s*)([^;]+)(;)`, "m");
+        const currentMatch = fnRe.exec(next);
+        if (currentMatch) {
+            const existingReturnType = currentMatch[2]?.trim() ?? "";
+            const replacement = Array.from(new Set(signatures.map((sig) => {
+                const returnType = sig.returnTypeText.includes("{")
+                    ? expandUnionsDeep(existingReturnType)
+                    : sig.returnTypeText;
+                return `export declare function ${name}${sig.typeParametersText}(${sig.parametersText}): ${returnType};`;
+            }))).join("\n");
+            next = next.replace(fnRe, replacement);
+            continue;
+        }
+        // If no function declaration match, try const Func<...> pattern
+        const constFuncRe = new RegExp(String.raw `^export\s+declare\s+const\s+${escapeRegExp(name)}\s*:\s*Func<([\s\S]+?)>\s*;`, "m");
+        const constMatch = constFuncRe.exec(next);
+        if (!constMatch || !constMatch[1])
+            continue;
+        const funcTypeArgs = splitTopLevelTypeArgs(constMatch[1]);
+        if (funcTypeArgs.length < 2)
+            continue;
+        // Last arg = return type, remaining args = parameter types
+        const facadeParamTypes = funcTypeArgs.slice(0, -1);
+        const facadeReturnType = funcTypeArgs[funcTypeArgs.length - 1];
+        // Use the first source signature for parameter names
+        const sourceSig = signatures[0];
+        const sourceParams = sourceSig.parametersText
+            .split(",")
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0);
+        // If count mismatch, skip patching for this declaration
+        if (sourceParams.length !== facadeParamTypes.length)
+            continue;
+        // Pair source parameter NAMES with facade parameter TYPES
+        const pairedParams = sourceParams.map((param, idx) => {
+            const colonIdx = param.indexOf(":");
+            const paramName = colonIdx >= 0 ? param.slice(0, colonIdx).trim() : param.trim();
+            return `${paramName}: ${facadeParamTypes[idx]}`;
+        });
+        const expandedReturnType = expandUnionsDeep(facadeReturnType);
+        const typeParamsText = sourceSig.typeParametersText;
+        const replacement = `export declare function ${name}${typeParamsText}(${pairedParams.join(", ")}): ${expandedReturnType};`;
+        next = next.replace(constFuncRe, replacement);
+    }
+    if (next !== original) {
+        writeFileSync(facadeDtsPath, next, "utf-8");
+    }
+    return { ok: true, value: undefined };
+};
 const classifyExportKind = (module, name) => {
     const isNamed = (stmt) => typeof stmt.name === "string";
     const findDecl = () => {
         for (const stmt of module.body) {
-            if (!("isExported" in stmt) || stmt.isExported !== true)
+            if (!("isExported" in stmt) ||
+                stmt.isExported !== true)
                 continue;
             if (isNamed(stmt) && stmt.name === name)
                 return stmt;
@@ -256,7 +493,10 @@ const resolveLocalModuleFile = (fromModule, fromFile, modulesByFile) => {
 };
 const buildModuleSourceIndex = (absoluteFilePath, fileKey) => {
     if (!existsSync(absoluteFilePath)) {
-        return { ok: false, error: `Failed to read source file for bindings augmentation: ${absoluteFilePath}` };
+        return {
+            ok: false,
+            error: `Failed to read source file for bindings augmentation: ${absoluteFilePath}`,
+        };
     }
     const content = readFileSync(absoluteFilePath, "utf-8");
     const scriptKind = absoluteFilePath.endsWith(".tsx")
@@ -268,13 +508,26 @@ const buildModuleSourceIndex = (absoluteFilePath, fileKey) => {
     const wrapperImportsByLocalName = new Map();
     const typeImportsByLocalName = new Map();
     const typeAliasesByName = new Map();
+    const exportedFunctionSignaturesByName = new Map();
     const memberTypesByClassAndMember = new Map();
-    const getMemberName = (name) => {
-        if (ts.isIdentifier(name))
-            return name.text;
-        if (ts.isStringLiteral(name) || ts.isNumericLiteral(name))
-            return name.text;
-        return undefined;
+    const printTypeParametersText = (typeParameters) => {
+        if (!typeParameters || typeParameters.length === 0)
+            return "";
+        return `<${typeParameters.map((tp) => tp.getText(sourceFile)).join(", ")}>`;
+    };
+    const printParameterText = (param) => {
+        const rest = param.dotDotDotToken ? "..." : "";
+        const name = param.name.getText(sourceFile);
+        const optional = param.questionToken ? "?" : "";
+        const type = param.type
+            ? printTypeNodeText(param.type, sourceFile)
+            : "unknown";
+        return `${rest}${name}${optional}: ${type}`;
+    };
+    const addExportedFunctionSignature = (name, sig) => {
+        const list = exportedFunctionSignaturesByName.get(name) ?? [];
+        list.push(sig);
+        exportedFunctionSignaturesByName.set(name, list);
     };
     for (const stmt of sourceFile.statements) {
         if (ts.isImportDeclaration(stmt)) {
@@ -295,9 +548,15 @@ const buildModuleSourceIndex = (absoluteFilePath, fileKey) => {
                 const isTypeOnly = clause.isTypeOnly || spec.isTypeOnly;
                 if (!isTypeOnly)
                     continue;
-                typeImportsByLocalName.set(localName, { source: moduleSpecifier, importedName });
+                typeImportsByLocalName.set(localName, {
+                    source: moduleSpecifier,
+                    importedName,
+                });
                 if (importedName === "ExtensionMethods") {
-                    wrapperImportsByLocalName.set(localName, { source: moduleSpecifier, importedName });
+                    wrapperImportsByLocalName.set(localName, {
+                        source: moduleSpecifier,
+                        importedName,
+                    });
                 }
             }
             continue;
@@ -308,31 +567,102 @@ const buildModuleSourceIndex = (absoluteFilePath, fileKey) => {
             typeAliasesByName.set(aliasName, { typeParameters, type: stmt.type });
             continue;
         }
+        if (ts.isFunctionDeclaration(stmt)) {
+            const hasExport = stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+            if (!hasExport || !stmt.name || !stmt.type)
+                continue;
+            const parametersText = stmt.parameters.map(printParameterText).join(", ");
+            addExportedFunctionSignature(stmt.name.text, {
+                typeParametersText: printTypeParametersText(stmt.typeParameters),
+                parametersText,
+                returnTypeText: printTypeNodeText(stmt.type, sourceFile),
+            });
+            continue;
+        }
+        if (ts.isVariableStatement(stmt)) {
+            const hasExport = stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+            if (!hasExport)
+                continue;
+            for (const decl of stmt.declarationList.declarations) {
+                if (!ts.isIdentifier(decl.name))
+                    continue;
+                const exportName = decl.name.text;
+                const init = decl.initializer;
+                if (!init)
+                    continue;
+                if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+                    const returnType = init.type;
+                    if (!returnType)
+                        continue;
+                    const parametersText = init.parameters
+                        .map(printParameterText)
+                        .join(", ");
+                    addExportedFunctionSignature(exportName, {
+                        typeParametersText: printTypeParametersText(init.typeParameters),
+                        parametersText,
+                        returnTypeText: printTypeNodeText(returnType, sourceFile),
+                    });
+                }
+            }
+            continue;
+        }
         if (ts.isClassDeclaration(stmt) && stmt.name) {
             const className = stmt.name.text;
-            const members = memberTypesByClassAndMember.get(className) ?? new Map();
+            const members = memberTypesByClassAndMember.get(className) ??
+                new Map();
             for (const member of stmt.members) {
                 if (ts.isGetAccessorDeclaration(member)) {
                     if (!member.name || !member.type)
                         continue;
-                    const name = getMemberName(member.name);
+                    const name = getPropertyNameText(member.name);
                     if (!name)
                         continue;
-                    members.set(name, member.type);
+                    members.set(name, {
+                        typeNode: member.type,
+                        typeText: printTypeNodeText(member.type, sourceFile),
+                        isOptional: false,
+                    });
                     continue;
                 }
                 if (ts.isPropertyDeclaration(member)) {
                     if (!member.name || !member.type)
                         continue;
-                    const name = getMemberName(member.name);
+                    const name = getPropertyNameText(member.name);
                     if (!name)
                         continue;
-                    members.set(name, member.type);
+                    members.set(name, {
+                        typeNode: member.type,
+                        typeText: printTypeNodeText(member.type, sourceFile),
+                        isOptional: member.questionToken !== undefined,
+                    });
                 }
             }
             if (members.size > 0) {
                 memberTypesByClassAndMember.set(className, members);
             }
+            continue;
+        }
+        if (ts.isInterfaceDeclaration(stmt)) {
+            const interfaceName = stmt.name.text;
+            const members = memberTypesByClassAndMember.get(interfaceName) ??
+                new Map();
+            for (const member of stmt.members) {
+                if (!ts.isPropertySignature(member))
+                    continue;
+                if (!member.name || !member.type)
+                    continue;
+                const name = getPropertyNameText(member.name);
+                if (!name)
+                    continue;
+                members.set(name, {
+                    typeNode: member.type,
+                    typeText: printTypeNodeText(member.type, sourceFile),
+                    isOptional: member.questionToken !== undefined,
+                });
+            }
+            if (members.size > 0) {
+                memberTypesByClassAndMember.set(interfaceName, members);
+            }
         }
     }
     return {
@@ -342,10 +672,27 @@ const buildModuleSourceIndex = (absoluteFilePath, fileKey) => {
             wrapperImportsByLocalName,
             typeImportsByLocalName,
             typeAliasesByName,
+            exportedFunctionSignaturesByName,
             memberTypesByClassAndMember,
         },
     };
 };
+const typeNodeUsesImportedTypeNames = (node, typeImportsByLocalName) => {
+    let found = false;
+    const visit = (current) => {
+        if (found)
+            return;
+        if (ts.isTypeReferenceNode(current) && ts.isIdentifier(current.typeName)) {
+            if (typeImportsByLocalName.has(current.typeName.text)) {
+                found = true;
+                return;
+            }
+        }
+        ts.forEachChild(current, visit);
+    };
+    visit(node);
+    return found;
+};
 const unwrapParens = (node) => {
     let current = node;
     while (ts.isParenthesizedTypeNode(current)) {
@@ -399,7 +746,8 @@ const collectExtensionWrapperImportsFromSourceType = (opts) => {
             continue;
         }
         const imported = info.typeImportsByLocalName.get(ident);
-        if (imported && (imported.source.startsWith(".") || imported.source.startsWith("/"))) {
+        if (imported &&
+            (imported.source.startsWith(".") || imported.source.startsWith("/"))) {
             const targetModule = resolveLocalModuleFile(imported.source, currentModuleKey, opts.modulesByFileKey);
             if (targetModule) {
                 const targetKey = normalizeModuleFileKey(targetModule.filePath);
@@ -453,7 +801,9 @@ const printIrType = (type, ctx) => {
         case "primitiveType":
             return type.name;
         case "literalType":
-            return typeof type.value === "string" ? JSON.stringify(type.value) : String(type.value);
+            return typeof type.value === "string"
+                ? JSON.stringify(type.value)
+                : String(type.value);
         case "anyType":
             return "any";
         case "unknownType":
@@ -469,7 +819,9 @@ const printIrType = (type, ctx) => {
             const args = type.typeArguments ?? [];
             if (args.length === 0)
                 return base;
-            const rendered = args.map((a) => printIrType(a, { parentPrecedence: 0 })).join(", ");
+            const rendered = args
+                .map((a) => printIrType(a, { parentPrecedence: 0 }))
+                .join(", ");
             return `${base}<${rendered}>`;
         }
         case "arrayType":
@@ -484,7 +836,9 @@ const printIrType = (type, ctx) => {
                         return p.pattern.name;
                     return `p${i + 1}`;
                 })();
-                const t = p.type ? printIrType(p.type, { parentPrecedence: 0 }) : "unknown";
+                const t = p.type
+                    ? printIrType(p.type, { parentPrecedence: 0 })
+                    : "unknown";
                 return `${name}: ${t}`;
             })
                 .join(", ");
@@ -492,11 +846,15 @@ const printIrType = (type, ctx) => {
             return wrap(`(${ps}) => ${ret}`, 2);
         }
         case "unionType": {
-            const rendered = type.types.map((t) => printIrType(t, { parentPrecedence: 0 })).join(" | ");
+            const rendered = type.types
+                .map((t) => printIrType(t, { parentPrecedence: 0 }))
+                .join(" | ");
             return wrap(rendered, 0);
         }
         case "intersectionType": {
-            const rendered = type.types.map((t) => printIrType(t, { parentPrecedence: 1 })).join(" & ");
+            const rendered = type.types
+                .map((t) => printIrType(t, { parentPrecedence: 1 }))
+                .join(" & ");
             return wrap(rendered, 1);
         }
         case "dictionaryType": {
@@ -504,10 +862,40 @@ const printIrType = (type, ctx) => {
             const v = printIrType(type.valueType, { parentPrecedence: 0 });
             return `Record<${k}, ${v}>`;
         }
-        case "objectType":
-            // Object type aliases are materialized as __Alias CLR types in source builds.
-            // If we reach here, the alias printer should have handled it separately.
-            return "{ /* object */ }";
+        case "objectType": {
+            if (type.members.length === 0)
+                return "{}";
+            const members = type.members
+                .map((member) => {
+                if (member.kind === "propertySignature") {
+                    const readonly = member.isReadonly ? "readonly " : "";
+                    const optional = member.isOptional ? "?" : "";
+                    const memberType = printIrType(member.type, {
+                        parentPrecedence: 0,
+                    });
+                    return `${readonly}${member.name}${optional}: ${memberType}`;
+                }
+                const typeParams = printTypeParameters(member.typeParameters);
+                const args = member.parameters
+                    .map((p, i) => {
+                    const name = p.pattern.kind === "identifierPattern"
+                        ? p.pattern.name
+                        : `p${i + 1}`;
+                    const optional = p.isOptional ? "?" : "";
+                    const paramType = p.type
+                        ? printIrType(p.type, { parentPrecedence: 0 })
+                        : "unknown";
+                    return `${name}${optional}: ${paramType}`;
+                })
+                    .join(", ");
+                const returnType = member.returnType
+                    ? printIrType(member.returnType, { parentPrecedence: 0 })
+                    : "void";
+                return `${member.name}${typeParams}(${args}): ${returnType}`;
+            })
+                .join("; ");
+            return `{ ${members} }`;
+        }
         default:
             // Exhaustiveness safety
             return "unknown";
@@ -529,11 +917,74 @@ const renderExportedTypeAlias = (stmt, internalIndexDts) => {
         const typeArgs = stmt.typeParameters && stmt.typeParameters.length > 0
             ? `<${stmt.typeParameters.map((tp) => tp.name).join(", ")}>`
             : "";
-        return { ok: true, value: `export type ${stmt.name}${typeParams} = Internal.${internalName}${typeArgs};` };
+        return {
+            ok: true,
+            value: `export type ${stmt.name}${typeParams} = Internal.${internalName}${typeArgs};`,
+        };
     }
     const rhs = printIrType(stmt.type, { parentPrecedence: 0 });
     return { ok: true, value: `export type ${stmt.name}${typeParams} = ${rhs};` };
 };
+/**
+ * Overlay already-augmented bindings from dependency assemblies.
+ *
+ * When a library references sibling Tsonic-built libraries (via references.libraries),
+ * tsbindgen regenerates types from CLR metadata, losing source-level augmentation
+ * (literal types, optional markers, brand optionality, etc.). The dependency's published
+ * bindings already have this augmentation applied, so we overlay them onto the
+ * freshly-generated copies.
+ */
+export const overlayDependencyBindings = (config, bindingsOutDir) => {
+    const depBindingsDirByAssembly = new Map();
+    for (const lib of config.libraries) {
+        if (!lib.toLowerCase().endsWith(".dll"))
+            continue;
+        const assemblyName = basename(lib, ".dll");
+        // Skip the current package's own assembly.
+        if (assemblyName === config.outputName)
+            continue;
+        // Convention: DLL at <project>/dist/<dotnetVersion>/<name>.dll,
+        // bindings at <project>/dist/tsonic/bindings/.
+        const depBindingsDir = join(dirname(dirname(lib)), "tsonic", "bindings");
+        if (existsSync(depBindingsDir)) {
+            depBindingsDirByAssembly.set(assemblyName, depBindingsDir);
+        }
+    }
+    if (depBindingsDirByAssembly.size === 0) {
+        return { ok: true, value: undefined };
+    }
+    // Scan generated bindings for namespace directories with internal/index.d.ts.
+    const generatedNamespaces = readdirSync(bindingsOutDir, {
+        withFileTypes: true,
+    })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+    for (const ns of generatedNamespaces) {
+        const internalIndexPath = join(bindingsOutDir, ns, "internal", "index.d.ts");
+        if (!existsSync(internalIndexPath))
+            continue;
+        const content = readFileSync(internalIndexPath, "utf-8");
+        const assemblyMatch = content.match(/^\/\/ Assembly:\s*(.+)\s*$/m);
+        if (!assemblyMatch || !assemblyMatch[1])
+            continue;
+        const assembly = assemblyMatch[1].trim();
+        const depDir = depBindingsDirByAssembly.get(assembly);
+        if (!depDir)
+            continue;
+        // Overlay the dependency's already-augmented internal/index.d.ts.
+        const depInternalIndex = join(depDir, ns, "internal", "index.d.ts");
+        if (existsSync(depInternalIndex)) {
+            copyFileSync(depInternalIndex, internalIndexPath);
+        }
+        // Overlay the dependency's facade .d.ts (may have type aliases, re-exports).
+        const facadeDts = join(bindingsOutDir, `${ns}.d.ts`);
+        const depFacadeDts = join(depDir, `${ns}.d.ts`);
+        if (existsSync(facadeDts) && existsSync(depFacadeDts)) {
+            copyFileSync(depFacadeDts, facadeDts);
+        }
+    }
+    return { ok: true, value: undefined };
+};
 export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
     const entryPoint = config.entryPoint;
     if (!entryPoint) {
@@ -552,7 +1003,10 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
     };
     const graphResult = buildModuleDependencyGraph(absoluteEntryPoint, compilerOptions);
     if (!graphResult.ok) {
-        return { ok: false, error: `Failed to analyze library sources:\n${renderDiagnostics(graphResult.error)}` };
+        return {
+            ok: false,
+            error: `Failed to analyze library sources:\n${renderDiagnostics(graphResult.error)}`,
+        };
     }
     const { modules, entryModule } = graphResult.value;
     const facadesByNamespace = new Map(indexFacadeFiles(bindingsOutDir));
@@ -661,8 +1115,10 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
                         `Could not find an exported declaration named '${exp.originalName}' in ${targetModule.filePath}.`,
                 };
             }
+            const spec = exp.name === exp.originalName
+                ? exp.name
+                : `${exp.originalName} as ${exp.name}`;
             const isTypeOnly = kind === "type";
-            const spec = exp.name === exp.originalName ? exp.name : `${exp.originalName} as ${exp.name}`;
             const key = `${targetFacade.moduleSpecifier}|${isTypeOnly ? "type" : "value"}`;
             const list = grouped.get(key) ?? [];
             list.push(spec);
@@ -697,13 +1153,20 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
             writeFileSync(entryFacade.facadeJsPath, next, "utf-8");
         }
     }
-    // 3) Preserve TS-authored extension wrapper annotations on exported class members.
+    // 3) Preserve TS-authored member typing semantics on exported class/interface members.
     // These wrapper types (ExtensionMethods<...>) do not exist in CLR metadata and therefore
     // cannot be discovered by tsbindgen when generating bindings from the DLL. We can,
     // however, safely re-apply them for Tsonic-authored libraries by reading the TS source
-    // graph and wrapping the CLR base member type in the published internal/index.d.ts.
+    // graph and patching the published internal/index.d.ts:
+    // - Re-apply ExtensionMethods wrappers (class + interface members)
+    // - Preserve optional (`?`) semantics by allowing `undefined` on patched members
+    // - For exported interfaces, preserve source structural member types when safe
     const sourceIndexByFileKey = new Map();
     for (const m of modules) {
+        // Synthetic IR modules (e.g., program-wide anonymous type declarations) do not
+        // correspond to real source files and must be ignored by source-based augmentation.
+        if (m.filePath.startsWith("__tsonic/"))
+            continue;
         const key = normalizeModuleFileKey(m.filePath);
         const absolutePath = resolve(absoluteSourceRoot, key);
         const indexed = buildModuleSourceIndex(absolutePath, key);
@@ -712,15 +1175,35 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
         sourceIndexByFileKey.set(key, indexed.value);
     }
     const overridesByInternalIndex = new Map();
+    const brandOptionalTypesByInternalIndex = new Map();
+    const functionSignaturesByFacade = new Map();
     for (const m of modules) {
-        const exportedClasses = m.body.filter((s) => s.kind === "classDeclaration" && s.isExported);
-        if (exportedClasses.length === 0)
+        if (m.filePath.startsWith("__tsonic/"))
             continue;
+        const exportedClasses = m.body.filter((s) => s.kind === "classDeclaration" && s.isExported);
+        const exportedInterfaces = m.body.filter((s) => s.kind === "interfaceDeclaration" && s.isExported);
+        const exportedAliases = m.body.filter((s) => s.kind === "typeAliasDeclaration" && s.isExported);
         const moduleKey = normalizeModuleFileKey(m.filePath);
         const sourceIndex = sourceIndexByFileKey.get(moduleKey);
         if (!sourceIndex)
             continue;
+        const hasExportedSourceFunctions = sourceIndex.exportedFunctionSignaturesByName.size > 0;
+        if (exportedClasses.length === 0 &&
+            exportedInterfaces.length === 0 &&
+            exportedAliases.length === 0 &&
+            !hasExportedSourceFunctions)
+            continue;
         const info = facadesByNamespace.get(m.namespace) ?? ensureFacade(m.namespace);
+        for (const [name, signatures,] of sourceIndex.exportedFunctionSignaturesByName) {
+            if (signatures.length === 0)
+                continue;
+            const byName = functionSignaturesByFacade.get(info.facadeDtsPath) ??
+                new Map();
+            const list = byName.get(name) ?? [];
+            list.push(...signatures);
+            byName.set(name, list);
+            functionSignaturesByFacade.set(info.facadeDtsPath, byName);
+        }
         for (const cls of exportedClasses) {
             const memberTypes = sourceIndex.memberTypesByClassAndMember.get(cls.name);
             if (!memberTypes)
@@ -732,25 +1215,115 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
                     continue;
                 if (member.accessibility === "private")
                     continue;
-                const annotatedType = memberTypes.get(member.name);
-                if (!annotatedType)
+                const sourceMember = memberTypes.get(member.name);
+                if (!sourceMember)
                     continue;
                 const wrappersResult = collectExtensionWrapperImportsFromSourceType({
                     startModuleKey: moduleKey,
-                    typeNode: annotatedType,
+                    typeNode: sourceMember.typeNode,
                     sourceIndexByFileKey,
                     modulesByFileKey: modulesByFile,
                 });
                 if (!wrappersResult.ok)
                     return wrappersResult;
                 const wrappers = wrappersResult.value;
-                if (wrappers.length === 0)
+                if (wrappers.length === 0 && !sourceMember.isOptional)
                     continue;
                 const list = overridesByInternalIndex.get(info.internalIndexDtsPath) ?? [];
                 list.push({
                     namespace: m.namespace,
                     className: cls.name,
                     memberName: member.name,
+                    isOptional: sourceMember.isOptional,
+                    wrappers,
+                });
+                overridesByInternalIndex.set(info.internalIndexDtsPath, list);
+            }
+        }
+        for (const iface of exportedInterfaces) {
+            const memberTypes = sourceIndex.memberTypesByClassAndMember.get(iface.name);
+            if (!memberTypes)
+                continue;
+            for (const member of iface.members) {
+                if (member.kind !== "propertySignature")
+                    continue;
+                const sourceMember = memberTypes.get(member.name);
+                if (!sourceMember)
+                    continue;
+                const wrappersResult = collectExtensionWrapperImportsFromSourceType({
+                    startModuleKey: moduleKey,
+                    typeNode: sourceMember.typeNode,
+                    sourceIndexByFileKey,
+                    modulesByFileKey: modulesByFile,
+                });
+                if (!wrappersResult.ok)
+                    return wrappersResult;
+                const wrappers = wrappersResult.value;
+                const canUseSourceTypeText = !typeNodeUsesImportedTypeNames(sourceMember.typeNode, sourceIndex.typeImportsByLocalName);
+                if (!canUseSourceTypeText && wrappers.length === 0)
+                    continue;
+                const list = overridesByInternalIndex.get(info.internalIndexDtsPath) ?? [];
+                list.push({
+                    namespace: m.namespace,
+                    className: iface.name,
+                    memberName: member.name,
+                    sourceTypeText: canUseSourceTypeText
+                        ? sourceMember.typeText
+                        : undefined,
+                    replaceWithSourceType: canUseSourceTypeText,
+                    isOptional: sourceMember.isOptional,
+                    wrappers,
+                });
+                overridesByInternalIndex.set(info.internalIndexDtsPath, list);
+            }
+            const brandTargets = brandOptionalTypesByInternalIndex.get(info.internalIndexDtsPath) ??
+                new Set();
+            brandTargets.add(iface.name);
+            brandOptionalTypesByInternalIndex.set(info.internalIndexDtsPath, brandTargets);
+        }
+        for (const alias of exportedAliases) {
+            const sourceAlias = sourceIndex.typeAliasesByName.get(alias.name);
+            if (!sourceAlias)
+                continue;
+            const aliasType = unwrapParens(sourceAlias.type);
+            if (!ts.isTypeLiteralNode(aliasType))
+                continue;
+            const arity = sourceAlias.typeParameters.length;
+            const internalAliasName = `${alias.name}__Alias${arity > 0 ? `_${arity}` : ""}`;
+            const brandTargets = brandOptionalTypesByInternalIndex.get(info.internalIndexDtsPath) ??
+                new Set();
+            brandTargets.add(internalAliasName);
+            brandOptionalTypesByInternalIndex.set(info.internalIndexDtsPath, brandTargets);
+            for (const member of aliasType.members) {
+                if (!ts.isPropertySignature(member))
+                    continue;
+                if (!member.name || !member.type)
+                    continue;
+                const memberName = getPropertyNameText(member.name);
+                if (!memberName)
+                    continue;
+                const wrappersResult = collectExtensionWrapperImportsFromSourceType({
+                    startModuleKey: moduleKey,
+                    typeNode: member.type,
+                    sourceIndexByFileKey,
+                    modulesByFileKey: modulesByFile,
+                });
+                if (!wrappersResult.ok)
+                    return wrappersResult;
+                const wrappers = wrappersResult.value;
+                const canUseSourceTypeText = !typeNodeUsesImportedTypeNames(member.type, sourceIndex.typeImportsByLocalName);
+                if (!canUseSourceTypeText && wrappers.length === 0)
+                    continue;
+                const list = overridesByInternalIndex.get(info.internalIndexDtsPath) ?? [];
+                list.push({
+                    namespace: m.namespace,
+                    className: internalAliasName,
+                    memberName,
+                    sourceTypeText: canUseSourceTypeText
+                        ? printTypeNodeText(member.type, member.getSourceFile())
+                        : undefined,
+                    replaceWithSourceType: canUseSourceTypeText,
+                    isOptional: member.questionToken !== undefined,
                     wrappers,
                 });
                 overridesByInternalIndex.set(info.internalIndexDtsPath, list);
@@ -762,6 +1335,16 @@ export const augmentLibraryBindingsFromSource = (config, bindingsOutDir) => {
         if (!result.ok)
             return result;
     }
+    for (const [internalIndex, typeNames] of brandOptionalTypesByInternalIndex) {
+        const result = patchInternalIndexBrandMarkersOptional(internalIndex, Array.from(typeNames.values()));
+        if (!result.ok)
+            return result;
+    }
+    for (const [facadePath, signaturesByName] of functionSignaturesByFacade) {
+        const result = patchFacadeWithSourceFunctionSignatures(facadePath, signaturesByName);
+        if (!result.ok)
+            return result;
+    }
     return { ok: true, value: undefined };
 };
 //# sourceMappingURL=library-bindings-augment.js.map