redscript-mc 2.6.2 → 3.0.0

package/benchmarks/stdlib-complexity.ts

@@ -0,0 +1,54 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+import {
+  benchmarkMeta,
+  listStdlibModules,
+  OptimizationLevel,
+  parseCliArgs,
+  round,
+  runPipeline,
+  summarizeFiles,
+  writeJsonReport,
+} from './_shared'
+
+const OPT_LEVELS: OptimizationLevel[] = [0, 1, 2]
+
+function main(): void {
+  const { output } = parseCliArgs(process.argv.slice(2))
+  const modules = listStdlibModules().map(modulePath => {
+    const source = fs.readFileSync(modulePath, 'utf8')
+    const byOpt = OPT_LEVELS.map(level => {
+      const result = runPipeline(source, {
+        namespace: `stdlib_${path.basename(modulePath, '.mcrs')}`,
+        filePath: modulePath,
+        optimizationLevel: level,
+      })
+      return {
+        optLevel: `O${level}`,
+        timingsMs: {
+          parse: round(result.timings.parseMs),
+          hir: round(result.timings.hirMs),
+          mir: round(result.timings.mirMs),
+          emit: round(result.timings.emitMs),
+          total: round(result.timings.totalMs),
+        },
+        ...summarizeFiles(result.files),
+        warnings: result.warnings.length,
+      }
+    })
+
+    return {
+      module: path.basename(modulePath),
+      path: modulePath,
+      results: byOpt,
+    }
+  })
+
+  writeJsonReport({
+    ...benchmarkMeta('stdlib-complexity'),
+    modules,
+  }, output)
+}
+
+main()

package/benchmarks/stdlib-size.md

@@ -0,0 +1,57 @@
+# Stdlib Size Benchmark
+
+Generated: 2026-03-21T22:24:27.633Z
+
+Host: Apple M4 | 10 cores | 16384 MB RAM | darwin 24.6.0 (arm64)
+
+| Module | O0 Files | O0 Lines | O1 Files | O1 Lines | O2 Files | O2 Lines |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| advanced.mcrs | 173 | 1473 | 173 | 1318 | 173 | 1318 |
+| bigint.mcrs | 202 | 1370 | 202 | 1094 | 202 | 1094 |
+| bits.mcrs | 79 | 535 | 79 | 491 | 79 | 491 |
+| bossbar.mcrs | 15 | 176 | 15 | 134 | 15 | 134 |
+| calculus.mcrs | 59 | 504 | 59 | 437 | 59 | 437 |
+| color.mcrs | 182 | 1277 | 182 | 1187 | 182 | 1187 |
+| combat.mcrs | 8 | 37 | 8 | 35 | 8 | 35 |
+| cooldown.mcrs | 16 | 80 | 16 | 63 | 16 | 63 |
+| dialog.mcrs | 19 | 72 | 19 | 57 | 19 | 57 |
+| easing.mcrs | 43 | 560 | 43 | 517 | 43 | 517 |
+| ecs.mcrs | 45 | 322 | 45 | 240 | 45 | 240 |
+| effects.mcrs | 13 | 88 | 13 | 47 | 13 | 47 |
+| events.mcrs | 3 | 15 | 3 | 15 | 3 | 15 |
+| expr.mcrs | 40 | 383 | 40 | 324 | 40 | 324 |
+| fft.mcrs | 36 | 303 | 36 | 258 | 36 | 258 |
+| geometry.mcrs | 97 | 644 | 97 | 578 | 97 | 578 |
+| graph.mcrs | 124 | 803 | 124 | 643 | 124 | 643 |
+| heap.mcrs | 81 | 407 | 81 | 307 | 81 | 307 |
+| interactions.mcrs | 39 | 183 | 39 | 142 | 39 | 142 |
+| inventory.mcrs | 6 | 51 | 6 | 26 | 6 | 26 |
+| linalg.mcrs | 36 | 730 | 36 | 536 | 36 | 536 |
+| list.mcrs | 380 | 1840 | 380 | 1603 | 380 | 1603 |
+| math.mcrs | 238 | 1843 | 238 | 1694 | 238 | 1694 |
+| math_hp.mcrs | 40 | 481 | 40 | 422 | 40 | 422 |
+| matrix.mcrs | 137 | 1525 | 137 | 1434 | 137 | 1434 |
+| mobs.mcrs | 1 | 2 | 1 | 2 | 1 | 2 |
+| noise.mcrs | 31 | 580 | 31 | 534 | 31 | 534 |
+| ode.mcrs | 53 | 621 | 55 | 559 | 55 | 559 |
+| parabola.mcrs | 36 | 275 | 36 | 258 | 36 | 258 |
+| particles.mcrs | 25 | 265 | 25 | 187 | 25 | 187 |
+| pathfind.mcrs | 193 | 1569 | 193 | 1389 | 192 | 1385 |
+| physics.mcrs | 35 | 263 | 35 | 253 | 35 | 253 |
+| player.mcrs | 8 | 39 | 8 | 31 | 8 | 31 |
+| quaternion.mcrs | 44 | 1044 | 44 | 981 | 44 | 981 |
+| random.mcrs | 39 | 336 | 39 | 315 | 39 | 315 |
+| result.mcrs | 26 | 127 | 26 | 110 | 26 | 110 |
+| scheduler.mcrs | 138 | 603 | 138 | 523 | 138 | 523 |
+| sets.mcrs | 1 | 2 | 1 | 2 | 1 | 2 |
+| signal.mcrs | 325 | 3786 | 326 | 3491 | 326 | 3490 |
+| sort.mcrs | 169 | 947 | 168 | 815 | 168 | 815 |
+| spawn.mcrs | 8 | 69 | 8 | 52 | 8 | 52 |
+| state.mcrs | 12 | 73 | 12 | 60 | 12 | 60 |
+| strings.mcrs | 5 | 28 | 5 | 19 | 5 | 19 |
+| tags.mcrs | 1 | 2 | 1 | 2 | 1 | 2 |
+| teams.mcrs | 11 | 141 | 11 | 82 | 11 | 82 |
+| timer.mcrs | 22 | 128 | 22 | 103 | 22 | 103 |
+| vec.mcrs | 164 | 1055 | 164 | 984 | 164 | 984 |
+| world.mcrs | 21 | 101 | 21 | 63 | 21 | 63 |
+| Total | 3479 | 27758 | 3481 | 24417 | 3480 | 24412 |

