@tsonic/frontend 0.0.14 → 0.0.16

package/dist/ir/binding/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Binding Layer — TS Symbol Resolution with Opaque Handles
+ *
+ * This module wraps TypeScript's symbol resolution APIs and returns opaque
+ * handles (DeclId, SignatureId, MemberId) instead of ts.Symbol/ts.Signature.
+ *
+ * ALLOWED APIs (symbol resolution only):
+ * - checker.getSymbolAtLocation(node) — Find symbol at AST node
+ * - checker.getAliasedSymbol(symbol) — Resolve import alias
+ * - checker.getExportSymbolOfSymbol(symbol) — Resolve export
+ * - symbol.getDeclarations() — Get AST declaration nodes
+ * - checker.getResolvedSignature(call) — Pick overload (type from declaration)
+ *
+ * BANNED APIs (these produce ts.Type, which violates INV-0):
+ * - checker.getTypeAtLocation
+ * - checker.getTypeOfSymbolAtLocation
+ * - checker.getContextualType
+ * - checker.typeToTypeNode
+ */
+import ts from "typescript";
+import { DeclId, SignatureId, MemberId, TypeSyntaxId } from "../type-system/types.js";
+import type { HandleRegistry } from "../type-system/internal/handle-types.js";
+/**
+ * Binding interface — wraps TS symbol resolution APIs.
+ *
+ * All methods return opaque handles. Use HandleRegistry to look up
+ * the underlying declaration/signature information.
+ */
+export interface Binding {
+    /**
+     * Resolve an identifier to its declaration.
+     * Uses checker.getSymbolAtLocation + symbol.getDeclarations().
+     */
+    resolveIdentifier(node: ts.Identifier): DeclId | undefined;
+    /**
+     * Resolve a type reference to its declaration.
+     * For qualified names (A.B.C), resolves the rightmost symbol.
+     */
+    resolveTypeReference(node: ts.TypeReferenceNode): DeclId | undefined;
+    /**
+     * Resolve a property access to its member declaration.
+     */
+    resolvePropertyAccess(node: ts.PropertyAccessExpression): MemberId | undefined;
+    /**
+     * Resolve an element access to its member (for known keys).
+     */
+    resolveElementAccess(node: ts.ElementAccessExpression): MemberId | undefined;
+    /**
+     * Pick the correct overload for a call expression.
+     * Uses checker.getResolvedSignature to pick the overload.
+     */
+    resolveCallSignature(node: ts.CallExpression): SignatureId | undefined;
+    /**
+     * Return candidate overload signatures for a call expression, filtered by arity.
+     *
+     * This is used when TypeScript overload selection is ambiguous due to
+     * erased types in the TS layer (e.g., `char` is `string` in TypeScript).
+     *
+     * IMPORTANT: This returns *candidates*, not the final selection.
+     * The TypeSystem remains the authority for semantic selection.
+     */
+    resolveCallSignatureCandidates(node: ts.CallExpression): readonly SignatureId[] | undefined;
+    /**
+     * Resolve new expression constructor signature.
+     */
+    resolveConstructorSignature(node: ts.NewExpression): SignatureId | undefined;
+    /**
+     * Return candidate overload signatures for a constructor call, filtered by arity.
+     */
+    resolveConstructorSignatureCandidates(node: ts.NewExpression): readonly SignatureId[] | undefined;
+    /**
+     * Resolve an import specifier to its actual declaration.
+     * Uses checker.getAliasedSymbol to follow the import chain.
+     */
+    resolveImport(node: ts.ImportSpecifier): DeclId | undefined;
+    /**
+     * Resolve a shorthand property assignment to its declaration.
+     * For `{ foo }` syntax, resolves `foo` to its declaration.
+     */
+    resolveShorthandAssignment(node: ts.ShorthandPropertyAssignment): DeclId | undefined;
+    /**
+     * Get the declaring type name for a resolved member handle.
+     *
+     * This is used for features that depend on the syntactic container of a member
+     * declaration (e.g. tsbindgen extension-method interfaces like `__Ext_*`).
+     */
+    getDeclaringTypeNameOfMember(member: MemberId): string | undefined;
+    /**
+     * Get the absolute source file path where a resolved member is declared.
+     *
+     * Used to disambiguate tsbindgen bindings when multiple CLR types share the same
+     * TS alias (e.g., `Server.listen` exists on both `nodejs.Server` and `nodejs.Http.Server`).
+     */
+    getSourceFilePathOfMember(member: MemberId): string | undefined;
+    /**
+     * Get the fully-qualified name for a declaration.
+     * Used for override detection and .NET type identification.
+     */
+    getFullyQualifiedName(decl: DeclId): string | undefined;
+    /**
+     * Get type predicate information from a signature.
+     * For functions with `x is T` return type.
+     */
+    getTypePredicateOfSignature(sig: SignatureId): TypePredicateInfo | undefined;
+    /**
+     * Capture a type syntax node for later conversion.
+     *
+     * Used for inline type syntax that cannot be captured at catalog-build time:
+     * - `as Foo` type assertions
+     * - `satisfies Bar` expressions
+     * - Generic type arguments in expressions
+     *
+     * The captured syntax can be converted to IrType via TypeSystem.typeFromSyntax().
+     * This is NOT an escape hatch — it's the correct boundary for inline syntax.
+     */
+    captureTypeSyntax(node: ts.TypeNode): TypeSyntaxId;
+    /**
+     * Capture multiple type arguments.
+     *
+     * Convenience method for capturing generic type arguments like `Foo<A, B, C>`.
+     */
+    captureTypeArgs(nodes: readonly ts.TypeNode[]): readonly TypeSyntaxId[];
+}
+/**
+ * BindingInternal — extended interface for TypeSystem construction only.
+ *
+ * INVARIANT (Alice's spec): Only createTypeSystem() should access
+ * _getHandleRegistry(). All other code uses the TypeSystem API.
+ */
+export interface BindingInternal extends Binding {
+    /**
+     * Get the handle registry for TypeSystem construction.
+     *
+     * INTERNAL USE ONLY: This method is NOT part of the public Binding API.
+     * Only createTypeSystem() should call this to access declaration info.
+     * All other code should use TypeSystem queries instead.
+     */
+    _getHandleRegistry(): HandleRegistry;
+}
+/**
+ * Type predicate information for `x is T` predicates.
+ */
+export type TypePredicateInfo = {
+    readonly kind: "typePredicate";
+    readonly parameterIndex: number;
+    readonly typeNode?: ts.TypeNode;
+};
+/**
+ * Create a Binding instance for a TypeScript program.
+ *
+ * Returns BindingInternal which includes _getHandleRegistry() for TypeSystem.
+ * Cast to Binding when passing to regular converters.
+ */
+export declare const createBinding: (checker: ts.TypeChecker) => BindingInternal;
+//# sourceMappingURL=index.d.ts.map

