@herb-tools/formatter 0.7.5 → 0.8.1

package/dist/types/cli.d.ts

@@ -3,4 +3,5 @@ export declare class CLI {
     private parseArguments;
     run(): Promise<void>;
     private readStdin;
+    private resolvePatternToFiles;
 }

package/dist/types/format-helpers.d.ts

@@ -0,0 +1,160 @@
+import { Node, HTMLTextNode, HTMLElementNode, HTMLOpenTagNode, HTMLCloseTagNode } from "@herb-tools/core";
+/**
+ * Analysis result for HTMLElementNode formatting decisions
+ */
+export interface ElementFormattingAnalysis {
+    openTagInline: boolean;
+    elementContentInline: boolean;
+    closeTagInline: boolean;
+}
+/**
+ * Content unit represents a piece of content in text flow
+ * Can be atomic (inline elements, ERB) or splittable (text)
+ */
+export interface ContentUnit {
+    content: string;
+    type: 'text' | 'inline' | 'erb' | 'block';
+    isAtomic: boolean;
+    breaksFlow: boolean;
+    isHerbDisable?: boolean;
+}
+/**
+ * Content unit paired with its source AST node
+ */
+export interface ContentUnitWithNode {
+    unit: ContentUnit;
+    node: Node | null;
+}
+export declare const FORMATTABLE_ATTRIBUTES: Record<string, string[]>;
+export declare const INLINE_ELEMENTS: Set<string>;
+export declare const CONTENT_PRESERVING_ELEMENTS: Set<string>;
+export declare const SPACEABLE_CONTAINERS: Set<string>;
+export declare const TIGHT_GROUP_PARENTS: Set<string>;
+export declare const TIGHT_GROUP_CHILDREN: Set<string>;
+export declare const SPACING_THRESHOLD = 3;
+/**
+ * Token list attributes that contain space-separated values and benefit from
+ * spacing around ERB content for readability
+ */
+export declare const TOKEN_LIST_ATTRIBUTES: Set<string>;
+/**
+ * Check if a node is pure whitespace (empty text node with only whitespace)
+ */
+export declare function isPureWhitespaceNode(node: Node): boolean;
+/**
+ * Check if a node is non-whitespace (has meaningful content)
+ */
+export declare function isNonWhitespaceNode(node: Node): boolean;
+/**
+ * Find the previous meaningful (non-whitespace) sibling
+ * Returns -1 if no meaningful sibling is found
+ */
+export declare function findPreviousMeaningfulSibling(siblings: Node[], currentIndex: number): number;
+/**
+ * Check if there's whitespace between two indices in children array
+ */
+export declare function hasWhitespaceBetween(children: Node[], startIndex: number, endIndex: number): boolean;
+/**
+ * Filter children to remove insignificant whitespace
+ */
+export declare function filterSignificantChildren(body: Node[]): Node[];
+/**
+ * Smart filter that preserves exactly ONE whitespace before herb:disable comments
+ */
+export declare function filterEmptyNodesForHerbDisable(nodes: Node[]): Node[];
+/**
+ * Check if a word is standalone closing punctuation
+ */
+export declare function isClosingPunctuation(word: string): boolean;
+/**
+ * Check if a line ends with opening punctuation
+ */
+export declare function lineEndsWithOpeningPunctuation(line: string): boolean;
+/**
+ * Check if a string is an ERB tag
+ */
+export declare function isERBTag(text: string): boolean;
+/**
+ * Check if a string ends with an ERB tag
+ */
+export declare function endsWithERBTag(text: string): boolean;
+/**
+ * Check if a string starts with an ERB tag
+ */
+export declare function startsWithERBTag(text: string): boolean;
+/**
+ * Determine if space is needed between the current line and the next word
+ */
+export declare function needsSpaceBetween(currentLine: string, word: string): boolean;
+/**
+ * Build a line by adding a word with appropriate spacing
+ */
+export declare function buildLineWithWord(currentLine: string, word: string): string;
+/**
+ * Check if a node is an inline element or ERB node
+ */
+export declare function isInlineOrERBNode(node: Node): boolean;
+/**
+ * Check if an element should be treated as inline based on its tag name
+ */
+export declare function isInlineElement(tagName: string): boolean;
+/**
+ * Check if the current inline element is adjacent to a previous inline element (no whitespace between)
+ */
+export declare function isAdjacentToPreviousInline(siblings: Node[], index: number): boolean;
+/**
+ * Check if a node should be appended to the last line (for adjacent inline elements and punctuation)
+ */
+export declare function shouldAppendToLastLine(child: Node, siblings: Node[], index: number): boolean;
+/**
+ * Check if user-intentional spacing should be preserved (double newlines between elements)
+ */
+export declare function shouldPreserveUserSpacing(child: Node, siblings: Node[], index: number): boolean;
+/**
+ * Check if children contain any text content with newlines
+ */
+export declare function hasMultilineTextContent(children: Node[]): boolean;
+/**
+ * Check if all nested elements in the children are inline elements
+ */
+export declare function areAllNestedElementsInline(children: Node[]): boolean;
+/**
+ * Check if element has complex ERB control flow
+ */
+export declare function hasComplexERBControlFlow(inlineNodes: Node[]): boolean;
+/**
+ * Check if children contain mixed text and inline elements (like "text<em>inline</em>text")
+ * or mixed ERB output and text (like "<%= value %> text")
+ * This indicates content that should be formatted inline even with structural newlines
+ */
+export declare function hasMixedTextAndInlineContent(children: Node[]): boolean;
+export declare function isContentPreserving(element: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode): boolean;
+/**
+ * Count consecutive inline elements/ERB at the start of children (with no whitespace between)
+ */
+export declare function countAdjacentInlineElements(children: Node[]): number;
+/**
+ * Check if a node represents a block-level element
+ */
+export declare function isBlockLevelNode(node: Node): boolean;
+/**
+ * Check if an element is a line-breaking element (br or hr)
+ */
+export declare function isLineBreakingElement(node: Node): boolean;
+/**
+ * Normalize text by replacing multiple spaces with single space and trim
+ * Then split into words
+ */
+export declare function normalizeAndSplitWords(text: string): string[];
+/**
+ * Check if text ends with whitespace
+ */
+export declare function endsWithWhitespace(text: string): boolean;
+/**
+ * Check if an ERB content node is a herb:disable comment
+ */
+export declare function isHerbDisableComment(node: Node): boolean;
+/**
+ * Check if a text node is YAML frontmatter (starts and ends with ---)
+ */
+export declare function isFrontmatter(node: Node): node is HTMLTextNode;

