@pyreon/reactivity 0.23.0 → 0.24.0

package/src/tests/lpih-source-location.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Live Program Inlay Hints — source-location capture for signal/computed/effect.
+ *
+ * Validates that:
+ *   1. When devtools is INACTIVE, no stack capture happens (zero cost).
+ *   2. When devtools is ACTIVE, every reactive creation captures the
+ *      USER's call site (not the framework's internal frames).
+ *   3. `getFireSummaries()` aggregates fires by location with the right
+ *      shape (count, lastFire, kind) and dedupes multiple nodes at the
+ *      same location.
+ *   4. Stack-line parsing handles V8, JSC, and Firefox formats.
+ *   5. `loc` field on `ReactiveNode` is surfaced via `getReactiveGraph()`.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { computed } from '../computed'
+import { effect } from '../effect'
+import {
+  _captureCallerLocation,
+  _parseStackLine,
+  activateReactiveDevtools,
+  deactivateReactiveDevtools,
+  getFireSummaries,
+  getReactiveGraph,
+} from '../reactive-devtools'
+import { signal } from '../signal'
+
+afterEach(() => {
+  deactivateReactiveDevtools()
+})
+
+describe('LPIH — stack-line parser', () => {
+  it('parses V8 parenthesized form', () => {
+    const loc = _parseStackLine(
+      '    at userCode (/Users/test/app.ts:42:7)',
+    )
+    expect(loc).toEqual({ file: '/Users/test/app.ts', line: 42, col: 7 })
+  })
+
+  it('parses V8 anonymous form', () => {
+    const loc = _parseStackLine('    at /Users/test/app.ts:42:7')
+    expect(loc).toEqual({ file: '/Users/test/app.ts', line: 42, col: 7 })
+  })
+
+  it('parses JSC / SpiderMonkey form', () => {
+    const loc = _parseStackLine('userCode@/Users/test/app.ts:42:7')
+    expect(loc).toEqual({ file: '/Users/test/app.ts', line: 42, col: 7 })
+  })
+
+  it('returns undefined for unparseable lines', () => {
+    expect(_parseStackLine('garbage')).toBeUndefined()
+    expect(_parseStackLine('')).toBeUndefined()
+  })
+
+  it('handles file paths with colons (Windows-like or URL schemes)', () => {
+    const loc = _parseStackLine(
+      '    at userCode (file:///Users/test/app.ts:42:7)',
+    )
+    // The regex captures the LAST ":line:col" pair — `file` includes any
+    // earlier colons (file:/// prefix preserved). Editors handle that.
+    expect(loc?.line).toBe(42)
+    expect(loc?.col).toBe(7)
+    expect(loc?.file).toContain('app.ts')
+  })
+})
+
+describe('LPIH — zero-cost when inactive', () => {
+  it('_captureCallerLocation returns undefined when inactive', () => {
+    expect(_captureCallerLocation(0)).toBeUndefined()
+    expect(_captureCallerLocation(5)).toBeUndefined()
+  })
+
+  it('node creation does not allocate Error when inactive', () => {
+    // Indirect proof: capture happens INSIDE the active guard.
+    // No throw, no stack, no observable cost in the path.
+    const s = signal(0)
+    s.set(1)
+    const c = computed(() => s() + 1)
+    c()
+    // No nodes registered because inactive.
+    expect(getReactiveGraph().nodes).toEqual([])
+  })
+})
+
+describe('LPIH — __sourceLocation option (R4 build-time injection)', () => {
+  it('signal() prefers __sourceLocation over stack capture', () => {
+    activateReactiveDevtools()
+    // Simulate what @pyreon/vite-plugin's injectSignalNames emits:
+    const injected = { file: '/some/build/path.tsx', line: 99, col: 42 }
+    const s = signal(0, { name: 'test', __sourceLocation: injected })
+    const nodes = getReactiveGraph().nodes
+    expect(nodes).toHaveLength(1)
+    // The captured location is the INJECTED one, not the test file's location.
+    expect(nodes[0]?.loc?.file).toBe('/some/build/path.tsx')
+    expect(nodes[0]?.loc?.line).toBe(99)
+    expect(nodes[0]?.loc?.col).toBe(42)
+    void s
+  })
+
+  it('signal() falls back to stack capture when __sourceLocation is absent', () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    const nodes = getReactiveGraph().nodes
+    expect(nodes).toHaveLength(1)
+    // Stack capture → location is the test file.
+    expect(nodes[0]?.loc?.file).toContain('lpih-source-location.test.ts')
+    void s
+  })
+})
+
+describe('LPIH — source-location capture for signals', () => {
+  it('captures the user call site for signal()', () => {
+    activateReactiveDevtools()
+    const s = signal(0) // ← this line
+    const nodes = getReactiveGraph().nodes
+    expect(nodes).toHaveLength(1)
+    expect(nodes[0]?.loc).toBeDefined()
+    expect(nodes[0]?.loc?.file).toContain('lpih-source-location.test.ts')
+    // The line number should point at THIS source file, not signal.ts internals.
+    expect(nodes[0]?.loc?.line).toBeGreaterThan(0)
+    void s
+  })
+
+  it('different signals get different locations', () => {
+    activateReactiveDevtools()
+    const a = signal(0)
+    const b = signal(0)
+    const nodes = getReactiveGraph().nodes
+    expect(nodes).toHaveLength(2)
+    const lineA = nodes[0]?.loc?.line
+    const lineB = nodes[1]?.loc?.line
+    expect(lineA).toBeDefined()
+    expect(lineB).toBeDefined()
+    expect(lineA).not.toBe(lineB)
+    void a
+    void b
+  })
+})
+
+describe('LPIH — source-location capture for computed', () => {
+  it('captures the user call site for computed()', () => {
+    activateReactiveDevtools()
+    const s = signal(1)
+    const c = computed(() => s() * 2) // ← user site
+    c()
+    const nodes = getReactiveGraph().nodes
+    const derived = nodes.find((n) => n.kind === 'derived')
+    expect(derived?.loc).toBeDefined()
+    expect(derived?.loc?.file).toContain('lpih-source-location.test.ts')
+  })
+})
+
+describe('LPIH — source-location capture for effect', () => {
+  it('captures the user call site for effect()', () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    const e = effect(() => {
+      s()
+    })
+    const nodes = getReactiveGraph().nodes
+    const eff = nodes.find((n) => n.kind === 'effect')
+    expect(eff?.loc).toBeDefined()
+    expect(eff?.loc?.file).toContain('lpih-source-location.test.ts')
+    e.dispose()
+  })
+})
+
+describe('LPIH — getFireSummaries()', () => {
+  it('returns empty when no nodes have locations', () => {
+    activateReactiveDevtools()
+    // No creations yet
+    expect(getFireSummaries()).toEqual([])
+  })
+
+  it('aggregates fires by location', () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    s.set(1)
+    s.set(2)
+    s.set(3)
+    const summaries = getFireSummaries()
+    expect(summaries).toHaveLength(1)
+    expect(summaries[0]?.count).toBe(3)
+    expect(summaries[0]?.kind).toBe('signal')
+    expect(summaries[0]?.lastFire).not.toBeNull()
+    expect(summaries[0]?.loc.file).toContain('lpih-source-location.test.ts')
+    void s
+  })
+
+  it('produces one summary per unique location', () => {
+    activateReactiveDevtools()
+    const a = signal(0)
+    const b = signal(0)
+    a.set(1)
+    a.set(2)
+    b.set(1)
+    const summaries = getFireSummaries()
+    expect(summaries).toHaveLength(2)
+    const total = summaries.reduce((acc, s) => acc + s.count, 0)
+    expect(total).toBe(3)
+    void a
+    void b
+  })
+
+  it('captures fires across signal + computed + effect', () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    const c = computed(() => s() * 2)
+    let observed = 0
+    const e = effect(() => {
+      observed = c()
+    })
+    s.set(5)
+    s.set(10)
+    const summaries = getFireSummaries()
+    // Expect at least 3 distinct locations (signal, computed, effect).
+    expect(summaries.length).toBeGreaterThanOrEqual(3)
+    const kinds = new Set(summaries.map((sum) => sum.kind))
+    expect(kinds.has('signal')).toBe(true)
+    expect(kinds.has('derived')).toBe(true)
+    expect(kinds.has('effect')).toBe(true)
+    expect(observed).toBe(20)
+    e.dispose()
+  })
+})
+
+describe('LPIH — rate1s EWMA tracking', () => {
+  it('rate1s is 0 for a node that has not fired', () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    const summaries = getFireSummaries()
+    // Signal was created but never written → rate1s = 0
+    const summary = summaries.find((x) => x.kind === 'signal')
+    expect(summary?.rate1s).toBe(0)
+    void s
+  })
+
+  it('rate1s rises with rapid fires', () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    for (let i = 0; i < 10; i++) s.set(i + 1)
+    const summaries = getFireSummaries()
+    const summary = summaries.find((x) => x.kind === 'signal')
+    expect(summary?.rate1s).toBeGreaterThan(0)
+    void s
+  })
+
+  it('rate1s for many rapid fires reflects fire density (>1)', () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    // 100 fires in rapid succession — dt → 0, decay ≈ 1.0, so each fire
+    // adds ~+1 to rate1s. At read time the value is decayed by the small
+    // elapsed time → still well above the threshold.
+    for (let i = 0; i < 100; i++) s.set(i + 1)
+    const summaries = getFireSummaries()
+    const summary = summaries.find((x) => x.kind === 'signal')
+    expect(summary?.rate1s).toBeGreaterThan(10)
+    void s
+  })
+
+  it('rate1s decays to ≈0 after the time constant elapses', async () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    s.set(1)
+    const initial = getFireSummaries().find((x) => x.kind === 'signal')
+    expect(initial?.rate1s).toBeGreaterThan(0.5)
+    // 1.5s = 1.5× TAU → rate1s should drop to exp(-1.5) ≈ 0.22× initial.
+    await new Promise((r) => setTimeout(r, 1500))
+    const decayed = getFireSummaries().find((x) => x.kind === 'signal')
+    expect(decayed?.rate1s).toBeLessThan(0.5)
+    void s
+  })
+
+  it('exported LPIH_RATE_TAU_MS constant equals 1000 (1 second)', async () => {
+    const { LPIH_RATE_TAU_MS } = await import('../reactive-devtools')
+    expect(LPIH_RATE_TAU_MS).toBe(1000)
+  })
+})

