@miliastry/quasar 1.0.0

package/src/Analysis/Passes/Analysis/__tests__/RainbowAnalyzer.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Tests for RainbowAnalyzer
+ */
+
+import { describe, it, expect } from 'vitest'
+import { greenNode, greenLeaf } from '../../../../Syntax/GreenNode'
+import type { GreenNode } from '../../../../Syntax/GreenNode'
+import { RainbowAnalyzer } from '../RainbowAnalyzer'
+import type { PipelineContext } from '../../../Contracts/PipelineContext'
+import { PipelineMode, ExportTarget } from '../../../Contracts/PipelineContext'
+import { ContributionKind } from '../../../Contracts/Contribution'
+
+const mockContext: PipelineContext = {
+  mode: PipelineMode.Batch,
+  target: ExportTarget.Miliastry,
+  featureFlags: {},
+  metadata: {},
+}
+
+function colorNode(hex: string, text: string): GreenNode {
+  // Widths of the real BBCode this stands for: `[color=#RRGGBB]` and `[/color]`.
+  const textLeaf = greenLeaf('text', text)
+  return greenNode('color', `=${hex}`, [textLeaf], 8 + hex.length, 8)
+}
+
+describe('RainbowAnalyzer', () => {
+  it('detects a classic rainbow (hue rotation, stable S/L)', () => {
+    // Red → Yellow → Green → Cyan → Blue — classic rainbow with high S, mid L
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'R'),
+      colorNode('#FFAA00', 'A'),
+      colorNode('#FFFF00', 'Y'),
+      colorNode('#00FF00', 'G'),
+      colorNode('#00FFFF', 'C'),
+      colorNode('#0000FF', 'B'),
+      colorNode('#AA00FF', 'V'),
+    ])
+
+    const analyzer = new RainbowAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results.length).toBeGreaterThanOrEqual(1)
+    if (results[0].kind === 'semantic') {
+      expect(results[0].confidence).toBeGreaterThan(0.5)
+    }
+  })
+
+  it('gives lower confidence to random colors (no hue rotation)', () => {
+    // Colors with varying hues, saturations, and lightness — no clear rainbow
+    const tree = greenNode('document', '', [
+      colorNode('#804868', 'A'),
+      colorNode('#7EB8E0', 'B'),
+      colorNode('#D194B3', 'C'),
+      colorNode('#43383A', 'D'),
+      colorNode('#595255', 'E'),
+    ])
+
+    const analyzer = new RainbowAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    // These have no clear hue rotation — confidence should be low
+    if (results.length > 0 && results[0].kind === 'semantic') {
+      expect(results[0].confidence).toBeLessThan(0.7)
+    }
+  })
+
+  it('ignores sequences shorter than minimum length (4)', () => {
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#00FF00', 'B'),
+      colorNode('#0000FF', 'C'),
+    ])
+
+    const analyzer = new RainbowAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results).toHaveLength(0)
+  })
+
+  it('reports diagnostics with hue delta and saturation deviation', () => {
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#FF8800', 'B'),
+      colorNode('#FFFF00', 'C'),
+      colorNode('#88FF00', 'D'),
+      colorNode('#00FF00', 'E'),
+    ])
+
+    const analyzer = new RainbowAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    if (results.length > 0 && results[0].kind === 'semantic') {
+      const diag = results[0].metadata.diagnostics as Record<string, unknown>
+      expect(typeof diag.hueDelta).toBe('number')
+      expect(typeof diag.saturationDeviation).toBe('number')
+      expect(typeof diag.lightnessDeviation).toBe('number')
+    }
+  })
+})

