numtypes 0.0.0

package/dist/transformer/ts-compat.js

@@ -0,0 +1,24 @@
+import * as ts from "typescript";
+export function isImportClauseTypeOnly(importClause) {
+    const fields = getImportClauseCompatFields(importClause);
+    if ("phaseModifier" in fields) {
+        return fields.phaseModifier === ts.SyntaxKind.TypeKeyword;
+    }
+    return fields.isTypeOnly === true;
+}
+export function updateImportClauseCompat(factory, importClause, name, namedBindings) {
+    const fields = getImportClauseCompatFields(importClause);
+    if ("phaseModifier" in fields) {
+        return factory.updateImportClause(importClause, fields.phaseModifier, name, namedBindings);
+    }
+    return updateImportClauseWithIsTypeOnly(factory, importClause, fields.isTypeOnly === true, name, namedBindings);
+}
+function updateImportClauseWithIsTypeOnly(factory, importClause, isTypeOnly, name, namedBindings) {
+    // TypeScript 5.8 exposes only the boolean import-clause update overload.
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    return factory.updateImportClause(importClause, isTypeOnly, name, namedBindings);
+}
+function getImportClauseCompatFields(importClause) {
+    return importClause;
+}
+//# sourceMappingURL=ts-compat.js.map

package/dist/transformer/ts-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ts-compat.js","sourceRoot":"","sources":["../../src/transformer/ts-compat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAgBjC,MAAM,UAAU,sBAAsB,CAAC,YAA6B;IAClE,MAAM,MAAM,GACV,2BAA2B,CAAC,YAAY,CAAC,CAAC;IAE5C,IAAI,eAAe,IAAI,MAAM,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC,aAAa,KAAK,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;IAC5D,CAAC;IAED,OAAO,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,OAAuB,EACvB,YAA6B,EAC7B,IAA+B,EAC/B,aAAiD;IAEjD,MAAM,MAAM,GACV,2BAA2B,CAAC,YAAY,CAAC,CAAC;IAE5C,IAAI,eAAe,IAAI,MAAM,EAAE,CAAC;QAC9B,OAAQ,OAA4C,CAAC,kBAAkB,CACrE,YAAY,EACZ,MAAM,CAAC,aAAa,EACpB,IAAI,EACJ,aAAa,CACd,CAAC;IACJ,CAAC;IAED,OAAO,gCAAgC,CACrC,OAAO,EACP,YAAY,EACZ,MAAM,CAAC,UAAU,KAAK,IAAI,EAC1B,IAAI,EACJ,aAAa,CACd,CAAC;AACJ,CAAC;AAED,SAAS,gCAAgC,CACvC,OAAuB,EACvB,YAA6B,EAC7B,UAAmB,EACnB,IAA+B,EAC/B,aAAiD;IAEjD,yEAAyE;IACzE,4DAA4D;IAC5D,OAAO,OAAO,CAAC,kBAAkB,CAC/B,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,aAAa,CACd,CAAC;AACJ,CAAC;AAED,SAAS,2BAA2B,CAClC,YAA6B;IAE7B,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/docs/implementation-plan.md