package/src/tests/lpih.test.ts

@@ -0,0 +1,351 @@
+/**
+ * LPIH runtime bridge — `writeLpihCache` + `startLpihPolling` tests.
+ *
+ * Proves the filesystem cache contract:
+ *   1. Atomic write (tmp + rename, never half-written)
+ *   2. Empty payload when devtools inactive
+ *   3. Real fire data when devtools active + signals firing
+ *   4. Polling helper writes repeatedly + disposer stops it
+ */
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest'
+import { computed } from '../computed'
+import { effect } from '../effect'
+import {
+  LPIH_DEFAULT_FILENAME,
+  getDefaultLpihCachePath,
+  startLpihPolling,
+  writeLpihCache,
+} from '../lpih'
+import {
+  activateReactiveDevtools,
+  deactivateReactiveDevtools,
+} from '../reactive-devtools'
+import { signal } from '../signal'
+
+let TMP_DIR: string
+
+beforeAll(() => {
+  TMP_DIR = mkdtempSync(join(tmpdir(), 'lpih-test-'))
+})
+
+afterAll(() => {
+  rmSync(TMP_DIR, { recursive: true, force: true })
+})
+
+beforeEach(() => {
+  deactivateReactiveDevtools()
+})
+
+afterEach(() => {
+  deactivateReactiveDevtools()
+})
+
+const readCache = (path: string): { fires: unknown[] } =>
+  JSON.parse(readFileSync(path, 'utf8')) as { fires: unknown[] }
+
+describe('writeLpihCache', () => {
+  it('writes an empty payload when devtools is inactive', async () => {
+    const path = join(TMP_DIR, 'inactive.json')
+    const count = await writeLpihCache(path)
+    expect(count).toBe(0)
+    const parsed = readCache(path)
+    expect(parsed.fires).toEqual([])
+  })
+
+  it('writes real fire data when devtools is active', async () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    s.set(1)
+    s.set(2)
+    s.set(3)
+    const path = join(TMP_DIR, 'active.json')
+    const count = await writeLpihCache(path)
+    expect(count).toBe(1) // one source location
+    const parsed = readCache(path) as {
+      fires: Array<{ file: string; line: number; count: number; kind: string }>
+    }
+    expect(parsed.fires).toHaveLength(1)
+    expect(parsed.fires[0]?.count).toBe(3)
+    expect(parsed.fires[0]?.kind).toBe('signal')
+    expect(parsed.fires[0]?.file).toContain('lpih.test.ts')
+    void s
+  })
+
+  it('captures signal + computed + effect locations', async () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    const c = computed(() => s() * 2)
+    const e = effect(() => {
+      c()
+    })
+    s.set(5)
+    s.set(10)
+    const path = join(TMP_DIR, 'multi.json')
+    await writeLpihCache(path)
+    const parsed = readCache(path) as {
+      fires: Array<{ kind: string; count: number }>
+    }
+    const kinds = new Set(parsed.fires.map((f) => f.kind))
+    expect(kinds.has('signal')).toBe(true)
+    expect(kinds.has('effect')).toBe(true)
+    // derived may show up as 'native:1' under bun's compiled inline callbacks
+    e.dispose()
+  })
+
+  it('overwrites existing file (atomic rename semantics)', async () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    const path = join(TMP_DIR, 'overwrite.json')
+
+    s.set(1)
+    await writeLpihCache(path)
+    const before = readCache(path) as { fires: Array<{ count: number }> }
+    expect(before.fires[0]?.count).toBe(1)
+
+    s.set(2)
+    s.set(3)
+    await writeLpihCache(path)
+    const after = readCache(path) as { fires: Array<{ count: number }> }
+    expect(after.fires[0]?.count).toBe(3) // updated count
+    void s
+  })
+
+  it('leaves no tmp files after successful write', async () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    s.set(1)
+    const path = join(TMP_DIR, 'no-tmp.json')
+    await writeLpihCache(path)
+    const fs = await import('node:fs/promises')
+    const files = await fs.readdir(TMP_DIR)
+    const tmpFiles = files.filter((f) => f.includes('.tmp.'))
+    expect(tmpFiles).toEqual([]) // tmp file should be renamed away
+    void s
+  })
+})
+
+describe('writeLpihCache — defensive cleanup', () => {
+  it('cleans up tmp file when rename fails (target is a directory)', async () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    s.set(1)
+    // Build a path whose target IS a directory — rename onto a directory
+    // throws EISDIR (POSIX) / EPERM (Windows). The tmp file should be
+    // unlinked even though writeLpihCache rethrows.
+    const targetDir = join(TMP_DIR, 'target-as-dir')
+    const fs = await import('node:fs/promises')
+    await fs.mkdir(targetDir, { recursive: true })
+
+    await expect(writeLpihCache(targetDir)).rejects.toBeDefined()
+
+    // No tmp file should be left behind in TMP_DIR.
+    const files = await fs.readdir(TMP_DIR)
+    const tmpFiles = files.filter(
+      (f) => f.startsWith('target-as-dir.tmp.') || f.includes('.tmp.'),
+    )
+    expect(tmpFiles).toEqual([])
+    void s
+  })
+
+  it('cleans up tmp file even when unlink fallback fails silently', async () => {
+    // This is the harder case: we want to assert the cleanup runs without
+    // letting an unlink-failure leak as the user-visible error. We can't
+    // easily make unlink fail in a portable way, but the code path is
+    // covered by the try/catch — verify the behavior: rejecting with the
+    // ORIGINAL rename error, never the unlink one.
+    activateReactiveDevtools()
+    const s = signal(0)
+    s.set(1)
+    const targetDir = join(TMP_DIR, 'silent-unlink')
+    const fs = await import('node:fs/promises')
+    await fs.mkdir(targetDir, { recursive: true })
+    try {
+      await writeLpihCache(targetDir)
+      expect.fail('should have rejected')
+    } catch (err) {
+      // The error message should reference the rename failure, NOT the
+      // unlink fallback — proof we prioritize the original error.
+      const code = (err as { code?: string }).code
+      expect(['EISDIR', 'EPERM', 'EACCES']).toContain(code)
+    }
+    void s
+  })
+})
+
+describe('startLpihPolling', () => {
+  it('timer is unref()d so polling does not block process exit', async () => {
+    activateReactiveDevtools()
+    const path = join(TMP_DIR, 'unref-check.json')
+    const dispose = startLpihPolling(path, 50)
+    // Wait one tick so the timer is actually scheduled.
+    await new Promise((r) => setTimeout(r, 100))
+    // Indirect check: the polling timer is internal, but we can verify
+    // the disposer stops cleanly without hanging. If unref() weren't
+    // applied, this test could still pass (since vitest holds the loop
+    // open) — the bisect test is "test runs at all without timing out",
+    // which is the load-bearing behavior.
+    dispose()
+    // After dispose, an in-flight async write may still be completing.
+    // Wait long enough for that to settle BEFORE the stat1 baseline,
+    // otherwise stat1 captures a stale mtime and stat2 sees the late
+    // write, racing the assertion. Slower CI runners trip this without
+    // the buffer.
+    const fs = await import('node:fs/promises')
+    await new Promise((r) => setTimeout(r, 100))
+    const stat1 = await fs.stat(path)
+    // Verify no NEW writes happen post-dispose + post-flush.
+    await new Promise((r) => setTimeout(r, 200))
+    const stat2 = await fs.stat(path)
+    expect(stat2.mtimeMs).toBe(stat1.mtimeMs)
+  })
+
+  it('writes repeatedly + disposer stops it', async () => {
+    activateReactiveDevtools()
+    const s = signal(0)
+    const path = join(TMP_DIR, 'polling.json')
+    const dispose = startLpihPolling(path, 50)
+
+    // Wait for at least 3 polls (150ms expected).
+    await new Promise((r) => setTimeout(r, 200))
+    s.set(1)
+    s.set(2)
+    await new Promise((r) => setTimeout(r, 100))
+
+    dispose()
+    const fs = await import('node:fs/promises')
+    const before = await fs.stat(path)
+
+    // After dispose, no new writes for 200ms.
+    await new Promise((r) => setTimeout(r, 200))
+    const after = await fs.stat(path)
+    expect(after.mtimeMs).toBe(before.mtimeMs) // mtime unchanged after dispose
+    void s
+  })
+})
+
+describe('getDefaultLpihCachePath', () => {
+  it('returns <cwd>/.pyreon-lpih.json when process.cwd is available', () => {
+    const out = getDefaultLpihCachePath()
+    expect(out).toBeTruthy()
+    expect(out).toContain(LPIH_DEFAULT_FILENAME)
+    // Should be a real cwd-rooted path
+    expect(out?.startsWith('/') || /^[A-Za-z]:/.test(out ?? '')).toBe(true)
+  })
+
+  it('exposes the canonical filename constant', () => {
+    expect(LPIH_DEFAULT_FILENAME).toBe('.pyreon-lpih.json')
+  })
+
+  it('returns null when process.cwd is unavailable (web worker fallback)', () => {
+    // Temporarily shadow process.cwd to simulate browser/worker.
+    // Cast `process` since the package's narrow type omits .cwd.
+    const proc = process as unknown as { cwd?: (() => string) | undefined }
+    const realCwd = proc.cwd
+    try {
+      delete proc.cwd
+      const out = getDefaultLpihCachePath()
+      expect(out).toBeNull()
+    } finally {
+      proc.cwd = realCwd
+    }
+  })
+})
+
+describe('writeLpihCache / startLpihPolling — default path resolution', () => {
+  it('writeLpihCache() with no arg writes to <cwd>/.pyreon-lpih.json', async () => {
+    // Move cwd to TMP_DIR so the default-path write lands somewhere
+    // we control + can clean up.
+    const fs = await import('node:fs/promises')
+    const proc = process as unknown as {
+      cwd(): string
+      chdir(p: string): void
+    }
+    const originalCwd = proc.cwd()
+    proc.chdir(TMP_DIR)
+    activateReactiveDevtools()
+    const s = signal(0)
+    s.set(1)
+    try {
+      const count = await writeLpihCache()
+      expect(count).toBe(1)
+      // Verify the file landed at the cwd-relative default location.
+      const stat = await fs.stat(join(TMP_DIR, LPIH_DEFAULT_FILENAME))
+      expect(stat.isFile()).toBe(true)
+    } finally {
+      proc.chdir(originalCwd)
+      // Best-effort cleanup
+      try {
+        await fs.unlink(join(TMP_DIR, LPIH_DEFAULT_FILENAME))
+      } catch {
+        /* */
+      }
+    }
+    void s
+  })
+
+  it('writeLpihCache(explicitPath) still honors the explicit path', async () => {
+    const fs = await import('node:fs/promises')
+    activateReactiveDevtools()
+    const s = signal(0)
+    s.set(1)
+    const explicit = join(TMP_DIR, 'explicit-override.json')
+    const count = await writeLpihCache(explicit)
+    expect(count).toBe(1)
+    const stat = await fs.stat(explicit)
+    expect(stat.isFile()).toBe(true)
+    void s
+  })
+
+  it('startLpihPolling() with no arg uses the default path', async () => {
+    const fs = await import('node:fs/promises')
+    const proc = process as unknown as {
+      cwd(): string
+      chdir(p: string): void
+    }
+    const originalCwd = proc.cwd()
+    proc.chdir(TMP_DIR)
+    activateReactiveDevtools()
+    const s = signal(0)
+    s.set(1)
+    try {
+      const dispose = startLpihPolling(undefined, 50)
+      await new Promise((r) => setTimeout(r, 150))
+      dispose()
+      const stat = await fs.stat(join(TMP_DIR, LPIH_DEFAULT_FILENAME))
+      expect(stat.isFile()).toBe(true)
+    } finally {
+      proc.chdir(originalCwd)
+      try {
+        await fs.unlink(join(TMP_DIR, LPIH_DEFAULT_FILENAME))
+      } catch {
+        /* */
+      }
+    }
+    void s
+  })
+
+  it('startLpihPolling() throws synchronously when no default + no path', () => {
+    const proc = process as unknown as { cwd?: (() => string) | undefined }
+    const realCwd = proc.cwd
+    try {
+      delete proc.cwd
+      expect(() => startLpihPolling()).toThrow(/no path provided/)
+    } finally {
+      proc.cwd = realCwd
+    }
+  })
+
+  it('writeLpihCache() rejects when no default + no path', async () => {
+    const proc = process as unknown as { cwd?: (() => string) | undefined }
+    const realCwd = proc.cwd
+    try {
+      delete proc.cwd
+      await expect(writeLpihCache()).rejects.toThrow(/no path provided/)
+    } finally {
+      proc.cwd = realCwd
+    }
+  })
+})