@herb-tools/formatter 0.8.10 → 0.9.0

package/src/formatter.ts

@@ -6,7 +6,7 @@ import { hasFormatterIgnoreDirective } from "./format-ignore.js"
 
 import type { Config } from "@herb-tools/config"
 import type { RewriteContext } from "@herb-tools/rewriter"
-import type { HerbBackend, ParseResult } from "@herb-tools/core"
+import type { HerbBackend, ParseResult, ParseOptions } from "@herb-tools/core"
 import type { FormatOptions } from "./options.js"
 
 /**
@@ -16,6 +16,7 @@ import type { FormatOptions } from "./options.js"
 export class Formatter {
   private herb: HerbBackend
   private options: Required<FormatOptions>
+  private parseOptions: ParseOptions
 
   /**
    * Creates a Formatter instance from a Config object (recommended).
@@ -48,16 +49,21 @@ export class Formatter {
    * @param herb - The Herb backend instance for parsing
    * @param options - Format options (including rewriters)
    */
-  constructor(herb: HerbBackend, options: FormatOptions = {}) {
+  constructor(herb: HerbBackend, options: FormatOptions = {}, parseOptions: ParseOptions = {}) {
     this.herb = herb
     this.options = resolveFormatOptions(options)
+    this.parseOptions = parseOptions
   }
 
   /**
    * Format a source string, optionally overriding format options per call.
    */
   format(source: string, options: FormatOptions = {}, filePath?: string): string {
-    let result = this.parse(source)
+    const result = this.parse(source)
+
+    if (result.options.action_view_helpers) {
+      console.warn("[Herb Formatter] Warning: Formatting a document parsed with `action_view_helpers: true`. The result may not be 100% accurate.")
+    }
 
     if (result.failed) return source
     if (isScaffoldTemplate(result)) return source
@@ -104,6 +110,6 @@ export class Formatter {
 
   private parse(source: string): ParseResult {
     this.herb.ensureBackend()
-    return this.herb.parse(source)
+    return this.herb.parse(source, this.parseOptions)
   }
 }

package/src/spacing-analyzer.ts

@@ -0,0 +1,244 @@
+import { Node, HTMLTextNode, HTMLElementNode, HTMLDoctypeNode, ERBContentNode, WhitespaceNode, XMLDeclarationNode } from "@herb-tools/core"
+import { isNode, getTagName, isERBNode, isERBOutputNode, isERBCommentNode, isCommentNode, isERBControlFlowNode } from "@herb-tools/core"
+import { findPreviousMeaningfulSibling, isBlockLevelNode, isContentPreserving, isNonWhitespaceNode } from "./format-helpers.js"
+
+import { INLINE_ELEMENTS, SPACEABLE_CONTAINERS } from "./format-helpers.js"
+
+/**
+ * SpacingAnalyzer determines when blank lines should be inserted between
+ * sibling elements. It implements the "rule of three" intelligent spacing
+ * system: adds spacing between 3+ meaningful siblings, respects semantic
+ * groupings, groups comments with following elements, and preserves
+ * user-added spacing.
+ */
+export class SpacingAnalyzer {
+  private nodeIsMultiline: Map<Node, boolean>
+  private tagGroupsCache = new Map<Node[], Map<number, { tagName: string; groupStart: number; groupEnd: number }>>()
+  private allSingleLineCache = new Map<Node[], boolean>()
+
+  constructor(nodeIsMultiline: Map<Node, boolean>) {
+    this.nodeIsMultiline = nodeIsMultiline
+  }
+
+  clear(): void {
+    this.tagGroupsCache.clear()
+    this.allSingleLineCache.clear()
+  }
+
+  /**
+   * Determine if spacing should be added between sibling elements
+   *
+   * This implements the "rule of three" intelligent spacing system:
+   * - Adds spacing between 3 or more meaningful siblings
+   * - Respects semantic groupings (e.g., ul/li, nav/a stay tight)
+   * - Groups comments with following elements
+   * - Preserves user-added spacing
+   *
+   * @param parentElement - The parent element containing the siblings
+   * @param siblings - Array of all sibling nodes
+   * @param currentIndex - Index of the current node being evaluated
+   * @returns true if spacing should be added before the current element
+   */
+  shouldAddSpacingBetweenSiblings(parentElement: HTMLElementNode | null, siblings: Node[], currentIndex: number): boolean {
+    const currentNode = siblings[currentIndex]
+    const previousMeaningfulIndex = findPreviousMeaningfulSibling(siblings, currentIndex)
+    const previousNode = previousMeaningfulIndex !== -1 ? siblings[previousMeaningfulIndex] : null
+
+    if (previousNode && (isNode(previousNode, XMLDeclarationNode) || isNode(previousNode, HTMLDoctypeNode))) {
+      return true
+    }
+
+    const hasMixedContent = siblings.some(child => isNode(child, HTMLTextNode) && child.content.trim() !== "")
+
+    if (hasMixedContent) return false
+
+    const isCurrentComment = isCommentNode(currentNode)
+    const isPreviousComment = previousNode ? isCommentNode(previousNode) : false
+    const isCurrentMultiline = this.isMultilineElement(currentNode)
+    const isPreviousMultiline = previousNode ? this.isMultilineElement(previousNode) : false
+
+    if (isPreviousComment && !isCurrentComment && (isNode(currentNode, HTMLElementNode) || isERBNode(currentNode))) {
+      return isPreviousMultiline && isCurrentMultiline
+    }
+
+    if (isPreviousComment && isCurrentComment) {
+      return false
+    }
+
+    if (isCurrentMultiline || isPreviousMultiline) {
+      return true
+    }
+
+    const meaningfulSiblings = siblings.filter(child => isNonWhitespaceNode(child))
+    const parentTagName = parentElement ? getTagName(parentElement) : null
+    const isSpaceableContainer = !parentTagName || SPACEABLE_CONTAINERS.has(parentTagName)
+    const tagGroups = this.detectTagGroups(siblings)
+
+    const cached = this.allSingleLineCache.get(siblings)
+    let allSingleLineHTMLElements: boolean
+    if (cached !== undefined) {
+      allSingleLineHTMLElements = cached
+    } else {
+      allSingleLineHTMLElements = meaningfulSiblings.every(node => isNode(node, HTMLElementNode) && !this.isMultilineElement(node))
+      this.allSingleLineCache.set(siblings, allSingleLineHTMLElements)
+    }
+
+    if (!isSpaceableContainer && meaningfulSiblings.length < 5) {
+      return false
+    }
+
+    const currentGroup = tagGroups.get(currentIndex)
+    const previousGroup = previousNode ? tagGroups.get(previousMeaningfulIndex) : undefined
+
+    if (currentGroup && previousGroup && currentGroup.groupStart === previousGroup.groupStart && currentGroup.groupEnd === previousGroup.groupEnd) {
+      return false
+    }
+
+    if (previousGroup && previousGroup.groupEnd === previousMeaningfulIndex) {
+      return true
+    }
+
+    if (allSingleLineHTMLElements && tagGroups.size === 0) {
+      return false
+    }
+
+    if (isNode(currentNode, HTMLElementNode)) {
+      const currentTagName = getTagName(currentNode)
+
+      if (currentTagName && INLINE_ELEMENTS.has(currentTagName)) {
+        return false
+      }
+    }
+
+    const isBlockElement = isBlockLevelNode(currentNode)
+    const isERBBlock = isERBNode(currentNode) && isERBControlFlowNode(currentNode)
+    const isComment = isCommentNode(currentNode)
+
+    return isBlockElement || isERBBlock || isComment
+  }
+
+  /**
+   * Check if there's a blank line (double newline) in the nodes at the given index
+   */
+  hasBlankLineBetween(body: Node[], index: number): boolean {
+    for (let lookbackIndex = index - 1; lookbackIndex >= 0 && lookbackIndex >= index - 2; lookbackIndex--) {
+      const node = body[lookbackIndex]
+
+      if (isNode(node, HTMLTextNode) && node.content.includes('\n\n')) {
+        return true
+      }
+
+      if (isNode(node, WhitespaceNode)) {
+        continue
+      }
+
+      break
+    }
+
+    for (let lookaheadIndex = index; lookaheadIndex < body.length && lookaheadIndex <= index + 1; lookaheadIndex++) {
+      const node = body[lookaheadIndex]
+
+      if (isNode(node, HTMLTextNode) && node.content.includes('\n\n')) {
+        return true
+      }
+
+      if (isNode(node, WhitespaceNode)) {
+        continue
+      }
+
+      break
+    }
+
+    return false
+  }
+
+  /**
+   * Check if a node will render as multiple lines when formatted.
+   */
+  private isMultilineElement(node: Node): boolean {
+    if (isNode(node, ERBContentNode)) {
+      return (node.content?.value || "").includes("\n")
+    }
+
+    if (isNode(node, HTMLElementNode) && isContentPreserving(node)) {
+      return true
+    }
+
+    const tracked = this.nodeIsMultiline.get(node)
+
+    if (tracked !== undefined) {
+      return tracked
+    }
+
+    return false
+  }
+
+  /**
+   * Get a grouping key for a node (tag name for HTML, ERB type for ERB)
+   */
+  private getGroupingKey(node: Node): string | null {
+    if (isNode(node, HTMLElementNode)) {
+      return getTagName(node)
+    }
+
+    if (isERBOutputNode(node)) return "erb-output"
+    if (isERBCommentNode(node)) return "erb-comment"
+    if (isERBNode(node)) return "erb-code"
+
+    return null
+  }
+
+  /**
+   * Detect groups of consecutive same-tag/same-type single-line elements
+   * Returns a map of index -> group info for efficient lookup
+   */
+  private detectTagGroups(siblings: Node[]): Map<number, { tagName: string; groupStart: number; groupEnd: number }> {
+    const cached = this.tagGroupsCache.get(siblings)
+    if (cached) return cached
+
+    const groupMap = new Map<number, { tagName: string; groupStart: number; groupEnd: number }>()
+    const meaningfulNodes: Array<{ index: number; groupKey: string }> = []
+
+    for (let i = 0; i < siblings.length; i++) {
+      const node = siblings[i]
+
+      if (!this.isMultilineElement(node)) {
+        const groupKey = this.getGroupingKey(node)
+
+        if (groupKey) {
+          meaningfulNodes.push({ index: i, groupKey })
+        }
+      }
+    }
+
+    let groupStart = 0
+
+    while (groupStart < meaningfulNodes.length) {
+      const startGroupKey = meaningfulNodes[groupStart].groupKey
+      let groupEnd = groupStart
+
+      while (groupEnd + 1 < meaningfulNodes.length && meaningfulNodes[groupEnd + 1].groupKey === startGroupKey) {
+        groupEnd++
+      }
+
+      if (groupEnd > groupStart) {
+        const groupStartIndex = meaningfulNodes[groupStart].index
+        const groupEndIndex = meaningfulNodes[groupEnd].index
+
+        for (let i = groupStart; i <= groupEnd; i++) {
+          groupMap.set(meaningfulNodes[i].index, {
+            tagName: startGroupKey,
+            groupStart: groupStartIndex,
+            groupEnd: groupEndIndex
+          })
+        }
+      }
+
+      groupStart = groupEnd + 1
+    }
+
+    this.tagGroupsCache.set(siblings, groupMap)
+
+    return groupMap
+  }
+}

package/src/text-flow-analyzer.ts

@@ -0,0 +1,212 @@
+import { isNode, getTagName, isERBCommentNode, isPureWhitespaceNode } from "@herb-tools/core"
+import { Node, HTMLTextNode, HTMLElementNode, ERBContentNode, WhitespaceNode } from "@herb-tools/core"
+
+import type { ContentUnitWithNode } from "./format-helpers.js"
+
+import {
+  hasWhitespaceBetween,
+  isHerbDisableComment,
+  isInlineElement,
+  isLineBreakingElement,
+} from "./format-helpers.js"
+
+import {
+  hasWhitespaceBeforeNode as hasWhitespaceBeforeNodeHelper,
+  lastUnitEndsWithWhitespace as lastUnitEndsWithWhitespaceHelper,
+  tryMergeAtomicAfterText as tryMergeAtomicAfterTextHelper,
+  tryMergeTextAfterAtomic as tryMergeTextAfterAtomicHelper,
+} from "./text-flow-helpers.js"
+
+/**
+ * Interface that the delegate must implement to provide
+ * rendering capabilities to the TextFlowAnalyzer.
+ */
+export interface TextFlowAnalyzerDelegate {
+  tryRenderInlineElement(element: HTMLElementNode): string | null
+  renderERBAsString(node: ERBContentNode): string
+}
+
+/**
+ * TextFlowAnalyzer converts AST nodes into the ContentUnitWithNode[]
+ * intermediate representation used by the TextFlowEngine for rendering.
+ */
+export class TextFlowAnalyzer {
+  private delegate: TextFlowAnalyzerDelegate
+
+  constructor(delegate: TextFlowAnalyzerDelegate) {
+    this.delegate = delegate
+  }
+
+  buildContentUnits(children: Node[]): ContentUnitWithNode[] {
+    const result: ContentUnitWithNode[] = []
+    let lastProcessedIndex = -1
+
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i]
+
+      if (isNode(child, WhitespaceNode)) continue
+
+      if (isPureWhitespaceNode(child) && !(isNode(child, HTMLTextNode) && child.content === ' ')) {
+        if (lastProcessedIndex >= 0) {
+          const hasNonWhitespaceAfter = children.slice(i + 1).some(node =>
+            !isNode(node, WhitespaceNode) && !isPureWhitespaceNode(node)
+          )
+
+          if (hasNonWhitespaceAfter) {
+            const previousNode = children[lastProcessedIndex]
+
+            if (!isLineBreakingElement(previousNode)) {
+              result.push({
+                unit: { content: ' ', type: 'text', isAtomic: true, breaksFlow: false },
+                node: child
+              })
+            }
+          }
+        }
+
+        continue
+      }
+
+      if (isNode(child, HTMLTextNode)) {
+        this.processTextNode(result, children, child, i, lastProcessedIndex)
+
+        lastProcessedIndex = i
+      } else if (isNode(child, HTMLElementNode)) {
+        const tagName = getTagName(child)
+
+        if (isInlineElement(tagName)) {
+          const merged = this.processInlineElement(result, children, child, i, lastProcessedIndex)
+
+          if (merged) {
+            lastProcessedIndex = i
+
+            continue
+          }
+        } else {
+          result.push({
+            unit: { content: '', type: 'block', isAtomic: false, breaksFlow: true },
+            node: child
+          })
+        }
+
+        lastProcessedIndex = i
+      } else if (isNode(child, ERBContentNode)) {
+        const merged = this.processERBContentNode(result, children, child, i, lastProcessedIndex)
+
+        if (merged) {
+          lastProcessedIndex = i
+
+          continue
+        }
+
+        lastProcessedIndex = i
+      } else {
+        result.push({
+          unit: { content: '', type: 'block', isAtomic: false, breaksFlow: true },
+          node: child
+        })
+
+        lastProcessedIndex = i
+      }
+    }
+
+    return result
+  }
+
+  private processTextNode(result: ContentUnitWithNode[], children: Node[], child: HTMLTextNode, index: number, lastProcessedIndex: number): void {
+    const isAtomic = child.content === ' '
+
+    if (!isAtomic && lastProcessedIndex >= 0 && result.length > 0) {
+      const hasWhitespace = hasWhitespaceBeforeNodeHelper(children, lastProcessedIndex, index, child)
+      const lastUnit = result[result.length - 1]
+      const lastIsAtomic = lastUnit.unit.isAtomic && (lastUnit.unit.type === 'erb' || lastUnit.unit.type === 'inline')
+
+      if (lastIsAtomic && !hasWhitespace && tryMergeTextAfterAtomicHelper(result, child)) {
+        return
+      }
+    }
+
+    result.push({
+      unit: { content: child.content, type: 'text', isAtomic, breaksFlow: false },
+      node: child
+    })
+  }
+
+  private processInlineElement(result: ContentUnitWithNode[], children: Node[], child: HTMLElementNode, index: number, lastProcessedIndex: number): boolean {
+    const inlineContent = this.delegate.tryRenderInlineElement(child)
+
+    if (inlineContent === null) {
+      result.push({
+        unit: { content: '', type: 'block', isAtomic: false, breaksFlow: true },
+        node: child
+      })
+
+      return false
+    }
+
+    if (lastProcessedIndex >= 0) {
+      const hasWhitespace = hasWhitespaceBetween(children, lastProcessedIndex, index) || lastUnitEndsWithWhitespaceHelper(result)
+
+      if (!hasWhitespace && tryMergeAtomicAfterTextHelper(result, children, lastProcessedIndex, inlineContent, 'inline', child)) {
+        return true
+      }
+    }
+
+    result.push({
+      unit: { content: inlineContent, type: 'inline', isAtomic: true, breaksFlow: false },
+      node: child
+    })
+
+    return false
+  }
+
+  private processERBContentNode(result: ContentUnitWithNode[], children: Node[], child: ERBContentNode, index: number, lastProcessedIndex: number): boolean {
+    const erbContent = this.delegate.renderERBAsString(child)
+    const herbDisable = isHerbDisableComment(child)
+
+    if (lastProcessedIndex >= 0) {
+      const hasWhitespace = hasWhitespaceBetween(children, lastProcessedIndex, index) || lastUnitEndsWithWhitespaceHelper(result)
+
+      if (!hasWhitespace && tryMergeAtomicAfterTextHelper(result, children, lastProcessedIndex, erbContent, 'erb', child)) {
+        return true
+      }
+
+      if (hasWhitespace && result.length > 0) {
+        const lastUnit = result[result.length - 1]
+        const lastIsAtomic = lastUnit.unit.isAtomic && (lastUnit.unit.type === 'inline' || lastUnit.unit.type === 'erb')
+
+        if (lastIsAtomic && !lastUnitEndsWithWhitespaceHelper(result)) {
+          result.push({
+            unit: { content: ' ', type: 'text', isAtomic: true, breaksFlow: false },
+            node: null
+          })
+        }
+      }
+    }
+
+    result.push({
+      unit: { content: erbContent, type: 'erb', isAtomic: true, breaksFlow: false, isHerbDisable: herbDisable },
+      node: child
+    })
+
+    if (isERBCommentNode(child) && !herbDisable) {
+      for (let j = index + 1; j < children.length; j++) {
+        const nextChild = children[j]
+        if (isNode(nextChild, WhitespaceNode)) continue
+        if (isPureWhitespaceNode(nextChild)) continue
+
+        const hasNewlineBefore = isNode(nextChild, HTMLTextNode) && /\n/.test(nextChild.content.split(/\S/)[0] || '')
+        if (nextChild.location.start.line > child.location.end.line || hasNewlineBefore) {
+          result.push({
+            unit: { content: '', type: 'text', isAtomic: false, breaksFlow: true },
+            node: null
+          })
+        }
+
+        break
+      }
+    }
+
+    return false
+  }
+}