package/benchmarks/stdlib-size.ts

@@ -0,0 +1,91 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+import {
+  benchmarkMeta,
+  listStdlibModules,
+  OptimizationLevel,
+  parseCliArgs,
+  runPipeline,
+  summarizeFiles,
+  writeTextReport,
+} from './_shared'
+
+const OPT_LEVELS: OptimizationLevel[] = [0, 1, 2]
+const DEFAULT_OUTPUT = 'benchmarks/stdlib-size.md'
+
+function formatReport(modules: Array<{
+  module: string
+  results: Array<{
+    optLevel: string
+    mcfunctionFileCount: number
+    mcfunctionLineCount: number
+  }>
+}>): string {
+  const meta = benchmarkMeta('stdlib-size')
+  const lines: string[] = [
+    '# Stdlib Size Benchmark',
+    '',
+    `Generated: ${meta.generatedAt}`,
+    '',
+    `Host: ${meta.host.cpuModel} | ${meta.host.cpuCount} cores | ${meta.host.totalMemoryMb} MB RAM | ${meta.host.platform} ${meta.host.release} (${meta.host.arch})`,
+    '',
+    '| Module | O0 Files | O0 Lines | O1 Files | O1 Lines | O2 Files | O2 Lines |',
+    '| --- | ---: | ---: | ---: | ---: | ---: | ---: |',
+  ]
+
+  for (const module of modules) {
+    const [o0, o1, o2] = module.results
+    lines.push(
+      `| ${module.module} | ${o0.mcfunctionFileCount} | ${o0.mcfunctionLineCount} | ${o1.mcfunctionFileCount} | ${o1.mcfunctionLineCount} | ${o2.mcfunctionFileCount} | ${o2.mcfunctionLineCount} |`
+    )
+  }
+
+  const totals = OPT_LEVELS.map(level => {
+    const index = level
+    return modules.reduce((acc, module) => {
+      acc.mcfunctionFileCount += module.results[index].mcfunctionFileCount
+      acc.mcfunctionLineCount += module.results[index].mcfunctionLineCount
+      return acc
+    }, { mcfunctionFileCount: 0, mcfunctionLineCount: 0 })
+  })
+
+  lines.push(
+    `| Total | ${totals[0].mcfunctionFileCount} | ${totals[0].mcfunctionLineCount} | ${totals[1].mcfunctionFileCount} | ${totals[1].mcfunctionLineCount} | ${totals[2].mcfunctionFileCount} | ${totals[2].mcfunctionLineCount} |`
+  )
+
+  return lines.join('\n')
+}
+
+function main(): void {
+  const { output } = parseCliArgs(process.argv.slice(2))
+  const modules = listStdlibModules().map(modulePath => {
+    const source = fs.readFileSync(modulePath, 'utf8')
+    const results = OPT_LEVELS.map(level => {
+      const result = runPipeline(source, {
+        namespace: `stdlib_${path.basename(modulePath, '.mcrs')}`,
+        filePath: modulePath,
+        optimizationLevel: level,
+      })
+      const summary = summarizeFiles(result.files)
+
+      return {
+        optLevel: `O${level}`,
+        mcfunctionFileCount: summary.mcfunctionFileCount,
+        mcfunctionLineCount: summary.mcfunctionLineCount,
+      }
+    })
+
+    return {
+      module: path.basename(modulePath),
+      results,
+    }
+  })
+
+  writeTextReport(
+    formatReport(modules),
+    output ?? DEFAULT_OUTPUT,
+  )
+}
+
+main()

