@miliastry/quasar 1.0.0

package/src/Analysis/Passes/Transform/CollapseGradientTransform.ts

@@ -0,0 +1,176 @@
+/**
+ * Quasar Analysis Framework — Collapse Gradient Transform
+ *
+ * Applies `collapse-gradient` actions from a TransformationPlan.
+ * Each action targets a sequence of adjacent [color] nodes and replaces
+ * them with a single [gradient] node containing all text children.
+ *
+ * The transform operates on the Green Tree and returns a new tree —
+ * it NEVER mutates the original.
+ *
+ * @example
+ * Before:
+ *   [color=#FF0000]H[/color][color=#EE1100]e[/color][color=#DD2200]l[/color]
+ * After:
+ *   [gradient=#FF0000,#EE1100,#DD2200]Hello[/gradient]
+ *
+ * @see TransformPass
+ */
+
+import type { TransformPass, TransformationPlan } from '../../Contracts/Pass'
+import type { PipelineContext } from '../../Contracts/PipelineContext'
+import type { GreenNode } from '../../../Syntax/GreenNode'
+import { greenNode, greenLeaf, childOffsets } from '../../../Syntax/GreenNode'
+
+// ── Supported action kinds ────────────────────────────────────────
+
+const COLLAPSE_KINDS = new Set(['collapse-gradient', 'collapse-gradient-auto'])
+
+export class CollapseGradientTransform implements TransformPass {
+  readonly id = 'collapse-gradient'
+
+  run(tree: GreenNode, plan: TransformationPlan, _context: PipelineContext): GreenNode {
+    // Filter only collapse-gradient actions
+    const actions = plan.actions.filter(a => COLLAPSE_KINDS.has(a.kind))
+
+    if (actions.length === 0) {
+      return tree // No changes
+    }
+
+    // Build a set of ranges to collapse (sorted by start position)
+    const ranges = actions
+      .map(a => ({
+        start: (a.payload.range as { start: number; end: number }).start,
+        end: (a.payload.range as { start: number; end: number }).end,
+        colors: ((a.payload.model as Record<string, unknown>)?.colors ?? []) as string[],
+        easing: ((a.payload.model as Record<string, unknown>)?.easing ?? 'linear') as string,
+      }))
+      .sort((a, b) => a.start - b.start)
+
+    // Apply transforms recursively
+    return this.transformNode(tree, ranges)
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  /**
+   * Walk the tree and collapse any sequences that fall within our ranges.
+   */
+  private transformNode(
+    node: GreenNode,
+    ranges: Array<{ start: number; end: number; colors: string[]; easing: string }>,
+    treeStart: number = 0,
+  ): GreenNode {
+    // Leaf node — no children to transform
+    if (node.children.length === 0) {
+      return node
+    }
+
+    const children = node.children as GreenNode[]
+
+    // Green nodes carry widths, not positions. The ranges being matched here
+    // come from the analyzers and are absolute, so the walk accumulates the
+    // offsets it needs as it descends.
+    const offsets = childOffsets(node, treeStart)
+
+    // Check if any range overlaps with this node's children
+    const nodeStart = offsets[0]
+    const nodeEnd = offsets[children.length]
+    const activeRanges = ranges.filter(
+      r => r.start >= nodeStart && r.end <= nodeEnd,
+    )
+
+    if (activeRanges.length === 0) {
+      // No ranges in this subtree — recurse into children
+      const newChildren = children.map((c, ci) => this.transformNode(c, ranges, offsets[ci]))
+      return this.rebuildNode(node, newChildren)
+    }
+
+    // Build new children, collapsing ranges into gradient nodes
+    const newChildren: GreenNode[] = []
+    let i = 0
+
+    while (i < children.length) {
+      const child = children[i]
+      const matchingRange = activeRanges.find(
+        r => offsets[i] >= r.start && offsets[i + 1] <= r.end,
+      )
+
+      if (matchingRange) {
+        // Find all children within this range
+        const rangeChildren: GreenNode[] = []
+        while (i < children.length && offsets[i + 1] <= matchingRange.end) {
+          rangeChildren.push(children[i])
+          i++
+        }
+
+        // Collapse into a single gradient node
+        const textNodes: string[] = []
+        const colorNodes: GreenNode[] = []
+
+        for (const rc of rangeChildren) {
+          if (rc.kind === 'color') {
+            colorNodes.push(rc)
+            // Collect text from inside the colour node
+            for (const textChild of rc.children as GreenNode[]) {
+              if (textChild.kind === 'text') {
+                textNodes.push(textChild.text)
+              }
+            }
+          } else if (rc.kind === 'text') {
+            textNodes.push(rc.text)
+          } else {
+            textNodes.push(rc.text || '')
+          }
+        }
+
+        // Create a text leaf inside the gradient node
+        const combinedText = textNodes.join('')
+        const textLeaf = greenLeaf('text', combinedText)
+
+        // Use the detected colours; fall back to extracted colours from nodes
+        let colors = matchingRange.colors
+        if (colors.length === 0) {
+          colors = colorNodes
+            .map(cn => this.extractHex(cn))
+            .filter((h): h is string => h !== null)
+        }
+
+        const colorsAttr = colors.join(',')
+        const gradientNode = greenNode('gradient', `=${colorsAttr}`, [textLeaf])
+        newChildren.push(gradientNode)
+      } else {
+        // Not in a collapse range — recurse and preserve
+        newChildren.push(this.transformNode(child, ranges, offsets[i]))
+        i++
+      }
+    }
+
+    return this.rebuildNode(node, newChildren)
+  }
+
+  /**
+   * Rebuild a node with the same kind/text/range but new children.
+   */
+  private rebuildNode(node: GreenNode, newChildren: GreenNode[]): GreenNode {
+    // If the node is a colour node and all children were collapsed,
+    // just return the first child instead (no need for empty colour)
+    if (node.kind === 'color' && newChildren.length === 0) {
+      return greenLeaf('text', node.text)
+    }
+
+    return greenNode(node.kind, node.text, newChildren,
+    )
+  }
+
+  /**
+   * Extract hex colour from a color node's text.
+   */
+  private 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
+  }
+}

