@reteps/tree-sitter-htmlmustache 0.8.0 → 0.9.0

package/src/core/formatting/index.ts

@@ -0,0 +1,185 @@
+/**
+ * IR-Based Formatter for HTML with Mustache templates.
+ *
+ * Architecture: AST Node → Doc IR → String
+ *
+ * Three phases:
+ * 1. Classification - Determine node type (block/inline/preserve)
+ * 2. AST → IR - Convert nodes to formatting commands
+ * 3. IR → String - Print with proper indentation
+ */
+
+import type { Node as SyntaxNode, Tree } from 'web-tree-sitter';
+import type { TextDocument } from 'vscode-languageserver-textdocument';
+
+/** Formatting options (structurally compatible with LSP FormattingOptions). */
+export interface FormattingOptions {
+  tabSize: number;
+  insertSpaces: boolean;
+}
+
+/** A position in a text document (0-based line and character). */
+export interface Position {
+  line: number;
+  character: number;
+}
+
+/** A range in a text document. */
+export interface Range {
+  start: Position;
+  end: Position;
+}
+
+/** A text edit to apply to a document. */
+export interface TextEdit {
+  range: Range;
+  newText: string;
+}
+
+import { print } from './printer.js';
+import { formatDocument as formatDocumentToDoc, FormatterContext } from './formatters.js';
+import { createIndentUnit } from './mergeOptions.js';
+import type { NoBreakDelimiter } from '../configSchema.js';
+import { findContainingNode, calculateIndentLevel } from './utils.js';
+import { isBlockLevel, getContentNodes, hasImplicitEndTags } from './classifier.js';
+import type { CustomCodeTagConfig } from '../customCodeTags.js';
+
+export interface FormatDocumentParams {
+  customTags?: CustomCodeTagConfig[];
+  printWidth?: number;
+  embeddedFormatted?: Map<number, string>;
+  mustacheSpaces?: boolean;
+  noBreakDelimiters?: NoBreakDelimiter[];
+}
+
+function buildCustomTagMap(customTags?: CustomCodeTagConfig[]): Map<string, CustomCodeTagConfig> | undefined {
+  if (!customTags || customTags.length === 0) return undefined;
+  const map = new Map<string, CustomCodeTagConfig>();
+  for (const config of customTags) {
+    map.set(config.name.toLowerCase(), config);
+  }
+  return map;
+}
+
+export function formatDocument(
+  tree: Tree,
+  document: TextDocument,
+  options: FormattingOptions,
+  params: FormatDocumentParams = {},
+): TextEdit[] {
+  const { printWidth = 80, embeddedFormatted, mustacheSpaces, noBreakDelimiters } = params;
+  const indentUnit = createIndentUnit(options);
+
+  if (tree.rootNode.hasError) return [];
+
+  const customTagMap = buildCustomTagMap(params.customTags);
+  const context: FormatterContext = {
+    document,
+    customTags: customTagMap,
+    embeddedFormatted,
+    mustacheSpaces,
+    noBreakDelimiters,
+  };
+  const doc = formatDocumentToDoc(tree.rootNode, context);
+  const formatted = print(doc, { indentUnit, printWidth });
+
+  const fullRange: Range = {
+    start: { line: 0, character: 0 },
+    end: document.positionAt(document.getText().length),
+  };
+
+  return [{ range: fullRange, newText: formatted }];
+}
+
+export function formatDocumentRange(
+  tree: Tree,
+  document: TextDocument,
+  range: Range,
+  options: FormattingOptions,
+  params: FormatDocumentParams = {},
+): TextEdit[] {
+  const { customTags, printWidth = 80, embeddedFormatted, mustacheSpaces, noBreakDelimiters } = params;
+  const indentUnit = createIndentUnit(options);
+
+  if (tree.rootNode.hasError) return [];
+
+  const customTagMap = buildCustomTagMap(customTags);
+
+  const startOffset = document.offsetAt(range.start);
+  const endOffset = document.offsetAt(range.end);
+
+  let targetNode = findContainingNode(tree.rootNode, startOffset, endOffset) ?? tree.rootNode;
+
+  // Walk up to the nearest block-level boundary so the output is anchored to a
+  // whole element, not mid-inline content.
+  while (
+    targetNode.parent &&
+    !isBlockLevel(targetNode, customTagMap) &&
+    targetNode.type !== 'document'
+  ) {
+    targetNode = targetNode.parent;
+  }
+
+  const indentLevel = calculateIndentLevel(
+    targetNode,
+    isBlockLevel,
+    hasImplicitEndTags,
+    getContentNodes
+  );
+
+  const context: FormatterContext = {
+    document,
+    customTags: customTagMap,
+    embeddedFormatted,
+    mustacheSpaces,
+    noBreakDelimiters,
+  };
+  const doc = formatNodeForRange(targetNode, context);
+  const formatted = print(doc, { indentUnit, printWidth });
+
+  const indentedFormatted = applyBaseIndent(formatted, indentLevel, indentUnit);
+
+  const nodeRange: Range = {
+    start: {
+      line: targetNode.startPosition.row,
+      character: targetNode.startPosition.column,
+    },
+    end: {
+      line: targetNode.endPosition.row,
+      character: targetNode.endPosition.column,
+    },
+  };
+
+  return [{ range: nodeRange, newText: indentedFormatted }];
+}
+
+import { formatNode } from './formatters.js';
+
+function formatNodeForRange(
+  node: SyntaxNode,
+  context: FormatterContext
+): import('./ir.js').Doc {
+  return formatNode(node, context);
+}
+
+function applyBaseIndent(
+  formatted: string,
+  indentLevel: number,
+  indentUnit: string
+): string {
+  if (indentLevel === 0) {
+    return formatted;
+  }
+
+  const baseIndent = indentUnit.repeat(indentLevel);
+  return formatted
+    .split('\n')
+    .map((line, index) => {
+      // Don't indent empty lines or the first line (it's at the node position)
+      if (line.trim() === '' || index === 0) {
+        return line;
+      }
+      return baseIndent + line;
+    })
+    .join('\n');
+}

