@bendyline/squisq 1.5.2 → 2.0.0

package/src/__tests__/asciiDiagramRepair.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import {
+  repairAsciiDiagram,
+  isRepairableDiagram,
+  detectAsciiDiagram,
+  parseAsciiDiagram,
+} from '../doc/asciiDiagram/index.js';
+import { POSITIVE_FIXTURES } from './fixtures/asciiDiagrams.js';
+
+/**
+ * Broken box art: package-name labels overflow their boxes and collide with
+ * neighbours, so the columns desync row-to-row. Conservative detection
+ * declines it (`garbled-labels`) — the opt-in repair pass reconstructs it.
+ * (A shorter second label line keeps a real `│` on one interior row, which is
+ * how real "half-broken" art still gives the tracer border evidence.)
+ */
+const BROKEN = [
+  '┌──────────┐   ┌──────────┐',
+  '│ @scope/alpha-svc  │   │ @scope/beta-svc   │',
+  '│ one      │   │ two      │',
+  '└────┬─────┘   └────┬─────┘',
+  '     │              │',
+  '     ▼              ▼',
+  '┌────────────────────────────┐',
+  '│ @scope/gamma-store         │',
+  '│ persists                   │',
+  '└────────────────────────────┘',
+].join('\n');
+
+describe('isRepairableDiagram', () => {
+  it('is true for broken box art that conservative detection declines', () => {
+    expect(detectAsciiDiagram(BROKEN).isDiagram).toBe(false);
+    expect(isRepairableDiagram(BROKEN)).toBe(true);
+  });
+
+  it('is false for a clean diagram (the canvas already handles it)', () => {
+    expect(detectAsciiDiagram(POSITIVE_FIXTURES.TWO_BOX_VERTICAL).isDiagram).toBe(true);
+    expect(isRepairableDiagram(POSITIVE_FIXTURES.TWO_BOX_VERTICAL)).toBe(false);
+  });
+
+  it('is false for non-box art (prose, file trees)', () => {
+    expect(isRepairableDiagram('just some\nplain prose\nwith no boxes')).toBe(false);
+    expect(isRepairableDiagram('src/\n├── index.ts\n└── utils/')).toBe(false);
+  });
+});
+
+describe('repairAsciiDiagram', () => {
+  it('recovers clean labels from overflowing/colliding boxes (band-segment matching)', () => {
+    const r = repairAsciiDiagram(BROKEN);
+    expect(r).not.toBeNull();
+    const firstLines = r!.diagram.nodes.map((n) => n.label.split('\n')[0]);
+    expect(firstLines).toEqual(['@scope/alpha-svc', '@scope/beta-svc', '@scope/gamma-store']);
+    // Hyphens/slashes in labels survive (they're not box-drawing chars).
+    expect(firstLines.every((l) => l.includes('/') && l.includes('-'))).toBe(true);
+  });
+
+  it('recovers the fan-in edges', () => {
+    const r = repairAsciiDiagram(BROKEN)!;
+    const edgeSet = new Set(r.diagram.edges.map((e) => `${e.source}->${e.target}`));
+    expect(edgeSet.has('scope-alpha-svc->scope-gamma-store')).toBe(true);
+    expect(edgeSet.has('scope-beta-svc->scope-gamma-store')).toBe(true);
+    // No phantom edge between the two horizontally-adjacent source boxes.
+    expect(edgeSet.has('scope-alpha-svc->scope-beta-svc')).toBe(false);
+  });
+
+  it('produces art that re-parses cleanly as a diagram (repair is a real fixpoint entry)', () => {
+    const r = repairAsciiDiagram(BROKEN)!;
+    const redetect = detectAsciiDiagram(r.art);
+    expect(redetect.isDiagram).toBe(true);
+    // Same box count, and labels are no longer garbled.
+    const reparsed = parseAsciiDiagram(r.art);
+    expect(reparsed.nodes.length).toBe(r.diagram.nodes.length);
+    expect(redetect.reasons.join(' ')).not.toMatch(/garbled/);
+  });
+
+  it('returns null when fewer than two boxes can be recovered', () => {
+    expect(repairAsciiDiagram('just prose\nno boxes here')).toBeNull();
+    expect(repairAsciiDiagram('┌───┐\n│ A │\n└───┘')).toBeNull();
+  });
+
+  it('marks the diagram as repaired', () => {
+    expect(repairAsciiDiagram(BROKEN)!.diagram.warnings).toContain('repaired');
+  });
+});