package/src/Analysis/Passes/Transform/MergeColorsTransform.ts

@@ -0,0 +1,126 @@
+/**
+ * Quasar Analysis Framework — Merge Colors Transform
+ *
+ * Applies `merge-colors` actions from a TransformationPlan.
+ * Each action targets a sequence of identical consecutive [color=#HEX]
+ * nodes and merges them into a single `[color]` wrapper with combined text.
+ *
+ * The transform operates on the Green Tree and returns a new tree —
+ * it NEVER mutates the original.
+ *
+ * @example
+ * Before:
+ *   [color=#FF0000]H[/color][color=#FF0000]e[/color][color=#FF0000]l[/color]
+ * After:
+ *   [color=#FF0000]Hel[/color]
+ *
+ * @see TransformPass
+ */
+
+import type { TransformPass, TransformationPlan } from '../../Contracts/Pass'
+import type { PipelineContext } from '../../Contracts/PipelineContext'
+import type { GreenNode } from '../../../Syntax/GreenNode'
+import { greenNode, greenLeaf, childOffsets } from '../../../Syntax/GreenNode'
+
+export class MergeColorsTransform implements TransformPass {
+  readonly id = 'merge-colors'
+
+  run(tree: GreenNode, plan: TransformationPlan, _context: PipelineContext): GreenNode {
+    const mergeActions = plan.actions.filter(a => a.kind === 'merge-colors')
+
+    if (mergeActions.length === 0) {
+      return tree
+    }
+
+    const ranges = mergeActions
+      .map(a => ({
+        start: (a.payload.range as { start: number; end: number }).start,
+        end: (a.payload.range as { start: number; end: number }).end,
+      }))
+      .sort((a, b) => a.start - b.start)
+
+    return this.transformNode(tree, ranges)
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  private transformNode(
+    node: GreenNode,
+    ranges: Array<{ start: number; end: number }>,
+    treeStart: number = 0,
+  ): GreenNode {
+    if (node.children.length === 0) return node
+
+    const children = node.children as GreenNode[]
+    // Green nodes carry widths, not positions. The ranges being matched here
+    // come from the analyzers and are absolute, so the walk accumulates the
+    // offsets it needs as it descends.
+    const offsets = childOffsets(node, treeStart)
+    const nodeStart = offsets[0]
+    const nodeEnd = offsets[children.length]
+
+    const activeRanges = ranges.filter(
+      r => r.start >= nodeStart && r.end <= nodeEnd,
+    )
+
+    if (activeRanges.length === 0) {
+      const newChildren = children.map((c, ci) => this.transformNode(c, ranges, offsets[ci]))
+      return this.rebuildNode(node, newChildren)
+    }
+
+    const newChildren: GreenNode[] = []
+    let i = 0
+
+    while (i < children.length) {
+      const child = children[i]
+      const matchingRange = activeRanges.find(
+        r => offsets[i] >= r.start && offsets[i + 1] <= r.end,
+      )
+
+      if (matchingRange && child.kind === 'color') {
+        // Collect all consecutive colour nodes with the SAME hex
+        const hex = this.extractHex(child)
+        const mergedTexts: string[] = []
+
+        while (
+          i < children.length &&
+          children[i].kind === 'color' &&
+          this.extractHex(children[i]) === hex &&
+          offsets[i + 1] <= matchingRange.end
+        ) {
+          // Get text from inside the colour node's children
+          for (const textChild of children[i].children as GreenNode[]) {
+            if (textChild.kind === 'text') {
+              mergedTexts.push(textChild.text)
+            }
+          }
+          i++
+        }
+
+        // Create a single merged colour node
+        const combinedText = mergedTexts.join('')
+        const textLeaf = greenLeaf('text', combinedText)
+        const merged = greenNode('color', child.text, [textLeaf], child.leadingWidth, child.trailingWidth)
+        newChildren.push(merged)
+      } else {
+        newChildren.push(this.transformNode(child, ranges, offsets[i]))
+        i++
+      }
+    }
+
+    return this.rebuildNode(node, newChildren)
+  }
+
+  private rebuildNode(node: GreenNode, newChildren: GreenNode[]): GreenNode {
+    return greenNode(node.kind, node.text, newChildren,
+    )
+  }
+
+  private 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
+  }
+}

