@miliastry/quasar 1.0.0

package/src/Analysis/Pipeline/PipelineBuilder.ts

@@ -0,0 +1,55 @@
+/**
+ * Quasar Analysis Framework — Pipeline Builder
+ *
+ * Provides a fluent API for assembling a Pipeline from individually
+ * registered passes.  Each stage (analysis / decision / transform)
+ * has its own registration method so TypeScript catches misuse at
+ * compile time.
+ *
+ * @example
+ * ```ts
+ * const pipeline = Pipeline
+ *   .builder()
+ *   .analysis(new CharacterCountAnalyzer())
+ *   .decision(new DefaultDecision())
+ *   .transform(new CollapseGradientTransform())
+ *   .build()
+ * ```
+ */
+
+import type { AnalyzerPass, DecisionPass, TransformPass } from '../Contracts/Pass'
+import type { PipelineStage } from './PipelineStage'
+import { Pipeline } from './Pipeline'
+
+export class PipelineBuilder {
+  private readonly passes: { stage: PipelineStage; pass: AnalyzerPass | DecisionPass | TransformPass }[] = []
+
+  /** Register one or more AnalyzerPasses (observation stage). */
+  analysis(...passes: AnalyzerPass[]): this {
+    for (const p of passes) {
+      this.passes.push({ stage: 'analysis', pass: p })
+    }
+    return this
+  }
+
+  /** Register one or more DecisionPasses (planning stage). */
+  decision(...passes: DecisionPass[]): this {
+    for (const p of passes) {
+      this.passes.push({ stage: 'decision', pass: p })
+    }
+    return this
+  }
+
+  /** Register one or more TransformPasses (mutation stage). */
+  transform(...passes: TransformPass[]): this {
+    for (const p of passes) {
+      this.passes.push({ stage: 'transform', pass: p })
+    }
+    return this
+  }
+
+  /** Build the Pipeline from the registered passes. */
+  build(): Pipeline {
+    return new Pipeline([...this.passes])
+  }
+}

package/src/Analysis/Pipeline/PipelineStage.ts

@@ -0,0 +1,19 @@
+/**
+ * Quasar Analysis Framework — Pipeline Stage
+ *
+ * Passes are grouped into stages that execute in order:
+ *
+ *   1. Analysis  — observe the tree, produce Contributions
+ *   2. Decision  — consume the AnalysisReport, produce a TransformationPlan
+ *   3. Transform — apply the plan to produce a new Green Tree
+ *
+ * @see Pass
+ */
+
+export const PipelineStage = {
+  Analysis: 'analysis',
+  Decision: 'decision',
+  Transform: 'transform',
+} as const
+
+export type PipelineStage = (typeof PipelineStage)[keyof typeof PipelineStage]

package/src/Analysis/Utils/color-utils.ts