@@ -0,0 +1,335 @@
+# Implementation Plan
+
+This document describes the staged implementation plan for the transformer.
+
+The core constraint is that TypeScript widens most branded numeric operations
+back to `number`. For example, if `a: i32` and `b: i32`, TypeScript evaluates
+`a + b` as `number`, not `i32`. The transformer must therefore maintain its own
+numeric-domain analysis instead of relying only on `checker.getTypeAtLocation`.
+
+## Terminology
+
+`TypeScript type` means the type reported by the TypeScript checker.
+
+`Numeric domain` means the transformer's internal classification:
+
+```text
+i32 | u32 | f32 | f64 | plain-number | unknown
+```
+
+`Domain-bound expression` means an expression whose result is known by the
+transformer to be closed over one numeric domain, even if TypeScript reports the
+expression as `number`.
+
+`Domain storage` means an lvalue location whose TypeScript type records a
+numeric domain for later operation dispatch. It does not guarantee that the
+stored JavaScript value has already been coerced into that domain.
+
+- a variable, parameter, property, or return position annotated with a numtypes
+  branded type;
+- a value inferred from a checked cast call such as `i32(expr)` or an unchecked
+  TypeScript assertion such as `expr as i32`;
+- a symbol already recorded by the transformer as domain storage.
+
+`Domain leak` means assigning a domain-bound expression into storage that
+TypeScript treats as plain `number`. Domain leaks are compile errors unless the
+user explicitly escapes the domain with a non-numtypes assertion such as
+`(a + b) as number`, `(a + b) as unknown`, or `(a + b) as any`. The operation
+itself is still lowered according to the operand domain; only the storage escape
+is explicit.
+
+Wrappers that do not change the value domain, such as non-null assertions and
+`satisfies` clauses, are not escapes. Domain-leak detection must unwrap them and
+inspect the real storage boundary.
+
+The transformer intentionally does not duplicate every check that TypeScript's
+type system already performs. When a normal TypeScript assignment or call
+signature rejects `number` where a branded type is required, that TypeScript
+diagnostic is part of the library contract. The transformer adds diagnostics for
+numtypes-specific semantics that TypeScript cannot express, such as arithmetic
+domain tracking, erased cast marker misuse, implicit widening boundaries, and
+ambiguous numeric unions.
+
+Because arithmetic over branded operands has TypeScript type `number`, a raw
+operation result cannot be assigned or returned directly where a branded type is
+required. Users must cross that TypeScript boundary with a checked cast call,
+for example `return f64(a / b)` rather than `return a / b` in a function declared
+as returning `f64`.
+
+Unchecked assertions are trusted TypeScript assertions. They may satisfy a
+branded boundary and select a domain for later analysis, but they never insert a
+runtime coercion by themselves. `(a + b) as i32` lowers the `a + b` operation
+only if that operation is already domain-bound by its operands. `(a + b) as i32`
+with plain `number` operands emits as `a + b`.
+
+Checked cast calls are boundary conversions, not implicit contexts for every
+nested operation. `i32(readNumber())` is valid because the whole plain-number
+expression is cast. `i32(a + b)` is still invalid when `a: i32` and `b: number`;
+the user must write `i32(a + i32(b))`.
+
+## Phase 1: Symbol Resolution
+
+Resolve the actual package symbols before doing any analysis.
+
+Tasks:
+
+- detect imports from `numtypes`;
+- resolve `i32`, `u32`, `f32`, and `f64` through the TypeScript checker;
+- reject lookalike local functions or variables with the same names;
+- build a per-source-file symbol table for cast calls and imported types;
+- preserve enough import metadata so the transform phase can remove phantom
+  imports later.
+
+Tests:
+
+- imported `i32` is recognized;
+- local `function i32(...)` is not recognized;
+- aliased imports such as `import { i32 as int }` are recognized;
+- type-only imports are recognized for annotations.
+
+## Phase 2: Domain Extraction From Types
+
+Implement helpers that map TypeScript types and type nodes to numeric domains.
+
+Tasks:
+
+- detect branded type aliases from `numtypes`;
+- read annotations on parameters, variables, properties, and return types;
+- read numtypes references inside arrays, tuples, object properties, and generic
+  type arguments for type surface preservation/erasure;
+- detect inferred branded types from checked cast calls and unchecked
+  TypeScript assertions;
+- classify plain `number` separately from `unknown`;
+- preserve storage unions that contain numtypes domains, and add diagnostics for
+  ambiguous intersections.
+
+Initial rule:
+
+```text
+i32/u32/f32/f64 annotation -> matching numeric domain
+plain number annotation -> plain-number
+missing annotation -> infer from initializer only if TypeScript already infers a branded type
+```
+
+This phase must not infer `const x = a + b` as `i32` just because the initializer
+is an `i32` operation. That expression is domain-bound, but the storage is still
+plain `number` unless the user explicitly casts it. For branded storage,
+`const x: i32 = i32(a + b)` is the valid TypeScript form.
+
+## Phase 3: Expression Domain Analysis
+
+Implement a recursive expression analyzer that returns both the TypeScript type
+and the internal numeric domain for each expression.
+
+Suggested result shape:
+
+```typescript
+interface ExpressionDomainResult {
+  readonly domain: NumericDomain | "plain-number" | "unknown";
+  readonly isDomainBound: boolean;
+  readonly requiresClosure: boolean;
+}
+```
+
+Rules:
+
+- identifier/property access: use the storage domain recorded for the symbol or
+  the branded TypeScript type;
+- checked cast call: source expression is analyzed first, then the target
+  domain is applied and emitted as a runtime coercion;
+- unchecked TypeScript assertion: the asserted domain is applied for analysis,
+  but the assertion itself emits no runtime coercion and is treated as a
+  trusted operand for later operations;
+- checked cast call argument: analyze the argument normally; the cast converts
+  the final argument value to the target domain, but it does not automatically
+  make mixed branded/plain operations inside the argument valid;
+- numeric literal: may be contextually coerced only when a target domain is
+  available;
+- unary arithmetic: domain follows the operand when the operator is supported;
+- binary arithmetic: same-domain operands produce a domain-bound expression of
+  that domain;
+- integer bitwise: allowed only for `i32` and `u32`;
+- mixed branded domains require explicit casts;
+- branded domain plus plain `number` requires an explicit cast unless the plain
+  side is an allowed contextual literal;
+- unsupported expressions return `unknown` and are rejected when a numeric
+  domain is required.
+
+The analyzer should cache results by `ts.Node` identity within one source file.
+
+## Phase 4: Contextual Domain Analysis
+
+Implement target-domain discovery for expression positions.
+
+Contextual domains:
+
+- variable initializer target from declaration annotation or inferred branded
+  cast result, only after the source has passed TypeScript's branded boundary;
+- assignment target from the resolved lvalue symbol, only after the source has
+  passed TypeScript's branded boundary;
+- return expression target from containing function return annotation, only
+  after the source has passed TypeScript's branded boundary;
+- argument target only from known numtypes cast functions;
+- conditional expression branch target from the containing target domain;
+- array/property element target only when its declared type is a numtypes domain.
+
+Compile errors:
+
+- domain-bound expression assigned to plain `number` storage;
+- domain-bound expression returned from an unannotated function;
+- domain-bound expression passed to a plain `number` parameter without explicit
+  escape or cast;
+- same-domain arithmetic stored in an unannotated variable when TypeScript would
+  infer plain `number`.
+
+Do not treat a branded lvalue annotation as permission to accept TypeScript
+invalid source such as `const x: i32 = a + b` or `return a / b` from a `f64`
+function. Those cases must be written with checked casts.
+
+Normal function and method parameters are not implicit domain contexts. A call
+such as `values.push(a + b)` for `values: i32[]` is intentionally rejected by
+TypeScript because `a + b` has TypeScript type `number`; users must write
+`values.push(i32(a + b))` when they want to cross that call boundary. This keeps
+call arguments explicit and avoids hidden contextual lowering through arbitrary
+signatures.
+
+Generic type arguments that contain numtypes domains are allowed as type surface,
+but they do not create special runtime semantics. The transformer should preserve
+or erase types such as `Array<i32>`, `[i32, f32]`, `Promise<i32>`, `Map<string,
+i32>`, and `Box<i32>`, but it should not interpret arbitrary generic methods,
+callbacks, or asynchronous resolution. Calls through those APIs rely on
+TypeScript signatures and explicit checked casts at value boundaries.
+
+Example:
+
+```typescript
+function f(a: i32, b: i32) {
+  const x = a + b;
+}
+```
+
+must produce:
+
+```text
+error: result of i32 operation is assigned to untyped variable 'x'; use a checked cast such as i32(...) at the boundary or explicitly escape to a non-numtypes type
+```
+
+Allowed forms:
+
+```typescript
+function f(a: i32, b: i32): i32 {
+  const x: i32 = i32(a + b);
+  return x;
+}
+
+function g(a: i32, b: i32) {
+  const x = i32(a + b);
+  return x;
+}
+```
+
+## Phase 5: Diagnostics Pass
+
+Run a pre-transform analysis pass that reports all errors before rewriting.
+
+Tasks:
+
+- traverse source files once and collect domain diagnostics;
+- include source spans and stable diagnostic codes;
+- make diagnostics deterministic and fixture-testable;
+- fail transform when diagnostics exist.
+
+Important diagnostic categories:
+
+- implicit cast from branded domain to plain `number`;
+- implicit cast between different branded domains;
+- mixed branded/plain operands inside an operation, even when the whole
+  expression is later wrapped in a checked cast;
+- bitwise operation on `f32` or `f64`;
+- domain-bound result escaping through unannotated storage;
+- unresolved or shadowed numtypes symbols;
+- erased cast marker misuse, such as storing or value-re-exporting `i32`;
+- unsupported expression shape in a domain-required context.
+
+## Phase 6: Expression Rewriting
+
+After diagnostics pass, rewrite expressions according to the domain analysis.
+
+Tasks:
+
+- insert operand coercions;
+- insert result closures;
+- lower integer multiplication to `Math.imul`;
+- preserve source evaluation order;
+- preserve prefix/postfix update value semantics;
+- preserve single evaluation for complex assignment targets;
+- do not treat compound assignments such as `a += b` as accepted branded-source
+  syntax; TypeScript rejects them for branded lvalues, so users must write
+  checked assignments such as `a = i32(a + b)`;
+- erase checked cast calls into coercion idioms;
+- erase unchecked TypeScript assertions without adding coercions;
+- remove phantom imports when no runtime import remains.
+
+The rewrite should use the cached domain analysis rather than re-deriving
+domains during emit.
+
+## Phase 7: Fixture Test Runner
+
+Build the source-to-source fixture runner.
+
+Fixture types:
+
+- `*.input.ts` and `*.output.ts` for successful transforms;
+- `*.input.ts` and `*.errors.txt` for diagnostics;
+- grouped directories for `i32`, `u32`, `f32`, `f64`, mixed domains,
+  assignments, and imports.
+
+The runner should normalize line endings and use TypeScript's printer so output
+is stable.
+
+## Phase 8: V8 Lowering Probes
+
+Add opt-in engine probes after the transform output is stable.
+
+Tasks:
+
+- generate small JS probes from fixture output;
+- run them under Node with explicit V8 flags;
+- record the Node and V8 versions in test output;
+- assert narrow, version-aware facts only;
+- keep these probes out of the default test command.
+
+Candidate probes:
+
+- i32 addition closure;
+- i32/u32 `Math.imul` multiplication;
+- u32 logical right shift;
+- f32 `Math.fround` arithmetic;
+- f64 unary-plus arithmetic.
+
+## Phase 9: Benchmarks
+
+Add opt-in benchmarks after correctness tests are meaningful.
+
+Benchmark groups:
+
+- transformer throughput on large files;
+- emitted i32/u32/f32/f64 runtime shapes;
+- baseline JavaScript versus transformed JavaScript;
+- compile-time overhead of diagnostics and domain analysis caching.
+
+Benchmarks should not gate normal correctness tests until there is a stable
+baseline and variance policy.
+
+## Implementation Order
+
+1. Symbol resolution.
+2. Type-to-domain extraction.
+3. Expression domain analyzer for identifiers, literals, casts, unary, binary.
+4. Contextual target-domain analyzer for variable declarations and returns.
+5. Diagnostics for implicit plain-number leaks.
+6. Fixture runner and first failing diagnostics fixtures.
+7. Expression rewrite for casts and simple binary arithmetic.
+8. Assignment/update rewrite.
+9. Import erasure.
+10. V8 probes and benchmark expansion.