package/src/Analysis/Passes/Analysis/__tests__/WaveAnalyzer.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Tests for WaveAnalyzer (size oscillation detection)
+ */
+
+import { describe, it, expect } from 'vitest'
+import { greenNode, greenLeaf } from '../../../../Syntax/GreenNode'
+import type { GreenNode } from '../../../../Syntax/GreenNode'
+import { WaveAnalyzer } from '../WaveAnalyzer'
+import type { PipelineContext } from '../../../Contracts/PipelineContext'
+import { PipelineMode, ExportTarget } from '../../../Contracts/PipelineContext'
+import { ContributionKind } from '../../../Contracts/Contribution'
+
+const mockContext: PipelineContext = {
+  mode: PipelineMode.Batch,
+  target: ExportTarget.Miliastry,
+  featureFlags: {},
+  metadata: {},
+}
+
+function sizeNode(size: number, text: string): GreenNode {
+  // Widths of the real BBCode this stands for: `[size=NN]` and `[/size]`.
+  const textLeaf = greenLeaf('text', text)
+  return greenNode('font_size', `=${size}`, [textLeaf], 7 + String(size).length, 7)
+}
+
+describe('WaveAnalyzer', () => {
+  it('detects a sine wave size pattern', () => {
+    // Sinusoidal sizes: 90 → 120 → 150 → 120 → 90
+    const tree = greenNode('document', '', [
+      sizeNode(90, 'A'),
+      sizeNode(120, 'B'),
+      sizeNode(150, 'C'),
+      sizeNode(120, 'D'),
+      sizeNode(90, 'E'),
+    ])
+
+    const analyzer = new WaveAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results.length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('gives higher confidence to clear wave patterns', () => {
+    // Perfect sine-like: 90→125→160→125→90
+    const tree = greenNode('document', '', [
+      sizeNode(90, 'A'),
+      sizeNode(110, 'B'),
+      sizeNode(140, 'C'),
+      sizeNode(160, 'D'),
+      sizeNode(140, 'E'),
+      sizeNode(110, 'F'),
+      sizeNode(90, 'G'),
+    ])
+
+    const analyzer = new WaveAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    if (results.length > 0 && results[0].kind === 'semantic') {
+      expect(results[0].confidence).toBeGreaterThan(0.4)
+    }
+  })
+
+  it('detects a wave pattern and produces a contribution', () => {
+    // Validates the WaveAnalyzer produces a semantic contribution for size patterns
+    const tree = greenNode('document', '', [
+      sizeNode(90, 'A'),
+      sizeNode(120, 'B'),
+      sizeNode(150, 'C'),
+      sizeNode(120, 'D'),
+      sizeNode(90, 'E'),
+      sizeNode(120, 'F'),
+      sizeNode(150, 'G'),
+    ])
+
+    const analyzer = new WaveAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results.length).toBeGreaterThanOrEqual(1)
+    if (results[0].kind === 'semantic') {
+      expect(results[0].label).toBe('Wave')
+      expect(results[0].metadata.model).toBeDefined()
+    }
+  })
+
+  it('ignores sequences shorter than minimum length (5)', () => {
+    const tree = greenNode('document', '', [
+      sizeNode(90, 'A'),
+      sizeNode(120, 'B'),
+      sizeNode(150, 'C'),
+      sizeNode(120, 'D'),
+    ])
+
+    const analyzer = new WaveAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results).toHaveLength(0)
+  })
+
+  it('reports diagnostics with periodicity score', () => {
+    const tree = greenNode('document', '', [
+      sizeNode(90, 'A'),
+      sizeNode(120, 'B'),
+      sizeNode(150, 'C'),
+      sizeNode(120, 'D'),
+      sizeNode(90, 'E'),
+      sizeNode(120, 'F'),
+      sizeNode(150, 'G'),
+    ])
+
+    const analyzer = new WaveAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    if (results.length > 0 && results[0].kind === 'semantic') {
+      const diag = results[0].metadata.diagnostics as Record<string, unknown>
+      expect(typeof diag.periodicityScore).toBe('number')
+      expect(typeof diag.transitionSmoothness).toBe('number')
+    }
+  })
+})

package/src/Analysis/Passes/Decision/DefaultDecision.ts