@@ -0,0 +1,132 @@
+/**
+ * Quasar Analysis Framework — Color Utilities
+ *
+ * Shared utility functions for color node analysis across all passes.
+ * Extracted here to avoid duplication across GradientAnalyzer,
+ * RainbowAnalyzer, MergeableColorAnalyzer, etc.
+ *
+ * @module
+ */
+
+import type { GreenNode } from '../../Syntax/GreenNode'
+
+// ── Hex extraction ────────────────────────────────────────────────
+
+/**
+ * Extract the hex colour from a [color] GreenNode.
+ * Supports both "=#FF0000" and "#FF0000" formats.
+ * Returns null if the node is not a color node or has invalid hex.
+ */
+export function extractHex(node: GreenNode): string | null {
+  if (node.kind !== 'color') return null
+  const text = node.text || ''
+  const eqIdx = text.indexOf('=')
+  const hex = eqIdx >= 0 ? text.slice(eqIdx + 1).trim() : text.trim()
+  return /^#[0-9A-Fa-f]{6}$/.test(hex) ? hex.toUpperCase() : null
+}
+
+/**
+ * Extract the size value from a [size] / [font_size] GreenNode.
+ * Supports "=150", "=90" formats.
+ * Returns null if the node is not a size node.
+ */
+export function extractSize(node: GreenNode): number | null {
+  if (node.kind !== 'font_size') return null
+  const text = node.text || ''
+  const eqIdx = text.indexOf('=')
+  const val = eqIdx >= 0 ? text.slice(eqIdx + 1).trim() : text.trim()
+  const num = parseInt(val, 10)
+  return isNaN(num) ? null : num
+}
+
+// ── Sigmoid ───────────────────────────────────────────────────────
+
+/**
+ * Sigmoid function to map a raw score to [0, 1] confidence.
+ * Centered at 0: sigmoid(0) = 0.5
+ * steepness controls the sharpness of the transition.
+ */
+export function sigmoid(x: number, steepness: number = 6): number {
+  return 1 / (1 + Math.exp(-x * steepness))
+}
+
+// ── Sequence helpers ──────────────────────────────────────────────
+
+/**
+ * A detected sequence of adjacent similar nodes in the Green Tree.
+ */
+export interface NodeSequence {
+  /** Extracted values (hex colours, sizes, etc.) in order */
+  readonly values: (string | number)[]
+  /** Start index in the parent's children array */
+  readonly startIdx: number
+  /** End index (exclusive) in the parent's children array */
+  readonly endIdx: number
+}
+
+/**
+ * Extract consecutive sequences of [color] or [font_size] nodes
+ * from a parent's children array.
+ *
+ * @param children - Direct children of a container node
+ * @param kind     - The node kind to extract ('color' or 'font_size')
+ * @param extract  - Function to extract values from matching nodes
+ * @returns Array of sequences found
+ */
+export function extractSequences<T extends string | number>(
+  children: GreenNode[],
+  kind: string,
+  extract: (node: GreenNode) => T | null,
+): Array<{ values: T[]; startIdx: number; endIdx: number }> {
+  const sequences: Array<{ values: T[]; startIdx: number; endIdx: number }> = []
+  let current: { values: T[]; startIdx: number } | null = null
+
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]
+    const val = child.kind === kind ? extract(child) : null
+
+    if (val !== null) {
+      if (current === null) {
+        current = { values: [val], startIdx: i }
+      } else {
+        current.values.push(val)
+      }
+    } else if (child.kind !== 'text' || child.text.trim() !== '') {
+      // Non-text, non-{kind} node OR non-whitespace text — end sequence
+      if (current !== null) {
+        sequences.push({ ...current, endIdx: i })
+        current = null
+      }
+    }
+  }
+
+  if (current !== null) {
+    sequences.push({ ...current, endIdx: children.length })
+  }
+
+  return sequences
+}
+
+/**
+ * Check if there are formatting tags between nodes in a sequence.
+ */
+export function checkFormattingBreaks(
+  children: GreenNode[],
+  seq: { startIdx: number; endIdx: number },
+  targetKind: string,
+): boolean {
+  for (let i = seq.startIdx; i < seq.endIdx; i++) {
+    const child = children[i]
+    if (child.kind !== targetKind && child.kind !== 'text') {
+      return true
+    }
+    if (child.kind === targetKind) {
+      for (const c of child.children as GreenNode[]) {
+        if (c.kind !== 'text' && c.kind !== 'spacing' && c.kind !== 'empty_line') {
+          return true
+        }
+      }
+    }
+  }
+  return false
+}