package/src/Analysis/Passes/Transform/RainbowCollapseTransform.ts

@@ -0,0 +1,83 @@
+/**
+ * Quasar Analysis Framework — Rainbow Collapse Transform
+ *
+ * Applies `collapse-rainbow` actions from a TransformationPlan.
+ * Replaces sequences of [color] nodes forming a hue-rotation pattern
+ * with a single [rainbow] node containing all text children.
+ *
+ * @example
+ * Before: [color=#FF0000]R[/color][color=#FFFF00]O[/color][color=#00FF00]Y[/color]
+ * After:  [rainbow]ROY[/rainbow]
+ */
+
+import type { TransformPass, TransformationPlan } from '../../Contracts/Pass'
+import type { PipelineContext } from '../../Contracts/PipelineContext'
+import type { GreenNode } from '../../../Syntax/GreenNode'
+import { greenNode, greenLeaf, childOffsets } from '../../../Syntax/GreenNode'
+
+export class RainbowCollapseTransform implements TransformPass {
+  readonly id = 'rainbow-collapse'
+
+  run(tree: GreenNode, plan: TransformationPlan, _context: PipelineContext): GreenNode {
+    const actions = plan.actions.filter(a => a.kind === 'collapse-rainbow')
+    if (actions.length === 0) return tree
+
+    const ranges = actions.map(a => ({
+      start: (a.payload.range as { start: number; end: number }).start,
+      end: (a.payload.range as { start: number; end: number }).end,
+    })).sort((a, b) => a.start - b.start)
+
+    return this.transformNode(tree, ranges)
+  }
+
+  private transformNode(node: GreenNode, ranges: Array<{ start: number; end: number }>, treeStart: number = 0): GreenNode {
+    if (node.children.length === 0) return node
+
+    const children = node.children as GreenNode[]
+    // Green nodes carry widths, not positions. The ranges being matched here
+    // come from the analyzers and are absolute, so the walk accumulates the
+    // offsets it needs as it descends.
+    const offsets = childOffsets(node, treeStart)
+    const nodeStart = offsets[0]
+    const nodeEnd = offsets[children.length]
+    const activeRanges = ranges.filter(r => r.start >= nodeStart && r.end <= nodeEnd)
+
+    if (activeRanges.length === 0) {
+      return greenNode(node.kind, node.text, children.map((c, ci) => this.transformNode(c, ranges, offsets[ci])))
+    }
+
+    const newChildren: GreenNode[] = []
+    let i = 0
+
+    while (i < children.length) {
+      const child = children[i]
+      const range = activeRanges.find(r => offsets[i] >= r.start && offsets[i + 1] <= r.end)
+
+      if (range && child.kind === 'color') {
+        const rangeChildren: GreenNode[] = []
+        const texts: string[] = []
+
+        while (i < children.length && offsets[i + 1] <= range.end) {
+          rangeChildren.push(children[i])
+          if (children[i].kind === 'color') {
+            for (const tc of children[i].children as GreenNode[]) {
+              if (tc.kind === 'text') texts.push(tc.text)
+            }
+          } else if (children[i].kind === 'text') {
+            texts.push(children[i].text)
+          }
+          i++
+        }
+
+        const combined = texts.join('')
+        const textLeaf = greenLeaf('text', combined)
+        newChildren.push(greenNode('rainbow', '', [textLeaf]))
+      } else {
+        newChildren.push(this.transformNode(child, ranges, offsets[i]))
+        i++
+      }
+    }
+
+    return greenNode(node.kind, node.text, newChildren)
+  }
+}

