xbintsc 0.5.22 → 0.5.31

package/scripts/support-matrix.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * Render `doc/support-matrix.md` and its Chinese mirror from the vendored
+ * test262 catalogue.
+ *
+ * The catalogue is executable evidence: `tests/conformance/test262.test.ts`
+ * compiles and runs every supported case (unmodified test262 files) and
+ * requires every unsupported case to fail with the listed diagnostic code.
+ * This script turns the same catalogue into the human-readable table, so the
+ * document cannot claim a feature the compiler does not exercise.
+ *
+ * Usage: npm run docs:matrix
+ */
+
+import { writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  SUPPORT_AREAS,
+  SUPPORTED_CASES,
+  UNSUPPORTED_CASES,
+  type SupportArea,
+} from "../tests/conformance/test262/manifest.js";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+type Language = "en" | "zh";
+
+export const MATRIX_FILES: Readonly<Record<Language, string>> = {
+  en: "doc/support-matrix.md",
+  zh: "doc/zh-CN/support-matrix.md",
+};
+
+export const TEST262_COMMIT = "d53ebc8b1931d9f1541e43d59650776e4b766248";
+
+function docLink(area: SupportArea, language: Language): string {
+  const relative = area.doc.startsWith("doc/") ? area.doc.slice("doc/".length) : area.doc;
+  return language === "en" ? relative : `../${relative}`;
+}
+
+function areaTitle(area: SupportArea, language: Language): string {
+  return language === "en" ? area.title : area.titleZh;
+}
+
+function count(area: SupportArea, cases: readonly { readonly area: string }[]): number {
+  return cases.filter((testCase) => testCase.area === area.id).length;
+}
+
+function rowsFor(language: Language): string {
+  return SUPPORT_AREAS.map((area) => {
+    const supported = count(area, SUPPORTED_CASES);
+    const unsupported = count(area, UNSUPPORTED_CASES);
+    return `| ${areaTitle(area, language)} | ${supported} | ${unsupported} | [${language === "en" ? "reference" : "参考"}](${docLink(area, language)}) |`;
+  }).join("\n");
+}
+
+function supportedTable(language: Language): string {
+  const header =
+    language === "en"
+      ? "| test262 case | Area | What it pins down |\n| --- | --- | --- |"
+      : "| test262 用例 | 领域 | 固化的行为 |\n| --- | --- | --- |";
+  const rows = SUPPORTED_CASES.map((testCase) => {
+    const area = SUPPORT_AREAS.find((candidate) => candidate.id === testCase.area)!;
+    const claim = language === "en" ? testCase.claim : testCase.claimZh;
+    return `| \`${testCase.path}\` | ${areaTitle(area, language)} | ${claim} |`;
+  });
+  return [header, ...rows].join("\n");
+}
+
+function unsupportedTable(language: Language): string {
+  const header =
+    language === "en"
+      ? "| test262 case | Area | Diagnostic | Why |\n| --- | --- | ---: | --- |"
+      : "| test262 用例 | 领域 | 诊断码 | 原因 |\n| --- | --- | ---: | --- |";
+  const rows = UNSUPPORTED_CASES.map((testCase) => {
+    const area = SUPPORT_AREAS.find((candidate) => candidate.id === testCase.area)!;
+    const claim = language === "en" ? testCase.claim : testCase.claimZh;
+    return `| \`${testCase.path}\` | ${areaTitle(area, language)} | TS${testCase.code} | ${claim} |`;
+  });
+  return [header, ...rows].join("\n");
+}
+
+export function renderSupportMatrix(language: Language): string {
+  const corpusLink =
+    language === "en" ? "../tests/conformance/test262/manifest.ts" : "../../tests/conformance/test262/manifest.ts";
+  const testLink =
+    language === "en" ? "../tests/conformance/test262.test.ts" : "../../tests/conformance/test262.test.ts";
+  const sourceLink =
+    language === "en" ? "../tests/conformance/test262/SOURCE.md" : "../../tests/conformance/test262/SOURCE.md";
+
+  if (language === "en") {
+    return `# Support matrix
+
+> Language: **English** | [简体中文](./zh-CN/support-matrix.md)
+
+> **Generated** by \`npm run docs:matrix\` from the executable catalogue in
+> [\`tests/conformance/test262/manifest.ts\`](${corpusLink}). Do not edit this
+> file by hand: change a case and regenerate.
+
+Every supported case is an unmodified [test262](https://github.com/tc39/test262)
+file (pinned at \`${TEST262_COMMIT}\`) that xbintsc compiles **and runs**; the
+[test262 suite](${testLink}) fails if one stops passing. The corpus is a
+representative subset, not a full test262 run. Every unsupported case
+is valid JavaScript that xbintsc currently rejects, pinned with the diagnostic
+code it produces. See [\`SOURCE.md\`](${sourceLink}) for the harness adaptation.
+Because the suite runs on every CI platform, this table cannot claim more than
+the compiler does.
+
+## Coverage by area
+
+| Area | Supported | Unsupported | Reference |
+| --- | ---: | ---: | --- |
+${rowsFor(language)}
+
+## Supported cases (test262, compiled and executed)
+
+${supportedTable(language)}
+
+## Unsupported cases (valid JavaScript, expected diagnostics)
+
+${unsupportedTable(language)}
+`;
+  }
+
+  return `# 支持矩阵
+
+> 语言：[English](../support-matrix.md) | **简体中文**
+
+> 本文件由 \`npm run docs:matrix\` 根据可执行语料
+> [\`tests/conformance/test262/manifest.ts\`](${corpusLink}) 生成，请勿手工编辑：
+> 修改用例后重新生成。
+
+每个“支持”用例都是 [test262](https://github.com/tc39/test262) 的原始文件
+（固定版本 \`${TEST262_COMMIT}\`），由 xbintsc 编译**并执行**；
+[test262 测试套件](${testLink}) 会在用例回归时失败。该语料是代表性
+子集，不是完整的 test262 全量运行。每个“不支持”用例都是
+xbintsc 目前会拒绝的合法 JavaScript，并以实际产生的诊断码固定下来。
+harness 的适配说明见 [\`SOURCE.md\`](${sourceLink})。该套件在 CI 的每个平台
+运行，因此本表不会声称编译器做不到的能力。
+
+## 各领域覆盖
+
+| 领域 | 支持 | 不支持 | 参考 |
+| --- | ---: | ---: | --- |
+${rowsFor(language)}
+
+## 支持的用例（test262，编译并执行）
+
+${supportedTable(language)}
+
+## 不支持的用例（合法 JavaScript，预期诊断）
+
+${unsupportedTable(language)}
+`;
+}
+
+function main(): void {
+  for (const language of ["en", "zh"] as const) {
+    const path = resolve(root, MATRIX_FILES[language]);
+    writeFileSync(path, renderSupportMatrix(language));
+    process.stdout.write(`xbintsc: wrote ${MATRIX_FILES[language]}\n`);
+  }
+}
+
+if (process.argv[1] !== undefined && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  main();
+}

