@stacksjs/zig-dtsx 0.9.10

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# zig-dtsx
+
+A high-performance TypeScript declaration file (.d.ts) emitter written in Zig. This is the native companion to the TypeScript-based `@stacksjs/dtsx`, providing the same output with significantly faster execution.
+
+## Overview
+
+`zig-dtsx` reimplements the dtsx declaration generation pipeline in Zig for maximum performance. It produces output identical to the TypeScript implementation and is used as a drop-in replacement when the compiled binary is available.
+
+## Installation
+
+```bash
+bun add @stacksjs/zig-dtsx -d
+```
+
+## Usage
+
+### As a Library
+
+```typescript
+import { processSource, ZIG_AVAILABLE } from '@stacksjs/zig-dtsx'
+
+if (ZIG_AVAILABLE) {
+  const dtsOutput = processSource(typescriptSource, true)
+  console.log(dtsOutput)
+}
+```
+
+### Building from Source
+
+Requires [Zig](https://ziglang.org/) to be installed.
+
+```bash
+# Build optimized release binary
+bun run build:zig
+
+# Build debug binary
+bun run build:zig-debug
+
+# Run Zig-native tests
+bun run test:zig
+```
+
+## Architecture
+
+The Zig implementation mirrors the TypeScript dtsx pipeline:
+
+1. **Scanner** - Tokenizes TypeScript source into a stream of tokens
+2. **Extractor** - Parses tokens and extracts declaration-relevant constructs (exports, types, interfaces, classes, functions, variables)
+3. **Emitter** - Produces `.d.ts` output from the extracted declarations
+
+The Zig binary communicates with the Node/Bun runtime via FFI, allowing seamless integration with the existing dtsx ecosystem.
+
+## Benchmarks
+
+```bash
+bun run benchmark
+```
+
+## Testing
+
+Tests validate that the Zig emitter produces identical output to the TypeScript implementation across all shared test fixtures.
+
+```bash
+# Run via Bun test runner
+bun test
+
+# Run Zig-native tests
+zig build test
+```
+
+## License
+
+MIT

package/build.zig

@@ -0,0 +1,79 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    // Shared library for FFI (needs libc for c_allocator)
+    const lib = b.addLibrary(.{
+        .linkage = .dynamic,
+        .name = "zig-dtsx",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/lib.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        }),
+    });
+    // Enable LTO on Linux release builds (LLD required; macOS Mach-O doesn't support LLD)
+    if (target.result.os.tag == .linux and optimize != .Debug) {
+        lib.use_lld = true;
+        lib.lto = .full;
+    }
+    // Strip debug symbols in release builds for smaller binary + faster loads
+    if (optimize != .Debug) {
+        lib.root_module.strip = true;
+    }
+    b.installArtifact(lib);
+
+    // CLI binary (needs libc for C stdio)
+    const exe = b.addExecutable(.{
+        .name = "zig-dtsx",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/main.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        }),
+    });
+    if (optimize != .Debug) {
+        exe.root_module.strip = true;
+    }
+    b.installArtifact(exe);
+
+    // CLI-only step (for cross-compilation without shared library)
+    const cli_install = b.addInstallArtifact(exe, .{});
+    const cli_step = b.step("cli", "Build only the CLI binary");
+    cli_step.dependOn(&cli_install.step);
+
+    // Run step
+    const run_cmd = b.addRunArtifact(exe);
+    run_cmd.step.dependOn(b.getInstallStep());
+    if (b.args) |args| {
+        run_cmd.addArgs(args);
+    }
+    const run_step = b.step("run", "Run the CLI");
+    run_step.dependOn(&run_cmd.step);
+
+    // Unit tests
+    const test_targets = [_][]const u8{
+        "src/char_utils.zig",
+        "src/types.zig",
+        "src/scanner.zig",
+        "src/emitter.zig",
+        "src/type_inference.zig",
+    };
+
+    const test_step = b.step("test", "Run unit tests");
+    for (test_targets) |test_file| {
+        const unit_test = b.addTest(.{
+            .root_module = b.createModule(.{
+                .root_source_file = b.path(test_file),
+                .target = target,
+                .optimize = optimize,
+            }),
+        });
+        const run_unit_test = b.addRunArtifact(unit_test);
+        test_step.dependOn(&run_unit_test.step);
+    }
+}