package/src/core/formatting/ir.ts

@@ -0,0 +1,202 @@
+/**
+ * Intermediate Representation (IR) for document formatting.
+ *
+ * This module defines the Doc type and builder functions for creating
+ * formatting commands. The IR is inspired by Prettier's document model.
+ */
+
+// Doc types - the IR for formatting
+export type Doc =
+  | string // literal text
+  | Concat
+  | Indent
+  | Hardline
+  | Softline
+  | Line
+  | Group
+  | Fill
+  | BreakParent
+  | IfBreak;
+
+export interface Concat {
+  type: 'concat';
+  parts: Doc[];
+}
+
+export interface Indent {
+  type: 'indent';
+  contents: Doc;
+}
+
+export interface Hardline {
+  type: 'hardline';
+}
+
+export interface Softline {
+  type: 'softline';
+}
+
+export interface Line {
+  type: 'line';
+}
+
+export interface Group {
+  type: 'group';
+  contents: Doc;
+  break?: boolean;
+  id?: symbol;
+}
+
+export interface Fill {
+  type: 'fill';
+  parts: Doc[];
+}
+
+export interface BreakParent {
+  type: 'breakParent';
+}
+
+export interface IfBreak {
+  type: 'ifBreak';
+  breakContents: Doc;
+  flatContents: Doc;
+  groupId?: symbol;
+}
+
+// Constants
+export const hardline: Hardline = { type: 'hardline' };
+export const softline: Softline = { type: 'softline' };
+export const line: Line = { type: 'line' };
+export const breakParent: BreakParent = { type: 'breakParent' };
+export const empty = '';
+
+/**
+ * Create a literal text node.
+ */
+export function text(value: string): string {
+  return value;
+}
+
+/**
+ * Concatenate multiple docs into a single doc.
+ */
+export function concat(parts: Doc[]): Doc {
+  // Flatten nested concats and filter empty strings
+  const flattened: Doc[] = [];
+  for (const part of parts) {
+    if (part === '') continue;
+    if (typeof part === 'object' && part.type === 'concat') {
+      flattened.push(...part.parts);
+    } else {
+      flattened.push(part);
+    }
+  }
+
+  if (flattened.length === 0) return '';
+  if (flattened.length === 1) return flattened[0];
+
+  return { type: 'concat', parts: flattened };
+}
+
+/**
+ * Indent the contents by one level.
+ */
+export function indent(contents: Doc): Doc {
+  if (contents === '') return '';
+  return { type: 'indent', contents };
+}
+
+/**
+ * Indent the contents by N levels.
+ */
+export function indentN(contents: Doc, n: number): Doc {
+  if (n <= 0 || contents === '') return contents;
+  let result = contents;
+  for (let i = 0; i < n; i++) {
+    result = indent(result);
+  }
+  return result;
+}
+
+/**
+ * Create a group that may be printed flat or broken across lines.
+ * When `shouldBreak` is true, the group will always break.
+ * When `id` is set, the group's mode can be referenced by `ifBreak` nodes.
+ */
+export function group(contents: Doc, options?: { shouldBreak?: boolean; id?: symbol }): Doc {
+  if (contents === '') return '';
+  const shouldBreak = options?.shouldBreak;
+  return { type: 'group', contents, break: shouldBreak || undefined, id: options?.id };
+}
+
+/**
+ * Create an ifBreak node that prints different content depending on
+ * whether the enclosing group breaks or stays flat.
+ * When `groupId` is set, checks that specific group's mode instead.
+ */
+export function ifBreak(breakContents: Doc, flatContents: Doc, options?: { groupId?: symbol }): Doc {
+  return { type: 'ifBreak', breakContents, flatContents, groupId: options?.groupId };
+}
+
+/**
+ * Create a fill for inline content that wraps when needed.
+ * Parts alternate between content and separators.
+ */
+export function fill(parts: Doc[]): Doc {
+  const filtered = parts.filter((p) => p !== '');
+  if (filtered.length === 0) return '';
+  if (filtered.length === 1) return filtered[0];
+  return { type: 'fill', parts: filtered };
+}
+
+/**
+ * Join docs with a separator.
+ */
+export function join(separator: Doc, docs: Doc[]): Doc {
+  const parts: Doc[] = [];
+  for (let i = 0; i < docs.length; i++) {
+    if (docs[i] === '') continue;
+    if (parts.length > 0) {
+      parts.push(separator);
+    }
+    parts.push(docs[i]);
+  }
+  return concat(parts);
+}
+
+// Type guards for working with Doc types
+export function isConcat(doc: Doc): doc is Concat {
+  return typeof doc === 'object' && doc.type === 'concat';
+}
+
+export function isIndent(doc: Doc): doc is Indent {
+  return typeof doc === 'object' && doc.type === 'indent';
+}
+
+export function isHardline(doc: Doc): doc is Hardline {
+  return typeof doc === 'object' && doc.type === 'hardline';
+}
+
+export function isSoftline(doc: Doc): doc is Softline {
+  return typeof doc === 'object' && doc.type === 'softline';
+}
+
+export function isLine(doc: Doc): doc is Line {
+  return typeof doc === 'object' && doc.type === 'line';
+}
+
+export function isGroup(doc: Doc): doc is Group {
+  return typeof doc === 'object' && doc.type === 'group';
+}
+
+export function isFill(doc: Doc): doc is Fill {
+  return typeof doc === 'object' && doc.type === 'fill';
+}
+
+export function isBreakParent(doc: Doc): doc is BreakParent {
+  return typeof doc === 'object' && doc.type === 'breakParent';
+}
+
+export function isIfBreak(doc: Doc): doc is IfBreak {
+  return typeof doc === 'object' && doc.type === 'ifBreak';
+}

