@herb-tools/formatter 0.5.0 → 0.6.1

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

@@ -0,0 +1,249 @@
+import { Printer } from "@herb-tools/printer";
+import { ParseResult, Node, DocumentNode, HTMLOpenTagNode, HTMLCloseTagNode, HTMLElementNode, HTMLAttributeNode, HTMLAttributeValueNode, HTMLAttributeNameNode, HTMLTextNode, HTMLCommentNode, HTMLDoctypeNode, ERBContentNode, ERBBlockNode, ERBEndNode, ERBElseNode, ERBIfNode, ERBWhenNode, ERBCaseNode, ERBCaseMatchNode, ERBWhileNode, ERBUntilNode, ERBForNode, ERBRescueNode, ERBEnsureNode, ERBBeginNode, ERBUnlessNode, ERBYieldNode, ERBInNode, XMLDeclarationNode, CDATANode, Token } from "@herb-tools/core";
+import type { ERBNode } from "@herb-tools/core";
+import type { FormatOptions } from "./options.js";
+/**
+ * Printer traverses the Herb AST using the Visitor pattern
+ * and emits a formatted string with proper indentation, line breaks, and attribute wrapping.
+ */
+export declare class FormatPrinter extends Printer {
+    /**
+     * @deprecated integrate indentWidth into this.options and update FormatOptions to extend from @herb-tools/printer options
+     */
+    private indentWidth;
+    /**
+     * @deprecated integrate maxLineLength into this.options and update FormatOptions to extend from @herb-tools/printer options
+     */
+    private maxLineLength;
+    /**
+     * @deprecated refactor to use @herb-tools/printer infrastructre (or rework printer use push and this.lines)
+     */
+    private lines;
+    private indentLevel;
+    private inlineMode;
+    private currentAttributeName;
+    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;
+    /**
+     * Get the current element (top of stack)
+     */
+    private get currentElement();
+    /**
+     * Get the current tag name from the current element context
+     */
+    private get currentTagName();
+    /**
+     * Append text to the last line instead of creating a new line
+     */
+    private pushToLastLine;
+    /**
+     * Capture output from a callback into a separate lines array
+     * Useful for testing what output would be generated without affecting the main output
+     */
+    private capture;
+    /**
+     * Capture all nodes that would be visited during a callback
+     * Returns a flat list of all nodes without generating any output
+     */
+    private captureNodes;
+    /**
+     * @deprecated refactor to use @herb-tools/printer infrastructre (or rework printer use push and this.lines)
+     */
+    private push;
+    /**
+     * @deprecated refactor to use @herb-tools/printer infrastructre (or rework printer use push and this.lines)
+     */
+    private pushWithIndent;
+    private withIndent;
+    private get indent();
+    /**
+     * Format ERB content with proper spacing around the inner content.
+     * Returns empty string if content is empty, otherwise wraps content with single spaces.
+     */
+    private formatERBContent;
+    /**
+     * Count total attributes including those inside ERB conditionals
+     */
+    private getTotalAttributeCount;
+    /**
+     * Extract inline nodes (non-attribute, non-whitespace) from a list of nodes
+     */
+    private extractInlineNodes;
+    /**
+     * 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
+     * @param hasExistingSpacing - Whether user-added spacing already exists
+     * @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;
+    /**
+     * Render attributes as a space-separated string
+     */
+    private renderAttributesString;
+    /**
+     * Determine if a tag should be rendered inline based on attribute count and other factors
+     */
+    private shouldRenderInline;
+    private getAttributeName;
+    private wouldClassAttributeBeMultiline;
+    private getAttributeValue;
+    private hasMultilineAttributes;
+    private formatClassAttribute;
+    private isFormattableAttribute;
+    private formatMultilineAttribute;
+    private formatMultilineAttributeValue;
+    private breakTokensIntoLines;
+    /**
+     * Render multiline attributes for a tag
+     */
+    private renderMultilineAttributes;
+    /**
+     * Reconstruct the text representation of an ERB node
+     * @param withFormatting - if true, format the content; if false, preserve original
+     */
+    private reconstructERBNode;
+    /**
+     * Print an ERB tag (<% %> or <%= %>) with single spaces around inner content.
+     */
+    printERBNode(node: ERBNode): void;
+    visitDocumentNode(node: DocumentNode): void;
+    visitHTMLElementNode(node: HTMLElementNode): void;
+    visitHTMLElementBody(body: Node[], element: HTMLElementNode): void;
+    /**
+     * Visit element children with intelligent spacing logic
+     */
+    private visitElementChildren;
+    visitHTMLOpenTagNode(node: HTMLOpenTagNode): void;
+    visitHTMLCloseTagNode(node: HTMLCloseTagNode): void;
+    visitHTMLTextNode(node: HTMLTextNode): void;
+    visitHTMLAttributeNode(node: HTMLAttributeNode): void;
+    visitHTMLAttributeNameNode(node: HTMLAttributeNameNode): void;
+    visitHTMLAttributeValueNode(node: HTMLAttributeValueNode): void;
+    visitHTMLCommentNode(node: HTMLCommentNode): void;
+    visitERBCommentNode(node: ERBContentNode): void;
+    visitHTMLDoctypeNode(node: HTMLDoctypeNode): void;
+    visitXMLDeclarationNode(node: XMLDeclarationNode): void;
+    visitCDATANode(node: CDATANode): void;
+    visitERBContentNode(node: ERBContentNode): void;
+    visitERBEndNode(node: ERBEndNode): void;
+    visitERBYieldNode(node: ERBYieldNode): void;
+    visitERBInNode(node: ERBInNode): void;
+    visitERBCaseMatchNode(node: ERBCaseMatchNode): void;
+    visitERBBlockNode(node: ERBBlockNode): void;
+    visitERBIfNode(node: ERBIfNode): void;
+    visitERBElseNode(node: ERBElseNode): void;
+    visitERBWhenNode(node: ERBWhenNode): void;
+    visitERBCaseNode(node: ERBCaseNode): void;
+    visitERBBeginNode(node: ERBBeginNode): void;
+    visitERBWhileNode(node: ERBWhileNode): void;
+    visitERBUntilNode(node: ERBUntilNode): void;
+    visitERBForNode(node: ERBForNode): void;
+    visitERBRescueNode(node: ERBRescueNode): void;
+    visitERBEnsureNode(node: ERBEnsureNode): void;
+    visitERBUnlessNode(node: ERBUnlessNode): void;
+    /**
+     * Analyzes an HTMLElementNode and returns formatting decisions for all parts
+     */
+    private analyzeElementFormatting;
+    /**
+     * Determines if the open tag should be rendered inline
+     */
+    private shouldRenderOpenTagInline;
+    /**
+     * Determines if the element content should be rendered inline
+     */
+    private shouldRenderElementContentInline;
+    /**
+     * Determines if the close tag should be rendered inline (usually follows content decision)
+     */
+    private shouldRenderCloseTagInline;
+    private isNonWhitespaceNode;
+    /**
+     * Check if an element should be treated as inline based on its tag name
+     */
+    private isInlineElement;
+    /**
+     * Check if we're in a text flow context (parent contains mixed text and inline elements)
+     */
+    private visitTextFlowChildren;
+    private isInTextFlowContext;
+    private renderInlineOpen;
+    renderAttribute(attribute: HTMLAttributeNode): string;
+    /**
+     * Try to render a complete element inline including opening tag, children, and closing tag
+     */
+    private tryRenderInlineFull;
+    /**
+     * 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;
+    /**
+     * 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
+     */
+    private hasMixedTextAndInlineContent;
+    /**
+     * Check if children contain any text content with newlines
+     */
+    private hasMultilineTextContent;
+    /**
+     * Check if all nested elements in the children are inline elements
+     */
+    private areAllNestedElementsInline;
+    /**
+     * Check if element has complex ERB control flow
+     */
+    private hasComplexERBControlFlow;
+    /**
+     * Filter children to remove insignificant whitespace
+     */
+    private filterSignificantChildren;
+    /**
+     * Filter out empty text nodes and whitespace nodes
+     */
+    private filterEmptyNodes;
+    private renderElementInline;
+    private renderChildrenInline;
+    private isContentPreserving;
+}

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
 export { Formatter } from "./formatter.js";
