@falsefalse/prettier-plugin-handlebars 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+import type { SourceRange } from 'template-format-core';
+export type { SourceRange } from 'template-format-core';
+export type Node = Program | ElementNode | TextNode | MustacheStatement | BlockStatement | PartialStatement | DecoratorStatement | CommentStatement | UnmatchedNode;
+export interface Program extends SourceRange {
+    type: 'Program';
+    body: Node[];
+}
+export interface AttributeValue extends SourceRange {
+    type: 'AttributeValue';
+    parts: AttributeValuePart[];
+    /** The value between the quotes, verbatim. Quotes inside a mustache get printed too. */
+    raw: string;
+}
+/** Everything that can stand in attribute position, or inside a value alongside its text. */
+export type AttributeBlockNode = MustacheStatement | BlockStatement | PartialStatement | DecoratorStatement | CommentStatement;
+export type AttributeValuePart = TextNode | AttributeBlockNode;
+/**
+ * `glued` marks an attribute the author wrote with no space before it. For a mustache or block in
+ * attribute position that space renders, so the printer may not invent one.
+ */
+export type ElementAttribute = SourceRange & {
+    glued?: boolean;
+} & ({
+    type: 'Attribute';
+    name: string;
+    value?: AttributeValue | null;
+} | {
+    type: 'RawAttribute';
+    raw: string;
+} | {
+    type: 'AttributeBlock';
+    block: AttributeBlockNode;
+});
+export interface ElementNode extends SourceRange {
+    type: 'ElementNode';
+    tag: string;
+    attributes: ElementAttribute[];
+    children: Node[];
+    selfClosing: boolean;
+    /** As on `TextNode`: inside a value the printer may not break the tag, every character renders. */
+    preserveWhitespace?: boolean;
+    /** Set only when the author spelled the closing tag differently; HTML tag names ignore case. */
+    closeTag?: string;
+    /** Span between the tag name and the closing `>`, so the attributes can be checked to cover it. */
+    attributesRange?: [number, number];
+    /** Span between the open tag's `>` and the close tag's `<`, so children can be checked to tile it. */
+    contentRange?: [number, number];
+}
+export interface TextNode extends SourceRange {
+    type: 'TextNode';
+    /** The source run, verbatim. Whitespace is content, never metadata. */
+    chars: string;
+    /** Content copied through untouched: raw-text elements, prettier-ignore regions. */
+    verbatim?: boolean;
+    /** Inside an attribute value, where every space renders and none of them are the printer's. */
+    preserveWhitespace?: boolean;
+}
+export type Expression = PathExpression | Literal | SubExpression;
+export type LiteralType = 'StringLiteral' | 'NumberLiteral' | 'BooleanLiteral' | 'NullLiteral' | 'UndefinedLiteral';
+export interface PathExpression extends SourceRange {
+    type: 'PathExpression';
+    /** `a.[b c].d`, `../../x`, `@index`, `this`, exactly as written. */
+    source: string;
+}
+export interface Literal extends SourceRange {
+    type: LiteralType;
+    /** Exactly as written, quotes included. */
+    source: string;
+}
+export interface SubExpression extends SourceRange {
+    type: 'SubExpression';
+    /** `(concat 'p' x)` including the parens, so every expression node prints from itself. */
+    source: string;
+    path: PathExpression | SubExpression;
+    params: Expression[];
+    hash: HashPair[];
+}
+export interface HashPair extends SourceRange {
+    /** Always a bare identifier: Handlebars rejects `a.b=1`. */
+    key: string;
+    value: Expression;
+}
+interface MustacheBase {
+    /** A SubExpression head is only reachable through a dynamic partial, `{{> (lookup . "n")}}`. */
+    path: PathExpression | SubExpression;
+    params: Expression[];
+    hash: HashPair[];
+    blockParams?: string[];
+    trimOpen?: boolean;
+    trimClose?: boolean;
+}
+/** The parts every call shares: a mustache, a block marker, a partial, a subexpression. */
+export type Call = Pick<MustacheBase, 'path' | 'params' | 'hash' | 'blockParams'>;
+export interface MustacheStatement extends MustacheBase, SourceRange {
+    type: 'MustacheStatement';
+    triple: boolean;
+}
+export interface ElseBranch extends MustacheBase, SourceRange {
+    type: 'ElseBranch';
+    program: Program;
+}
+export interface BlockStatement extends MustacheBase, SourceRange {
+    type: 'BlockStatement';
+    program: Program;
+    inverseChain?: ElseBranch[];
+    inverse: Program;
+    inverseTrimOpen?: boolean;
+    inverseTrimClose?: boolean;
+    blockPrefix?: '#' | '#>' | '#*' | '^' | '<' | '$';
+    closeTrimOpen?: boolean;
+    closeTrimClose?: boolean;
+}
+export interface PartialStatement extends MustacheBase, SourceRange {
+    type: 'PartialStatement';
+}
+export interface DecoratorStatement extends MustacheBase, SourceRange {
+    type: 'DecoratorStatement';
+}
+export interface CommentStatement extends SourceRange {
+    type: 'CommentStatement';
+    value: string;
+    multiline: boolean;
+    block: boolean;
+    /** express-hbs' `{{!< name}}` layout directive, which must not be padded into prose. */
+    layout?: boolean;
+    trimOpen?: boolean;
+    trimClose?: boolean;
+}
+export interface UnmatchedNode extends SourceRange {
+    type: 'UnmatchedNode';
+    raw: string;
+    /** As on `TextNode`: in a value the trailing gap is content, not somewhere to break. */
+    preserveWhitespace?: boolean;
+}
+export type ParseEndReason = 'blockEnd' | 'else' | 'tagClose' | null;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/whitespace.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Two classes, because which one is right depends on which language owns the text. A loose `\s`
+ * in the parser or the expression reader is Handlebars' and points here.
+ *
+ * Import the module, not the names: `whitespace.html` against `whitespace.handlebars` at the
+ * call site is the point.
+ */
+/**
+ * HTML's set. Not `\s`, which also matches U+00A0 - a non-breaking space is content, so
+ * `<div title=a b>` is one attribute holding one and `<div a b>` is one attribute named `a b`.
+ * Written out once; every class below is built from it, including the two in `parser.ts`.
+ */
+export declare const htmlCharacters = "\\t\\n\\f\\r ";
+/** `/[\t\n\f\r ]/u` */
+export declare const html: RegExp;
+/** `/[\t\n\f\r ]+/u` - collapsing a run to one space, or splitting text into its gaps. */
+export declare const htmlRun: RegExp;
+/** `/[\t\n\f\r ]+/gu` - for `replace`. Kept apart: `lastIndex` makes `g` unsafe to `test`. */
+export declare const htmlRunGlobal: RegExp;
+/**
+ * Handlebars' whitespace is `\s`, U+00A0 included: its lexer reads `{{foo bar}}` as path
+ * `foo` and param `bar`. Narrowing these to `html` would put the expression reader out of step
+ * with the runtime, and no corpus holds an NBSP inside a mustache to catch it. A `\s` spliced
+ * into a larger pattern - `/^else\s+/` - stays written out, and is this class too.
+ */
+export declare const handlebars: RegExp;
+/** `/\s+/u` - splitting a mustache's inner text into words. */
+export declare const handlebarsRun: RegExp;