package/src/Analysis/__tests__/Integration.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Quasar Analysis Framework — Integration Tests
+ *
+ * End-to-end tests that exercise the full pipeline with real passes:
+ *   GradientAnalyzer → DefaultDecision → CollapseGradientTransform
+ *   MergeableColorAnalyzer → DefaultDecision → MergeColorsTransform
+ */
+
+import { describe, it, expect } from 'vitest'
+import { greenNode, greenLeaf } from '../../Syntax/GreenNode'
+import type { GreenNode } from '../../Syntax/GreenNode'
+import { Pipeline } from '../Pipeline/Pipeline'
+import { PipelineBuilder } from '../Pipeline/PipelineBuilder'
+import { GradientAnalyzer } from '../Passes/Analysis/GradientAnalyzer'
+import { MergeableColorAnalyzer } from '../Passes/Analysis/MergeableColorAnalyzer'
+import { DefaultDecision } from '../Passes/Decision/DefaultDecision'
+import { CollapseGradientTransform } from '../Passes/Transform/CollapseGradientTransform'
+import { MergeColorsTransform } from '../Passes/Transform/MergeColorsTransform'
+import type { PipelineContext } from '../Contracts/PipelineContext'
+import { PipelineMode, ExportTarget } from '../Contracts/PipelineContext'
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+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)
+}
+
+const interactiveContext: PipelineContext = {
+  mode: PipelineMode.Interactive,
+  target: ExportTarget.Miliastry,
+  featureFlags: {},
+  metadata: {},
+}
+
+const batchOsuContext: PipelineContext = {
+  mode: PipelineMode.Batch,
+  target: ExportTarget.Osu,
+  featureFlags: {},
+  metadata: {},
+}
+
+// ── Tests ─────────────────────────────────────────────────────────
+
+describe('Gradient pipeline (full integration)', () => {
+  it('collapses a clear gradient with miliastry target', () => {
+    // [color=#FF0000]H[/color][color=#EE1100]e[/color][color=#DD2200]l[/color][color=#CC3300]l[/color][color=#BB4400]o[/color]
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'H'),
+      colorNode('#EE1100', 'e'),
+      colorNode('#DD2200', 'l'),
+      colorNode('#CC3300', 'l'),
+      colorNode('#BB4400', 'o'),
+    ])
+
+    const pipeline = new PipelineBuilder()
+      .analysis(new GradientAnalyzer())
+      .decision(new DefaultDecision())
+      .transform(new CollapseGradientTransform())
+      .build()
+
+    const result = pipeline.run(tree, interactiveContext)
+    const treeChildren = result.tree.children as GreenNode[]
+
+    // After collapsing, we should have a single gradient node
+    const gradientNodes = treeChildren.filter(c => c.kind === 'gradient')
+    expect(gradientNodes.length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('preserves non-gradient color sequences with osu target', () => {
+    // Random colors — low confidence, below osu threshold
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#00FF00', 'B'),
+      colorNode('#0000FF', 'C'),
+    ])
+
+    const pipeline = new PipelineBuilder()
+      .analysis(new GradientAnalyzer())
+      .decision(new DefaultDecision())
+      .transform(new CollapseGradientTransform())
+      .build()
+
+    const result = pipeline.run(tree, batchOsuContext)
+    const treeChildren = result.tree.children as GreenNode[]
+
+    // With only 3 random colors, confidence should be below osu threshold
+    const gradientNodes = treeChildren.filter(c => c.kind === 'gradient')
+    expect(gradientNodes).toHaveLength(0)
+  })
+
+  it('produces an AnalysisReport with contributions', () => {
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#EE1100', 'B'),
+      colorNode('#DD2200', 'C'),
+      colorNode('#CC3300', 'D'),
+    ])
+
+    const pipeline = new PipelineBuilder()
+      .analysis(new GradientAnalyzer())
+      .build()
+
+    const result = pipeline.run(tree, interactiveContext)
+
+    expect(result.report.contributions.length).toBeGreaterThanOrEqual(1)
+    expect(result.report.elapsedMs).toBeGreaterThanOrEqual(0)
+    expect(result.report.passCount).toBe(1)
+  })
+})
+
+describe('Merge colors pipeline (full integration)', () => {
+  it('merges identical consecutive color nodes', () => {
+    // [color=#FF0000]H[/color][color=#FF0000]e[/color][color=#FF0000]l[/color]
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'H'),
+      colorNode('#FF0000', 'e'),
+      colorNode('#FF0000', 'l'),
+    ])
+
+    const pipeline = new PipelineBuilder()
+      .analysis(new MergeableColorAnalyzer())
+      .decision(new DefaultDecision())
+      .transform(new MergeColorsTransform())
+      .build()
+
+    const result = pipeline.run(tree, interactiveContext)
+    const treeChildren = result.tree.children as GreenNode[]
+
+    // Should be 1 colour node (merged) instead of 3
+    const colorNodes = treeChildren.filter(c => c.kind === 'color')
+    expect(colorNodes).toHaveLength(1)
+  })
+})
+
+describe('Combined pipeline', () => {
+  it('runs multiple analysis passes and produces correct report', () => {
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#EE1100', 'B'),
+      colorNode('#DD2200', 'C'),
+      colorNode('#FF0000', 'X'),  // part of mergeable (different from gradient sequence)
+      colorNode('#FF0000', 'Y'),
+    ])
+
+    const pipeline = new PipelineBuilder()
+      .analysis(new GradientAnalyzer(), new MergeableColorAnalyzer())
+      .decision(new DefaultDecision())
+      .build()
+
+    const result = pipeline.run(tree, interactiveContext)
+
+    // Should have contributions from both analyzers
+    const analysisContributions = result.report.contributions
+    const gradientContributions = analysisContributions.filter(c => c.kind === 'semantic' && c.label === 'Gradient')
+    const mergeContributions = analysisContributions.filter(c => c.kind === 'optimization' && c.label === 'Merge Colors')
+
+    expect(gradientContributions.length).toBeGreaterThanOrEqual(1)
+    expect(mergeContributions.length).toBeGreaterThanOrEqual(1)
+  })
+})

