@smoothbricks/lmao 0.1.0

package/src/lib/tracers/__tests__/NoOpTracer.test.ts

@@ -0,0 +1,204 @@
+/**
+ * NoOpTracer tests
+ *
+ * Tests for the NoOpTracer class - a tracer that executes ops but
+ * produces no output (no-op lifecycle hooks).
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { createTestTracerOptions } from '../../__tests__/test-helpers.js';
+import { defineLogSchema, defineOpContext, S } from '../../defineOpContext.js';
+import { defineCodeError } from '../../result.js';
+import { NoOpTracer } from '../NoOpTracer.js';
+
+// Test schema
+const testSchema = defineLogSchema({
+  userId: S.category(),
+});
+
+// Error factory for tests
+const VALIDATION_ERROR = defineCodeError('VALIDATION_ERROR')<{ field: string }>();
+
+describe('NoOpTracer', () => {
+  describe('instantiation', () => {
+    it('should create a NoOpTracer instance', () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const tracer = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+      expect(tracer).toBeDefined();
+      expect(tracer.trace).toBeDefined();
+      expect(tracer.flush).toBeDefined();
+    });
+
+    it('should allow destructuring trace and flush', () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { trace, flush } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+      expect(typeof trace).toBe('function');
+      expect(typeof flush).toBe('function');
+    });
+  });
+
+  describe('trace execution', () => {
+    it('should execute functions and return result', async () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { trace } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      const result = await trace('test-trace', async (ctx) => {
+        ctx.tag.userId('user-123');
+        return { success: true, value: 'sync-result' };
+      });
+
+      expect(result).toEqual({ success: true, value: 'sync-result' });
+    });
+
+    it('should execute async functions and return result', async () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { trace } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      const result = await trace('test-trace', async (ctx) => {
+        await Promise.resolve();
+        ctx.tag.userId('user-456');
+        return 'async-result';
+      });
+
+      expect(result).toBe('async-result');
+    });
+
+    it('should propagate exceptions from traced functions', async () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { trace } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      await expect(
+        trace('test-trace', async () => {
+          throw new Error('test-error');
+        }),
+      ).rejects.toThrow('test-error');
+    });
+
+    it('should support nested spans', async () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { defineOp } = ctx;
+      const { trace } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      const childOp = defineOp('child', (ctx) => {
+        return ctx.ok('child-done');
+      });
+
+      const result = await trace('parent-trace', async (ctx) => {
+        const childResult = await ctx.span('child-span', childOp);
+        expect(childResult.success).toBe(true);
+        return 'parent-done';
+      });
+
+      expect(result).toBe('parent-done');
+    });
+  });
+
+  describe('flush', () => {
+    it('should be a no-op that returns resolved promise', async () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { flush } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      // Should not throw, should resolve immediately
+      await expect(flush()).resolves.toBeUndefined();
+    });
+
+    it('should clear pending buffers without processing', async () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { trace, flush } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      // Create a trace
+      await trace('test-trace', async () => {
+        return 'done';
+      });
+
+      // Flush should clear without doing anything
+      await flush();
+    });
+  });
+
+  describe('lifecycle hooks', () => {
+    it('should not throw when hooks are called (they are no-ops)', async () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { defineOp } = ctx;
+      const { trace } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      const childOp1 = defineOp('c1', (c) => c.ok(1));
+      const childOp2 = defineOp('c2', (c) => c.ok(2));
+
+      // Should complete without any errors
+      const result = await trace('test-trace', async (ctx) => {
+        // Create multiple nested spans to trigger all hooks
+        await ctx.span('child1', childOp1);
+        await ctx.span('child2', childOp2);
+        return 'done';
+      });
+
+      expect(result).toBe('done');
+    });
+  });
+
+  describe('use cases', () => {
+    it('should work for tests that do not need trace inspection', async () => {
+      // This demonstrates using NoOpTracer for testing business logic
+      // without caring about trace output
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { trace } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      const result = await trace('math-test', async () => {
+        return 2 + 2;
+      });
+
+      expect(result).toBe(4);
+    });
+
+    it('should support ctx.ok() for successful results', async () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { defineOp } = ctx;
+      const { trace } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      const successOp = defineOp('success', (ctx) => {
+        return ctx.ok({ status: 'success' });
+      });
+
+      const result = await trace('ok-test', successOp);
+      expect(result.success).toBe(true);
+    });
+
+    it('should support ctx.err() for error results', async () => {
+      const ctx = defineOpContext({
+        logSchema: testSchema,
+      });
+      const { defineOp } = ctx;
+      const { trace } = new NoOpTracer(ctx, { ...createTestTracerOptions() });
+
+      const failingOp = defineOp('failing', (ctx) => {
+        return ctx.err(VALIDATION_ERROR({ field: 'email' }));
+      });
+
+      const result = await trace('err-test', failingOp);
+      expect(result.success).toBe(false);
+    });
+  });
+});

package/src/lib/tracers/__tests__/StdioTracer.test.ts

@@ -0,0 +1,313 @@
+/**
+ * StdioTracer tests
+ *
+ * Tests for the StdioTracer class - a tracer that prints spans to stdout/stderr
+ * with color-coded trace IDs, indentation, and human-readable formatting.
+ */
+
+// Configure Node.js timestamp implementation - MUST be first import
+import '../../__tests__/test-helpers.js';
+
+import { describe, expect, it } from 'bun:test';
+import { Writable } from 'node:stream';
+import { createTestTracerOptions } from '../../__tests__/test-helpers.js';
+import { defineOpContext } from '../../defineOpContext.js';
+import { defineCodeError } from '../../result.js';
+import { S } from '../../schema/builder.js';
+import { defineLogSchema } from '../../schema/defineLogSchema.js';
+import { StdioTracer, type StdioWritable } from '../StdioTracer.js';
+
+// Error code factory for tests
+const TEST_ERROR = defineCodeError('CODE')<{ message: string }>();
+
+type MockStream = { stream: StdioWritable; output: string[] };
+
+// Create a mock writable stream that captures output
+function createMockStream(): MockStream {
+  const output: string[] = [];
+  const writable = new Writable({
+    write(chunk, _encoding, callback) {
+      output.push(chunk.toString());
+      callback();
+    },
+  });
+  const stream: StdioWritable = {
+    write(chunk: string): boolean {
+      return writable.write(chunk);
+    },
+  };
+  return { stream, output };
+}
+
+describe('StdioTracer', () => {
+  const testSchema = defineLogSchema({
+    userId: S.category(),
+  });
+
+  const ctx = defineOpContext({
+    logSchema: testSchema,
+  });
+  const { defineOp } = ctx;
+
+  describe('basic output', () => {
+    it('should write trace start and end to stdout', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+      await trace('my-trace', testOp);
+
+      // Should have trace start and trace end lines
+      expect(output.length).toBeGreaterThanOrEqual(2);
+      expect(output.some((line) => line.includes('my-trace'))).toBe(true);
+    });
+
+    it('should include trace_id in output', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+      await trace('id-test', testOp);
+
+      // trace_id is W3C format (32 hex chars), should appear in brackets
+      expect(output.some((line) => /\[[a-f0-9]{32}\]/.test(line))).toBe(true);
+    });
+
+    it('should include timestamp in output', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+      await trace('ts-test', testOp);
+
+      // ISO timestamp format
+      expect(output.some((line) => /\d{4}-\d{2}-\d{2}T/.test(line))).toBe(true);
+    });
+
+    it('should render log message templates using row values', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => {
+        ctx.log.info('Processing {{userId}}').userId('u-123');
+        return ctx.ok('done');
+      });
+
+      await trace('format-test', testOp);
+
+      expect(output.some((line) => line.includes('INFO Processing u-123'))).toBe(true);
+    });
+  });
+
+  describe('nested spans with indentation', () => {
+    it('should indent child spans', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const childOp = defineOp('child', (ctx) => ctx.ok('c'));
+      const parentOp = defineOp('parent', async (ctx) => {
+        await ctx.span('child-span', childOp);
+        return ctx.ok('p');
+      });
+
+      await trace('root', parentOp);
+
+      // Find lines with child-span - should have indentation
+      const childLines = output.filter((line) => line.includes('child-span'));
+      expect(childLines.length).toBeGreaterThan(0);
+
+      // Child lines should have leading spaces (indentation)
+      const hasIndent = childLines.some((line) => /\s{2,}.*child-span/.test(line));
+      expect(hasIndent).toBe(true);
+    });
+
+    it('should use tree characters (├─ and └─)', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const childOp = defineOp('child', (ctx) => ctx.ok('c'));
+      const parentOp = defineOp('parent', async (ctx) => {
+        await ctx.span('tree-child', childOp);
+        return ctx.ok('p');
+      });
+
+      await trace('tree-root', parentOp);
+
+      // Should have tree branch characters
+      const hasStartBranch = output.some((line) => line.includes('├─'));
+      const hasEndBranch = output.some((line) => line.includes('└─'));
+
+      expect(hasStartBranch).toBe(true);
+      expect(hasEndBranch).toBe(true);
+    });
+  });
+
+  describe('status indicators', () => {
+    it('should show [OK] for successful spans', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+      await trace('ok-test', testOp);
+
+      expect(output.some((line) => line.includes('[OK]'))).toBe(true);
+    });
+
+    it('should show [ERR] for ctx.err() results', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.err(TEST_ERROR({ message: 'error' })));
+      await trace('err-test', testOp);
+
+      expect(output.some((line) => line.includes('[ERR]'))).toBe(true);
+    });
+
+    it('should show [EXCEPTION] and write to stderr for thrown errors', async () => {
+      const { stream: out, output: stdout } = createMockStream();
+      const { stream: err, output: stderr } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const failOp = defineOp('fail', async () => {
+        throw new Error('boom');
+      });
+
+      await expect(trace('exception-test', failOp)).rejects.toThrow('boom');
+
+      // EXCEPTION should go to stderr for child spans
+      // But root trace might go to stdout
+      const allOutput = [...stdout, ...stderr];
+      expect(allOutput.some((line) => line.includes('[EXCEPTION]') || line.includes('EXCEPTION'))).toBe(true);
+    });
+  });
+
+  describe('duration formatting', () => {
+    it('should include duration in span end output', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', async (ctx) => {
+        await new Promise((r) => setTimeout(r, 10)); // Small delay
+        return ctx.ok('done');
+      });
+
+      await trace('duration-test', testOp);
+
+      // Should have duration with unit (ms, µs, ns, or s)
+      expect(output.some((line) => /\(\d+\.\d+(?:s|ms|µs|ns)\)/.test(line))).toBe(true);
+    });
+  });
+
+  describe('concurrent trace isolation', () => {
+    it('should track indent per trace_id for concurrent traces', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const childOp = defineOp('child', async (ctx) => {
+        await new Promise((r) => setTimeout(r, 5));
+        return ctx.ok('c');
+      });
+
+      const parentOp = defineOp('parent', async (ctx) => {
+        await ctx.span('nested', childOp);
+        return ctx.ok('p');
+      });
+
+      // Run two traces concurrently
+      await Promise.all([trace('trace-A', parentOp), trace('trace-B', parentOp)]);
+
+      // Both traces should complete without corrupted indentation
+      // This is hard to assert precisely, but at minimum both should appear
+      expect(output.some((line) => line.includes('trace-A'))).toBe(true);
+      expect(output.some((line) => line.includes('trace-B'))).toBe(true);
+    });
+  });
+
+  describe('color support', () => {
+    it('should include ANSI color codes when enabled', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      // Enable colors
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: true });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+      await trace('color-test', testOp);
+
+      // Should have ANSI escape codes (ESC character followed by [<number>m)
+      const hasAnsi = output.some((line) => {
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: Testing for ANSI escape sequences
+        return /\u001b\[\d+m/.test(line);
+      });
+      expect(hasAnsi).toBe(true);
+    });
+
+    it('should not include ANSI codes when colors disabled', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      // Disable colors
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+      await trace('no-color-test', testOp);
+
+      // Should NOT have ANSI escape codes
+      const hasAnsi = output.some((line) => {
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: Testing for ANSI escape sequences
+        return /\u001b\[\d+m/.test(line);
+      });
+      expect(hasAnsi).toBe(false);
+    });
+  });
+
+  describe('separator line', () => {
+    it('should print separator line at trace end', async () => {
+      const { stream: out, output } = createMockStream();
+      const { stream: err } = createMockStream();
+
+      const tracer = new StdioTracer(ctx, { ...createTestTracerOptions(), out, err, colorEnabled: false });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+      await trace('sep-test', testOp);
+
+      // Should have line of = characters
+      expect(output.some((line) => /={10,}/.test(line))).toBe(true);
+    });
+  });
+});