package/src/Analysis/Passes/Transform/WaveCollapseTransform.ts

@@ -0,0 +1,88 @@
+/**
+ * Quasar Analysis Framework — Wave Collapse Transform
+ *
+ * Applies `collapse-wave` actions from a TransformationPlan.
+ * Replaces sequences of [size=N] nodes forming a sinusoidal pattern
+ * with a single [grow] node containing all text children and the
+ * detected size range in metadata.
+ *
+ * @example
+ * Before: [size=90]A[/size][size=150]B[/size][size=90]C[/size]
+ * After:  [grow]ABC[/grow]  (with metadata: min=90, max=150)
+ */
+
+import type { TransformPass, TransformationPlan } from '../../Contracts/Pass'
+import type { PipelineContext } from '../../Contracts/PipelineContext'
+import type { GreenNode } from '../../../Syntax/GreenNode'
+import { greenNode, greenLeaf, childOffsets } from '../../../Syntax/GreenNode'
+
+export class WaveCollapseTransform implements TransformPass {
+  readonly id = 'wave-collapse'
+
+  run(tree: GreenNode, plan: TransformationPlan, _context: PipelineContext): GreenNode {
+    const actions = plan.actions.filter(a => a.kind === 'collapse-wave')
+    if (actions.length === 0) return tree
+
+    const ranges = actions.map(a => ({
+      start: (a.payload.range as { start: number; end: number }).start,
+      end: (a.payload.range as { start: number; end: number }).end,
+      min: (a.payload.model as Record<string, unknown>)?.minSize as number ?? 90,
+      max: (a.payload.model as Record<string, unknown>)?.maxSize as number ?? 160,
+    })).sort((a, b) => a.start - b.start)
+
+    return this.transformNode(tree, ranges)
+  }
+
+  private transformNode(
+    node: GreenNode,
+    ranges: Array<{ start: number; end: number; min: number; max: number }>,
+    treeStart: number = 0,
+  ): GreenNode {
+    if (node.children.length === 0) return node
+
+    const children = node.children as GreenNode[]
+    // Green nodes carry widths, not positions. The ranges being matched here
+    // come from the analyzers and are absolute, so the walk accumulates the
+    // offsets it needs as it descends.
+    const offsets = childOffsets(node, treeStart)
+    const nodeStart = offsets[0]
+    const nodeEnd = offsets[children.length]
+    const activeRanges = ranges.filter(r => r.start >= nodeStart && r.end <= nodeEnd)
+
+    if (activeRanges.length === 0) {
+      return greenNode(node.kind, node.text, children.map((c, ci) => this.transformNode(c, ranges, offsets[ci])))
+    }
+
+    const newChildren: GreenNode[] = []
+    let i = 0
+
+    while (i < children.length) {
+      const child = children[i]
+      const range = activeRanges.find(r => offsets[i] >= r.start && offsets[i + 1] <= r.end)
+
+      if (range && ['font_size', 'size'].includes(child.kind)) {
+        const texts: string[] = []
+        while (i < children.length && offsets[i + 1] <= range.end) {
+          if (['font_size', 'size'].includes(children[i].kind)) {
+            for (const tc of children[i].children as GreenNode[]) {
+              if (tc.kind === 'text') texts.push(tc.text)
+            }
+          } else if (children[i].kind === 'text') {
+            texts.push(children[i].text)
+          }
+          i++
+        }
+
+        const combined = texts.join('')
+        const textLeaf = greenLeaf('text', combined)
+        const attr = `=${range.min},${range.max}`
+        newChildren.push(greenNode('grow', attr, [textLeaf]))
+      } else {
+        newChildren.push(this.transformNode(child, ranges, offsets[i]))
+        i++
+      }
+    }
+
+    return greenNode(node.kind, node.text, newChildren)
+  }
+}