package/src/Analysis/__tests__/Pipeline.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Quasar Analysis Framework — Pipeline Tests
+ *
+ * Validates that the core pipeline infrastructure works:
+ * - Pass interfaces are correctly typed
+ * - PipelineBuilder assembles passes
+ * - Pipeline executes them in order
+ * - CharacterCountAnalyzer (PoC) produces expected metrics
+ */
+
+import { describe, it, expect } from 'vitest'
+import { greenNode, greenLeaf } from '../../Syntax/GreenNode'
+import type { GreenNode } from '../../Syntax/GreenNode'
+import { Pipeline } from '../Pipeline/Pipeline'
+import { PipelineBuilder } from '../Pipeline/PipelineBuilder'
+import { CharacterCountAnalyzer } from '../Passes/Utility/CharacterCountAnalyzer'
+import type { PipelineContext } from '../Contracts/PipelineContext'
+import { PipelineMode, ExportTarget } from '../Contracts/PipelineContext'
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+const mockContext: PipelineContext = {
+  mode: PipelineMode.Batch,
+  target: ExportTarget.Osu,
+  featureFlags: {},
+  metadata: {},
+}
+
+function buildSimpleTree(): GreenNode {
+  // root
+  // ├── heading "Hello"
+  // └── text "World"
+  const headingText = greenLeaf('text', 'Hello')
+  const heading = greenNode('heading', '', [headingText])
+  const worldText = greenLeaf('text', 'World')
+  return greenNode('root', '', [heading, worldText])
+}
+
+// ── Tests ─────────────────────────────────────────────────────────
+
+describe('Pipeline Infrastructure', () => {
+  describe('PipelineBuilder', () => {
+    it('builds a pipeline from passes', () => {
+      const pipeline = new PipelineBuilder()
+        .analysis(new CharacterCountAnalyzer())
+        .build()
+
+      expect(pipeline).toBeInstanceOf(Pipeline)
+    })
+
+    it('accepts multiple analysis passes', () => {
+      const pipeline = new PipelineBuilder()
+        .analysis(new CharacterCountAnalyzer(), new CharacterCountAnalyzer())
+        .build()
+
+      expect(pipeline).toBeInstanceOf(Pipeline)
+    })
+
+    it('rejects analysis passes in decision/transform slots at type level', () => {
+      // TypeScript enforces that builder.analysis() only accepts AnalyzerPass
+      // instances. This is a compile-time check that can't be validated with
+      // vitest. At runtime we just verify the builder doesn't throw for valid usage.
+      const builder = new PipelineBuilder()
+      expect(() => builder.analysis(new CharacterCountAnalyzer())).not.toThrow()
+    })
+  })
+
+  describe('Pipeline execution', () => {
+    it('executes analysis passes and produces a report', () => {
+      const pipeline = new PipelineBuilder()
+        .analysis(new CharacterCountAnalyzer())
+        .build()
+
+      const tree = buildSimpleTree()
+      const result = pipeline.run(tree, mockContext)
+
+      expect(result.report.contributions).toHaveLength(1)
+      expect(result.report.passCount).toBe(1)
+      expect(result.report.elapsedMs).toBeGreaterThanOrEqual(0)
+    })
+
+    it('preserves the original tree when no transforms are registered', () => {
+      const pipeline = new PipelineBuilder()
+        .analysis(new CharacterCountAnalyzer())
+        .build()
+
+      const tree = buildSimpleTree()
+      const result = pipeline.run(tree, mockContext)
+
+      expect(result.tree).toBe(tree) // same reference since no transforms
+    })
+
+    it('reports correct character count', () => {
+      const pipeline = new PipelineBuilder()
+        .analysis(new CharacterCountAnalyzer())
+        .build()
+
+      const tree = buildSimpleTree()
+      const result = pipeline.run(tree, mockContext)
+
+      const metricsContribution = result.report.contributions[0]
+      expect(metricsContribution).toMatchObject({
+        kind: 'metrics',
+        metrics: { characters: 10 }, // "Hello" (5) + "World" (5)
+      })
+    })
+
+    it('handles empty trees gracefully', () => {
+      const pipeline = new PipelineBuilder()
+        .analysis(new CharacterCountAnalyzer())
+        .build()
+
+      const emptyTree = greenNode('root', '', [])
+      const result = pipeline.run(emptyTree, mockContext)
+
+      const metricsContribution = result.report.contributions[0]
+      expect(metricsContribution).toMatchObject({
+        kind: 'metrics',
+        metrics: { characters: 0 },
+      })
+    })
+  })
+
+  describe('PipelineBuilder direct usage', () => {
+    it('works via new PipelineBuilder()', () => {
+      const pipeline = new PipelineBuilder()
+        .analysis(new CharacterCountAnalyzer())
+        .build()
+
+      expect(pipeline).toBeInstanceOf(Pipeline)
+    })
+  })
+})

