@stacksjs/zig-dtsx 0.9.10

package/src/types.zig

@@ -0,0 +1,105 @@
+const std = @import("std");
+
+/// Declaration kinds matching the TypeScript scanner output
+pub const DeclarationKind = enum {
+    import_decl,
+    export_decl,
+    function_decl,
+    variable_decl,
+    interface_decl,
+    type_decl,
+    class_decl,
+    enum_decl,
+    module_decl,
+    namespace_decl,
+    unknown_decl,
+
+    pub fn toString(self: DeclarationKind) []const u8 {
+        return switch (self) {
+            .import_decl => "import",
+            .export_decl => "export",
+            .function_decl => "function",
+            .variable_decl => "variable",
+            .interface_decl => "interface",
+            .type_decl => "type",
+            .class_decl => "class",
+            .enum_decl => "enum",
+            .module_decl => "module",
+            .namespace_decl => "namespace",
+            .unknown_decl => "unknown",
+        };
+    }
+};
+
+/// A single declaration extracted from TypeScript source.
+/// `text` contains the pre-built DTS output for this declaration.
+/// `name_slice` and other slices point into the original source buffer.
+pub const Declaration = struct {
+    kind: DeclarationKind,
+    /// Name of the declaration (slice into source or allocated)
+    name: []const u8 = "",
+    /// Pre-built DTS text for this declaration (owned, allocated)
+    text: []const u8 = "",
+    /// Whether this declaration is exported
+    is_exported: bool = false,
+    /// Whether this is a default export
+    is_default: bool = false,
+    /// Whether this is type-only (for imports/exports)
+    is_type_only: bool = false,
+    /// Whether this is a side-effect import
+    is_side_effect: bool = false,
+    /// Module source for imports (e.g., 'node:fs')
+    source_module: []const u8 = "",
+    /// Leading comments (JSDoc, block, single-line)
+    leading_comments: ?[]const []const u8 = null,
+    /// Start position in source
+    start: usize = 0,
+    /// End position in source
+    end: usize = 0,
+    /// Whether this function had a body (for overload detection)
+    has_body: bool = false,
+    /// Initializer text for variable declarations
+    value: []const u8 = "",
+    /// Type annotation text
+    type_annotation: []const u8 = "",
+    /// Whether this is async
+    is_async: bool = false,
+    /// Whether this is a generator
+    is_generator: bool = false,
+    /// Modifiers like ['const', 'const assertion'], ['abstract']
+    modifiers: ?[]const []const u8 = null,
+    /// Generics text
+    generics: []const u8 = "",
+    /// Extends clause
+    extends_clause: []const u8 = "",
+    /// Implements list
+    implements_list: ?[]const []const u8 = null,
+    /// Cached parsed import (populated during scan, avoids re-parsing in emitter)
+    parsed_import: ?ParsedImport = null,
+};
+
+/// Parsed import statement for filtering/sorting
+pub const ParsedImport = struct {
+    default_name: ?[]const u8 = null,
+    named_items: []const []const u8 = &.{},
+    source: []const u8 = "",
+    is_type_only: bool = false,
+    is_namespace: bool = false,
+    namespace_name: ?[]const u8 = null,
+    /// Pre-resolved item names (type/as stripped) for fast filtering
+    resolved_items: []const []const u8 = &.{},
+};
+
+/// Constructor parameter modifiers (hoisted to avoid per-call allocation)
+pub const PARAM_MODIFIERS = [_][]const u8{
+    "public",
+    "protected",
+    "private",
+    "readonly",
+    "override",
+};
+
+test "DeclarationKind toString" {
+    try std.testing.expectEqualStrings("function", DeclarationKind.function_decl.toString());
+    try std.testing.expectEqualStrings("import", DeclarationKind.import_decl.toString());
+}

package/test/benchmark.ts