package/src/__tests__/asciiTimelineDetect.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'vitest';
+import {
+  detectAsciiTimeline,
+  isAsciiTimelineFence,
+  isEligibleAsciiTimelineFenceLang,
+  isExplicitTimelineLang,
+  renderAsciiTimeline,
+  type AsciiTimeline,
+} from '../doc/asciiTimeline/index.js';
+import { detectAsciiDiagram } from '../doc/asciiDiagram/index.js';
+import { detectTree } from '../doc/treeview/index.js';
+import type { MarkdownCodeBlock } from '../markdown/types.js';
+import {
+  MULTI_TRACK_BRANCH_TIMELINE,
+  SINGLE_POINT_ASCII_TIMELINE,
+  TICK_INTERPOLATION_TIMELINE,
+  WRAPPED_CLIENT_KERNEL_TIMELINE,
+} from './fixtures/asciiTimelines.js';
+
+describe('detectAsciiTimeline', () => {
+  it('recognizes the exact tick/interpolation example as an untagged timeline', () => {
+    const detection = detectAsciiTimeline(TICK_INTERPOLATION_TIMELINE);
+    expect(detection.isTimeline).toBe(true);
+    expect(detection.timeline?.tracks).toHaveLength(2);
+    expect(detection.reasons).toContain('strong-markers');
+  });
+
+  it('recognizes multiple tracks and an explicit branch declaration', () => {
+    const detection = detectAsciiTimeline(MULTI_TRACK_BRANCH_TIMELINE);
+    expect(detection.isTimeline).toBe(true);
+    expect(detection.timeline?.tracks).toHaveLength(2);
+    expect(detection.timeline?.links).toEqual([
+      { source: 't29', target: 'f29', label: 'interpolation path' },
+    ]);
+  });
+
+  it('conservatively recognizes a multi-lane flow with a wrapped return edge', () => {
+    const detection = detectAsciiTimeline(WRAPPED_CLIENT_KERNEL_TIMELINE);
+    expect(detection.isTimeline).toBe(true);
+    expect(detection.reasons).toContain('wrapped-flow');
+    expect(detection.timeline?.tracks).toHaveLength(2);
+    expect(detectAsciiDiagram(WRAPPED_CLIENT_KERNEL_TIMELINE).isDiagram).toBe(false);
+
+    const withoutReturn = WRAPPED_CLIENT_KERNEL_TIMELINE.replace(/┐/gu, '│').replace(/┘/gu, '│');
+    expect(detectAsciiTimeline(withoutReturn).isTimeline).toBe(false);
+  });
+
+  it('only accepts a sparse ASCII track when author intent is explicit', () => {
+    expect(detectAsciiTimeline(SINGLE_POINT_ASCII_TIMELINE).isTimeline).toBe(false);
+    const explicit = detectAsciiTimeline(SINGLE_POINT_ASCII_TIMELINE, { explicit: true });
+    expect(explicit.isTimeline).toBe(true);
+    expect(explicit.timeline?.tracks[0].events).toMatchObject([
+      { id: 'alpha', label: 'Alpha', marker: 'filled' },
+    ]);
+  });
+
+  it('accepts a cadence-only track through an explicit timeline fence', () => {
+    const cadence = 'client frames (120 Hz): f f f f f';
+    expect(detectAsciiTimeline(cadence).isTimeline).toBe(false);
+    expect(detectAsciiTimeline(cadence, { explicit: true }).isTimeline).toBe(true);
+    const fence: MarkdownCodeBlock = { type: 'code', lang: 'timeline', value: cadence };
+    expect(isAsciiTimelineFence(fence)).toBe(true);
+  });
+
+  it('keeps the exact sample mutually exclusive with tree and box-diagram codecs', () => {
+    expect(detectTree(TICK_INTERPOLATION_TIMELINE).isTree).toBe(false);
+    expect(detectAsciiDiagram(TICK_INTERPOLATION_TIMELINE).isDiagram).toBe(false);
+  });
+
+  it('does not steal a tree item whose label happens to contain a marker rail', () => {
+    const tree = ['root/', '├── ●────────● benchmark.txt', '└── notes.md'].join('\n');
+    expect(detectAsciiTimeline(tree).isTimeline).toBe(false);
+    expect(detectTree(tree).isTree).toBe(true);
+  });
+
+  it('does not steal marker rails inside deeply nested tree items', () => {
+    const tree = [
+      'root/',
+      '│   └── child/',
+      '│       └── grandchild/',
+      '│           └── ●────────● benchmark.txt',
+    ].join('\n');
+    expect(detectAsciiTimeline(tree).isTimeline).toBe(false);
+    expect(detectTree(tree).isTree).toBe(true);
+  });
+
+  it('leaves a single closed box as authored code instead of treating its top as an axis', () => {
+    const box = ['┌──●────●──┐', '│ content  │', '└──────────┘'].join('\n');
+    expect(detectAsciiTimeline(box).isTimeline).toBe(false);
+  });
+
+  it('allows a lone top elbow to act as an above-axis callout', () => {
+    const callout = ['     ┌─ warmup', '────●────●────►'].join('\n');
+    expect(detectAsciiTimeline(callout).isTimeline).toBe(true);
+  });
+
+  it('uses an inert-language allowlist and a durable explicit tag', () => {
+    for (const lang of [undefined, null, '', 'text', 'txt', 'plain', 'ascii', 'timeline']) {
+      expect(isEligibleAsciiTimelineFenceLang(lang)).toBe(true);
+    }
+    for (const lang of ['js', 'typescript', 'python', 'yaml', 'json', 'bash']) {
+      expect(isEligibleAsciiTimelineFenceLang(lang)).toBe(false);
+    }
+    for (const lang of ['timeline', ' Timeline ', 'TIMELINE']) {
+      expect(isExplicitTimelineLang(lang)).toBe(true);
+    }
+    expect(isExplicitTimelineLang('text')).toBe(false);
+  });
+
+  it('combines the language gate with explicit detection for code fences', () => {
+    const fence = (lang?: string): MarkdownCodeBlock => ({
+      type: 'code',
+      ...(lang !== undefined ? { lang } : {}),
+      value: SINGLE_POINT_ASCII_TIMELINE,
+    });
+    expect(isAsciiTimelineFence(fence())).toBe(false);
+    expect(isAsciiTimelineFence(fence('timeline'))).toBe(true);
+    expect(isAsciiTimelineFence(fence('js'))).toBe(false);
+  });
+
+  it('rejects over-wide art before running the grid parsers', () => {
+    const tooWide = `●${'─'.repeat(401)}●`;
+    expect(detectAsciiTimeline(tooWide)).toMatchObject({
+      isTimeline: false,
+      reasons: [expect.stringMatching(/^too-wide\(/)],
+    });
+  });
+
+  it('allows long canonical callout form while retaining the ordinary line cap', () => {
+    const timeline: AsciiTimeline = {
+      tracks: Array.from({ length: 150 }, (_, index) => ({
+        id: `track-${index}`,
+        label: `Track ${index}`,
+        row: index,
+        startColumn: 0,
+        endColumn: 10,
+        events: [
+          { id: `start-${index}`, label: 'Start', column: 0, side: 'above' as const },
+          { id: `end-${index}`, label: 'End', column: 10, side: 'below' as const },
+        ],
+      })),
+      links: [],
+      width: 11,
+      height: 150,
+      style: 'unicode',
+      warnings: [],
+    };
+    const canonical = renderAsciiTimeline(timeline);
+    expect(canonical.split('\n').length).toBeGreaterThan(400);
+    expect(detectAsciiTimeline(canonical, { explicit: true }).isTimeline).toBe(true);
+
+    const arbitrary = Array.from({ length: 401 }, () => '●────────●').join('\n');
+    expect(detectAsciiTimeline(arbitrary, { explicit: true }).reasons[0]).toMatch(
+      /^too-many-lines\(/,
+    );
+  });
+});

package/src/__tests__/asciiTimelineParse.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, it } from 'vitest';
+import { asciiTimelineToTemplateData, parseAsciiTimeline } from '../doc/asciiTimeline/index.js';
+import {
+  MULTI_TRACK_BRANCH_TIMELINE,
+  TICK_INTERPOLATION_TIMELINE,
+  WRAPPED_CLIENT_KERNEL_TIMELINE,
+} from './fixtures/asciiTimelines.js';
+
+describe('parseAsciiTimeline', () => {
+  it('extracts tick labels, delta callouts, and fractional pointer events from the exact sample', () => {
+    const timeline = parseAsciiTimeline(TICK_INTERPOLATION_TIMELINE);
+    expect(timeline.tracks).toHaveLength(2);
+
+    const [kernel, client] = timeline.tracks;
+    expect(kernel.label).toBe('kernel ticks (30 Hz)');
+    expect(kernel.endLabel).toBe('sim time');
+    expect(client.label).toBe('client frames (e.g. 120 Hz)');
+
+    const events = kernel.events;
+    const milestones = events.filter((event) => event.marker === 'filled');
+    expect(milestones.map((event) => event.label)).toEqual(['T28', 'T29', 'T30', 'T31']);
+    expect(milestones.map((event) => event.description)).toEqual([
+      'deltas sent: Δ28',
+      'Δ29',
+      'Δ30',
+      'Δ31',
+    ]);
+    expect(milestones.map((event) => event.side)).toEqual(['above', 'above', 'above', 'above']);
+    expect(milestones.map((event) => event.descriptionSide)).toEqual([
+      'below',
+      'below',
+      'below',
+      'below',
+    ]);
+
+    const cadence = client.events.filter((event) => event.callout === false);
+    expect(cadence).toHaveLength(16);
+    expect(cadence.every((event) => event.marker === 'hollow')).toBe(true);
+    expect(client.events).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          label: 'estimated kernel clock',
+          description: 'estTick ≈ 30.4',
+          marker: 'hollow',
+        }),
+        expect.objectContaining({
+          label: 'render position',
+          description: expect.stringContaining('interpolate between snapshot T28 and T29'),
+          marker: 'hollow',
+        }),
+      ]),
+    );
+  });
+
+  it('parses multiple tracks and resolves explicit branch declarations by stable event id', () => {
+    const timeline = parseAsciiTimeline(MULTI_TRACK_BRANCH_TIMELINE);
+    expect(timeline.tracks.map((track) => track.label)).toEqual(['Kernel', 'Client']);
+    expect(timeline.tracks.map((track) => track.events.map((event) => event.id))).toEqual([
+      ['t28', 't29'],
+      ['f28', 'f29'],
+    ]);
+    expect(timeline.links).toEqual([{ source: 't29', target: 'f29', label: 'interpolation path' }]);
+    expect(timeline.warnings).toEqual([]);
+  });
+
+  it('maps a wrapped client/kernel flow into tracks, events, and a return branch', () => {
+    const timeline = parseAsciiTimeline(WRAPPED_CLIENT_KERNEL_TIMELINE);
+    expect(timeline.warnings).toEqual([]);
+    expect(timeline.tracks.map((track) => track.label)).toEqual([
+      'CLIENT (main thread)',
+      'KERNEL (Web Worker / Node)',
+    ]);
+
+    const events = timeline.tracks.flatMap((track) => track.events);
+    expect(events.map((event) => event.label)).toEqual(
+      expect.arrayContaining([
+        'input events',
+        'InputMap',
+        'command',
+        'validate (schema)',
+        'command-rejected event',
+        'queue at tick T',
+        'dirty-tracked per-tick delta',
+        'delta {tick T}',
+        'interpolation buffer',
+        'keyframe',
+        'error surfaced to user/agent',
+      ]),
+    );
+    expect(events.find((event) => event.id === 'interpolation-buffer')?.description).toBe(
+      '(render ~1.5 ticks behind, lerp/slerp)',
+    );
+    expect(timeline.tracks[0].events.map((event) => event.id)).toEqual(
+      expect.arrayContaining(['input-events', 'inputmap', 'command', 'delta-tick-t', 'keyframe']),
+    );
+    expect(timeline.links).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ source: 'command', target: 'validate-schema' }),
+        expect.objectContaining({ source: 'dirty-tracked-per-tick-delta', target: 'delta-tick-t' }),
+        expect.objectContaining({
+          source: 'command-rejected-event',
+          target: 'error-surfaced-to-user-agent',
+        }),
+      ]),
+    );
+  });
+
+  it('normalizes every track against one shared horizontal scale', () => {
+    const timeline = parseAsciiTimeline(MULTI_TRACK_BRANCH_TIMELINE);
+    const { tracks, links } = asciiTimelineToTemplateData(timeline);
+    expect(tracks).toHaveLength(2);
+    expect(tracks[0].events.map((event) => event.position)).toEqual(
+      tracks[1].events.map((event) => event.position),
+    );
+    for (const event of tracks.flatMap((track) => track.events)) {
+      expect(event.position).toBeGreaterThanOrEqual(0);
+      expect(event.position).toBeLessThanOrEqual(1);
+    }
+    expect(links).toEqual(timeline.links);
+  });
+
+  it('is deterministic and never throws on empty or malformed input', () => {
+    expect(parseAsciiTimeline('')).toMatchObject({ tracks: [], links: [], warnings: [] });
+    expect(() => parseAsciiTimeline('not a timeline\nfunction x() {}')).not.toThrow();
+    expect(parseAsciiTimeline(MULTI_TRACK_BRANCH_TIMELINE)).toEqual(
+      parseAsciiTimeline(MULTI_TRACK_BRANCH_TIMELINE.replace(/\n/g, '\r\n')),
+    );
+  });
+
+  it('keeps prose arrows and double hyphens inside inline event descriptions', () => {
+    const timeline = parseAsciiTimeline(
+      'Flow: ● Compare :: A > B; release--candidate {#compare side=above} ───►',
+    );
+
+    expect(timeline.tracks[0].events[0]).toMatchObject({
+      id: 'compare',
+      label: 'Compare',
+      description: 'A > B; release--candidate',
+    });
+  });
+
+  it('keeps leading CLI flags, negative values, and rail-like prose in authored labels', () => {
+    const timeline = parseAsciiTimeline('Flags: ● --watch ─────● -1.5 ─────● ─phase ─────►');
+
+    expect(timeline.tracks[0].events.map((event) => event.label)).toEqual([
+      '--watch',
+      '-1.5',
+      '─phase',
+    ]);
+  });
+
+  it('keeps direct-source arrow prose, pointer offsets, and end-label punctuation', () => {
+    const arrow = parseAsciiTimeline('Flow: ●────● Result :: A -> B');
+    expect(arrow.tracks[0].events[1].description).toBe('A -> B');
+
+    const pointer = parseAsciiTimeline(['●────────●────────►', '     ▲ -1.5'].join('\n'));
+    expect(pointer.tracks[0].events.map((event) => event.label)).toContain('-1.5');
+
+    const endLabel = parseAsciiTimeline('Track: ● A ─────● B ───► --phase');
+    expect(endLabel.tracks[0].endLabel).toBe('--phase');
+  });
+
+  it('does not duplicate a suffix-only axis label at the left edge', () => {
+    const track = parseAsciiTimeline('────●────●────► sim time').tracks[0];
+    expect(track.label).toBeUndefined();
+    expect(track.endLabel).toBe('sim time');
+  });
+
+  it('promotes a cadence point when an authored elbow adds a callout', () => {
+    const timeline = parseAsciiTimeline(['Client: f f f f', '        └─ dropped frame'].join('\n'));
+    expect(timeline.tracks[0].events).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ label: 'dropped frame', callout: true, side: 'below' }),
+      ]),
+    );
+  });
+
+  it('preserves a leading minus in an elbow callout', () => {
+    const timeline = parseAsciiTimeline(['●────────●────────►', '└─-1.5'].join('\n'));
+    expect(timeline.tracks[0].events[0].description).toBe('-1.5');
+  });
+
+  it('keeps trailing prose braces when they are not timeline metadata', () => {
+    const timeline = parseAsciiTimeline('Flow: ● Deploy {phase} ───►');
+    expect(timeline.tracks[0].events[0].label).toBe('Deploy {phase}');
+  });
+
+  it('segments multiple fractional pointers on the same row', () => {
+    const timeline = parseAsciiTimeline(
+      ['●────────●────────●────────►', '  ▲ A         ▲ B'].join('\n'),
+    );
+    const pointerLabels = timeline.tracks[0].events
+      .filter((event) => event.marker === 'hollow')
+      .map((event) => event.label);
+    expect(pointerLabels).toEqual(['A', 'B']);
+  });
+
+  it('does not turn hyphenated Unicode event labels into phantom ASCII markers', () => {
+    const timeline = parseAsciiTimeline('Flow: ● Go-live {#go} ─────● Done {#done} ─────►');
+
+    expect(timeline.style).toBe('unicode');
+    expect(timeline.tracks[0].events.map((event) => event.label)).toEqual(['Go-live', 'Done']);
+    expect(timeline.tracks[0].events.map((event) => event.id)).toEqual(['go', 'done']);
+  });
+});