package/src/Analysis/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Quasar Analysis Framework — Public API
+ *
+ * A pipeline-based analysis and transformation engine for Green Trees.
+ *
+ * @module
+ * @see Analysis/ARCHITECTURE.md (planned)
+ */
+
+// ── Contracts ─────────────────────────────────────────────────────
+export type { Pass } from './Contracts/Pass'
+export type { AnalyzerPass, DecisionPass, TransformPass } from './Contracts/Pass'
+export type { TransformationPlan, TransformAction } from './Contracts/Pass'
+
+export type { Contribution } from './Contracts/Contribution'
+export type {
+  SemanticContribution,
+  DiagnosticContribution,
+  OptimizationContribution,
+  MetricsContribution,
+} from './Contracts/Contribution'
+export { ContributionKind } from './Contracts/Contribution'
+
+export type { AnalysisReport } from './Contracts/AnalysisReport'
+
+export type { PipelineContext } from './Contracts/PipelineContext'
+export { PipelineMode, ExportTarget } from './Contracts/PipelineContext'
+
+// ── Pipeline ──────────────────────────────────────────────────────
+export { Pipeline } from './Pipeline/Pipeline'
+export type { PipelineResult } from './Pipeline/Pipeline'
+export { PipelineBuilder } from './Pipeline/PipelineBuilder'
+export { PipelineStage } from './Pipeline/PipelineStage'
+
+// ── Analysis Passes ───────────────────────────────────────────────
+export { CharacterCountAnalyzer } from './Passes/Utility/CharacterCountAnalyzer'
+export { MergeableColorAnalyzer } from './Passes/Analysis/MergeableColorAnalyzer'
+export { GradientAnalyzer } from './Passes/Analysis/GradientAnalyzer'
+export type { GradientModel, GradientDiagnostics, GradientStop } from './Passes/Analysis/GradientAnalyzer'
+export { RainbowAnalyzer } from './Passes/Analysis/RainbowAnalyzer'
+export type { RainbowModel, RainbowDiagnostics } from './Passes/Analysis/RainbowAnalyzer'
+export { WaveAnalyzer } from './Passes/Analysis/WaveAnalyzer'
+export type { WaveModel, WaveDiagnostics } from './Passes/Analysis/WaveAnalyzer'
+
+// ── Decision Passes ───────────────────────────────────────────────
+export { DefaultDecision } from './Passes/Decision/DefaultDecision'
+
+// ── Transform Passes ──────────────────────────────────────────────
+export { CollapseGradientTransform } from './Passes/Transform/CollapseGradientTransform'
+export { RainbowCollapseTransform } from './Passes/Transform/RainbowCollapseTransform'
+export { WaveCollapseTransform } from './Passes/Transform/WaveCollapseTransform'
+export { MergeColorsTransform } from './Passes/Transform/MergeColorsTransform'