package/src/core/formatting/mergeOptions.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure option merging + indent-unit construction.
+ *
+ * EditorConfig-aware merging lives in `lsp/server/src/formatting/editorconfig.ts`
+ * and layers on top of these results by passing its result as `overrides`.
+ */
+
+import type { FormattingOptions } from './index.js';
+import type { HtmlMustacheConfig } from '../configSchema.js';
+
+/**
+ * Merge base options with `configFile` (indentSize only) and optional
+ * `overrides` (tabSize / insertSpaces). Pure; no fs.
+ *
+ * Priority (low → high): lspOptions < configFile.indentSize < overrides.
+ * `insertSpaces` never comes from `configFile` — only `lspOptions` or `overrides`.
+ */
+export function mergeOptions(
+  lspOptions: FormattingOptions,
+  configFile?: HtmlMustacheConfig | null,
+  overrides?: Partial<FormattingOptions>,
+): FormattingOptions {
+  let tabSize = lspOptions.tabSize;
+  if (configFile?.indentSize !== undefined) tabSize = configFile.indentSize;
+  if (overrides?.tabSize !== undefined) tabSize = overrides.tabSize;
+
+  const insertSpaces = overrides?.insertSpaces ?? lspOptions.insertSpaces;
+
+  return { tabSize, insertSpaces };
+}
+
+export function createIndentUnit(options: FormattingOptions): string {
+  return options.insertSpaces ? ' '.repeat(options.tabSize) : '\t';
+}

