xbintsc 0.3.35 → 0.3.49

package/scripts/build-gui-shaders.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * Compile the GUI engine's shaders ahead of time and embed them in
+ * `runtime/ext_gui/renderer_shaders_data.h`.
+ *
+ * SDL_GPU cannot compile GLSL or HLSL at runtime: each backend consumes its own
+ * binary format. The engine therefore ships:
+ *
+ *   - SPIR-V, for Vulkan, compiled from `runtime/ext_gui/spirv/*.{vert,frag}`
+ *     with `glslc` (from the Vulkan SDK); and
+ *   - DXIL, for Direct3D 12, compiled from `runtime/ext_gui/shaders.hlsl` with
+ *     `dxc` (inside the Windows SDK).
+ *
+ * Metal needs no blob: SDL compiles the MSL literals in `renderer_shaders.h` at
+ * runtime.
+ *
+ * The generated header is committed so a machine without either compiler (Linux,
+ * macOS CI) still builds the engine; only the corresponding backend is
+ * unavailable there.
+ *
+ * Environment:
+ *   xbintsc_GLSLC  explicit `glslc` path (default: newest `C:\VulkanSDK\*`)
+ *   xbintsc_DXC    explicit `dxc` path (default: newest Windows SDK)
+ *
+ * Usage:
+ *   node scripts/build-gui-shaders.mjs          # regenerate the header
+ *   node scripts/build-gui-shaders.mjs --check  # fail if it is out of date
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const engineDir = join(root, "runtime", "ext_gui");
+const glslDir = join(engineDir, "spirv");
+const hlsl = join(engineDir, "shaders.hlsl");
+const header = join(engineDir, "renderer_shaders_data.h");
+const scratch = join(root, "build", "gui-shaders");
+
+/** SPIR-V programs: GLSL source file and the symbol to emit. */
+const SPIRV_PROGRAMS = [
+  { source: "fill.vert", symbol: "kFillSpirvVs" },
+  { source: "fill.frag", symbol: "kFillSpirvFs" },
+  { source: "quad.vert", symbol: "kTextSpirvVs" },
+  { source: "text.frag", symbol: "kTextSpirvFs" },
+  { source: "image.frag", symbol: "kImageSpirvFs" },
+];
+
+/** DXIL programs: HLSL entry point, stage and the symbol to emit. */
+const DXIL_PROGRAMS = [
+  { target: "vs_6_0", entry: "vs_main", symbol: "kFillDxilVs" },
+  { target: "ps_6_0", entry: "fs_main", symbol: "kFillDxilFs" },
+  { target: "vs_6_0", entry: "vs_text", symbol: "kTextDxilVs" },
+  { target: "ps_6_0", entry: "fs_text", symbol: "kTextDxilFs" },
+  { target: "ps_6_0", entry: "fs_image", symbol: "kImageDxilFs" },
+];
+
+function fail(message) {
+  console.error(`xbintsc: ${message}`);
+  process.exit(1);
+}
+
+/** Newest version-suffixed directory under `base`, or undefined. */
+function newestVersionDir(base, isVersion) {
+  if (!existsSync(base)) return undefined;
+  const versions = readdirSync(base)
+    .filter(isVersion)
+    .sort((a, b) => {
+      const pa = a.split(".").map(Number);
+      const pb = b.split(".").map(Number);
+      for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0) return diff;
+      }
+      return 0;
+    })
+    .reverse();
+  return { base, versions };
+}
+
+/** Locate `glslc`: the explicit override, then the newest installed Vulkan SDK. */
+function findGlslc() {
+  if (process.env.xbintsc_GLSLC) return process.env.xbintsc_GLSLC;
+  const found = newestVersionDir("C:\\VulkanSDK", (name) => /^\d+\.\d+\.\d+\.\d+$/.test(name));
+  if (!found) return undefined;
+  for (const version of found.versions) {
+    const bin = join(found.base, version, "Bin");
+    for (const name of ["glslc.exe", "glslc"]) {
+      if (existsSync(join(bin, name))) return join(bin, name);
+    }
+  }
+  return undefined;
+}
+
+/** Locate `dxc`: the explicit override, then the newest Windows SDK. */
+function findDxc() {
+  if (process.env.xbintsc_DXC) return process.env.xbintsc_DXC;
+  const found = newestVersionDir("C:\\Program Files (x86)\\Windows Kits\\10\\bin", (name) =>
+    /^\d+\.\d+\.\d+\.\d+$/.test(name),
+  );
+  if (!found) return undefined;
+  for (const version of found.versions) {
+    for (const arch of ["x64", "arm64"]) {
+      const candidate = join(found.base, version, arch, "dxc.exe");
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+/** Compile `args` with `tool`, failing with its output on a non-zero exit. */
+function compile(tool, args, label) {
+  const result = spawnSync(tool, args, { encoding: "utf8" });
+  if (result.status !== 0) {
+    fail(`${label} failed:\n${result.stderr ?? ""}${result.stdout ?? ""}`);
+  }
+}
+
+/** Render one blob as a C++ array initializer, 16 bytes per line. */
+function renderArray(symbol, bytes) {
+  const lines = [];
+  for (let i = 0; i < bytes.length; i += 16) {
+    lines.push("  " + Array.from(bytes.subarray(i, i + 16)).join(", ") + ",");
+  }
+  return [
+    `inline constexpr unsigned char ${symbol}[] = {`,
+    ...lines,
+    "};",
+    `inline constexpr size_t ${symbol}Size = sizeof(${symbol});`,
+  ].join("\n");
+}
+
+mkdirSync(scratch, { recursive: true });
+
+const blobs = [];
+
+const glslc = findGlslc();
+if (glslc === undefined) {
+  fail(
+    "no glslc found; install the Vulkan SDK (https://vulkan.lunarg.com) or set " +
+      `xbintsc_GLSLC.\nThe committed ${header} was not regenerated.`,
+  );
+}
+for (const program of SPIRV_PROGRAMS) {
+  const output = join(scratch, `${program.symbol}.spv`);
+  compile(
+    glslc,
+    ["-c", join(glslDir, program.source), "-o", output],
+    `glslc ${program.source}`,
+  );
+  blobs.push({ symbol: program.symbol, bytes: readFileSync(output) });
+}
+
+const dxc = findDxc();
+if (dxc === undefined) {
+  fail(
+    "no dxc found; install the Windows SDK or set xbintsc_DXC.\n" +
+      `The committed ${header} was not regenerated.`,
+  );
+}
+for (const program of DXIL_PROGRAMS) {
+  const output = join(scratch, `${program.symbol}.dxil`);
+  compile(
+    dxc,
+    ["-T", program.target, "-E", program.entry, "-Fo", output, hlsl],
+    `dxc ${program.target} ${program.entry}`,
+  );
+  blobs.push({ symbol: program.symbol, bytes: readFileSync(output) });
+}
+
+rmSync(scratch, { recursive: true, force: true });
+
+const generated = [
+  "/*",
+  " * Generated by `scripts/build-gui-shaders.mjs` — do not edit.",
+  " *",
+  " * SPIR-V blobs (Vulkan) compiled from `runtime/ext_gui/spirv/` with glslc, and",
+  " * DXIL blobs (Direct3D 12) compiled from `runtime/ext_gui/shaders.hlsl` with dxc.",
+  " * The Metal path uses the MSL literals in `renderer_shaders.h` directly.",
+  " */",
+  "#ifndef XT_GUI_RENDERER_SHADERS_DATA_H",
+  "#define XT_GUI_RENDERER_SHADERS_DATA_H",
+  "",
+  "#include <stddef.h>",
+  "",
+  ...blobs.map((blob) => renderArray(blob.symbol, blob.bytes)),
+  "",
+  "#endif /* XT_GUI_RENDERER_SHADERS_DATA_H */",
+  "",
+].join("\n");
+
+if (process.argv.includes("--check")) {
+  const current = existsSync(header) ? readFileSync(header, "utf8") : "";
+  if (current !== generated) {
+    fail(`${header} is out of date; run \`node scripts/build-gui-shaders.mjs\``);
+  }
+  console.log(`xbintsc: ${header} is up to date`);
+} else {
+  writeFileSync(header, generated);
+  const total = blobs.reduce((sum, blob) => sum + blob.bytes.length, 0);
+  console.log(`xbintsc: wrote ${header} (${blobs.length} blobs, ${total} bytes)`);
+}

package/scripts/build-gui.ts

@@ -53,6 +53,32 @@ const isWindows = process.platform === "win32";
 const objectSuffix = isWindows ? ".obj" : ".o";
 const output = join(outDir, isWindows ? "gui.lib" : "gui.a");
 
+/* CMake generator and ABI settings used for every vendored library. Ninja is
+ * selected on Windows because the Visual Studio generator imports the
+ * machine-wide MSBuild/vcpkg integration, whose `LIBPATH` shadows the Windows
+ * SDK and makes the compiler probe fail with
+ * `LNK1104: cannot open file 'ucrtd.lib'`.
+ *
+ * `CMAKE_MSVC_RUNTIME_LIBRARY` is pinned to the *static* CRT (`MultiThreaded`),
+ * which is clang's Windows default (`-defaultlib:libcmt`) and what xbintsc uses
+ * for its own runtime objects. Building the vendored libraries against the DLL
+ * CRT instead fails the final link with
+ * `LNK2038: mismatch detected for 'RuntimeLibrary'`. The variable only takes
+ * effect when policy CMP0091 is NEW, but FreeType and HarfBuzz declare
+ * `cmake_minimum_required` below 3.15, which defaults the policy to OLD and
+ * silently ignores it — hence `CMAKE_POLICY_DEFAULT_CMP0091`. The C/C++ compilers
+ * are pinned to the same clang the engine is compiled with, so every object in
+ * `gui.a` shares one ABI and optimization behaviour. */
+const cmakeGeneratorArgs: readonly string[] = isWindows
+  ? [
+      "-G", "Ninja",
+      "-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded",
+      "-DCMAKE_POLICY_DEFAULT_CMP0091=NEW",
+      "-DCMAKE_C_COMPILER=clang",
+      "-DCMAKE_CXX_COMPILER=clang++",
+    ]
+  : [];
+
 const SDL_TAG = process.env.SDL3_TAG || "release-3.2.10";
 const FREETYPE_VERSION = process.env.FREETYPE_VERSION || "2.13.3";
 const HARFBUZZ_VERSION = process.env.HARFBUZZ_VERSION || "10.1.0";
@@ -178,6 +204,7 @@ if (!existingSdlArchive) {
   const configureArgs = [
     "-S", sdlSrc,
     "-B", sdlBuild,
+    ...cmakeGeneratorArgs,
     "-DCMAKE_BUILD_TYPE=Release",
     "-DSDL_SHARED=OFF",
     "-DSDL_STATIC=ON",
@@ -220,6 +247,7 @@ if (!existsSync(freetypeArchive() ?? "")) {
   run(cmake, [
     "-S", freetypeSrc,
     "-B", freetypeBuild,
+    ...cmakeGeneratorArgs,
     "-DCMAKE_BUILD_TYPE=Release",
     "-DBUILD_SHARED_LIBS=OFF",
     /* We only need TrueType/OpenType outlines; skip the optional codecs. */
@@ -240,6 +268,7 @@ if (!existsSync(harfbuzzArchive() ?? "")) {
   run(cmake, [
     "-S", harfbuzzSrc,
     "-B", harfbuzzBuild,
+    ...cmakeGeneratorArgs,
     "-DCMAKE_BUILD_TYPE=Release",
     "-DBUILD_SHARED_LIBS=OFF",
     "-DHB_BUILD_UTILS=OFF",
@@ -272,6 +301,12 @@ const sources = readdirSync(engineDir)
 
 const objects: string[] = [];
 const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", ...includeFlags];
+/* The engine is C++ and the MSVC C++ runtime must match the static C CRT that
+ * clang links by default, so let every engine object record `libcpmt` as a
+ * default library. The extension itself only contributes the DLL import library
+ * (`-lmsvcprt`, `src/extensions/gui/index.ts`), which is inconsistent with that
+ * CRT and makes the final link fail with `LNK2038`/unresolved `__imp_*`. */
+if (isWindows) cxxFlags.push("-Xclang", "--dependent-lib=libcpmt");
 /* The MSVC ABI rejects `-fPIC`; position independence is the default elsewhere. */
 if (!isWindows) cxxFlags.splice(3, 0, "-fPIC");
 for (const source of sources) {

package/scripts/check-file-length.ts

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Enforce the per-file line budget for code ESLint cannot parse.
+ *
+ * ESLint's `max-lines` rule already caps the TypeScript/JavaScript sources at
+ * 600 lines (see `eslint.config.js`). This script applies the same budget to
+ * the runtime's C, C++, Rust and `#include`d `.inc` fragments plus shell
+ * scripts, so *every* code file stays focused and small.
+ *
+ * Vendored third-party sources that must ship verbatim (notably the
+ * single-header `stb_image.h`) are exempt: they are not ours to split.
+ *
+ * Run via `npm run lint` (or `tsx scripts/check-file-length.ts`).
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(new URL(".", import.meta.url)), "..");
+
+/** Maximum number of lines allowed in a single code file. */
+const MAX_LINES = 600;
+
+const CODE_EXTENSIONS = new Set([".c", ".h", ".cc", ".cpp", ".hpp", ".rs", ".inc", ".sh"]);
+
+const IGNORED_DIRECTORIES = new Set([
+  ".git",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "scratch",
+  "target",
+  "vendor",
+]);
+
+/** Vendored third-party sources that ship verbatim and are not ours to split. */
+const VENDORED_FILES = new Set([join("runtime", "ext_gui", "stb_image.h")]);
+
+/** Machine-generated files: they are reproduced from their sources by a script,
+ * so their size is not a sign of a module that needs splitting. */
+const GENERATED_FILES = new Set([join("runtime", "ext_gui", "renderer_shaders_data.h")]);
+
+interface Offense {
+  file: string;
+  lines: number;
+}
+
+function countLines(path: string): number {
+  const content = readFileSync(path, "utf8");
+  if (content.length === 0) return 0;
+  // A trailing newline terminates the last line instead of starting a new one.
+  const lines = content.split("\n");
+  return content.endsWith("\n") ? lines.length - 1 : lines.length;
+}
+
+function collect(dir: string, offenses: Offense[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRECTORIES.has(entry.name)) continue;
+      // `runtime/lib` holds prebuilt archives, never sources.
+      if (relative(root, full) === join("runtime", "lib")) continue;
+      collect(full, offenses);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const dot = entry.name.lastIndexOf(".");
+    if (dot < 0 || !CODE_EXTENSIONS.has(entry.name.slice(dot))) continue;
+    const file = relative(root, full);
+    if (VENDORED_FILES.has(file) || GENERATED_FILES.has(file)) continue;
+    const lines = countLines(full);
+    if (lines > MAX_LINES) offenses.push({ file, lines });
+  }
+}
+
+const offenses: Offense[] = [];
+collect(root, offenses);
+
+if (offenses.length > 0) {
+  console.error(`xbintsc: code files must stay under ${MAX_LINES} lines - split them by responsibility:`);
+  for (const offense of offenses.sort((a, b) => b.lines - a.lines)) {
+    console.error(`  ${offense.file}: ${offense.lines} lines`);
+  }
+  process.exit(1);
+}
+
+console.log(`xbintsc: all code files are within ${MAX_LINES} lines`);

package/src/cli/hints.ts

@@ -0,0 +1,194 @@
+/**
+ * Documentation pointers for diagnostics.
+ *
+ * Every failure printed by the CLI ends with a `hint:` line naming the document
+ * that explains what to do next. The messages already say what is wrong; these
+ * lines say where to read more, which is what keeps an agent (or a person) from
+ * re-deriving the language subset one failed build at a time.
+ *
+ * The paths are relative to the repository root, so they stay clickable in
+ * GitHub's rendered output and on a terminal that links paths.
+ */
+
+import { DiagnosticCode, type Diagnostic } from "../diagnostics/diagnostic.js";
+
+/** Where a reader should go next. */
+export interface DocumentationPointer {
+  /** Message printed after `hint:`. */
+  readonly text: string;
+  /** Repository-relative path to the document. */
+  readonly path: string;
+}
+
+export const DOC_LANGUAGE_SUPPORT = "doc/ai/language-support.md";
+export const DOC_EXTENSIONS = "doc/ai/extensions.md";
+export const DOC_TROUBLESHOOTING = "doc/ai/troubleshooting.md";
+export const DOC_CLI = "doc/ai/cli.md";
+export const DOC_REQUIREMENTS = "doc/requirements.md";
+
+const CHECKER_HINT: DocumentationPointer = {
+  text: "the compiler supports a subset of TypeScript; check what is implemented before rewriting",
+  path: DOC_LANGUAGE_SUPPORT,
+};
+
+const REQUIREMENT_HINT: DocumentationPointer = {
+  text: "xbintsc needs clang 16 or newer; run `xbintsc doctor` to see the resolved toolchain",
+  path: DOC_REQUIREMENTS,
+};
+
+/** Hint for a clang failure: a missing or too-old clang has a specific answer. */
+export function toolchainPointer(message: string): DocumentationPointer {
+  const usesTypedPointers = /defined with type '\[.*i8\]\*' but expected 'i8\*'/.test(message);
+  if (usesTypedPointers || /No C compiler found/i.test(message)) return REQUIREMENT_HINT;
+  return {
+    text: "read the clang output above, then the toolchain section of the troubleshooting guide",
+    path: DOC_TROUBLESHOOTING,
+  };
+}
+
+/** A thrown failure the CLI can name, in table order. */
+export interface ThrownFailure {
+  /** Tested against the thrown message. */
+  readonly match: RegExp;
+  readonly code: DiagnosticCode;
+  readonly pointer: DocumentationPointer;
+}
+
+/**
+ * Failures the CLI reports as a message instead of a diagnostic. Matching on the
+ * text is what lets each one reach the document that actually explains it —
+ * a missing manifest and an unknown extension are both "cannot read something",
+ * but only one of them is answered by the CLI reference.
+ */
+const THROWN_FAILURES: readonly ThrownFailure[] = [
+  {
+    match: /native extension manifest/i,
+    code: DiagnosticCode.IOError,
+    pointer: {
+      text: "check the manifest path and its JSON; objects are relative to the manifest file",
+      path: DOC_EXTENSIONS,
+    },
+  },
+  {
+    match: /Unknown extension/i,
+    code: DiagnosticCode.IOError,
+    pointer: {
+      text: "run `xbintsc help` for the flag, and see the built-in extensions this build ships",
+      path: DOC_EXTENSIONS,
+    },
+  },
+  {
+    match: /config|JSON/i,
+    code: DiagnosticCode.IOError,
+    pointer: {
+      text: "check the project config path and its fields",
+      path: DOC_CLI,
+    },
+  },
+];
+
+/** The failure a thrown error's message describes, if any. */
+export function thrownFailure(message: string): ThrownFailure | undefined {
+  return THROWN_FAILURES.find((failure) => failure.match.test(message));
+}
+
+/**
+ * The completion for an unclassified thrown error: the toolchain's own wording
+ * is the only thing worth directing a reader to.
+ */
+export const UNEXPECTED_FAILURE_HINT: DocumentationPointer = {
+  text: "this failure has no dedicated guide; check the resolved toolchain and the source paths",
+  path: DOC_TROUBLESHOOTING,
+};
+
+/**
+ * The document that explains a diagnostic, or `undefined` for internal errors
+ * that no reader can act on.
+ */
+export function documentationFor(diagnostic: Diagnostic): DocumentationPointer | undefined {
+  switch (diagnostic.code) {
+    // Lexer, parser and binder report a precise location; the guidance is the
+    // same subset reference.
+    case DiagnosticCode.UnterminatedString:
+    case DiagnosticCode.UnterminatedTemplate:
+    case DiagnosticCode.UnterminatedComment:
+    case DiagnosticCode.InvalidCharacter:
+    case DiagnosticCode.InvalidNumber:
+    case DiagnosticCode.InvalidEscape:
+    case DiagnosticCode.UnexpectedToken:
+    case DiagnosticCode.ExpectedToken:
+    case DiagnosticCode.ExpectedIdentifier:
+    case DiagnosticCode.UnexpectedEof:
+    case DiagnosticCode.InvalidAssignmentTarget:
+    case DiagnosticCode.DuplicateDefault:
+    case DiagnosticCode.InvalidTypeSyntax:
+    case DiagnosticCode.DuplicateIdentifier:
+    case DiagnosticCode.CannotFindName:
+    case DiagnosticCode.IllegalRedeclaration:
+    case DiagnosticCode.CannotAssignToConst:
+    case DiagnosticCode.UnsupportedFeature:
+      return CHECKER_HINT;
+
+    // Every codegen and bundler error carries its own message; the subset page
+    // is what separates "you wrote unsupported code" from "you wrote a bug".
+    case DiagnosticCode.CodegenError:
+      return CHECKER_HINT;
+
+    case DiagnosticCode.ModuleNotFound:
+      return {
+        text: "Node modules need the `node` extension (`--ext node`); third-party npm packages are not supported",
+        path: DOC_EXTENSIONS,
+      };
+
+    case DiagnosticCode.IOError:
+      return {
+        text: "check the path and the project config; paths in xbintsc.config.json resolve against that file",
+        path: DOC_TROUBLESHOOTING,
+      };
+
+    case DiagnosticCode.ToolchainError:
+      return toolchainPointer(diagnostic.message);
+
+    case DiagnosticCode.IncrementalCacheError:
+      return {
+        text: "the incremental cache could not be trusted; retry with `--force` or remove the cache directory",
+        path: DOC_CLI,
+      };
+
+    // The checker codes are defined but never emitted today.
+    case DiagnosticCode.TypeMismatch:
+    case DiagnosticCode.NotCallable:
+    case DiagnosticCode.PropertyNotFound:
+    case DiagnosticCode.ArgumentCountMismatch:
+      return CHECKER_HINT;
+  }
+}
+
+/** Render one `hint:` line, or `undefined` when the code has no document. */
+export function formatDocumentationHint(diagnostic: Diagnostic): string | undefined {
+  const pointer = documentationFor(diagnostic);
+  if (!pointer) return undefined;
+  return `hint: ${pointer.text} — see ${pointer.path}`;
+}
+
+/**
+ * One hint line per failing diagnostic, in first-seen order and without
+ * repeating a document the reader has already been sent to.
+ */
+export function documentationHints(diagnostics: readonly Diagnostic[]): string[] {
+  const lines: string[] = [];
+  const seen = new Set<string>();
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.category !== "error") continue;
+    const line = formatDocumentationHint(diagnostic);
+    if (line === undefined || seen.has(line)) continue;
+    seen.add(line);
+    lines.push(line);
+  }
+  return lines;
+}
+
+/** Render one hint line for an already-classified thrown failure. */
+export function formatThrownHint(pointer: DocumentationPointer): string {
+  return `hint: ${pointer.text} — see ${pointer.path}`;
+}