package/build.zig.zon

@@ -0,0 +1,11 @@
+.{
+    .name = .zig_dtsx,
+    .version = "0.1.0",
+    .fingerprint = 0x545e4f1c4c6ae840,
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+    },
+    .dependencies = .{},
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@stacksjs/zig-dtsx",
+  "type": "module",
+  "version": "0.9.10",
+  "description": "High-performance DTS emitter written in Zig",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build:zig": "zig build -Doptimize=ReleaseFast",
+    "build:zig-debug": "zig build",
+    "build": "bun run build:zig",
+    "test": "bun test",
+    "test:zig": "zig build test",
+    "benchmark": "bun run test/benchmark.ts"
+  },
+  "dependencies": {
+    "@stacksjs/dtsx": "0.9.10"
+  }
+}

package/src/char_utils.zig

@@ -0,0 +1,158 @@
+/// Character constants and classification functions for the TypeScript scanner.
+/// Direct port of scanner.ts lines 9-49.
+
+// Character code constants for fast comparison
+pub const CH_SPACE: u8 = 32;
+pub const CH_TAB: u8 = 9;
+pub const CH_LF: u8 = 10;
+pub const CH_CR: u8 = 13;
+pub const CH_SLASH: u8 = 47;
+pub const CH_STAR: u8 = 42;
+pub const CH_SQUOTE: u8 = 39;
+pub const CH_DQUOTE: u8 = 34;
+pub const CH_BACKTICK: u8 = 96;
+pub const CH_BACKSLASH: u8 = 92;
+pub const CH_LBRACE: u8 = 123;
+pub const CH_RBRACE: u8 = 125;
+pub const CH_LPAREN: u8 = 40;
+pub const CH_RPAREN: u8 = 41;
+pub const CH_LBRACKET: u8 = 91;
+pub const CH_RBRACKET: u8 = 93;
+pub const CH_LANGLE: u8 = 60;
+pub const CH_RANGLE: u8 = 62;
+pub const CH_SEMI: u8 = 59;
+pub const CH_COLON: u8 = 58;
+pub const CH_EQUAL: u8 = 61;
+pub const CH_COMMA: u8 = 44;
+pub const CH_DOT: u8 = 46;
+pub const CH_QUESTION: u8 = 63;
+pub const CH_HASH: u8 = 35;
+pub const CH_AT: u8 = 64;
+pub const CH_DOLLAR: u8 = 36;
+pub const CH_UNDERSCORE: u8 = 95;
+pub const CH_EXCL: u8 = 33;
+pub const CH_PIPE: u8 = 124;
+pub const CH_AMP: u8 = 38;
+pub const CH_CARET: u8 = 94;
+pub const CH_TILDE: u8 = 126;
+pub const CH_PLUS: u8 = 43;
+pub const CH_MINUS: u8 = 45;
+pub const CH_PERCENT: u8 = 37;
+
+pub const CH_BOM: u16 = 0xFEFF;
+
+/// Check if a character is whitespace (space, tab, LF, CR)
+pub inline fn isWhitespace(ch: u8) bool {
+    return ch == CH_SPACE or ch == CH_TAB or ch == CH_LF or ch == CH_CR;
+}
+
+/// Check if a character can start an identifier (A-Z, a-z, _, $, or >127 for Unicode)
+pub inline fn isIdentStart(ch: u8) bool {
+    return (ch >= 'A' and ch <= 'Z') or (ch >= 'a' and ch <= 'z') or ch == CH_UNDERSCORE or ch == CH_DOLLAR or ch > 127;
+}
+
+/// Check if a character can continue an identifier (isIdentStart + 0-9)
+pub inline fn isIdentChar(ch: u8) bool {
+    return isIdentStart(ch) or (ch >= '0' and ch <= '9');
+}
+
+/// Check if a character is a digit (0-9)
+pub inline fn isDigit(ch: u8) bool {
+    return ch >= '0' and ch <= '9';
+}
+
+/// Find needle in haystack starting from start position
+pub inline fn indexOf(haystack: []const u8, needle: []const u8, start: usize) ?usize {
+    if (needle.len == 0) return start;
+    if (start + needle.len > haystack.len) return null;
+    return std.mem.indexOfPos(u8, haystack, start, needle);
+}
+
+/// Find a single byte in haystack starting from start position
+pub inline fn indexOfChar(haystack: []const u8, needle: u8, start: usize) ?usize {
+    if (start >= haystack.len) return null;
+    return std.mem.indexOfScalarPos(u8, haystack, start, needle);
+}
+
+/// Slice source[start..end) with leading/trailing whitespace trimmed
+pub fn sliceTrimmed(source: []const u8, start_pos: usize, end_pos: usize) []const u8 {
+    var s = start_pos;
+    var e = end_pos;
+    if (s >= e) return "";
+
+    // Fast path: if endpoints are already non-whitespace, skip trim loops
+    if (!isWhitespace(source[s]) and !isWhitespace(source[e - 1])) {
+        return source[s..e];
+    }
+
+    while (s < e and isWhitespace(source[s])) s += 1;
+    while (e > s and isWhitespace(source[e - 1])) e -= 1;
+    return source[s..e];
+}
+
+/// Check if a string starts with a given prefix
+pub inline fn startsWith(str: []const u8, prefix: []const u8) bool {
+    if (str.len < prefix.len) return false;
+    return std.mem.eql(u8, str[0..prefix.len], prefix);
+}
+
+/// Check if a string ends with a given suffix
+pub inline fn endsWith(str: []const u8, suffix: []const u8) bool {
+    if (str.len < suffix.len) return false;
+    return std.mem.eql(u8, str[str.len - suffix.len ..], suffix);
+}
+
+/// Check if a string contains a substring
+pub inline fn contains(str: []const u8, needle: []const u8) bool {
+    return std.mem.indexOf(u8, str, needle) != null;
+}
+
+const std = @import("std");
+
+// --- Tests ---
+test "isWhitespace" {
+    try std.testing.expect(isWhitespace(' '));
+    try std.testing.expect(isWhitespace('\t'));
+    try std.testing.expect(isWhitespace('\n'));
+    try std.testing.expect(isWhitespace('\r'));
+    try std.testing.expect(!isWhitespace('a'));
+    try std.testing.expect(!isWhitespace('/'));
+}
+
+test "isIdentStart" {
+    try std.testing.expect(isIdentStart('a'));
+    try std.testing.expect(isIdentStart('Z'));
+    try std.testing.expect(isIdentStart('_'));
+    try std.testing.expect(isIdentStart('$'));
+    try std.testing.expect(isIdentStart(200)); // Unicode
+    try std.testing.expect(!isIdentStart('0'));
+    try std.testing.expect(!isIdentStart(' '));
+}
+
+test "isIdentChar" {
+    try std.testing.expect(isIdentChar('a'));
+    try std.testing.expect(isIdentChar('0'));
+    try std.testing.expect(isIdentChar('_'));
+    try std.testing.expect(!isIdentChar(' '));
+    try std.testing.expect(!isIdentChar(';'));
+}
+
+test "sliceTrimmed" {
+    const src = "  hello  ";
+    try std.testing.expectEqualStrings("hello", sliceTrimmed(src, 0, src.len));
+    try std.testing.expectEqualStrings("hello", sliceTrimmed(src, 2, 7));
+}
+
+test "indexOf" {
+    const s = "hello world";
+    try std.testing.expectEqual(@as(?usize, 6), indexOf(s, "world", 0));
+    try std.testing.expectEqual(@as(?usize, null), indexOf(s, "xyz", 0));
+    try std.testing.expectEqual(@as(?usize, null), indexOf(s, "world", 7));
+}
+
+test "startsWith and endsWith" {
+    try std.testing.expect(startsWith("export const", "export"));
+    try std.testing.expect(!startsWith("import", "export"));
+    try std.testing.expect(endsWith("hello world", "world"));
+    try std.testing.expect(!endsWith("hello", "world"));
+}