@miliastry/quasar 1.0.6 → 1.2.0

package/src/Edits/Rules/Rule.ts

@@ -0,0 +1,145 @@
+/**
+ * Quasar — Optimization Rule contract
+ *
+ * Every rule reads the Green Tree and returns `PlannedEdit[]` addressed to
+ * offsets in the ORIGINAL source. Rules never mutate the tree, never build a
+ * new one, and never see each other's output — the only thing that arbitrates
+ * between them is `resolveEditConflicts`.
+ *
+ * Three obligations, all of them load-bearing:
+ *
+ * 1. **Maximal.** A rule emits the final form in one pass. It may not rely on
+ *    being run again: applying an edit invalidates every later offset, so
+ *    there is no second pass to be had. Where `ASTOptimizer` merged pairwise
+ *    and iterated to a fixpoint, a rule here recognises the whole run.
+ * 2. **Deterministic.** Same tree in, same edits out, in the same order.
+ * 3. **Spelling-preserving.** Prefer deleting the author's bytes over
+ *    generating replacements. `[Color = "#FF0000"]` must survive a merge
+ *    intact; the exporter would have rewritten it to `[color=#FF0000]`.
+ *
+ * @see resolveEditConflicts
+ */
+
+import type { GreenNode } from '../../Syntax/GreenNode'
+import { childOffsets } from '../../Syntax/GreenNode'
+import type { PlannedEdit } from '../EditPlan'
+
+// ── Contract ──────────────────────────────────────────────────────
+
+export interface RuleContext {
+  /** The document exactly as the author wrote it. */
+  readonly source: string
+  /** Green root, whose width equals `source.length`. */
+  readonly root: GreenNode
+}
+
+export interface OptimizationRule {
+  /** Stable identifier; also the final tie-break in the conflict order. */
+  readonly id: string
+  /**
+   * Arbitration weight. A rule that rewrites a whole region must outrank the
+   * rules that tweak tokens inside it, so the region's own normal form wins.
+   */
+  readonly priority: number
+  /** Short human label, shown in the "what did the minifier do" list. */
+  readonly label: string
+  run(context: RuleContext): PlannedEdit[]
+}
+
+// ── Positioned tree walking ───────────────────────────────────────
+
+/**
+ * A node together with its absolute start offset in the source.
+ *
+ * Green nodes carry widths, not positions, so every rule that wants a range
+ * has to accumulate offsets on the way down. This pairing is what the rules
+ * pass around instead of bare nodes.
+ */
+export interface Positioned {
+  readonly node: GreenNode
+  readonly start: number
+}
+
+/** Absolute end offset (exclusive). */
+export function endOf(p: Positioned): number {
+  return p.start + p.node.width
+}
+
+/** The range of the opening delimiter — `[color=#F00]`. */
+export function openRange(p: Positioned): { start: number; end: number } {
+  return { start: p.start, end: p.start + p.node.leadingWidth }
+}
+
+/** The range of the closing delimiter — `[/color]`. */
+export function closeRange(p: Positioned): { start: number; end: number } {
+  const end = endOf(p)
+  return { start: end - p.node.trailingWidth, end }
+}
+
+/** Children paired with their absolute offsets, in document order. */
+export function positionedChildren(p: Positioned): Positioned[] {
+  const children = p.node.children as readonly GreenNode[]
+  if (children.length === 0) return []
+  const offsets = childOffsets(p.node, p.start)
+  const out: Positioned[] = new Array(children.length)
+  for (let i = 0; i < children.length; i++) {
+    out[i] = { node: children[i], start: offsets[i] }
+  }
+  return out
+}
+
+/**
+ * A node that actually has both delimiters in the source.
+ *
+ * The parser synthesises a closing tag for `[b]never closed`, which comes back
+ * as `trailingWidth === 0`. Deleting a delimiter that occupies no bytes is a
+ * no-op at best; treating a synthetic close as if it were real is a
+ * correctness bug. Rules that move or remove delimiters check this first.
+ */
+export function hasBothDelimiters(p: Positioned): boolean {
+  return p.node.leadingWidth > 0 && p.node.trailingWidth > 0
+}
+
+// ── Edit construction ─────────────────────────────────────────────
+
+/** A deletion of an exact source range. */
+export function deletion(
+  range: { start: number; end: number },
+  ruleId: string,
+  priority: number,
+  label?: string,
+): PlannedEdit {
+  return { start: range.start, end: range.end, text: '', ruleId, priority, label }
+}
+
+/**
+ * Merge deletions that touch into single edits.
+ *
+ * Two deletions `[a,b)` and `[b,c)` are legal side by side — the conflict
+ * resolver calls them disjoint — but they describe one contiguous removal.
+ * Emitting them separately inflates the edit count for no benefit and makes
+ * the "N optimisations applied" number lie about how much happened.
+ *
+ * Input must be sorted by `start` and non-overlapping.
+ */
+export function coalesceDeletions(edits: readonly PlannedEdit[]): PlannedEdit[] {
+  if (edits.length < 2) return [...edits]
+
+  const out: PlannedEdit[] = []
+  for (const edit of edits) {
+    const previous = out[out.length - 1]
+    const joinable =
+      previous !== undefined &&
+      previous.text === '' &&
+      edit.text === '' &&
+      previous.end === edit.start &&
+      previous.ruleId === edit.ruleId &&
+      previous.priority === edit.priority
+    if (joinable) {
+      out[out.length - 1] = { ...previous, end: edit.end }
+    } else {
+      out.push(edit)
+    }
+  }
+  return out
+}