@@ -0,0 +1,139 @@
+/**
+ * Quasar Analysis Framework — Default Decision
+ *
+ * Consumes an AnalysisReport and produces a TransformationPlan.
+ * The decision logic depends on the PipelineContext:
+ *
+ *   - target === 'miliastry':
+ *       Aggressively collapses detected gradients (confidence ≥ 0.6).
+ *   - target === 'osu':
+ *       Only collapses very high-confidence gradients (confidence ≥ 0.95).
+ *   - mode === 'batch' || mode === 'import':
+ *       Uses the OSU threshold by default.
+ *
+ * Optimisation opportunities (mergeable colours) are always included
+ * regardless of target, but only when the count exceeds 1.
+ *
+ * @see DecisionPass
+ * @see TransformationPlan
+ */
+
+import type { DecisionPass, TransformationPlan, TransformAction } from '../../Contracts/Pass'
+import type { AnalysisReport } from '../../Contracts/AnalysisReport'
+import type { PipelineContext } from '../../Contracts/PipelineContext'
+import { ContributionKind } from '../../Contracts/Contribution'
+import type { SemanticContribution } from '../../Contracts/Contribution'
+import { ExportTarget } from '../../Contracts/PipelineContext'
+
+// ── Thresholds ────────────────────────────────────────────────────
+
+const THRESHOLDS = {
+  [ExportTarget.Miliastry]: {
+    autoCollapse: 0.6,       // Suggest for anything ≥ 60%
+    forceCollapse: 0.85,     // Auto-collapse without asking ≥ 85%
+  },
+  [ExportTarget.Osu]: {
+    autoCollapse: 0.95,      // Only collapse very confident gradients
+    forceCollapse: 0.99,     // Near-certain
+  },
+  [ExportTarget.HTML]: {
+    autoCollapse: 0.8,       // Moderate — HTML can handle gradients natively
+    forceCollapse: 0.95,
+  },
+  [ExportTarget.Markdown]: {
+    autoCollapse: 0.95,      // Conservative — Markdown has no colour support
+    forceCollapse: 0.99,
+  },
+} as const
+
+const DEFAULT_THRESHOLD = {
+  autoCollapse: 0.8,
+  forceCollapse: 0.95,
+}
+
+export class DefaultDecision implements DecisionPass {
+  readonly id = 'default-decision'
+
+  run(report: AnalysisReport, context: PipelineContext): TransformationPlan {
+    const actions: TransformAction[] = []
+    const thresholds = THRESHOLDS[context.target] ?? DEFAULT_THRESHOLD
+
+    for (const contribution of report.contributions) {
+      switch (contribution.kind) {
+        case ContributionKind.Semantic:
+          this.handleSemantic(contribution, thresholds, actions)
+          break
+
+        case ContributionKind.Optimization:
+          this.handleOptimization(contribution, actions)
+          break
+
+        // Diagnostics and metrics don't produce actions by default
+        default:
+          break
+      }
+    }
+
+    return { actions: Object.freeze(actions) }
+  }
+
+  // ── Semantic handlers ───────────────────────────────────────────
+
+  /** Map contribution label → transform action kind */
+  private labelToActionKind(label: string): string | null {
+    switch (label) {
+      case 'Gradient': return 'collapse-gradient'
+      case 'Rainbow':  return 'collapse-rainbow'
+      case 'Wave':     return 'collapse-wave'
+      default:         return null
+    }
+  }
+
+  private handleSemantic(
+    contribution: SemanticContribution,
+    thresholds: { autoCollapse: number; forceCollapse: number },
+    sink: TransformAction[],
+  ): void {
+    const { confidence } = contribution
+    const actionKind = this.labelToActionKind(contribution.label)
+    if (!actionKind) return
+
+    if (confidence >= thresholds.forceCollapse) {
+      sink.push({
+        kind: actionKind,
+        payload: {
+          range: contribution.range,
+          model: contribution.metadata.model as Record<string, unknown>,
+          autoCollapse: true,
+        },
+      })
+    } else if (confidence >= thresholds.autoCollapse) {
+      sink.push({
+        kind: actionKind,
+        payload: {
+          range: contribution.range,
+          model: contribution.metadata.model as Record<string, unknown>,
+          autoCollapse: false,
+          confidence,
+        },
+      })
+    }
+  }
+
+  // ── Optimization handlers ───────────────────────────────────────
+
+  private handleOptimization(
+    contribution: { label: string; range: { start: number; end: number } },
+    sink: TransformAction[],
+  ): void {
+    if (contribution.label === 'Merge Colors') {
+      // Always suggest merging identical consecutive colours
+      sink.push({
+        kind: 'merge-colors',
+        payload: {
+          range: contribution.range,
+        },
+      })
+    }
+  }
+}