package/dist/ir/binding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ir/binding/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EACL,MAAM,EACN,WAAW,EACX,QAAQ,EACR,YAAY,EAKb,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EACV,cAAc,EAUf,MAAM,yCAAyC,CAAC;AAOjD;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IAKtB;;;OAGG;IACH,iBAAiB,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IAE3D;;;OAGG;IACH,oBAAoB,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAAC;IAErE;;OAEG;IACH,qBAAqB,CACnB,IAAI,EAAE,EAAE,CAAC,wBAAwB,GAChC,QAAQ,GAAG,SAAS,CAAC;IAExB;;OAEG;IACH,oBAAoB,CAAC,IAAI,EAAE,EAAE,CAAC,uBAAuB,GAAG,QAAQ,GAAG,SAAS,CAAC;IAM7E;;;OAGG;IACH,oBAAoB,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,GAAG,WAAW,GAAG,SAAS,CAAC;IAEvE;;;;;;;;OAQG;IACH,8BAA8B,CAC5B,IAAI,EAAE,EAAE,CAAC,cAAc,GACtB,SAAS,WAAW,EAAE,GAAG,SAAS,CAAC;IAEtC;;OAEG;IACH,2BAA2B,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;IAE7E;;OAEG;IACH,qCAAqC,CACnC,IAAI,EAAE,EAAE,CAAC,aAAa,GACrB,SAAS,WAAW,EAAE,GAAG,SAAS,CAAC;IAMtC;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC;IAM5D;;;OAGG;IACH,0BAA0B,CACxB,IAAI,EAAE,EAAE,CAAC,2BAA2B,GACnC,MAAM,GAAG,SAAS,CAAC;IAEtB;;;;;OAKG;IACH,4BAA4B,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IAEnE;;;;;OAKG;IACH,yBAAyB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IAEhE;;;OAGG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAExD;;;OAGG;IACH,2BAA2B,CAAC,GAAG,EAAE,WAAW,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAM7E;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,GAAG,YAAY,CAAC;IAEnD;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,QAAQ,EAAE,GAAG,SAAS,YAAY,EAAE,CAAC;CACzE;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAgB,SAAQ,OAAO;IAC9C;;;;;;OAMG;IACH,kBAAkB,IAAI,cAAc,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC;CACjC,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,EAAE,CAAC,WAAW,KAAG,eAiuBvD,CAAC"}