@@ -0,0 +1,343 @@
+/**
+ * Benchmark: Zig DTS (CLI + FFI) vs TypeScript DTS emitter
+ *
+ * Three runners:
+ *   1. Zig CLI  — spawns zig-out/bin/zig-dtsx, pipes via stdin
+ *   2. Zig FFI  — calls the shared library in-process via Bun FFI
+ *   3. TS       — calls processSource() from @stacksjs/dtsx in-process
+ *
+ * Two benchmark modes:
+ *   A. Single-file — each fixture processed individually
+ *   B. Multi-file project — all fixtures processed as a batch
+ *
+ * Usage: bun run test/benchmark.ts [--quick] [--cli-only]
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const fixturesDir = resolve(import.meta.dir, '../../dtsx/test/fixtures')
+const zigBinary = resolve(import.meta.dir, '..', 'zig-out', 'bin', 'zig-dtsx')
+const args = process.argv.slice(2)
+const quick = args.includes('--quick')
+const cliOnly = args.includes('--cli-only')
+
+// ---------------------------------------------------------------------------
+// Runners
+// ---------------------------------------------------------------------------
+
+function zigCli(input: string): string {
+  const result = spawnSync(zigBinary, [], {
+    input,
+    encoding: 'utf-8',
+    maxBuffer: 50 * 1024 * 1024,
+  })
+  if (result.error) throw result.error
+  return result.stdout
+}
+
+let zigFfi: ((_input: string) => string) | null = null
+let tsProcess: ((_input: string) => string) | null = null
+
+async function loadRunners(): Promise<void> {
+  // Zig FFI
+  if (!cliOnly) {
+    try {
+      const { processSource } = await import('../src/index')
+      zigFfi = (source: string) => processSource(source, true)
+    }
+    catch {
+      console.log('  Zig FFI: not available (run "zig build" first)')
+    }
+  }
+
+  // TS
+  try {
+    const mod = await import('@stacksjs/dtsx')
+    const fn = (mod as any).processSource ?? (mod as any).default?.processSource
+    if (fn) {
+      tsProcess = (source: string) => fn(source, 'bench.ts', true)
+    }
+    else {
+      console.log('  TS: processSource not found in @stacksjs/dtsx')
+    }
+  }
+  catch {
+    console.log('  TS: could not import @stacksjs/dtsx')
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatBytes(bytes: number): string {
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)}MB`
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)}KB`
+  return `${bytes}B`
+}
+
+interface SingleResult {
+  name: string
+  inputSize: number
+  zigCliMs: number
+  zigFfiMs: number | null
+  tsMs: number | null
+}
+
+function bench(fn: (input: string) => string, input: string, iterations: number): number {
+  // warmup
+  for (let i = 0; i < 3; i++) fn(input)
+  const start = performance.now()
+  for (let i = 0; i < iterations; i++) fn(input)
+  return (performance.now() - start) / iterations
+}
+
+// ---------------------------------------------------------------------------
+// A) Single-file benchmark
+// ---------------------------------------------------------------------------
+
+async function singleFileBenchmark(): Promise<SingleResult[]> {
+  const fixtures = [
+    'imports', 'exports', 'function', 'function-types', 'variable',
+    'interface', 'class', 'enum', 'type', 'namespace',
+    'generics', 'advanced-types', 'edge-cases', 'complex-class', 'module',
+    'type-only-imports', 'comments',
+  ]
+
+  const iterations = quick ? 20 : 100
+  const results: SingleResult[] = []
+
+  for (const fixture of fixtures) {
+    const inputPath = join(fixturesDir, 'input', `${fixture}.ts`)
+    if (!existsSync(inputPath)) continue
+
+    const input = readFileSync(inputPath, 'utf-8')
+    const inputSize = Buffer.byteLength(input, 'utf-8')
+
+    const zigCliMs = bench(zigCli, input, iterations)
+    const zigFfiMs = zigFfi ? bench(zigFfi, input, iterations) : null
+    const tsMs = tsProcess ? bench(tsProcess, input, iterations) : null
+
+    results.push({ name: fixture, inputSize, zigCliMs, zigFfiMs, tsMs })
+  }
+
+  // Large file — fewer iterations
+  const checkerPath = join(fixturesDir, 'input', 'checker.ts')
+  if (existsSync(checkerPath)) {
+    const input = readFileSync(checkerPath, 'utf-8')
+    const inputSize = Buffer.byteLength(input, 'utf-8')
+    const iters = quick ? 2 : 5
+    const zigCliMs = bench(zigCli, input, iters)
+    const zigFfiMs = zigFfi ? bench(zigFfi, input, iters) : null
+    const tsMs = tsProcess ? bench(tsProcess, input, iters) : null
+    results.push({ name: 'checker.ts (large)', inputSize, zigCliMs, zigFfiMs, tsMs })
+  }
+
+  // Real-world fixtures
+  for (const rw of ['lodash-like', 'react-like']) {
+    const rwPath = join(fixturesDir, 'input', 'real-world', `${rw}.ts`)
+    if (!existsSync(rwPath)) continue
+    const input = readFileSync(rwPath, 'utf-8')
+    const inputSize = Buffer.byteLength(input, 'utf-8')
+    const iters = quick ? 10 : 50
+    const zigCliMs = bench(zigCli, input, iters)
+    const zigFfiMs = zigFfi ? bench(zigFfi, input, iters) : null
+    const tsMs = tsProcess ? bench(tsProcess, input, iters) : null
+    results.push({ name: rw, inputSize, zigCliMs, zigFfiMs, tsMs })
+  }
+
+  return results
+}
+
+// ---------------------------------------------------------------------------
+// B) Multi-file project benchmark
+// ---------------------------------------------------------------------------
+
+interface ProjectResult {
+  name: string
+  fileCount: number
+  totalSize: number
+  zigCliMs: number
+  zigFfiMs: number | null
+  tsMs: number | null
+}
+
+function collectInputFiles(dir: string): { name: string, content: string }[] {
+  const files: { name: string, content: string }[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith('.ts')) {
+      files.push({ name: entry.name, content: readFileSync(join(dir, entry.name), 'utf-8') })
+    }
+    else if (entry.isDirectory()) {
+      for (const sub of readdirSync(join(dir, entry.name), { withFileTypes: true })) {
+        if (sub.isFile() && sub.name.endsWith('.ts')) {
+          files.push({
+            name: `${entry.name}/${sub.name}`,
+            content: readFileSync(join(dir, entry.name, sub.name), 'utf-8'),
+          })
+        }
+      }
+    }
+  }
+  return files
+}
+
+function benchProject(
+  runner: (input: string) => string,
+  files: { content: string }[],
+  iterations: number,
+): number {
+  // warmup
+  for (let w = 0; w < 2; w++) {
+    for (const f of files) runner(f.content)
+  }
+  const start = performance.now()
+  for (let i = 0; i < iterations; i++) {
+    for (const f of files) runner(f.content)
+  }
+  return (performance.now() - start) / iterations
+}
+
+async function multiFileBenchmark(): Promise<ProjectResult[]> {
+  const results: ProjectResult[] = []
+  const inputDir = join(fixturesDir, 'input')
+  const allFiles = collectInputFiles(inputDir)
+
+  // Small project: just the basic fixtures (no checker.ts)
+  const smallFiles = allFiles.filter(f => !f.name.includes('checker'))
+  const smallSize = smallFiles.reduce((s, f) => s + Buffer.byteLength(f.content, 'utf-8'), 0)
+  const smallIters = quick ? 5 : 20
+
+  {
+    const zigCliMs = benchProject(zigCli, smallFiles, smallIters)
+    const zigFfiMs = zigFfi ? benchProject(zigFfi, smallFiles, smallIters) : null
+    const tsMs = tsProcess ? benchProject(tsProcess, smallFiles, smallIters) : null
+    results.push({
+      name: 'All fixtures (excl. checker)',
+      fileCount: smallFiles.length,
+      totalSize: smallSize,
+      zigCliMs,
+      zigFfiMs,
+      tsMs,
+    })
+  }
+
+  // Full project: everything including checker.ts
+  const fullSize = allFiles.reduce((s, f) => s + Buffer.byteLength(f.content, 'utf-8'), 0)
+  const fullIters = quick ? 2 : 5
+
+  {
+    const zigCliMs = benchProject(zigCli, allFiles, fullIters)
+    const zigFfiMs = zigFfi ? benchProject(zigFfi, allFiles, fullIters) : null
+    const tsMs = tsProcess ? benchProject(tsProcess, allFiles, fullIters) : null
+    results.push({
+      name: 'Full project (all files)',
+      fileCount: allFiles.length,
+      totalSize: fullSize,
+      zigCliMs,
+      zigFfiMs,
+      tsMs,
+    })
+  }
+
+  return results
+}
+
+// ---------------------------------------------------------------------------
+// Output formatting
+// ---------------------------------------------------------------------------
+
+function printSingleResults(results: SingleResult[]): void {
+  const hasFFI = results.some(r => r.zigFfiMs !== null)
+  const hasTS = results.some(r => r.tsMs !== null)
+
+  // Header
+  let header = `${'Fixture'.padEnd(22)} ${'Size'.padStart(8)}`
+  header += ` ${'Zig CLI'.padStart(10)}`
+  if (hasFFI) header += ` ${'Zig FFI'.padStart(10)}`
+  if (hasTS) header += ` ${'TS'.padStart(10)}`
+  if (hasFFI) header += ` ${'FFI/TS'.padStart(8)}`
+  console.log(header)
+  console.log('-'.repeat(header.length))
+
+  for (const r of results) {
+    let row = `${r.name.padEnd(22)} ${formatBytes(r.inputSize).padStart(8)}`
+    row += ` ${(r.zigCliMs.toFixed(2) + 'ms').padStart(10)}`
+    if (hasFFI) row += ` ${r.zigFfiMs !== null ? (r.zigFfiMs.toFixed(2) + 'ms').padStart(10) : 'n/a'.padStart(10)}`
+    if (hasTS) row += ` ${r.tsMs !== null ? (r.tsMs.toFixed(2) + 'ms').padStart(10) : 'n/a'.padStart(10)}`
+    if (hasFFI && r.zigFfiMs !== null && r.tsMs !== null) {
+      const speedup = r.tsMs / r.zigFfiMs
+      row += ` ${(speedup.toFixed(1) + 'x').padStart(8)}`
+    }
+    console.log(row)
+  }
+
+  // Summary
+  if (hasFFI && hasTS) {
+    const withBoth = results.filter(r => r.zigFfiMs !== null && r.tsMs !== null)
+    if (withBoth.length > 0) {
+      const avgFFI = withBoth.reduce((s, r) => s + r.zigFfiMs!, 0) / withBoth.length
+      const avgTS = withBoth.reduce((s, r) => s + r.tsMs!, 0) / withBoth.length
+      console.log(`\n  Zig FFI avg: ${avgFFI.toFixed(3)}ms — TS avg: ${avgTS.toFixed(3)}ms — FFI is ${(avgTS / avgFFI).toFixed(1)}x faster`)
+    }
+  }
+}
+
+function printProjectResults(results: ProjectResult[]): void {
+  const hasFFI = results.some(r => r.zigFfiMs !== null)
+  const hasTS = results.some(r => r.tsMs !== null)
+
+  let header = `${'Project'.padEnd(32)} ${'Files'.padStart(6)} ${'Size'.padStart(8)}`
+  header += ` ${'Zig CLI'.padStart(10)}`
+  if (hasFFI) header += ` ${'Zig FFI'.padStart(10)}`
+  if (hasTS) header += ` ${'TS'.padStart(10)}`
+  if (hasFFI) header += ` ${'FFI/TS'.padStart(8)}`
+  console.log(header)
+  console.log('-'.repeat(header.length))
+
+  for (const r of results) {
+    let row = `${r.name.padEnd(32)} ${String(r.fileCount).padStart(6)} ${formatBytes(r.totalSize).padStart(8)}`
+    row += ` ${(r.zigCliMs.toFixed(1) + 'ms').padStart(10)}`
+    if (hasFFI) row += ` ${r.zigFfiMs !== null ? (r.zigFfiMs.toFixed(1) + 'ms').padStart(10) : 'n/a'.padStart(10)}`
+    if (hasTS) row += ` ${r.tsMs !== null ? (r.tsMs.toFixed(1) + 'ms').padStart(10) : 'n/a'.padStart(10)}`
+    if (hasFFI && r.zigFfiMs !== null && r.tsMs !== null) {
+      const speedup = r.tsMs / r.zigFfiMs
+      row += ` ${(speedup.toFixed(1) + 'x').padStart(8)}`
+    }
+    console.log(row)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  if (!existsSync(zigBinary)) {
+    console.error(`Zig binary not found at: ${zigBinary}`)
+    console.error('Run "zig build -Doptimize=ReleaseFast" first.')
+    process.exit(1)
+  }
+
+  console.log('\n=== zig-dtsx Benchmark ===\n')
+  console.log(`Zig CLI binary: ${zigBinary}`)
+  console.log(`Mode: ${quick ? 'quick' : 'full'}${cliOnly ? ' (CLI only)' : ''}\n`)
+
+  console.log('Loading runners...')
+  await loadRunners()
+
+  // A) Single-file benchmark
+  console.log('\n--- Single-File Benchmark ---\n')
+  const singleResults = await singleFileBenchmark()
+  printSingleResults(singleResults)
+
+  // B) Multi-file project benchmark
+  console.log('\n\n--- Multi-File Project Benchmark ---\n')
+  const projectResults = await multiFileBenchmark()
+  printProjectResults(projectResults)
+
+  console.log('\n')
+}
+
+main().catch(console.error)

package/test/fixtures/output/variable.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Example of const declaration
+ */
+export declare const conf: {
+  apiUrl: 'https://api.stacksjs.org';
+  timeout: '5000'
+};
+/** @defaultValue 'test' */
+export declare let test: string;
+/** @defaultValue 'Hello World' */
+export declare var helloWorld: string;
+/**
+ * @defaultValue
+ * ```ts
+ * {
+ *   someString: 'Stacks',
+ *   someNumber: 1000,
+ *   someBoolean: true,
+ *   someFalse: false,
+ *   someFunction: () => unknown,
+ *   anotherOne: () => unknown,
+ *   someArray: [1, 2, 3],
+ *   someNestedArray: [ [1, 2, 3], [4, 5, 6, 7, 8, 9, 10], ],
+ *   someNestedArray2: [ [1, 2, 3], [4, 5, 6, 7, 8, 9, 10], 'dummy value', ],
+ *   someNestedArray3: [ [1, 2, 3], [4, 5, 6, 7, 8, 9, 10], 'dummy value', [11, 12, 13], ],
+ *   someObject: { key: 'value' },
+ *   someNestedObject: { key: { nestedKey: 'value' }, otherKey: { nestedKey2: () => unknown } },
+ *   someNestedObjectArray: [ { key: 'value' }, { key2: 'value2' }, ]
+ * }
+ * ```
+ */
+export declare const someObject: {
+  /** @defaultValue 'Stacks' */
+  someString: string;
+  /** @defaultValue 1000 */
+  someNumber: number;
+  /** @defaultValue true */
+  someBoolean: boolean;
+  /** @defaultValue false */
+  someFalse: boolean;
+  someFunction: () => unknown;
+  anotherOne: () => unknown;
+  someArray: number[];
+  someNestedArray: number[][];
+  someNestedArray2: (number[] | string)[];
+  someNestedArray3: (number[] | string)[];
+  someOtherNestedArray: ((string | number | unknown | (() => unknown))[] | number[])[];
+  someComplexArray: ({
+  /** @defaultValue 'value' */
+  key: string
+}[] | ({
+  /** @defaultValue 'value2' */
+  key2: string
+} | string | number)[] | (string | unknown)[])[];
+  someObject: {
+  /** @defaultValue 'value' */
+  key: string
+};
+  someNestedObject: { key: { /** @defaultValue 'value' */ nestedKey: string }; otherKey: { nestedKey: unknown; nestedKey2: () => unknown } };
+  someNestedObjectArray: ({
+  /** @defaultValue 'value' */
+  key: string
+} | {
+  /** @defaultValue 'value2' */
+  key2: string
+})[];
+  someOtherObject: unknown;
+  someInlineCall2: unknown;
+  someInlineCall3: unknown
+};
+/** @defaultValue `{ 'Content-Type': 'application/json' }` */
+export declare const defaultHeaders: {
+  /** @defaultValue 'application/json' */
+  'Content-Type': string
+};
+/**
+ * Complex Arrays and Tuples
+ * @defaultValue
+ * ```ts
+ * {
+ *   matrix: [ [1, 2, [3, 4, [5, 6]]], ['a', 'b', ['c', 'd']], [true, [false, [true]]], ],
+ *   tuples: [ [1, 'string', true] as const, ['literal', 42, false] as const, ]
+ * }
+ * ```
+ */
+export declare const complexArrays: {
+  matrix: ((number | (number | number[])[])[] | (string | string[])[] | (boolean | (boolean | boolean[])[])[])[];
+  tuples: readonly [
+    readonly [1, 'string', true] |
+    readonly ['literal', 42, false]
+  ];
+  mixedArrays: (Date | Promise<string> | (() => unknown) | (() => Generator<any, any, any>))[]
+};
+/**
+ * Nested Object Types with Methods
+ * @defaultValue
+ * ```ts
+ * {
+ *   handlers: {
+ *     onSuccess<T>: (data: T) => unknown,
+ *     onError: (error: Error & { code?: number }) => unknown,
+ *     someOtherMethod: () => unknown
+ *   },
+ *   utils: {
+ *     formatters: {
+ *       date: (input: Date) => unknown,
+ *       currency: (amount: number, currency?) => unknown
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare const complexObject: {
+  handlers: { onSuccess<T>: (data: T) => unknown; onError: (error: Error & { code?: number }) => unknown; someOtherMethod: () => unknown };
+  utils: { formatters: { date: (input: Date) => unknown; currency: (amount: number, currency?) => unknown } }
+};
+// Method Decorators and Metadata (declares as unknown, because it should rely on explicit type)
+export declare const methodDecorator: (
+  target: any,
+  propertyKey: string,
+  descriptor: PropertyDescriptor
+) => unknown;
+// declares as SomeType
+export declare const methodDecoratorWithExplicitType: (
+  target: any,
+  propertyKey: string,
+  descriptor: PropertyDescriptor
+) => SomeType;
+// Complex Constants with Type Inference
+export declare const CONFIG_MAP: {
+  development: {
+  features: {
+  auth: {
+  providers: readonly ['google', 'github'];
+  settings: {
+  timeout: 5000;
+  retries: 3
+}
+}
+}
+};
+  production: {
+  features: {
+  auth: {
+  providers: readonly ['google', 'github', 'microsoft'];
+  settings: {
+  timeout: 3000;
+  retries: 5
+}
+}
+}
+}
+};
+export declare const command: {
+  run: unknown;
+  runSync: unknown
+};