@miliastry/quasar 1.0.6 → 1.1.0

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
+  }
+}

package/src/Edits/Rules/reorderWrappers.ts

@@ -0,0 +1,154 @@
+/**
+ * Quasar — `reorder-wrappers` (opt-in)
+ *
+ * Puts a chain of single-child wrappers into a canonical order:
+ *
+ *   [color=#F00][b]x[/b][/color]  →  [b][color=#F00]x[/color][/b]
+ *
+ * ## It saves no bytes, and that is why it is not in the default preset
+ *
+ * Reordering removes nothing. Its value is canonical form — two documents that
+ * differ only in wrapper order become byte-identical, which is what lets other
+ * rules recognise runs they would otherwise miss. On its own, in a *minifier*,
+ * it produces a diff across someone's document in exchange for zero
+ * characters, so `defaultRules()` leaves it out and callers opt in.
+ *
+ * ## Byte-swaps, never regeneration
+ *
+ * The delimiters are moved, not rebuilt: each slot receives the exact source
+ * bytes of the delimiter that belongs there. `[Color = "#F00"]` comes out the
+ * other side character for character, which a tag-rebuilding implementation
+ * could not promise.
+ *
+ * ## Maximal
+ *
+ * The whole chain is sorted at once. Swapping one adjacent pair at a time
+ * would need repeated passes over offsets that no longer exist, so
+ * `[color][b][i]x[/i][/b][/color]` is permuted in a single step. The sort is
+ * stable, so equal-rank wrappers keep the order the author wrote.
+ */
+
+import type { PlannedEdit } from '../EditPlan'
+import {
+  type OptimizationRule,
+  type RuleContext,
+  type Positioned,
+  positionedChildren,
+  openRange,
+  closeRange,
+  hasBothDelimiters,
+} from './Rule'
+
+export const REORDER_WRAPPERS_PRIORITY = 5
+
+/**
+ * Nesting rank — lower belongs further out.
+ *
+ * Links outermost (a link wrapping styled text is the common authoring
+ * intent), then metrics, then weight/decoration, then colour innermost. Kinds
+ * absent from the table are not reordered at all: an unranked tag may carry
+ * layout or semantics that nesting order changes.
+ */
+const RANK: Readonly<Record<string, number>> = {
+  url: 1,
+  email: 1,
+  profile: 1,
+  font_size: 2,
+  font: 2,
+  bold: 3,
+  italic: 3,
+  underline: 3,
+  strikethrough: 3,
+  color: 4,
+}
+
+export class ReorderWrappersRule implements OptimizationRule {
+  readonly id = 'reorder-wrappers'
+  readonly priority = REORDER_WRAPPERS_PRIORITY
+  readonly label = 'Canonicalise nested wrapper order'
+
+  run(context: RuleContext): PlannedEdit[] {
+    const sink: PlannedEdit[] = []
+    this.scan({ node: context.root, start: 0 }, context.source, sink)
+    sink.sort((a, b) => a.start - b.start || a.end - b.end)
+    return sink
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  private scan(item: Positioned, source: string, sink: PlannedEdit[]): void {
+    for (const child of positionedChildren(item)) {
+      const chain = this.chainFrom(child)
+
+      if (chain.length >= 2) {
+        this.emitPermutation(chain, source, sink)
+        // Continue below the chain. `scan` iterates its argument's children,
+        // so the innermost wrapper is what gets handed down — passing its
+        // children instead would skip a level.
+        this.scan(chain[chain.length - 1], source, sink)
+        continue
+      }
+
+      this.scan(child, source, sink)
+    }
+  }
+
+  /** The maximal run of rankable single-child wrappers starting at `item`. */
+  private chainFrom(item: Positioned): Positioned[] {
+    const chain: Positioned[] = []
+    let current: Positioned | undefined = item
+
+    while (
+      current &&
+      RANK[current.node.kind] !== undefined &&
+      hasBothDelimiters(current) &&
+      current.node.children.length === 1
+    ) {
+      chain.push(current)
+      const [only] = positionedChildren(current)
+      current = only
+    }
+    return chain
+  }
+
+  private emitPermutation(
+    chain: readonly Positioned[],
+    source: string,
+    sink: PlannedEdit[],
+  ): void {
+    const order = chain.map((_, index) => index)
+    // Stable by construction: ties fall back to the original index.
+    order.sort((a, b) => RANK[chain[a].node.kind] - RANK[chain[b].node.kind] || a - b)
+
+    if (order.every((sourceIndex, slot) => sourceIndex === slot)) return
+
+    const label = `Canonicalise ${chain.map(c => `[${c.node.kind}]`).join('')}`
+
+    for (let slot = 0; slot < chain.length; slot++) {
+      const from = chain[order[slot]]
+      if (order[slot] === slot) continue
+
+      const openSlot = openRange(chain[slot])
+      const closeSlot = closeRange(chain[slot])
+      const openFrom = openRange(from)
+      const closeFrom = closeRange(from)
+
+      sink.push({
+        start: openSlot.start,
+        end: openSlot.end,
+        text: source.slice(openFrom.start, openFrom.end),
+        ruleId: this.id,
+        priority: this.priority,
+        label,
+      })
+      sink.push({
+        start: closeSlot.start,
+        end: closeSlot.end,
+        text: source.slice(closeFrom.start, closeFrom.end),
+        ruleId: this.id,
+        priority: this.priority,
+        label,
+      })
+    }
+  }
+}