-export { defaultFormatOptions, resolveFormatOptions } from "./options.js";
+export { FormatPrinter } from "./format-printer.js";
 export type { FormatOptions } from "./options.js";
+export { defaultFormatOptions, resolveFormatOptions } from "./options.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/formatter",
-  "version": "0.5.0",
+  "version": "0.6.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,7 +35,10 @@
     }
   },
   "dependencies": {
-    "@herb-tools/core": "0.5.0",
+    "@herb-tools/core": "0.6.1",
+    "@herb-tools/printer": "0.6.1"
+  },
+  "devDependencies": {
     "glob": "^11.0.3"
   },
   "files": [

package/src/cli.ts

@@ -14,11 +14,11 @@ const pluralize = (count: number, singular: string, plural: string = singular +
 
 export class CLI {
   private usage = dedent`
-    Usage: herb-format [file|directory] [options]
+    Usage: herb-format [file|directory|glob-pattern] [options]
 
     Arguments:
-      file|directory   File to format, directory to format all **/*.html.erb files within,
-                       or '-' for stdin (omit to format all **/*.html.erb files in current directory)
+      file|directory|glob-pattern   File to format, directory to format all **/*.html.erb files within,
+                                    glob pattern to match files, or '-' for stdin (omit to format all **/*.html.erb files in current directory)
 
     Options:
       -c, --check      check if files are formatted without modifying them
@@ -27,8 +27,12 @@ export class CLI {
 
     Examples:
       herb-format                            # Format all **/*.html.erb files in current directory
-      herb-format templates/                 # Format and **/*.html.erb within the given directory
+      herb-format index.html.erb             # Format and write single file
       herb-format templates/index.html.erb   # Format and write single file
+      herb-format templates/                 # Format and **/*.html.erb within the given directory
+      herb-format "templates/**/*.html.erb"  # Format all .html.erb files in templates directory using glob pattern
+      herb-format "**/*.html.erb"            # Format all .html.erb files using glob pattern
+      herb-format "**/*.xml.erb"             # Format all .xml.erb files using glob pattern
       herb-format --check                    # Check if all **/*.html.erb files are formatted
       herb-format --check templates/         # Check if all **/*.html.erb files in templates/ are formatted
       cat template.html.erb | herb-format    # Format from stdin to stdout
@@ -53,7 +57,7 @@ export class CLI {
         process.exit(0)
       }
 
-      console.log("⚠️  Experimental Preview: The formatter is in early development. Please report any unexpected behavior or bugs to https://github.com/marcoroth/herb/issues")
+      console.log("⚠️  Experimental Preview: The formatter is in early development. Please report any unexpected behavior or bugs to https://github.com/marcoroth/herb/issues/new?template=formatting-issue.md")
       console.log()
 
       const formatter = new Formatter(Herb)
@@ -86,17 +90,58 @@ export class CLI {
 
         process.stdout.write(output)
       } else if (file) {
+        let isDirectory = false
+        let isFile = false
+        let pattern = file
+
         try {
           const stats = statSync(file)
+          isDirectory = stats.isDirectory()
+          isFile = stats.isFile()
+        } catch {
+          // Not a file/directory, treat as glob pattern
+        }
 
-          if (stats.isDirectory()) {
-            const pattern = join(file, "**/*.html.erb")
-            const files = await glob(pattern)
+        if (isDirectory) {
+          pattern = join(file, "**/*.html.erb")
+        } else if (isFile) {
+          const source = readFileSync(file, "utf-8")
+          const result = formatter.format(source)
+          const output = result.endsWith('\n') ? result : result + '\n'
 
-            if (files.length === 0) {
-              console.log(`No files found matching pattern: ${resolve(pattern)}`)
-              process.exit(0)
+          if (output !== source) {
+            if (isCheckMode) {
+              console.log(`File is not formatted: ${file}`)
+              process.exit(1)
+            } else {
+              writeFileSync(file, output, "utf-8")
+              console.log(`Formatted: ${file}`)
             }
+          } else if (isCheckMode) {
+            console.log(`File is properly formatted: ${file}`)
+          }
+
+          process.exit(0)
+        }
+
+        try {
+          const files = await glob(pattern)
+
+          if (files.length === 0) {
+            try {
+              statSync(file)
+            } catch {
+              if (!file.includes('*') && !file.includes('?') && !file.includes('[') && !file.includes('{')) {
+                console.error(`Error: Cannot access '${file}': ENOENT: no such file or directory`)
+
+                process.exit(1)
+              }
+            }
+
+            console.log(`No files found matching pattern: ${resolve(pattern)}`)
+
+            process.exit(0)
+          }
 
             let formattedCount = 0
             let unformattedFiles: string[] = []
@@ -134,23 +179,6 @@ export class CLI {
             } else {
               console.log(`\nChecked ${files.length} ${pluralize(files.length, 'file')}, formatted ${formattedCount} ${pluralize(formattedCount, 'file')}`)
             }
-          } else {
-            const source = readFileSync(file, "utf-8")
-            const result = formatter.format(source)
-            const output = result.endsWith('\n') ? result : result + '\n'
-
-            if (output !== source) {
-              if (isCheckMode) {
-                console.log(`File is not formatted: ${file}`)
-                process.exit(1)
-              } else {
-                writeFileSync(file, output, "utf-8")
-                console.log(`Formatted: ${file}`)
-              }
-            } else if (isCheckMode) {
-              console.log(`File is properly formatted: ${file}`)
-            }
-          }
 
         } catch (error) {
           console.error(`Error: Cannot access '${file}':`, error)