package/dist/whitespace.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Two classes, because which one is right depends on which language owns the text. A loose `\s`
+ * in the parser or the expression reader is Handlebars' and points here.
+ *
+ * Import the module, not the names: `whitespace.html` against `whitespace.handlebars` at the
+ * call site is the point.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handlebarsRun = exports.handlebars = exports.htmlRunGlobal = exports.htmlRun = exports.html = exports.htmlCharacters = void 0;
+/**
+ * HTML's set. Not `\s`, which also matches U+00A0 - a non-breaking space is content, so
+ * `<div title=a b>` is one attribute holding one and `<div a b>` is one attribute named `a b`.
+ * Written out once; every class below is built from it, including the two in `parser.ts`.
+ */
+exports.htmlCharacters = '\\t\\n\\f\\r ';
+/** `/[\t\n\f\r ]/u` */
+exports.html = new RegExp(`[${exports.htmlCharacters}]`, 'u');
+/** `/[\t\n\f\r ]+/u` - collapsing a run to one space, or splitting text into its gaps. */
+exports.htmlRun = new RegExp(`[${exports.htmlCharacters}]+`, 'u');
+/** `/[\t\n\f\r ]+/gu` - for `replace`. Kept apart: `lastIndex` makes `g` unsafe to `test`. */
+exports.htmlRunGlobal = new RegExp(`[${exports.htmlCharacters}]+`, 'gu');
+/**
+ * Handlebars' whitespace is `\s`, U+00A0 included: its lexer reads `{{foo bar}}` as path
+ * `foo` and param `bar`. Narrowing these to `html` would put the expression reader out of step
+ * with the runtime, and no corpus holds an NBSP inside a mustache to catch it. A `\s` spliced
+ * into a larger pattern - `/^else\s+/` - stays written out, and is this class too.
+ */
+exports.handlebars = /\s/u;
+/** `/\s+/u` - splitting a mustache's inner text into words. */
+exports.handlebarsRun = /\s+/u;