package/src/Analysis/Passes/Utility/CharacterCountAnalyzer.ts

@@ -0,0 +1,45 @@
+/**
+ * Quasar Analysis Framework — Character Count Analyzer (Proof of Concept)
+ *
+ * The simplest possible AnalyzerPass: it walks the Green Tree and counts
+ * text characters.  This validates that the full pipeline works:
+ *
+ *   Green Tree → Analyzer → Contribution → Aggregated Report
+ *
+ * No algorithms, no colours, no decisions — just validating the pipe.
+ */
+
+import type { AnalyzerPass } from '../../Contracts/Pass'
+import type { PipelineContext } from '../../Contracts/PipelineContext'
+import type { Contribution } from '../../Contracts/Contribution'
+import { ContributionKind } from '../../Contracts/Contribution'
+import type { GreenNode } from '../../../Syntax/GreenNode'
+
+export class CharacterCountAnalyzer implements AnalyzerPass {
+  readonly id = 'character-count'
+
+  run(tree: GreenNode, _context: PipelineContext): Contribution[] {
+    const count = this.countChars(tree)
+
+    return [
+      {
+        kind: ContributionKind.Metrics,
+        metrics: {
+          characters: count,
+        },
+      },
+    ]
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  private countChars(node: GreenNode): number {
+    let total = node.text?.length ?? 0
+    if (node.children) {
+      for (const child of node.children) {
+        total += this.countChars(child)
+      }
+    }
+    return total
+  }
+}

package/src/Analysis/Pipeline/Pipeline.ts

@@ -0,0 +1,133 @@
+/**
+ * Quasar Analysis Framework — Pipeline
+ *
+ * The Pipeline is itself a Pass — it can be composed inside larger
+ * pipelines.  Execution is strictly ordered:
+ *
+ *   1. All analysis passes run, collecting contributions.
+ *   2. The aggregated AnalysisReport is fed to each decision pass.
+ *   3. Each transform pass receives the current tree + plan and
+ *      returns a new tree (never mutating the original).
+ *
+ * @example
+ * ```ts
+ * const pipeline = new Pipeline([
+ *   { stage: 'analysis', pass: new CharacterCountAnalyzer() },
+ * ])
+ * const report = pipeline.run(tree, context)
+ * ```
+ */
+
+import type { AnalyzerPass, DecisionPass, TransformPass, TransformationPlan } from '../Contracts/Pass'
+import type { AnalysisReport } from '../Contracts/AnalysisReport'
+import type { PipelineContext } from '../Contracts/PipelineContext'
+import type { PipelineStage } from './PipelineStage'
+import type { GreenNode } from '../../Syntax/GreenNode'
+import type { Contribution } from '../Contracts/Contribution'
+
+interface StageEntry {
+  readonly stage: PipelineStage
+  readonly pass: AnalyzerPass | DecisionPass | TransformPass
+}
+
+export interface PipelineResult {
+  /** The final (possibly transformed) Green Tree. */
+  readonly tree: GreenNode
+  /** The aggregated analysis report. */
+  readonly report: AnalysisReport
+}
+
+export class Pipeline {
+  constructor(private readonly stages: readonly StageEntry[]) {}
+
+  // ── Public API ──────────────────────────────────────────────────
+
+  /**
+   * Execute the full pipeline against `tree` with the given `context`.
+   *
+   * @returns The final tree and analysis report.
+   */
+  run(tree: GreenNode, context: PipelineContext): PipelineResult {
+    const start = performance.now()
+    let currentTree = tree
+    const allContributions: Contribution[] = []
+    let latestPlan: TransformationPlan = { actions: [] }
+    const analysisPassCount: number = this.stages.filter(s => s.stage === 'analysis').length
+
+    for (const entry of this.stages) {
+      switch (entry.stage) {
+        case 'analysis':
+          this.runAnalysis(entry.pass as AnalyzerPass, currentTree, context, allContributions)
+          break
+
+        case 'decision': {
+          const report = this.buildReport(allContributions, analysisPassCount, start)
+          latestPlan = this.runDecision(entry.pass as DecisionPass, report, context)
+          break
+        }
+
+        case 'transform':
+          currentTree = this.runTransform(entry.pass as TransformPass, currentTree, latestPlan, context)
+          break
+      }
+    }
+
+    const elapsed = performance.now() - start
+    const report = this.buildReport(allContributions, analysisPassCount, elapsed)
+    return { tree: currentTree, report }
+  }
+
+  /**
+   * Use PipelineBuilder to construct a Pipeline:
+   *
+   * ```ts
+   * import { PipelineBuilder } from './PipelineBuilder'
+   * const pipeline = new PipelineBuilder()
+   *   .analysis(new CharacterCountAnalyzer())
+   *   .build()
+   * ```
+   */
+
+  // ── Internal helpers ────────────────────────────────────────────
+
+  private runAnalysis(
+    pass: AnalyzerPass,
+    tree: GreenNode,
+    context: PipelineContext,
+    sink: Contribution[],
+  ): void {
+    const contributions = pass.run(tree, context)
+    for (const c of contributions) {
+      sink.push(c)
+    }
+  }
+
+  private runDecision(
+    pass: DecisionPass,
+    report: AnalysisReport,
+    context: PipelineContext,
+  ): TransformationPlan {
+    return pass.run(report, context)
+  }
+
+  private runTransform(
+    pass: TransformPass,
+    tree: GreenNode,
+    plan: TransformationPlan,
+    context: PipelineContext,
+  ): GreenNode {
+    return pass.run(tree, plan, context)
+  }
+
+  private buildReport(
+    contributions: Contribution[],
+    passCount: number,
+    elapsedMs: number,
+  ): AnalysisReport {
+    return {
+      contributions: Object.freeze([...contributions]),
+      passCount,
+      elapsedMs,
+    }
+  }
+}