package/dist/types/format-printer.d.ts

@@ -25,12 +25,6 @@ export declare class FormatPrinter extends Printer {
     private elementStack;
     private elementFormattingAnalysis;
     source: string;
-    private static readonly INLINE_ELEMENTS;
-    private static readonly CONTENT_PRESERVING_ELEMENTS;
-    private static readonly SPACEABLE_CONTAINERS;
-    private static readonly TIGHT_GROUP_PARENTS;
-    private static readonly TIGHT_GROUP_CHILDREN;
-    private static readonly SPACING_THRESHOLD;
     constructor(source: string, options: Required<FormatOptions>);
     print(input: Node | ParseResult | Token): string;
     /**
@@ -94,23 +88,10 @@ export declare class FormatPrinter extends Printer {
      * @returns true if spacing should be added before the current element
      */
     private shouldAddSpacingBetweenSiblings;
-    /**
-     * Token list attributes that contain space-separated values and benefit from
-     * spacing around ERB content for readability
-     */
-    private static readonly TOKEN_LIST_ATTRIBUTES;
     /**
      * Check if we're currently processing a token list attribute that needs spacing
      */
-    private isInTokenListAttribute;
-    /**
-     * Find the previous meaningful (non-whitespace) sibling
-     */
-    private findPreviousMeaningfulSibling;
-    /**
-     * Check if a node represents a block-level element
-     */
-    private isBlockLevelNode;
+    private get isInTokenListAttribute();
     /**
      * Render attributes as a space-separated string
      */
@@ -119,8 +100,8 @@ export declare class FormatPrinter extends Printer {
      * Determine if a tag should be rendered inline based on attribute count and other factors
      */
     private shouldRenderInline;
-    private getAttributeName;
     private wouldClassAttributeBeMultiline;
+    private getAttributeName;
     private getAttributeValue;
     private hasMultilineAttributes;
     private formatClassAttribute;
@@ -192,58 +173,114 @@ export declare class FormatPrinter extends Printer {
      * Determines if the close tag should be rendered inline (usually follows content decision)
      */
     private shouldRenderCloseTagInline;
-    private isNonWhitespaceNode;
+    private formatFrontmatter;
     /**
-     * Check if an element should be treated as inline based on its tag name
+     * Append a child node to the last output line
      */
-    private isInlineElement;
+    private appendChildToLastLine;
     /**
-     * Check if we're in a text flow context (parent contains mixed text and inline elements)
+     * Visit children in a text flow context (mixed text and inline elements)
+     * Handles word wrapping and keeps adjacent inline elements together
      */
     private visitTextFlowChildren;
-    private isInTextFlowContext;
-    private renderInlineOpen;
-    renderAttribute(attribute: HTMLAttributeNode): string;
     /**
-     * Try to render a complete element inline including opening tag, children, and closing tag
+     * Wrap remaining words that don't fit on the current line
+     * Returns the wrapped lines with proper indentation
      */
-    private tryRenderInlineFull;
+    private wrapRemainingWords;
     /**
-     * Try to render just the children inline (without tags)
+     * Try to merge text starting with punctuation to inline content
+     * Returns object with merged content and whether processing should stop
      */
-    private tryRenderChildrenInline;
+    private tryMergePunctuationText;
     /**
-     * Try to render children inline if they are simple enough.
-     * Returns the inline string if possible, null otherwise.
+     * Render adjacent inline elements together on one line
      */
-    private tryRenderInline;
+    private renderAdjacentInlineElements;
+    /**
+     * Render an inline element as a string
+     */
+    private renderInlineElementAsString;
+    /**
+     * Render an ERB node as a string
+     */
+    private renderERBAsString;
+    /**
+     * Visit remaining children after processing adjacent inline elements
+     */
+    private visitRemainingChildren;
+    /**
+     * Build words array from text/inline/ERB and wrap them
+     */
+    private buildAndWrapTextFlow;
+    /**
+     * Try to merge text that follows an atomic unit (ERB/inline) with no whitespace
+     * Returns true if merge was performed
+     */
+    private tryMergeTextAfterAtomic;
+    /**
+     * Try to merge an atomic unit (ERB/inline) with preceding text that has no whitespace
+     * Returns true if merge was performed
+     */
+    private tryMergeAtomicAfterText;
+    /**
+     * Check if there's whitespace between current node and last processed node
+     */
+    private hasWhitespaceBeforeNode;
+    /**
+     * Check if last unit in result ends with whitespace
+     */
+    private lastUnitEndsWithWhitespace;
     /**
-     * Check if children contain mixed text and inline elements (like "text<em>inline</em>text")
-     * or mixed ERB output and text (like "<%= value %> text")
-     * This indicates content that should be formatted inline even with structural newlines
+     * Process a text node and add it to results (with potential merging)
      */
-    private hasMixedTextAndInlineContent;
+    private processTextNode;
     /**
-     * Check if children contain any text content with newlines
+     * Process an inline element and add it to results (with potential merging)
      */
-    private hasMultilineTextContent;
+    private processInlineElement;
     /**
-     * Check if all nested elements in the children are inline elements
+     * Process an ERB content node and add it to results (with potential merging)
      */
-    private areAllNestedElementsInline;
+    private processERBContentNode;
     /**
-     * Check if element has complex ERB control flow
+     * Convert AST nodes to content units with node references
      */
-    private hasComplexERBControlFlow;
+    private buildContentUnitsWithNodes;
     /**
-     * Filter children to remove insignificant whitespace
+     * Flush accumulated words to output with wrapping
      */
-    private filterSignificantChildren;
+    private flushWords;
+    /**
+     * Wrap words to fit within line length and push to output
+     * Handles punctuation spacing intelligently
+     * Excludes herb:disable comments from line length calculations
+     */
+    private wrapAndPushWords;
+    private isInTextFlowContext;
+    private renderInlineOpen;
+    renderAttribute(attribute: HTMLAttributeNode): string;
+    /**
+     * Try to render a complete element inline including opening tag, children, and closing tag
+     */
+    private tryRenderInlineFull;
+    /**
+     * Check if children contain a leading herb:disable comment (after optional whitespace)
+     */
+    private hasLeadingHerbDisable;
+    /**
+     * Try to render just the children inline (without tags)
+     */
+    private tryRenderChildrenInline;
+    /**
+     * Try to render children inline if they are simple enough.
+     * Returns the inline string if possible, null otherwise.
+     */
+    private tryRenderInline;
     /**
-     * Filter out empty text nodes and whitespace nodes
+     * Get filtered children, using smart herb:disable filtering if needed
      */
-    private filterEmptyNodes;
+    private getFilteredChildren;
     private renderElementInline;
     private renderChildrenInline;
-    private isContentPreserving;
 }

package/dist/types/formatter.d.ts

@@ -1,5 +1,6 @@
-import type { FormatOptions } from "./options.js";
+import type { Config } from "@herb-tools/config";
 import type { HerbBackend } from "@herb-tools/core";
+import type { FormatOptions } from "./options.js";
 /**
  * Formatter uses a Herb Backend to parse the source and then
  * formats the resulting AST into a well-indented, wrapped string.
@@ -7,10 +8,25 @@ import type { HerbBackend } from "@herb-tools/core";
 export declare class Formatter {
     private herb;
     private options;
+    /**
+     * Creates a Formatter instance from a Config object (recommended).
+     *
+     * @param herb - The Herb backend instance for parsing
+     * @param config - Optional Config instance for formatter options
+     * @param options - Additional options to override config
+     * @returns A configured Formatter instance
+     */
+    static from(herb: HerbBackend, config?: Config, options?: FormatOptions): Formatter;
+    /**
+     * Creates a new Formatter instance.
+     *
+     * @param herb - The Herb backend instance for parsing
+     * @param options - Format options (including rewriters)
+     */
     constructor(herb: HerbBackend, options?: FormatOptions);
     /**
      * Format a source string, optionally overriding format options per call.
      */
-    format(source: string, options?: FormatOptions): string;
+    format(source: string, options?: FormatOptions, filePath?: string): string;
     private parse;
 }

package/dist/types/options.d.ts

@@ -1,14 +1,21 @@
+import type { ASTRewriter, StringRewriter } from "@herb-tools/rewriter";
 /**
  * Formatting options for the Herb formatter.
  *
  * indentWidth: number of spaces per indentation level.
  * maxLineLength: maximum line length before wrapping text or attributes.
+ * preRewriters: AST rewriters to run before formatting.
+ * postRewriters: String rewriters to run after formatting.
  */
 export interface FormatOptions {
     /** number of spaces per indentation level; defaults to 2 */
     indentWidth?: number;
     /** maximum line length before wrapping; defaults to 80 */
     maxLineLength?: number;
+    /** Pre-format rewriters (transform AST before formatting); defaults to [] */
+    preRewriters?: ASTRewriter[];
+    /** Post-format rewriters (transform string after formatting); defaults to [] */
+    postRewriters?: StringRewriter[];
 }
 /**
  * Default values for formatting options.

package/dist/types/scaffold-template-detector.d.ts

@@ -0,0 +1,12 @@
+import { Visitor } from "@herb-tools/core";
+import type { ERBContentNode, ParseResult } from "@herb-tools/core";
+export declare const isScaffoldTemplate: (result: ParseResult) => boolean;
+/**
+ * Visitor that detects if the AST represents a Rails scaffold template.
+ * Scaffold templates contain escaped ERB tags (<%%= or <%%)
+ * and should not be formatted to preserve their exact structure.
+ */
+export declare class ScaffoldTemplateDetector extends Visitor {
+    hasEscapedERB: boolean;
+    visitERBContentNode(node: ERBContentNode): void;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,23 @@
+import type { CustomRewriterLoaderOptions } from "@herb-tools/rewriter/loader";
+export interface FormatterRewriterOptions extends CustomRewriterLoaderOptions {
+    /**
+     * Whether to load custom rewriters from the project
+     * Defaults to true
+     */
+    loadCustomRewriters?: boolean;
+    /**
+     * Names of pre-format rewriters to run (in order)
+     */
+    pre?: string[];
+    /**
+     * Names of post-format rewriters to run (in order)
+     */
+    post?: string[];
+}
+export interface FormatterRewriterInfo {
+    preCount: number;
+    postCount: number;
+    warnings: string[];
+    preNames: string[];
+    postNames: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/formatter",
-  "version": "0.7.5",
+  "version": "0.8.1",
   "description": "Auto-formatter for HTML+ERB templates with intelligent indentation, line wrapping, and ERB-aware pretty-printing.",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -35,11 +35,10 @@
     }
   },
   "dependencies": {
-    "@herb-tools/core": "0.7.5",
-    "@herb-tools/printer": "0.7.5"
-  },
-  "devDependencies": {
-    "glob": "^11.0.3"
+    "@herb-tools/config": "0.8.1",
+    "@herb-tools/core": "0.8.1",
+    "@herb-tools/printer": "0.8.1",
+    "@herb-tools/rewriter": "0.8.1"
   },
   "files": [
     "package.json",