package/docs/EDITOR_SETUP.md

@@ -0,0 +1,107 @@
+# Editor Setup
+
+The plugin works through Prettier. Editors must be configured so Prettier is selected as the formatter for `.hbs` / `.handlebars` files and can resolve the plugin from the project.
+
+## VS Code
+
+Install:
+
+- [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+- Optional companion extension: [HBS Master](https://marketplace.visualstudio.com/items?itemName=poliklot.hbs-master)
+
+Recommended workspace settings:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "prettier.documentSelectors": ["**/*.hbs", "**/*.handlebars"],
+  "[handlebars]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}
+```
+
+Recommended Prettier config:
+
+```js
+/** @type {import("prettier").Config} */
+module.exports = {
+  plugins: ['@falsefalse/prettier-plugin-handlebars'],
+  overrides: [
+    {
+      files: ["*.hbs", "*.handlebars"],
+      options: {
+        parser: "handlebars",
+      },
+    },
+  ],
+};
+```
+
+If VS Code still does not format files, open the Prettier output panel and check whether it is using the workspace Prettier package.
+
+## WebStorm / PhpStorm / other JetBrains IDEs
+
+1. Install `prettier` and `@falsefalse/prettier-plugin-handlebars` in the project.
+2. Open **Settings → Languages & Frameworks → JavaScript → Prettier**.
+3. Point **Prettier package** to the local `node_modules/prettier` package.
+4. Enable **Run on save** for `.hbs` / `.handlebars` if desired.
+5. Keep the explicit `overrides` rule in your Prettier config.
+
+If the IDE formats the file as plain HTML, run the CLI command below to verify that project config is correct:
+
+```bash
+npx prettier --check "**/*.{hbs,handlebars}"
+```
+
+## Neovim / Vim
+
+Use the local project Prettier binary and pass the file path so Prettier can resolve config and parser overrides.
+
+Example command for formatter plugins:
+
+```bash
+./node_modules/.bin/prettier --stdin-filepath template.hbs
+```
+
+If your formatter does not pass `--stdin-filepath`, use explicit plugin and parser args:
+
+```bash
+./node_modules/.bin/prettier \
+  --plugin @falsefalse/prettier-plugin-handlebars \
+  --parser handlebars
+```
+
+## Sublime Text
+
+[JsPrettier](https://packagecontrol.io/packages/JsPrettier) reads the position back out of
+Prettier's stderr rather than out of the error object, and it matches on the plain name. That is
+why syntax errors from this plugin call themselves `SyntaxError` rather than something more
+specific:
+
+```
+[error] page.hbs: SyntaxError: unclosed tag: expected </span> (3:3)
+```
+
+Rename that and the cursor goes nowhere. `src/errors.ts` says so next to the assignment, and
+`test/syntax-errors.test.ts` has a test that fails if it drifts.
+
+## Syntax errors in the editor
+
+Malformed templates are rejected rather than reformatted, so an editor that formats on save will
+report a failure instead of silently writing a degraded file. The error carries a source range
+(`loc.start` and `loc.end`), which is enough for an editor to select the offending construct, not
+just jump to the line.
+
+If the editor reports the error but does not move the cursor, it is reading stderr rather than the
+error object — see the Sublime Text note above.
+
+## CLI sanity check
+
+When an editor behaves differently from the terminal, use this as the source of truth:
+
+```bash
+npx prettier --write "**/*.{hbs,handlebars}"
+```
+
+If that command works, the plugin is configured correctly and the remaining problem is editor resolution.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,89 @@
+# Troubleshooting
+
+## Prettier does not format `.hbs` files
+
+Almost always a resolution problem, not a formatting one. Prettier will not pick a plugin's parser
+for an extension unless you say so:
+
+```js
+/** @type {import("prettier").Config} */
+module.exports = {
+  plugins: ['@falsefalse/prettier-plugin-handlebars'],
+  overrides: [{ files: ['*.hbs', '*.handlebars'], options: { parser: 'handlebars' } }],
+};
+```
+
+Check, in order:
+
+1. `npx prettier --check "**/*.{hbs,handlebars}"` — the terminal is the source of truth. If this
+   works and the editor does not, the problem is editor resolution; see
+   [EDITOR_SETUP.md](./EDITOR_SETUP.md).
+2. `.prettierignore` does not cover the files.
+3. The plugin resolves from the project, not a global install: `npm ls prettier`.
+
+In a pnpm or monorepo layout the plugin may not be hoisted where Prettier looks. Give it an
+explicit path:
+
+```js
+plugins: [require.resolve('@falsefalse/prettier-plugin-handlebars')];
+```
+
+## Prettier picks the HTML parser instead
+
+The `overrides` entry is missing, or a broader entry above it already claimed `*.hbs`. Prettier
+applies the last matching override, so put the Handlebars one last.
+
+## `SyntaxError: unclosed tag: expected </div> (12:3)`
+
+Not a plugin bug — the template is malformed and the plugin refuses to guess. See
+[the README](../README.md#malformed-input-is-rejected) for the full list of what is rejected and
+the two escape hatches.
+
+The common surprises:
+
+- **Optional end tags are not optional here.** `<li>`, `<td>`, `<p>` and friends must be closed,
+  even though the HTML spec lets you omit them.
+- **`{{#*inline "name"}}` closes with `{{/inline}}`**, not `{{/name}}`.
+- **A typo'd closer reports at the opener.** `{{#if a}}x{{/unless}}` says "unclosed block:
+  expected `{{/if}}`" and points at the `{{#if}}`, because that is where the parser knows
+  something is wrong. Crossed constructs report at the closer, which is the more useful place:
+  `{{#each xs}}{{#if a}}x{{/each}}{{/if}}` points at `{{/each}}`.
+- **A missing quote swallows the tag.** `<div class="foo>` reports "unterminated tag: expected
+  `'>'`" — the quote is what actually went wrong.
+
+## A block of markup must stay byte-for-byte
+
+```hbs
+{{! prettier-ignore }}
+<div   class="keep   exactly"></div>
+```
+
+Or a range, which is also the escape hatch for markup that is deliberately unbalanced:
+
+```hbs
+{{! prettier-ignore-start }}
+<script>
+  window.data = {{ rawJson }};
+</script>
+{{! prettier-ignore-end }}
+```
+
+## The formatter left my file alone and I expected it to change something
+
+It probably did the right thing. The formatter reproduces whitespace between siblings exactly, so
+a template that is already consistent with the author's own line breaks has nothing to change. It
+only reflows inside tags and mustaches, and only when a line exceeds `printWidth`.
+
+Conversely, if you want a block joined onto one line, join it yourself — the formatter will keep
+it that way. It will not join lines you separated.
+
+## Debug checklist
+
+1. `npx prettier --check "**/*.{hbs,handlebars}"`
+2. `npm ls prettier @falsefalse/prettier-plugin-handlebars`
+3. `.prettierignore` does not cover the files
+4. The editor uses the workspace Prettier, not a bundled one
+
+If none of that explains it,
+[open an issue](https://github.com/falsefalse/prettier-plugin-handlebars/issues) with the smallest
+template that reproduces the problem and the Prettier version you are on.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@falsefalse/prettier-plugin-handlebars",
+  "version": "0.0.1",
+  "description": "Whitespace-aware Handlebars formatter for Prettier",
+  "contributors": [
+    "Claude <noreply@anthropic.com>"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/plugin.js",
+  "types": "./dist/plugin.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/plugin.d.ts",
+      "require": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/falsefalse/prettier-plugin-handlebars.git"
+  },
+  "bugs": {
+    "url": "https://github.com/falsefalse/prettier-plugin-handlebars/issues"
+  },
+  "homepage": "https://github.com/falsefalse/prettier-plugin-handlebars#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "prettier",
+    "prettier-plugin",
+    "handlebars",
+    "hbs",
+    "html",
+    "formatter"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "docs/EDITOR_SETUP.md",
+    "docs/TROUBLESHOOTING.md"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p ./ts.base.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "npm run build && npm run typecheck && npm test && npm run gates",
+    "gates": "node scripts/run-parser-fuzz-check.mjs && node scripts/run-format-fuzz-check.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check",
+    "fuzz:format": "npm run build && node scripts/run-format-fuzz-check.mjs",
+    "fuzz:parser": "npm run build && node scripts/run-parser-fuzz-check.mjs",
+    "corpus:diff": "npm run build && node scripts/corpus-diff.mjs",
+    "corpus:gate": "npm run build && node scripts/run-property-gate.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.0",
+    "handlebars": "^4.7.9",
+    "prettier": "^3.9.6",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "prettier": ">=3.0.0"
+  },
+  "dependencies": {
+    "template-format-core": "^0.1.1"
+  }
+}