package/src/Analysis/Passes/Decision/__tests__/DefaultDecision.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Tests for DefaultDecision
+ */
+
+import { describe, it, expect } from 'vitest'
+import { DefaultDecision } from '../DefaultDecision'
+import { ContributionKind } from '../../../Contracts/Contribution'
+import type { AnalysisReport } from '../../../Contracts/AnalysisReport'
+import type { PipelineContext } from '../../../Contracts/PipelineContext'
+import { PipelineMode, ExportTarget } from '../../../Contracts/PipelineContext'
+
+const baseReport: AnalysisReport = {
+  contributions: [],
+  passCount: 1,
+  elapsedMs: 10,
+}
+
+function osuContext(overrides: Partial<PipelineContext> = {}): PipelineContext {
+  return {
+    mode: PipelineMode.Batch,
+    target: ExportTarget.Osu,
+    featureFlags: {},
+    metadata: {},
+    ...overrides,
+  }
+}
+
+function miliastryContext(overrides: Partial<PipelineContext> = {}): PipelineContext {
+  return {
+    mode: PipelineMode.Interactive,
+    target: ExportTarget.Miliastry,
+    featureFlags: {},
+    metadata: {},
+    ...overrides,
+  }
+}
+
+describe('DefaultDecision', () => {
+  describe('gradient detection', () => {
+    it('excludes gradients below the threshold for osu target', () => {
+      const decision = new DefaultDecision()
+      const report: AnalysisReport = {
+        ...baseReport,
+        contributions: [
+          {
+            kind: ContributionKind.Semantic,
+            label: 'Gradient',
+            confidence: 0.5, // Below threshold
+            range: { start: 0, end: 50 },
+            metadata: {
+              model: { colors: ['#FF0000', '#00FF00'], easing: 'linear', charCount: 5 },
+              diagnostics: {},
+            },
+          },
+        ],
+      }
+
+      const plan = decision.run(report, osuContext())
+      expect(plan.actions).toHaveLength(0)
+    })
+
+    it('includes gradients above auto-threshold for osu target', () => {
+      const decision = new DefaultDecision()
+      const report: AnalysisReport = {
+        ...baseReport,
+        contributions: [
+          {
+            kind: ContributionKind.Semantic,
+            label: 'Gradient',
+            confidence: 0.96, // Above osu threshold (0.95)
+            range: { start: 0, end: 50 },
+            metadata: {
+              model: { colors: ['#FF0000', '#EE1100', '#DD2200'], easing: 'linear', charCount: 3 },
+              diagnostics: {},
+            },
+          },
+        ],
+      }
+
+      const plan = decision.run(report, osuContext())
+      expect(plan.actions).toHaveLength(1)
+      expect(plan.actions[0].kind).toBe('collapse-gradient')
+    })
+
+    it('uses lower threshold for miliastry target', () => {
+      const decision = new DefaultDecision()
+      const report: AnalysisReport = {
+        ...baseReport,
+        contributions: [
+          {
+            kind: ContributionKind.Semantic,
+            label: 'Gradient',
+            confidence: 0.7, // Above miliastry threshold (0.6)
+            range: { start: 0, end: 50 },
+            metadata: {
+              model: { colors: ['#FF0000', '#EE1100', '#DD2200'], easing: 'linear', charCount: 3 },
+              diagnostics: {},
+            },
+          },
+        ],
+      }
+
+      const plan = decision.run(report, miliastryContext())
+      expect(plan.actions).toHaveLength(1)
+      expect(plan.actions[0].kind).toBe('collapse-gradient')
+    })
+
+    it('uses forceCollapse for very high confidence', () => {
+      const decision = new DefaultDecision()
+      const report: AnalysisReport = {
+        ...baseReport,
+        contributions: [
+          {
+            kind: ContributionKind.Semantic,
+            label: 'Gradient',
+            confidence: 0.9,
+            range: { start: 0, end: 50 },
+            metadata: {
+              model: { colors: ['#FF0000', '#EE1100', '#DD2200'], easing: 'linear', charCount: 3 },
+              diagnostics: {},
+            },
+          },
+        ],
+      }
+
+      const plan = decision.run(report, miliastryContext())
+      // 0.9 ≥ 0.85 = force collapse
+      expect(plan.actions[0].payload.autoCollapse).toBe(true)
+    })
+  })
+
+  describe('optimization detection', () => {
+    it('includes merge-colors optimizations', () => {
+      const decision = new DefaultDecision()
+      const report: AnalysisReport = {
+        ...baseReport,
+        contributions: [
+          {
+            kind: ContributionKind.Optimization,
+            label: 'Merge Colors',
+            description: '3 consecutive [color=#FF0000] tags',
+            estimatedImprovement: '-66%',
+            range: { start: 0, end: 30 },
+          },
+        ],
+      }
+
+      const plan = decision.run(report, osuContext())
+      expect(plan.actions).toHaveLength(1)
+      expect(plan.actions[0].kind).toBe('merge-colors')
+    })
+  })
+
+  describe('edge cases', () => {
+    it('returns empty plan for empty report', () => {
+      const decision = new DefaultDecision()
+      const plan = decision.run(baseReport, osuContext())
+      expect(plan.actions).toHaveLength(0)
+    })
+
+    it('ignores non-semantic and non-optimization contributions', () => {
+      const decision = new DefaultDecision()
+      const report: AnalysisReport = {
+        ...baseReport,
+        contributions: [
+          { kind: ContributionKind.Metrics, metrics: { characters: 100 } },
+          {
+            kind: ContributionKind.Diagnostic,
+            severity: 'info',
+            message: 'Test diagnostic',
+          },
+        ],
+      }
+
+      const plan = decision.run(report, osuContext())
+      expect(plan.actions).toHaveLength(0)
+    })
+  })
+})