package/src/Edits/Rules/dropEmptyTags.ts

@@ -0,0 +1,110 @@
+/**
+ * Quasar — `drop-empty-tags`
+ *
+ * Removes formatting tags that enclose nothing: `[b][/b]`, `[color=#F00][/color]`.
+ *
+ * ## Only tags whose absence is invisible
+ *
+ * The droppable set is an explicit allowlist of inline formatting, not "any
+ * tag with no children". An empty `[box]` still draws a frame, an empty
+ * `[quote]` still draws a quote block, and `[img]`/`[youtube]` carry their
+ * payload in the attribute rather than in children — deleting any of those
+ * changes what the reader sees. Anything not on the list stays, including
+ * tags this engine does not recognise.
+ *
+ * ## Outermost-first, so no second pass is needed
+ *
+ * `[b][i][/i][/b]` is empty all the way down. Dropping the inner tag would
+ * leave `[b][/b]`, which is empty again — the classic reason `ASTOptimizer`
+ * needs a fixpoint. Instead this rule asks whether a node renders nothing
+ * *transitively* and deletes the outermost one it finds, in a single edit,
+ * without descending into it.
+ */
+
+import type { GreenNode } from '../../Syntax/GreenNode'
+import type { PlannedEdit } from '../EditPlan'
+import {
+  type OptimizationRule,
+  type RuleContext,
+  type Positioned,
+  positionedChildren,
+  hasBothDelimiters,
+  deletion,
+} from './Rule'
+
+export const DROP_EMPTY_PRIORITY = 80
+
+/**
+ * Inline formatting whose empty form is guaranteed to render nothing.
+ *
+ * Deliberately conservative. A kind is only here if an empty instance of it
+ * produces no glyphs, no box, no line break and no side effect.
+ */
+export const DROPPABLE_WHEN_EMPTY: ReadonlySet<string> = new Set([
+  'bold',
+  'italic',
+  'underline',
+  'strikethrough',
+  'color',
+  'font_size',
+  'font',
+  'sup',
+  'sub',
+  'mark',
+])
+
+export class DropEmptyTagsRule implements OptimizationRule {
+  readonly id = 'drop-empty-tags'
+  readonly priority = DROP_EMPTY_PRIORITY
+  readonly label = 'Remove empty formatting tags'
+
+  run(context: RuleContext): PlannedEdit[] {
+    const sink: PlannedEdit[] = []
+    this.scan({ node: context.root, start: 0 }, sink)
+    return sink
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  private scan(item: Positioned, sink: PlannedEdit[]): void {
+    for (const child of positionedChildren(item)) {
+      if (this.isDroppable(child)) {
+        sink.push(
+          deletion(
+            { start: child.start, end: child.start + child.node.width },
+            this.id,
+            this.priority,
+            `Remove empty [${child.node.kind}]`,
+          ),
+        )
+        // Deleted whole; nothing inside it can still be worth an edit.
+        continue
+      }
+      this.scan(child, sink)
+    }
+  }
+
+  private isDroppable(item: Positioned): boolean {
+    return (
+      DROPPABLE_WHEN_EMPTY.has(item.node.kind) &&
+      hasBothDelimiters(item) &&
+      rendersNothing(item.node)
+    )
+  }
+}
+
+/**
+ * Whether a node contributes no visible output at all.
+ *
+ * `spacing` and `empty_line` are explicitly *not* nothing — they are the
+ * document's line breaks.
+ */
+function rendersNothing(node: GreenNode): boolean {
+  if (node.kind === 'text') return (node.text ?? '') === ''
+  if (node.kind === 'spacing' || node.kind === 'empty_line') return false
+  if (!DROPPABLE_WHEN_EMPTY.has(node.kind)) return false
+
+  const children = node.children as readonly GreenNode[]
+  if (children.length === 0) return node.width - node.leadingWidth - node.trailingWidth === 0
+  return children.every(rendersNothing)
+}

package/src/Edits/Rules/dropRedundantNesting.ts

@@ -0,0 +1,120 @@
+/**
+ * Quasar — `drop-redundant-nesting`
+ *
+ * Removes a tag nested directly inside an identical one:
+ *
+ *   [color=#F00]a[color=#F00]b[/color][/color]  →  [color=#F00]ab[/color]
+ *
+ * The inner delimiters are the ones deleted, so the outer tag — and the
+ * author's spelling of it — is what survives.
+ *
+ * Identity is the same normalised comparison the merge rule uses, so
+ * `[color=#F00]` inside `[color=#FF0000]` counts as redundant: the colours are
+ * equal even though the spellings are not.
+ *
+ * Siblings do not disqualify anything. In `[color=X]a[color=X]b[/color][/color]`
+ * the inner tag is still setting a colour that is already in force, so
+ * dropping its delimiters cannot change the render.
+ *
+ * ## Only tags that do nothing when nested in themselves
+ *
+ * "Redundant" has to be earned, not assumed. `[size=50]` renders as
+ * `font-size:50%`, and a percentage is relative to its parent — so
+ * `[size=50][size=50]x[/size][/size]` is 25%, not 50%, and the inner tag is
+ * doing real work. `[sup]` stacks its vertical offset the same way. Removing
+ * either would shrink or lift the text, which is not a smaller document, it is
+ * a different one.
+ *
+ * @see IDEMPOTENT_WHEN_NESTED
+ */
+
+import type { PlannedEdit } from '../EditPlan'
+import {
+  type OptimizationRule,
+  type RuleContext,
+  type Positioned,
+  positionedChildren,
+  openRange,
+  closeRange,
+  hasBothDelimiters,
+  deletion,
+} from './Rule'
+import { mergeIdentity } from './tagValue'
+
+export const DROP_REDUNDANT_NESTING_PRIORITY = 90
+
+/**
+ * Kinds whose effect is unchanged by being applied twice.
+ *
+ * A colour inside the same colour is still that colour; bold inside bold is
+ * still bold. Excluded are the properties that **compound**: `font_size`
+ * multiplies percentages, and `sup`/`sub` add their vertical offsets. Anything
+ * not listed is left alone, unknown tags included.
+ */
+export const IDEMPOTENT_WHEN_NESTED: ReadonlySet<string> = new Set([
+  'color',
+  'bold',
+  'italic',
+  'underline',
+  'strikethrough',
+  'font',
+  'mark',
+])
+
+export class DropRedundantNestingRule implements OptimizationRule {
+  readonly id = 'drop-redundant-nesting'
+  readonly priority = DROP_REDUNDANT_NESTING_PRIORITY
+  readonly label = 'Remove tags nested inside an identical tag'
+
+  run(context: RuleContext): PlannedEdit[] {
+    const sink: PlannedEdit[] = []
+    this.scan({ node: context.root, start: 0 }, new Map(), sink)
+    sink.sort((a, b) => a.start - b.start || a.end - b.end)
+    return sink
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  /**
+   * `inForce` maps a node kind to the identity its NEAREST ancestor of that
+   * kind established.
+   *
+   * Keyed by kind rather than carrying a single inherited identity, because an
+   * ancestor's colour survives an intervening tag of another kind:
+   * `[color=X][b][color=X]…` is still redundant. Overwriting on the way down
+   * is what makes it the *nearest* ancestor — in
+   * `[color=X][color=Y][color=X]…` the innermost tag restores a colour that Y
+   * had overridden, so it is doing real work and must stay.
+   */
+  private scan(
+    item: Positioned,
+    inForce: ReadonlyMap<string, string>,
+    sink: PlannedEdit[],
+  ): void {
+    for (const child of positionedChildren(item)) {
+      const identity = mergeIdentity(child.node)
+
+      if (
+        identity !== null &&
+        IDEMPOTENT_WHEN_NESTED.has(child.node.kind) &&
+        inForce.get(child.node.kind) === identity &&
+        hasBothDelimiters(child)
+      ) {
+        const label = `Remove redundant nested [${child.node.kind}]`
+        sink.push(deletion(openRange(child), this.id, this.priority, label))
+        sink.push(deletion(closeRange(child), this.id, this.priority, label))
+        // Deleting the delimiters leaves the ancestor's identity in force.
+        this.scan(child, inForce, sink)
+        continue
+      }
+
+      if (identity === null) {
+        this.scan(child, inForce, sink)
+      } else {
+        const nested = new Map(inForce)
+        nested.set(child.node.kind, identity)
+        this.scan(child, nested, sink)
+      }
+    }
+  }
+}

package/src/Edits/Rules/index.ts

@@ -0,0 +1,28 @@
+export type { OptimizationRule, RuleContext, Positioned } from './Rule'
+export {
+  endOf,
+  openRange,
+  closeRange,
+  positionedChildren,
+  hasBothDelimiters,
+  deletion,
+  coalesceDeletions,
+} from './Rule'
+export {
+  attributeValue,
+  normalizeColorValue,
+  shortenableHex,
+  mergeIdentity,
+  MERGEABLE_INLINE,
+  BRIDGES_WHITESPACE,
+} from './tagValue'
+export { MergeAdjacentRule, MERGE_ADJACENT_PRIORITY, type MergeAdjacentOptions } from './mergeAdjacent'
+export { DropEmptyTagsRule, DROP_EMPTY_PRIORITY, DROPPABLE_WHEN_EMPTY } from './dropEmptyTags'
+export { DropRedundantNestingRule, DROP_REDUNDANT_NESTING_PRIORITY } from './dropRedundantNesting'
+export { ShortenHexRule, SHORTEN_HEX_PRIORITY } from './shortenHex'
+export {
+  UnwrapInvisibleColorRule,
+  UNWRAP_INVISIBLE_COLOR_PRIORITY,
+  isInvisibleWhitespace,
+} from './unwrapInvisibleColor'
+export { ReorderWrappersRule, REORDER_WRAPPERS_PRIORITY } from './reorderWrappers'

package/src/Edits/Rules/mergeAdjacent.ts

@@ -0,0 +1,224 @@
+/**
+ * Quasar — `merge-adjacent`
+ *
+ * Fuses runs of identically-attributed sibling tags into one:
+ *
+ *   [color=#FF0000]H[/color][color=#FF0000]e[/color][color=#FF0000]y[/color]
+ *   → [color=#FF0000]Hey[/color]
+ *
+ * This is where the bytes are. A per-character gradient spends ~23 bytes of
+ * delimiter on every 1 byte of text; collapsing a run of identical colours is
+ * the single largest saving available on a real userpage.
+ *
+ * ## It only ever deletes
+ *
+ * The merged tag is not generated. The first member's opening delimiter and
+ * the last member's closing delimiter are left exactly as the author typed
+ * them, and only the seams between members are removed:
+ *
+ *   [Color = "#F00"]a[/color][color=#ff0000]b[/color]
+ *   [Color = "#F00"]a‹  deleted  ›b[/color]
+ *
+ * So `[Color = "#F00"]` survives with its capital C, its spaces and its
+ * quotes. A rule that rebuilt the tag would have normalised all three, which
+ * is exactly the drift that makes whole-document re-export unusable in an
+ * editor.
+ *
+ * ## Maximal in one pass
+ *
+ * `ASTOptimizer` merges pairwise and iterates to a fixpoint. Edits addressed
+ * to the original source cannot do that — applying one invalidates every later
+ * offset — so this rule recognises the **whole run at once**, and then
+ * descends into the content the merge is about to create:
+ *
+ *   [b][color=X]a[/color][/b][b][color=X]bc[/color][/b]
+ *
+ * Merging the two `[b]` makes their colour children siblings, and those merge
+ * too. The recursion walks that *virtual* child list, so both levels come out
+ * of a single pass. Crucially the inner seams sit inside the members' content
+ * and the outer seams sit between members, so the two sets never overlap.
+ *
+ * @see mergeIdentity — what "identically attributed" means
+ * @see BRIDGES_WHITESPACE — when a gap between members may be absorbed
+ */
+
+import type { GreenNode } from '../../Syntax/GreenNode'
+import type { PlannedEdit } from '../EditPlan'
+import {
+  type OptimizationRule,
+  type RuleContext,
+  type Positioned,
+  positionedChildren,
+  openRange,
+  closeRange,
+  hasBothDelimiters,
+  deletion,
+  coalesceDeletions,
+} from './Rule'
+import { mergeIdentity, BRIDGES_WHITESPACE, attributeValue } from './tagValue'
+import { isInvisibleWhitespace } from './unwrapInvisibleColor'
+
+/** Horizontal whitespace only — a newline is a paragraph break, never a gap. */
+const HORIZONTAL_BLANK = /^[ \t]*$/
+
+export const MERGE_ADJACENT_PRIORITY = 100
+
+export interface MergeAdjacentOptions {
+  /**
+   * Restrict the rule to these node kinds. Omitted, every kind
+   * {@link mergeIdentity} recognises is eligible.
+   */
+  readonly kinds?: ReadonlySet<string>
+}
+
+export class MergeAdjacentRule implements OptimizationRule {
+  readonly id = 'merge-adjacent'
+  readonly priority = MERGE_ADJACENT_PRIORITY
+  readonly label = 'Merge adjacent identical tags'
+
+  private readonly kinds?: ReadonlySet<string>
+
+  constructor(options: MergeAdjacentOptions = {}) {
+    this.kinds = options.kinds
+  }
+
+  run(context: RuleContext): PlannedEdit[] {
+    const sink: PlannedEdit[] = []
+    this.scan(positionedChildren({ node: context.root, start: 0 }), sink)
+    // Emitted parent-first; the plan reads better in document order, and
+    // `coalesceDeletions` requires it.
+    sink.sort((a, b) => a.start - b.start || a.end - b.end)
+    return coalesceDeletions(sink)
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  private identityOf(node: GreenNode): string | null {
+    if (this.kinds && !this.kinds.has(node.kind)) return null
+
+    // A colour wrapping nothing but whitespace is never a run *member*, only
+    // ever a bridge — `unwrap-invisible-color` owns those delimiters.
+    //
+    // Adopting one as a member is a genuine corruption, and an instructive
+    // one: a merged run keeps its first member's opening delimiter, so when
+    // the whitespace node led the run, merge kept the delimiter that unwrap
+    // was independently deleting. The two edits do not overlap, so the
+    // conflict resolver — which can only arbitrate claims on the same bytes —
+    // had nothing to arbitrate, and the document came out with an unbalanced
+    // `[/color]`. Rules must not depend on each other's edits surviving.
+    if (node.kind === 'color' && isInvisibleWhitespace(node)) return null
+
+    return mergeIdentity(node)
+  }
+
+  /**
+   * A node that may sit between two members and be absorbed by the merge.
+   *
+   * Blank text, or a colour tag wrapping nothing but blank text — the shape
+   * `unwrap-invisible-color` exists to delete. Treating it as a gap rather
+   * than as a wall lets `[color=A]x[/color][color=B] [/color][color=A]y[/color]`
+   * still fuse its two `A` members; the `B` tag survives this rule untouched
+   * and is removed by the other one, whose edits are disjoint from these.
+   */
+  private isBridge(item: Positioned): boolean {
+    if (item.node.kind === 'text') return HORIZONTAL_BLANK.test(item.node.text ?? '')
+    return item.node.kind === 'color' && isInvisibleWhitespace(item.node)
+  }
+
+  /**
+   * Walk one sibling list, fusing every maximal run it contains.
+   *
+   * The list is not always a real node's children: after a merge is planned,
+   * the members' children are spliced together and scanned as the sibling list
+   * the merged tag will actually have.
+   */
+  private scan(items: readonly Positioned[], sink: PlannedEdit[]): void {
+    let i = 0
+
+    while (i < items.length) {
+      const identity = this.identityOf(items[i].node)
+
+      if (identity === null) {
+        this.scan(positionedChildren(items[i]), sink)
+        i++
+        continue
+      }
+
+      const bridges = BRIDGES_WHITESPACE.has(items[i].node.kind)
+      const members: number[] = [i]
+
+      // Extend while the next sibling is either another member or — for kinds
+      // where it is invisible — blank text between two of them.
+      let j = i + 1
+      while (j < items.length) {
+        if (this.identityOf(items[j].node) === identity) {
+          members.push(j)
+          j++
+          continue
+        }
+        if (bridges && this.isBridge(items[j])) {
+          j++
+          continue
+        }
+        break
+      }
+
+      const last = members[members.length - 1]
+      const merging =
+        members.length >= 2 && members.every(index => hasBothDelimiters(items[index]))
+
+      if (merging) {
+        this.emitSeams(items, members, sink)
+        this.scan(this.virtualContent(items, members, last), sink)
+      } else {
+        // No merge: every element up to and including the last member still
+        // has to be visited on its own.
+        for (let t = i; t <= last; t++) this.scan(positionedChildren(items[t]), sink)
+      }
+
+      i = last + 1
+    }
+  }
+
+  /**
+   * Delete each member's closing delimiter and the next member's opening one.
+   *
+   * Two edits per seam rather than one span, because a bridge may sit between
+   * them and must survive. When nothing separates them the two deletions touch
+   * and `coalesceDeletions` folds them back into a single edit.
+   */
+  private emitSeams(
+    items: readonly Positioned[],
+    members: readonly number[],
+    sink: PlannedEdit[],
+  ): void {
+    const head = items[members[0]].node
+    const what = attributeValue(head) ? `${head.kind}=${attributeValue(head)}` : head.kind
+    const label = `Merge ${members.length} × [${what}]`
+
+    for (let m = 0; m < members.length - 1; m++) {
+      const current = items[members[m]]
+      const next = items[members[m + 1]]
+      sink.push(deletion(closeRange(current), this.id, this.priority, label))
+      sink.push(deletion(openRange(next), this.id, this.priority, label))
+    }
+  }
+
+  /**
+   * The sibling list the merged tag will hold: every member's children in
+   * order, with any bridging text kept in place between them.
+   */
+  private virtualContent(
+    items: readonly Positioned[],
+    members: readonly number[],
+    last: number,
+  ): Positioned[] {
+    const isMember = new Set(members)
+    const out: Positioned[] = []
+    for (let t = members[0]; t <= last; t++) {
+      if (isMember.has(t)) out.push(...positionedChildren(items[t]))
+      else out.push(items[t])
+    }
+    return out
+  }
+}