package/docs/lib-implementation.md

@@ -0,0 +1,77 @@
+# Lib Implementation
+
+The authoritative public symbol surface is `src/lib/index.ts`. This document
+must stay aligned with that file.
+
+These symbols are phantom runtime markers: user code imports and calls the
+function symbols before transformation, but the transformer must lower every
+function call to the matching JavaScript coercion idiom and remove the package
+import when no runtime value remains.
+
+The function symbols are only valid as direct checked cast calls such as
+`i32(value)` or namespace-qualified direct calls such as `nt.i32(value)`.
+Because the package root has no runtime implementation, users must not store,
+pass, object-shorthand, optional-call, optional-access, spread-call,
+type-argument-call, parenthesized-callee-call, or value-re-export these function
+symbols. Type-only re-exports of the branded type aliases are allowed.
+
+The exported type aliases are type-only domain markers. A TypeScript assertion
+such as `value as i32` or `<i32>value` is unchecked and must not insert a runtime
+coercion by itself. It only changes the domain that later numtypes operations
+use for dispatch. Use the function form, such as `i32(value)`, when runtime
+coercion is required at that expression boundary.
+
+The package root intentionally has no executable implementation. The emitted
+JavaScript for `src/lib/index.ts` should remain effectively empty.
+
+## Public Surface
+
+```typescript
+declare const i32Brand: unique symbol;
+declare const u32Brand: unique symbol;
+declare const f32Brand: unique symbol;
+declare const f64Brand: unique symbol;
+
+export type i32 = number & {
+  readonly [i32Brand]: never;
+};
+
+export type u32 = number & {
+  readonly [u32Brand]: never;
+};
+
+export type f32 = number & {
+  readonly [f32Brand]: never;
+};
+
+export type f64 = number & {
+  readonly [f64Brand]: never;
+};
+
+export declare function i32(value: number): i32;
+
+export declare function u32(value: number): u32;
+
+export declare function f32(value: number): f32;
+
+export declare function f64(value: number): f64;
+```
+
+## Transformer Lowering
+
+The runtime behavior for checked cast calls is produced by the transformer, not
+by these declarations.
+
+```typescript
+i32(value) => value | 0
+u32(value) => value >>> 0
+f32(value) => Math.fround(value)
+f64(value) => +value
+```
+
+Unchecked TypeScript assertions erase like normal TypeScript syntax.
+
+```typescript
+value as i32 => value
+<i32>value => value
+```