package/src/ast/common.ts

@@ -33,6 +33,7 @@ import type {
   PropertyAccessExpression,
   RegularExpressionLiteral,
   SatisfiesExpression,
+  SequenceExpression,
   SpreadElement,
   StringLiteral,
   TaggedTemplateExpression,
@@ -143,6 +144,7 @@ export type Expression =
   | ConditionalExpression
   | AsExpression
   | SatisfiesExpression
+  | SequenceExpression
   | NonNullExpression
   | TypeOfExpression
   | VoidExpression

package/src/ast/declarations.ts

@@ -75,7 +75,11 @@ export interface ExpressionWithTypeArguments extends Node {
   readonly typeArguments: TypeNode[];
 }
 
-export type ClassElement = PropertyDeclaration | MethodDeclaration | ConstructorDeclaration;
+export type ClassElement =
+  | PropertyDeclaration
+  | MethodDeclaration
+  | ConstructorDeclaration
+  | ClassStaticBlockDeclaration;
 
 export interface PropertyDeclaration extends Node {
   readonly kind: SyntaxKind.PropertyDeclaration;
@@ -108,6 +112,13 @@ export interface ConstructorDeclaration extends Node {
   readonly body?: Block;
 }
 
+/** `static { ... }`: runs once, while the class is being defined. */
+export interface ClassStaticBlockDeclaration extends Node {
+  readonly kind: SyntaxKind.ClassStaticBlockDeclaration;
+  readonly modifiers: Modifier[];
+  readonly body: Block;
+}
+
 export interface ClassDeclaration extends Node {
   readonly kind: SyntaxKind.ClassDeclaration;
   readonly name?: Identifier;

package/src/ast/expressions.ts

@@ -206,6 +206,12 @@ export interface ParenthesizedExpression extends Node {
   readonly expression: Expression;
 }
 
+/** `a, b, c`: evaluates every operand left to right, yields the last value. */
+export interface SequenceExpression extends Node {
+  readonly kind: SyntaxKind.SequenceExpression;
+  readonly expressions: Expression[];
+}
+
 export interface PrefixUnaryExpression extends Node {
   readonly kind: SyntaxKind.PrefixUnaryExpression;
   readonly operator: PrefixUnaryOperator;

package/src/ast/kinds.ts

@@ -63,6 +63,7 @@ export const enum SyntaxKind {
   ObjectBindingPattern = 47,
   BindingElement = 48,
   ComputedPropertyName = 49,
+  SequenceExpression = 50,
 
   // Statements
   ExpressionStatement = 60,
@@ -112,6 +113,7 @@ export const enum SyntaxKind {
   ExportAssignment = 119,
   NamedExports = 120,
   ExportSpecifier = 121,
+  ClassStaticBlockDeclaration = 122,
 
   // Types
   TypeReference = 200,

package/src/binder/binder.ts

@@ -20,6 +20,7 @@ import type { Identifier, Node, SourceFileNode } from "../ast/nodes.js";
 import {
   ScopeKind,
   type ClassInfo,
+  type DeclarationConflict,
   type FunctionInfo,
   type MutableFunction,
   type Scope,
@@ -45,6 +46,7 @@ export class Binder {
   readonly symbolOfIdentifier = new Map<Identifier, SymbolInfo>();
   readonly scopes = new Map<Node, Scope>();
   readonly unresolved: Identifier[] = [];
+  readonly conflicts: DeclarationConflict[] = [];
   nextSymbolId = 1;
   nextFunctionId = 1;
   nextClassId = 1;
@@ -83,6 +85,7 @@ export class Binder {
       symbolOfIdentifier: this.symbolOfIdentifier,
       scopes: this.scopes,
       unresolved: this.unresolved,
+      conflicts: this.conflicts,
     };
   }
 

package/src/binder/declarations.ts

@@ -20,6 +20,71 @@ import { SymbolKind, type MutableFunction, type Scope, type SymbolInfo } from ".
 import { childNodes } from "./helpers.js";
 import type { Binder } from "./binder.js";
 
+/** Kinds that only introduce a type name, never a runtime binding. */
+const TYPE_ONLY_KINDS: ReadonlySet<SymbolKind> = new Set([
+  SymbolKind.Interface,
+  SymbolKind.TypeAlias,
+]);
+
+function isVarLike(kind: SymbolKind): boolean {
+  return kind === SymbolKind.Var || kind === SymbolKind.Function;
+}
+
+/**
+ * Whether a declaration of `next` may legally share a scope with `existing`.
+ *
+ * This is JavaScript's redeclaration rules plus TypeScript's declaration
+ * merging, kept deliberately explicit: a wrong `true` would hide a real bug, a
+ * wrong `false` would make valid code fail to compile. Only the cases this
+ * compiler can actually see are covered; anything unknown is treated as legal.
+ */
+export function declarationsCanMerge(existing: SymbolKind, next: SymbolKind): boolean {
+  if (existing === next) {
+    /* Repeated `var` / `function` / `interface` / `enum` declarations merge.
+     * Two imports may also share a name: bundling merges every module into one
+     * scope, and separate modules routinely import the same builtin
+     * (`readFileSync` from `node:fs`, `dirname` from `node:path`). The import
+     * map is keyed by symbol id, so keeping the first declaration is enough.
+     * `let`, `const`, `class` and parameters do not merge. */
+    return (
+      existing === SymbolKind.Var ||
+      existing === SymbolKind.Function ||
+      existing === SymbolKind.Interface ||
+      existing === SymbolKind.Namespace ||
+      existing === SymbolKind.Enum ||
+      existing === SymbolKind.Import
+    );
+  }
+  // `var` and `function` are both function-scoped and may coexist in any order.
+  if (isVarLike(existing) && isVarLike(next)) return true;
+  // `var` may redeclare a parameter; `let`/`const` may not.
+  if (
+    (existing === SymbolKind.Parameter && next === SymbolKind.Var) ||
+    (existing === SymbolKind.Var && next === SymbolKind.Parameter)
+  ) {
+    return true;
+  }
+  // Namespaces merge with classes, functions, enums and each other.
+  if (existing === SymbolKind.Namespace || next === SymbolKind.Namespace) return true;
+  // A class and an interface merge their instance shape.
+  if (
+    (existing === SymbolKind.Class && next === SymbolKind.Interface) ||
+    (existing === SymbolKind.Interface && next === SymbolKind.Class)
+  ) {
+    return true;
+  }
+  // An import binds both a value and a type name, so it conflicts with any
+  // same-name local declaration.
+  if (existing === SymbolKind.Import || next === SymbolKind.Import) return false;
+  // Value and type names live in separate declaration spaces, except classes
+  // and enums, which declare a type as well as a value.
+  if (TYPE_ONLY_KINDS.has(existing) !== TYPE_ONLY_KINDS.has(next)) {
+    const valueKind = TYPE_ONLY_KINDS.has(existing) ? next : existing;
+    return valueKind !== SymbolKind.Class && valueKind !== SymbolKind.Enum;
+  }
+  return false;
+}
+
 export interface DeclarationMethods {
   declareBinding(this: Binder, name: BindingName, kind: SymbolKind, declaration: Node, scope: Scope, mutable: boolean): SymbolInfo | undefined;
   declare(this: Binder, name: string, kind: SymbolKind, node: Node, scope: Scope, mutable: boolean): SymbolInfo;
@@ -60,6 +125,11 @@ export const declarationMethods: DeclarationMethods = {
   ): SymbolInfo {
     const existing = scope.symbols.get(name);
     if (existing) {
+      // `(anonymous)` is the binder's placeholder for `export default
+      // function () {}`; those have no user-visible name to collide.
+      if (name !== "(anonymous)" && !declarationsCanMerge(existing.kind, kind)) {
+        this.conflicts.push({ name, existing, kind, node });
+      }
       // `var` redeclarations and duplicate functions merge into one symbol.
       if (
         (kind === SymbolKind.Var && existing.kind === SymbolKind.Var) ||

package/src/binder/references.ts

@@ -33,7 +33,9 @@ import type { ArrayBindingPattern, ObjectBindingPattern, Parameter } from "../as
 import {
   ScopeKind,
   SymbolKind,
+  type ClassFieldInfo,
   type ClassInfo,
+  type ClassStaticInit,
   type FunctionInfo,
   type FunctionNode,
   type MutableFunction,
@@ -136,6 +138,23 @@ export const referenceMethods: ReferenceMethods = {
       case SyntaxKind.LabeledStatement:
         this.bindNode((node as unknown as { statement: Node }).statement, scope);
         return;
+      case SyntaxKind.SwitchStatement: {
+        const statement = node as unknown as {
+          expression: Expression;
+          clauses: { expression?: Expression; statements: Statement[] }[];
+        };
+        this.bindNode(statement.expression, scope);
+        /* Every `case` body shares the switch's block scope, so the
+         * declarations they contain have to be pre-declared before any clause
+         * is bound. Without this a `const` declared directly in a `case`
+         * clause had no symbol and later phases crashed on it. */
+        for (const clause of statement.clauses) {
+          this.bindNode(clause.expression, scope);
+          this.predeclareStatements(clause.statements, scope);
+        }
+        for (const clause of statement.clauses) this.bindStatements(clause.statements, scope);
+        return;
+      }
       case SyntaxKind.BreakStatement:
       case SyntaxKind.ContinueStatement:
         return;
@@ -150,6 +169,15 @@ export const referenceMethods: ReferenceMethods = {
       case SyntaxKind.TypeAliasDeclaration:
         // Type-only: skip the body entirely.
         return;
+      case SyntaxKind.EnumDeclaration: {
+        /* Member names are keys of the generated object, not bindings; only an
+         * initializer (`A = foo()`) contains runtime references. */
+        const members = (node as unknown as { members: { initializer?: Expression }[] }).members;
+        for (const member of members) {
+          if (member.initializer) this.bindNode(member.initializer, scope);
+        }
+        return;
+      }
       case SyntaxKind.ImportDeclaration:
         return;
       case SyntaxKind.ExportDeclaration: {
@@ -204,6 +232,22 @@ export const referenceMethods: ReferenceMethods = {
         this.bindBlock(clause.block, catchScope);
         return;
       }
+      /* Type positions are erased, so their identifiers are not runtime
+       * references. Walking them would put `Foo` from `x as Foo` or the type
+       * arguments of `f<Foo>()` into `unresolved`, and the checker would then
+       * report a value that never exists. */
+      case SyntaxKind.AsExpression:
+      case SyntaxKind.SatisfiesExpression:
+      case SyntaxKind.NonNullExpression:
+        this.bindNode((node as unknown as { expression: Expression }).expression, scope);
+        return;
+      case SyntaxKind.CallExpression:
+      case SyntaxKind.NewExpression: {
+        const call = node as unknown as { expression: Expression; arguments: Expression[] };
+        this.bindNode(call.expression, scope);
+        for (const argument of call.arguments) this.bindNode(argument, scope);
+        return;
+      }
       default:
         break;
     }
@@ -211,10 +255,24 @@ export const referenceMethods: ReferenceMethods = {
   },
 
   bindVariableList(list: VariableDeclarationList, scope: Scope): void {
+    const declarationKind =
+      list.declarationKind === "const"
+        ? SymbolKind.Const
+        : list.declarationKind === "var"
+          ? SymbolKind.Var
+          : SymbolKind.Let;
     for (const declaration of list.declarations) {
-      const symbol = this.symbolOfDeclaration.get(declaration);
       if (declaration.name.kind === SyntaxKind.Identifier) {
-        this.symbolOfDeclaration.set(declaration.name, symbol ?? this.symbolOfDeclaration.get(declaration) as SymbolInfo);
+        /* Normally the declaration was pre-declared; if it was not (a code
+         * path that binds statements without pre-declaring them), declare it
+         * here rather than storing an empty entry that later phases would
+         * dereference. */
+        const name = declaration.name as Identifier;
+        const symbol =
+          this.symbolOfDeclaration.get(declaration) ??
+          this.symbolOfDeclaration.get(name) ??
+          this.declareBinding(name, declarationKind, declaration, scope, declarationKind !== SymbolKind.Const);
+        if (symbol) this.symbolOfDeclaration.set(name, symbol);
       } else {
         this.bindBindingPattern(declaration.name, scope);
       }
@@ -329,6 +387,8 @@ export const referenceMethods: ReferenceMethods = {
       fields: [],
       methods: [],
       statics: [],
+      staticBlocks: [],
+      staticInit: [],
     };
     this.classes.push(info);
     this.classOfNode.set(node, info);
@@ -337,6 +397,9 @@ export const referenceMethods: ReferenceMethods = {
     this.scopes.set(node, classScope);
 
     let constructor: FunctionInfo | undefined;
+    /* `static { ... }` functions, so the field pass below can interleave them
+     * with static fields in declaration order. */
+    const staticBlockFns = new Map<Node, FunctionInfo>();
     for (const member of node.members) {
       if (member.kind === SyntaxKind.ConstructorDeclaration) {
         const ctor = member as ConstructorDeclaration;
@@ -354,6 +417,14 @@ export const referenceMethods: ReferenceMethods = {
         }
         if (isStatic) (info.statics as FunctionInfo[]).push(fn);
         else (info.methods as FunctionInfo[]).push(fn);
+      } else if (member.kind === SyntaxKind.ClassStaticBlockDeclaration) {
+        /* A static block is a function-like body: it runs once with `this`
+         * bound to the class, so it is bound like a static method and called
+         * right after the class value is built. */
+        const block = member as unknown as { body: Block };
+        const fn = this.createClassFunction(member, "static", [], block.body, classScope, info, true, false);
+        (info.staticBlocks as FunctionInfo[]).push(fn);
+        staticBlockFns.set(member, fn);
       }
     }
     if (!constructor) {
@@ -371,7 +442,17 @@ export const referenceMethods: ReferenceMethods = {
         this.current = constructor as MutableFunction;
         if (property.initializer) this.bindNode(property.initializer, classScope);
         this.current = owner;
-        info.fields.push({ name: classMemberName(property.name), initializer: property.initializer, fn: constructor, isStatic });
+        const field: ClassFieldInfo = {
+          name: classMemberName(property.name),
+          initializer: property.initializer,
+          fn: constructor,
+          isStatic,
+        };
+        (info.fields as ClassFieldInfo[]).push(field);
+        if (isStatic) (info.staticInit as ClassStaticInit[]).push({ kind: "field", field });
+      } else if (member.kind === SyntaxKind.ClassStaticBlockDeclaration) {
+        const fn = staticBlockFns.get(member);
+        if (fn) (info.staticInit as ClassStaticInit[]).push({ kind: "block", fn });
       }
     }
 

package/src/binder/types.ts

@@ -43,6 +43,24 @@ export interface SymbolInfo {
   boxed: boolean;
 }
 
+/**
+ * A same-scope declaration that cannot legally merge with the symbol already
+ * bound to that name (`let x` twice, `function f` then `const f`, ...).
+ *
+ * The binder records the conflict instead of reporting it: whether it is an
+ * error is checker policy (`--no-check` keeps the old, permissive behaviour),
+ * while the fact itself is cheap to capture during the one declaration pass.
+ */
+export interface DeclarationConflict {
+  readonly name: string;
+  /** The symbol the name was already bound to. */
+  readonly existing: SymbolInfo;
+  /** The kind of the offending declaration. */
+  readonly kind: SymbolKind;
+  /** The offending declaration node (the second one to use the name). */
+  readonly node: Node;
+}
+
 export type FunctionNode = SourceFileNode | FunctionDeclaration | FunctionExpression | ArrowFunction;
 
 export interface FunctionInfo {
@@ -88,10 +106,20 @@ export interface ClassInfo {
   readonly fields: ClassFieldInfo[];
   readonly methods: FunctionInfo[];
   readonly statics: FunctionInfo[];
+  /** `static { ... }` blocks, in declaration order. */
+  readonly staticBlocks: FunctionInfo[];
+  /** Static fields and static blocks, interleaved in declaration order: they
+   *  run in source order, while static methods are installed before both. */
+  readonly staticInit: ClassStaticInit[];
   ctor?: FunctionInfo;
   /** The symbol the class name binds to, when there is one. */
 }
 
+/** One static element evaluated at class-definition time, in source order. */
+export type ClassStaticInit =
+  | { readonly kind: "field"; readonly field: ClassFieldInfo }
+  | { readonly kind: "block"; readonly fn: FunctionInfo };
+
 export interface ClassFieldInfo {
   readonly name: string;
   readonly initializer: Expression | undefined;
@@ -129,6 +157,8 @@ export interface BindResult {
   readonly scopes: Map<Node, Scope>;
   /** Identifier references that could not be resolved in user code. */
   readonly unresolved: Identifier[];
+  /** Same-scope declarations that cannot merge (see {@link DeclarationConflict}). */
+  readonly conflicts: readonly DeclarationConflict[];
 }
 
 export interface MutableFunction extends FunctionInfo {

package/src/canonical.ts

@@ -0,0 +1,37 @@
+/**
+ * Canonical bytes for compiler-emitted artifacts.
+ *
+ * The compiler runs on Windows, macOS and Linux, and can be compiled by
+ * itself. Anything it writes into a byte-compared artifact — LLVM IR, debug
+ * metadata, the compiler fingerprint, the bundled module text and the `path`
+ * module's results — has to use the same representation on every host. These
+ * constants are that representation: do not spell `"/"` or `"\n"` in code that
+ * emits an artifact.
+ *
+ * Native paths are deliberately different. Diagnostics, `import.meta.filename`
+ * and `process.cwd()` keep the host separator, exactly like Node. Convert a
+ * native path with {@link artifactPath} only when it enters an artifact.
+ */
+
+/** Separator between path segments in a compiler artifact. Deliberately not
+ *  selected by `process.platform`: every host writes `/`, so the same source
+ *  produces the same bytes (and Windows accepts `/` in every API). */
+export const ARTIFACT_PATH_SEPARATOR = "/";
+
+/** Line ending between records in a compiler artifact. Deliberately not
+ *  `os.EOL`/`"\r\n"` on Windows: the runtime opens stdout/stderr in binary
+ *  mode, and CRLF would make IR, fingerprints and documentation differ per
+ *  host. */
+export const ARTIFACT_LINE_ENDING = "\n";
+
+/**
+ * Rewrite a native path for an artifact: `C:\dir\file.ts` becomes
+ * `C:/dir/file.ts`. A backslash is always a separator here, matching how the
+ * runtime and Node treat Windows paths.
+ */
+export function artifactPath(path: string): string {
+  // `split`/`join` is measurably faster than a regex or `replaceAll` for the
+  // short paths this sees (it runs once per emitted stack frame), and it is the
+  // exact transform the compiler used before it was centralised.
+  return path.split("\\").join(ARTIFACT_PATH_SEPARATOR);
+}