package/src/core/formatting/printer.ts

@@ -0,0 +1,242 @@
+/**
+ * Printer module - converts Doc IR to formatted string.
+ *
+ * The printer traverses the Doc tree and produces a string with proper
+ * indentation and line breaks.
+ */
+
+import type { Doc } from './ir.js';
+
+export interface PrinterOptions {
+  /** The indentation string (e.g., '  ' for 2 spaces or '\t' for tab) */
+  indentUnit: string;
+  /** Maximum line width before breaking (used for group fitting) */
+  printWidth?: number;
+}
+
+interface PrintState {
+  indentLevel: number;
+  mode: 'flat' | 'break';
+  groupModes: Map<symbol, 'flat' | 'break'>;
+}
+
+/**
+ * Print a Doc to a string with the given options.
+ */
+export function print(doc: Doc, options: PrinterOptions): string {
+  const output: string[] = [];
+  const state: PrintState = { indentLevel: 0, mode: 'break', groupModes: new Map() };
+
+  printDoc(doc, state, output, options);
+
+  return output.join('');
+}
+
+/**
+ * Walk the output buffer backward to find the current column position
+ * (characters since the last newline).
+ */
+function currentColumn(output: string[]): number {
+  let col = 0;
+  for (let i = output.length - 1; i >= 0; i--) {
+    const chunk = output[i];
+    const nlIndex = chunk.lastIndexOf('\n');
+    if (nlIndex !== -1) {
+      col += chunk.length - nlIndex - 1;
+      return col;
+    }
+    col += chunk.length;
+  }
+  return col;
+}
+
+/**
+ * Check if a Doc tree contains a breakParent anywhere.
+ */
+function containsBreakParent(doc: Doc): boolean {
+  if (typeof doc === 'string') return false;
+  switch (doc.type) {
+    case 'breakParent':
+      return true;
+    case 'concat':
+      return doc.parts.some(containsBreakParent);
+    case 'indent':
+      return containsBreakParent(doc.contents);
+    case 'group':
+      return containsBreakParent(doc.contents);
+    case 'fill':
+      return doc.parts.some(containsBreakParent);
+    case 'ifBreak':
+      return (
+        containsBreakParent(doc.breakContents) ||
+        containsBreakParent(doc.flatContents)
+      );
+    default:
+      return false;
+  }
+}
+
+function printDoc(
+  doc: Doc,
+  state: PrintState,
+  output: string[],
+  options: PrinterOptions
+): void {
+  if (typeof doc === 'string') {
+    output.push(doc);
+    return;
+  }
+
+  switch (doc.type) {
+    case 'concat':
+      for (const part of doc.parts) {
+        printDoc(part, state, output, options);
+      }
+      break;
+
+    case 'indent':
+      state.indentLevel++;
+      printDoc(doc.contents, state, output, options);
+      state.indentLevel--;
+      break;
+
+    case 'hardline':
+      output.push('\n');
+      output.push(makeIndent(state.indentLevel, options));
+      break;
+
+    case 'softline':
+      if (state.mode === 'break') {
+        output.push('\n');
+        output.push(makeIndent(state.indentLevel, options));
+      }
+      // In flat mode, softline produces nothing
+      break;
+
+    case 'line':
+      if (state.mode === 'break') {
+        output.push('\n');
+        output.push(makeIndent(state.indentLevel, options));
+      } else {
+        // In flat mode, line produces a space
+        output.push(' ');
+      }
+      break;
+
+    case 'group': {
+      if (doc.break || containsBreakParent(doc.contents)) {
+        // Forced break
+        const prevMode = state.mode;
+        state.mode = 'break';
+        if (doc.id) state.groupModes.set(doc.id, 'break');
+        printDoc(doc.contents, state, output, options);
+        state.mode = prevMode;
+      } else {
+        // Try to fit on one line
+        const flatOutput: string[] = [];
+        const flatState: PrintState = { ...state, mode: 'flat', groupModes: new Map(state.groupModes) };
+        printDoc(doc.contents, flatState, flatOutput, options);
+
+        const flatContent = flatOutput.join('');
+        const printWidth = options.printWidth ?? 80;
+        const col = currentColumn(output);
+
+        // Check if it fits (no newlines and within width from current column)
+        if (
+          !flatContent.includes('\n') &&
+          col + flatContent.length <= printWidth
+        ) {
+          if (doc.id) state.groupModes.set(doc.id, 'flat');
+          output.push(flatContent);
+        } else {
+          // Break mode
+          const prevMode = state.mode;
+          state.mode = 'break';
+          if (doc.id) state.groupModes.set(doc.id, 'break');
+          printDoc(doc.contents, state, output, options);
+          state.mode = prevMode;
+        }
+      }
+      break;
+    }
+
+    case 'fill':
+      printFill(doc.parts, state, output, options);
+      break;
+
+    case 'ifBreak': {
+      const effectiveMode = doc.groupId
+        ? (state.groupModes.get(doc.groupId) ?? state.mode)
+        : state.mode;
+      if (effectiveMode === 'break') {
+        printDoc(doc.breakContents, state, output, options);
+      } else {
+        printDoc(doc.flatContents, state, output, options);
+      }
+      break;
+    }
+
+    case 'breakParent':
+      // breakParent is handled by containsBreakParent() in group evaluation.
+      // If we reach here outside a group, force break mode.
+      state.mode = 'break';
+      break;
+  }
+}
+
+/**
+ * Print fill: content and separator pairs, keeping items on the same line
+ * when they fit, breaking when they don't.
+ * Parts alternate: [content, separator, content, separator, ..., content]
+ */
+function printFill(
+  parts: Doc[],
+  state: PrintState,
+  output: string[],
+  options: PrinterOptions
+): void {
+  if (parts.length === 0) return;
+
+  const printWidth = options.printWidth ?? 80;
+
+  for (let i = 0; i < parts.length; i++) {
+    const content = parts[i];
+    const separator = i + 1 < parts.length ? parts[i + 1] : null;
+
+    // Print the content
+    printDoc(content, state, output, options);
+
+    if (separator === null) break;
+
+    // Try printing separator + next content flat
+    const nextContent = i + 2 < parts.length ? parts[i + 2] : null;
+    if (nextContent !== null) {
+      const testOutput: string[] = [];
+      const flatState: PrintState = { ...state, mode: 'flat' };
+      printDoc(separator, flatState, testOutput, options);
+      printDoc(nextContent, flatState, testOutput, options);
+      const testStr = testOutput.join('');
+      const col = currentColumn(output);
+
+      if (!testStr.includes('\n') && col + testStr.length <= printWidth) {
+        // Fits: print separator flat
+        const sepOutput: string[] = [];
+        printDoc(separator, flatState, sepOutput, options);
+        output.push(sepOutput.join(''));
+      } else {
+        // Doesn't fit: print separator in break mode
+        printDoc(separator, { ...state, mode: 'break' }, output, options);
+      }
+    } else {
+      // Last separator with no following content, print in current mode
+      printDoc(separator, state, output, options);
+    }
+
+    // Skip the separator in the loop
+    i++;
+  }
+}
+
+function makeIndent(level: number, options: PrinterOptions): string {
+  return options.indentUnit.repeat(level);
+}