package/coverage-report.md

@@ -0,0 +1,177 @@
+# RedScript Coverage Report
+
+Generated on 2026-03-21 from:
+
+```sh
+export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"
+npx jest --testPathPattern="^(?!.*mc-integration)" --forceExit --coverage --coverageReporters=json-summary
+```
+
+## Current Coverage
+
+### Total
+
+- Statements: 88.5% (2436/2754)
+- Branches: 80.2% (1108/1381)
+- Functions: 94.7% (306/323)
+- Lines: 89.8% (2205/2455)
+
+### Test Run Status
+
+Coverage artifacts were produced, but the run did **not** finish cleanly.
+
+- `src/__tests__/lsp/completion.test.ts`: `wordAt` expectation mismatch (`Expected ""`, `Received "fn"`).
+- `src/__tests__/repl-server.test.ts`: sandbox prevents binding `0.0.0.0:3000` (`listen EPERM`), causing hook timeouts.
+- `src/__tests__/repl-server-extra.test.ts`: same `listen EPERM` issue.
+- `src/__tests__/compile-all.test.ts`: new examples under `examples/rpg/` fail compilation due to string concatenation with `+`.
+
+Result: treat the coverage numbers below as the current repository snapshot, not a fully green baseline.
+
+## Lowest Branch Coverage Files
+
+Files with more than 5 branches, sorted by branch coverage:
+
+| File | Branches | Covered | Pct |
+| --- | ---: | ---: | ---: |
+| `src/events/types.ts` | 14 | 1 | 7.1% |
+| `src/types/mc-version.ts` | 11 | 2 | 18.2% |
+| `src/lir/lower.ts` | 66 | 39 | 59.1% |
+| `src/optimizer/interprocedural.ts` | 55 | 37 | 67.3% |
+| `src/optimizer/unroll.ts` | 118 | 83 | 70.3% |
+| `src/optimizer/copy_prop.ts` | 49 | 36 | 73.5% |
+| `src/tuner/engine.ts` | 36 | 27 | 75.0% |
+| `src/optimizer/coroutine.ts` | 190 | 148 | 77.9% |
+| `src/mc-validator/index.ts` | 122 | 96 | 78.7% |
+| `src/optimizer/lir/dead_slot.ts` | 37 | 30 | 81.1% |
+| `src/mir/verify.ts` | 64 | 52 | 81.2% |
+| `src/lexer/index.ts` | 185 | 156 | 84.3% |
+
+## Highest-Value Uncovered Branches
+
+Priority is based on a mix of branch count, centrality in the compile pipeline, and risk of silent miscompilation.
+
+### P1: `src/lir/lower.ts`
+
+Why it matters:
+
+- Core MIR -> LIR lowering stage.
+- Misses 27 of 66 branches.
+- Bugs here can silently generate wrong commands across many features.
+
+Most likely missing branch families from source review:
+
+- Dynamic NBT read/write helper paths and helper reuse.
+- Multi-predecessor block extraction and on-demand block function generation.
+- `cmp` lowering differences, especially `ne` vs non-`ne`.
+- `score_write` const vs temp source paths.
+- Early-return guard paths like missing block / already-visited block.
+
+Best next tests:
+
+- MIR fixtures with dynamic array read/write on multiple arrays to exercise helper cache hit and miss.
+- CFG with shared join blocks to force `multiPredBlocks` handling.
+- Comparison cases covering `eq`, `ne`, `<`, `<=`, `>`, `>=`.
+- `score_write` using both immediate constants and temp operands.
+
+### P1: `src/optimizer/coroutine.ts`
+
+Why it matters:
+
+- Large surface area: 42 missed branches.
+- Complex state-machine transform where regressions are hard to detect by inspection.
+
+Most likely missing branch families:
+
+- Back-edge absent path vs real loop path.
+- Macro/raw interpolation skip logic in `fnContainsMacroCalls`.
+- Dominator / predecessor corner cases with unusual CFGs.
+- Continuation partitioning and dispatcher generation for irregular loop shapes.
+
+Best next tests:
+
+- Coroutine candidates containing raw builtins and interpolated `__raw:` calls that should be skipped.
+- Functions with multiple back edges / nested loops / disconnected predecessor shapes.
+- Cases where a coroutine annotation targets a function that cannot be transformed cleanly but should degrade safely.
+
+### P1: `src/mc-validator/index.ts`
+
+Why it matters:
+
+- User-facing validation layer.
+- Misses 26 of 122 branches.
+- Good ROI because each new test is cheap and branch-heavy.
+
+Most likely missing branch families:
+
+- `execute ... run ...` malformed placements.
+- `scoreboard players` action-specific arity failures.
+- Unsupported `data` target/mode combinations.
+- `return run` vs integer return validation.
+- Brigadier tree fallback / redirect traversal edge cases.
+
+Best next tests:
+
+- Table-driven invalid command cases for each specialized validator.
+- Redirect-heavy commands and partial-token failures to stress `walk()`.
+
+### P2: `src/optimizer/interprocedural.ts`
+
+Why it matters:
+
+- Misses 18 of 55 branches.
+- This pass changes call graph shape; mistakes can create wrong specialization or missed optimization.
+
+Most likely missing branch families:
+
+- Skip specialization when callee missing, macro, direct recursion, self-recursive, arity mismatch, or multi-block.
+- Rewrite pass when specialized target exists vs does not exist.
+- Negative constant mangling and mixed constant signatures.
+
+Best next tests:
+
+- A matrix of `call` sites that individually trigger each skip condition.
+- A module where one pass creates a specialization and a later pass rewrites downstream call sites to it.
+
+### P2: `src/optimizer/unroll.ts`
+
+Why it matters:
+
+- Misses 35 of 118 branches.
+- Optimization pass, so lower product risk than lowering/validation, but still meaningful.
+
+Most likely missing branch families:
+
+- Rejection paths in loop recognition.
+- Pre-header detection failures.
+- Latch increment pattern variants.
+- Non-zero / negative / over-limit bounds.
+- Substitution coverage for `call_macro`, `return null`, `branch`, and dynamic NBT write cases.
+
+Best next tests:
+
+- Synthetic MIR loops that fail one recognition predicate at a time.
+- Bodies containing `call_macro`, null returns, and dynamic writes so substitution paths execute.
+
+## Lower-Priority Low-Percent Files
+
+These percentages look bad, but they are smaller and lower leverage than the pipeline/core modules above.
+
+- `src/events/types.ts` (7.1%): likely missing negative parsing and `toTypeNode()` variants. Easy to improve, low risk.
+- `src/types/mc-version.ts` (18.2%): mostly invalid-format parsing branches. Easy win, but limited impact.
+- `src/tuner/engine.ts` (75.0%): moderate branch gaps, but isolated from compiler correctness.
+- `src/optimizer/copy_prop.ts` (73.5%): worth improving after lowering / validator / specialization work.
+
+## Recommended Order
+
+1. `src/lir/lower.ts`
+2. `src/mc-validator/index.ts`
+3. `src/optimizer/coroutine.ts`
+4. `src/optimizer/interprocedural.ts`
+5. `src/optimizer/unroll.ts`
+6. `src/optimizer/copy_prop.ts`
+7. Small cleanup wins: `src/events/types.ts`, `src/types/mc-version.ts`
+
+## Notes
+
+- The worktree is not clean. Existing changes were present in `src/ast/types.ts`, `src/lexer/index.ts`, `src/parser/index.ts`, and `examples/rpg/`.
+- The failing `compile-all` cases are very likely tied to the new `examples/rpg/` files currently in the worktree.

package/dist/src/__tests__/budget.test.js

@@ -20,6 +20,10 @@ function mkModule(functions) {
 // Unit tests: estimateCommandCount
 // ---------------------------------------------------------------------------
 describe('estimateCommandCount', () => {
+    test('missing function returns 0', () => {
+        const mod = mkModule([mkFn('main', [])]);
+        expect((0, budget_1.estimateCommandCount)('missing', mod)).toBe(0);
+    });
     test('flat function — counts each instruction as 1', () => {
         const fn = mkFn('simple', [
             { kind: 'score_set', dst: slot('$x'), value: 0 },

package/dist/src/__tests__/cache/cache-behavior.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * cache-behavior.test.ts
+ *
+ * Focused tests for cache behavior:
+ *   - Same code compiled twice → second compile uses cache
+ *   - Modified code → cache invalidation
+ *   - stdlib / shared module caching
+ *   - Edge cases to push src/cache/ coverage > 85%
+ */
+export {};