muggle-pug 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johnson Chu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+Pug compiled to HTML as pieces that map to the pug code.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+muggle-pug depends only on `pug-lexer` and `pug-parser`, and builds no mappings: every consumer turns the pieces into the mappings of its own tooling.
+
+## Usage
+
+```ts
+import { parse } from 'muggle-pug';
+
+const { htmlCode, pieces, ast, error, emptyLineEnds } = parse('div.foo hello');
+// htmlCode: "<div class='foo'>hello</div>"
+// pieces: [..., { start: 8, end: 13 }, ...]
+```
+
+- `pieces`: the HTML, as new text and `{ start, end, text? }` ranges of the pug code. A range without `text` copies the pug code there; `text` is HTML that maps to the range as a whole, such as `class` for the `.` of `.foo`, or the closing quote that pug adds to its value (an empty range).
+- `htmlCode`: the text of the pieces.
+- `ast`: the pug AST, with 1-based lines and columns.
+- `error`: the lexer or parser error, with 0-based `line` and `column`.
+- `emptyLineEnds`: the offsets of the line ends of the empty lines before a line.
+
+Vue dedents a pug template, but pug rejects an indented first line, so an indented template is parsed as the children of a `template` tag that is blanked out of the HTML and left out of the mapped pieces, the AST and the offsets.

package/out/index.d.ts

@@ -0,0 +1 @@
+export * from './parse';

package/out/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./parse"), exports);
+//# sourceMappingURL=index.js.map

package/out/lines.d.ts

@@ -0,0 +1,15 @@
+/** Line and column offsets of a text, as `TextDocument` of `vscode-languageserver-textdocument` reads them. */
+export declare class Lines {
+    readonly text: string;
+    private readonly offsets;
+    constructor(text: string);
+    /** The offset of the 0-based `line` and `character`, clamped to the text and before the end of the line. */
+    offsetAt(line: number, character: number): number;
+    /** The 0-based line of `offset`. */
+    lineAt(offset: number): number;
+    /** The text of the 0-based `line`, without its line break, except a `\r` of a `\r\n`. */
+    lineText(line: number): string;
+    /** `offset` clamped to the text and moved before the end of its line. */
+    private normalize;
+    private beforeEOL;
+}

package/out/lines.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Lines = void 0;
+/** Line and column offsets of a text, as `TextDocument` of `vscode-languageserver-textdocument` reads them. */
+class Lines {
+    constructor(text) {
+        this.text = text;
+        this.offsets = [0];
+        for (let i = 0; i < text.length; i++) {
+            const ch = text.charCodeAt(i);
+            if (isEOL(ch)) {
+                if (ch === 13 && text.charCodeAt(i + 1) === 10) {
+                    i++;
+                }
+                this.offsets.push(i + 1);
+            }
+        }
+    }
+    /** The offset of the 0-based `line` and `character`, clamped to the text and before the end of the line. */
+    offsetAt(line, character) {
+        const { offsets } = this;
+        if (line >= offsets.length) {
+            return this.text.length;
+        }
+        if (line < 0) {
+            return 0;
+        }
+        const lineOffset = offsets[line];
+        if (character <= 0) {
+            return lineOffset;
+        }
+        const nextLineOffset = line + 1 < offsets.length ? offsets[line + 1] : this.text.length;
+        return this.beforeEOL(Math.min(lineOffset + character, nextLineOffset), lineOffset);
+    }
+    /** The 0-based line of `offset`. */
+    lineAt(offset) {
+        const { offsets } = this;
+        offset = Math.max(Math.min(offset, this.text.length), 0);
+        let low = 0;
+        let high = offsets.length;
+        while (low < high) {
+            const mid = (low + high) >>> 1;
+            if (offsets[mid] > offset) {
+                high = mid;
+            }
+            else {
+                low = mid + 1;
+            }
+        }
+        return low - 1;
+    }
+    /** The text of the 0-based `line`, without its line break, except a `\r` of a `\r\n`. */
+    lineText(line) {
+        const endOffset = this.offsetAt(line + 1, 0);
+        const end = this.lineAt(endOffset) === line ? endOffset : endOffset - 1;
+        return this.text.substring(this.offsetAt(line, 0), this.normalize(end));
+    }
+    /** `offset` clamped to the text and moved before the end of its line. */
+    normalize(offset) {
+        offset = Math.max(Math.min(offset, this.text.length), 0);
+        return this.beforeEOL(offset, this.offsets[this.lineAt(offset)]);
+    }
+    beforeEOL(offset, lineOffset) {
+        while (offset > lineOffset && isEOL(this.text.charCodeAt(offset - 1))) {
+            offset--;
+        }
+        return offset;
+    }
+}
+exports.Lines = Lines;
+function isEOL(ch) {
+    return ch === 13 || ch === 10;
+}
+//# sourceMappingURL=lines.js.map

package/out/parse.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Generated HTML: new text, which maps nowhere, or the range `start`..`end` of the pug code. A range without `text` is
+ * a copy of the pug code there; `text` is HTML that maps to the range as a whole, such as `class` for the `.` of
+ * `.foo`, or the closing quote that pug adds to its value (an empty range). An empty range is an anchor.
+ */
+export type PugPiece = string | {
+    start: number;
+    end: number;
+    text?: string;
+};
+export interface PugError {
+    code: string;
+    msg: string;
+    /** 0-based. */
+    line: number;
+    /** 0-based. */
+    column: number;
+    filename: string;
+}
+export interface PugParseResult {
+    /** The HTML of the pieces. */
+    htmlCode: string;
+    pieces: PugPiece[];
+    /** The pug AST, with 1-based lines and columns of the pug code. */
+    ast: Node | undefined;
+    error: PugError | undefined;
+    /** The offsets of the line ends of the empty lines that the pug code has before a line. */
+    emptyLineEnds: number[];
+}
+/**
+ * Compiles pug to HTML pieces, which map to the pug code.
+ *
+ * Vue dedents a pug template (`dedent` of `@vue/compiler-sfc`), but pug reads an indented first line as an
+ * error, so an indented template is parsed as the children of a `template` tag. The tag is blanked out of
+ * the HTML and left out of the mapped pieces, the AST and the offsets, which are all of `pugCode`.
+ */
+export declare function parse(pugCode: string): PugParseResult;
+export type Node = BlockNode | MixinNode | TagNode | TextNode | CommentNode | BlockCommentNode;
+export interface BlockNode {
+    type: 'Block';
+    nodes: Node[];
+    line: number;
+}
+export interface TagNode {
+    type: 'Tag';
+    name: string;
+    selfClosing: boolean;
+    block: BlockNode;
+    attrs: {
+        name: string;
+        val: string | true;
+        line: number;
+        column: number;
+        mustEscape: boolean;
+    }[];
+    attributeBlocks: {}[];
+    isInline: boolean;
+    line: number;
+    column: number;
+}
+export interface TextNode {
+    type: 'Text';
+    val: string;
+    line: number;
+    column: number;
+}
+export interface CommentNode {
+    type: 'Comment';
+    val: string;
+    buffer: boolean;
+    line: number;
+    column: number;
+}
+export interface BlockCommentNode {
+    type: 'BlockComment';
+    block: BlockNode;
+    val: string;
+    buffer: boolean;
+    line: number;
+    column: number;
+}
+export interface MixinNode {
+    type: 'Mixin';
+    name: string;
+    args: null;
+    block: BlockNode | null;
+    line: number;
+    column: number;
+}

package/out/parse.js

@@ -0,0 +1,347 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parse = parse;
+const pug_lexer_1 = __importDefault(require("pug-lexer"));
+const lines_1 = require("./lines");
+const pugParser = require('pug-parser');
+const indentedPrefix = 'template\n';
+const startTagLength = '<template>'.length;
+const endTagLength = '</template>'.length;
+/**
+ * Compiles pug to HTML pieces, which map to the pug code.
+ *
+ * Vue dedents a pug template (`dedent` of `@vue/compiler-sfc`), but pug reads an indented first line as an
+ * error, so an indented template is parsed as the children of a `template` tag. The tag is blanked out of
+ * the HTML and left out of the mapped pieces, the AST and the offsets, which are all of `pugCode`.
+ */
+function parse(pugCode) {
+    if (calculateMinIndent(pugCode) === 0) {
+        return parseCode(pugCode);
+    }
+    const prefixedCode = indentedPrefix + pugCode;
+    const parsed = parseCode(prefixedCode);
+    return {
+        ...blankTemplateTag(parsed.pieces, prefixedCode, parsed.htmlCode.length),
+        error: parsed.error && { ...parsed.error, line: parsed.error.line - 1 },
+        ast: parsed.ast && toPrevLine(parsed.ast.nodes[0].block),
+        emptyLineEnds: parsed.emptyLineEnds.map(offset => offset - indentedPrefix.length),
+    };
+}
+/** Blanks the tags of the `template` around the HTML, and shifts the pieces that map past the prefix. */
+function blankTemplateTag(pieces, prefixedCode, htmlLength) {
+    if (htmlLength < startTagLength + endTagLength) {
+        const htmlCode = ' '.repeat(startTagLength + endTagLength);
+        return { htmlCode, pieces: [htmlCode] };
+    }
+    const prefixLength = indentedPrefix.length;
+    const endTagStart = htmlLength - endTagLength;
+    const result = [];
+    let offset = 0;
+    for (const piece of pieces) {
+        const text = pieceText(piece, prefixedCode);
+        const start = offset;
+        offset += text.length;
+        let blanked = text;
+        if (start < startTagLength || offset > endTagStart) {
+            blanked = '';
+            for (let i = 0; i < text.length; i++) {
+                const at = start + i;
+                blanked += at < startTagLength || at >= endTagStart ? ' ' : text[i];
+            }
+        }
+        if (typeof piece === 'string' || piece.start < prefixLength) {
+            result.push(blanked);
+        }
+        else if (piece.text === undefined && blanked === text) {
+            result.push({ start: piece.start - prefixLength, end: piece.end - prefixLength });
+        }
+        else {
+            result.push({ start: piece.start - prefixLength, end: piece.end - prefixLength, text: blanked });
+        }
+    }
+    return { htmlCode: toString(result, prefixedCode.slice(prefixLength)), pieces: result };
+}
+function pieceText(piece, pugCode) {
+    return typeof piece === 'string' ? piece : piece.text ?? pugCode.slice(piece.start, piece.end);
+}
+function toString(pieces, pugCode) {
+    return pieces.map(piece => pieceText(piece, pugCode)).join('');
+}
+function calculateMinIndent(s) {
+    const lines = s.split('\n');
+    const minIndent = lines.reduce(function (minIndent, line) {
+        if (line.trim() === '') {
+            return minIndent;
+        }
+        const indent = line.match(/^\s*/)?.[0]?.length || 0;
+        return Math.min(indent, minIndent);
+    }, Infinity);
+    return minIndent;
+}
+function toPrevLine(node) {
+    const visited = new Set();
+    visit(node);
+    return node;
+    function visit(obj) {
+        if (visited.has(obj)) {
+            return;
+        }
+        visited.add(obj);
+        if ('line' in obj && typeof obj.line === 'number') {
+            obj.line--;
+        }
+        for (const value of Object.values(obj)) {
+            if (value && typeof value === 'object') {
+                visit(value);
+            }
+        }
+    }
+}
+function parseCode(pugCode) {
+    const fileName = 'file.pug';
+    const lines = new lines_1.Lines(pugCode);
+    const codes = [];
+    let error;
+    let emptyLineEnds = [];
+    let attrsBlocks;
+    let ast;
+    try {
+        const tokens = (0, pug_lexer_1.default)(pugCode, { filename: fileName });
+        emptyLineEnds = collectEmptyLineEnds(tokens);
+        attrsBlocks = collectAttrsBlocks(tokens);
+        ast = pugParser(tokens, { filename: fileName, src: pugCode });
+        visitNode(ast, undefined, undefined);
+        codes.push(mapped('', pugCode.trimEnd().length));
+    }
+    catch (e) {
+        const _error = e;
+        error = {
+            ..._error,
+            line: _error.line - 1,
+            column: _error.column - 1,
+        };
+    }
+    return {
+        htmlCode: toString(codes, pugCode),
+        pieces: codes,
+        error,
+        ast,
+        emptyLineEnds,
+    };
+    /** `text` that maps to `sourceLength` chars at `offset`; a copy of them carries no text. */
+    function mapped(text, offset, sourceLength = text.length) {
+        const end = offset + sourceLength;
+        return text === pugCode.slice(offset, end) ? { start: offset, end } : { start: offset, end, text };
+    }
+    function visitNode(node, next, parent) {
+        if (node.type === 'Block') {
+            for (let i = 0; i < node.nodes.length; i++) {
+                visitNode(node.nodes[i], node.nodes[i + 1], node);
+            }
+        }
+        else if (node.type === 'Mixin') {
+            if (node.block) {
+                visitNode(node.block, undefined, node);
+            }
+        }
+        else if (node.type === 'Tag') {
+            const pugTagRange = getDocRange(node.line, node.column, node.name.length);
+            codes.push(mapped('', pugTagRange.start));
+            const selfClosing = node.block.nodes.length === 0;
+            const startTagEnd = addStartTag(node, selfClosing);
+            if (!selfClosing) {
+                visitNode(node.block, next, parent);
+                addEndTag(node, next, parent);
+            }
+            codes.push(mapped('', selfClosing ? startTagEnd : pugTagRange.start));
+        }
+        else if (node.type === 'Text') {
+            codes.push(mapped(node.val, getDocOffset(node.line, node.column)));
+        }
+    }
+    /** Returns the end of the start tag in the pug code. */
+    function addStartTag(node, selfClosing) {
+        codes.push(mapped('', getDocOffset(node.line, node.column)));
+        codes.push('<');
+        const tagRange = getDocRange(node.line, node.column, node.name.length);
+        let end = tagRange.start;
+        if (pugCode.substring(tagRange.start, tagRange.end) === node.name) {
+            codes.push(mapped(node.name, tagRange.start));
+            end = tagRange.end;
+        }
+        else {
+            codes.push(node.name);
+        }
+        for (const attr of node.attrs.filter(attr => !attr.mustEscape)) {
+            codes.push(' ');
+            if (attr.name === 'class' || attr.name === 'id') {
+                const offset = getDocOffset(attr.line, attr.column);
+                for (const char of attr.name) {
+                    codes.push(mapped(char, offset));
+                }
+            }
+            else {
+                codes.push(attr.name);
+            }
+            if (typeof attr.val !== 'boolean') {
+                codes.push('=');
+                const offset = getDocOffset(attr.line, attr.column);
+                const literalName = attr.val.slice(1, -1);
+                if ((attr.name === 'class' || attr.name === 'id')
+                    && pugCode.slice(offset + 1, offset + 1 + literalName.length) === literalName) {
+                    // `'foo'` of `.foo`: the opening quote is the `.`, and the closing quote has no source
+                    codes.push(mapped(attr.val.slice(0, -1), offset));
+                    codes.push(mapped(attr.val.slice(-1), offset + 1 + literalName.length, 0));
+                    end = Math.max(end, offset + 1 + literalName.length);
+                }
+                else {
+                    codes.push(mapped(attr.val, offset));
+                }
+            }
+        }
+        const attrsBlock = attrsBlocks.get(getDocOffset(node.line, node.column)); // support attr auto-complete in spaces
+        if (attrsBlock) {
+            codes.push(' ');
+            codes.push(mapped(attrsBlock.text, attrsBlock.offset));
+            end = Math.max(end, attrsBlock.end);
+        }
+        if (selfClosing) {
+            codes.push(' />');
+        }
+        else {
+            codes.push('>');
+        }
+        return end;
+    }
+    function addEndTag(node, next, parent) {
+        let nextStart;
+        if (next) {
+            if (next.type === 'Block') {
+                nextStart = getDocOffset(next.line, 1);
+            }
+            else {
+                nextStart = getDocOffset(next.line, next.column);
+            }
+        }
+        else if (!parent) {
+            nextStart = pugCode.length;
+        }
+        if (nextStart !== undefined) {
+            codes.push(mapped('', nextStart));
+        }
+        codes.push(`</${node.name}>`);
+    }
+    function collectEmptyLineEnds(tokens) {
+        const ends = [];
+        for (const token of tokens) {
+            if (token.type === 'newline' || token.type === 'outdent') {
+                let currentLine = token.loc.start.line - 2;
+                let prevLine = lines.lineText(currentLine);
+                while (prevLine.trim() === '') {
+                    ends.push(lines.offsetAt(currentLine + 1, 0) - 1);
+                    if (currentLine <= 0) {
+                        break;
+                    }
+                    currentLine--;
+                    prevLine = lines.lineText(currentLine);
+                }
+            }
+        }
+        return ends.sort((a, b) => a - b);
+    }
+    function collectAttrsBlocks(tokens) {
+        const blocks = new Map();
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            if (token.type === 'start-attributes') {
+                let tagStart = token;
+                for (let j = i - 1; j >= 0; j--) {
+                    const prevToken = tokens[j];
+                    if (prevToken.type === 'newline'
+                        || prevToken.type === 'indent'
+                        || prevToken.type === 'outdent'
+                        || prevToken.type === ':') {
+                        break;
+                    }
+                    tagStart = prevToken;
+                    if (prevToken.type === 'tag') {
+                        break;
+                    }
+                }
+                let prevToken = token;
+                let text = '';
+                for (i++; i < tokens.length; i++) {
+                    const attrToken = tokens[i];
+                    addPrevSpace(attrToken);
+                    if (attrToken.type === 'attribute') {
+                        let attrText = pugCode.substring(getDocOffset(attrToken.loc.start.line, attrToken.loc.start.column), getDocOffset(attrToken.loc.end.line, attrToken.loc.end.column));
+                        if (typeof attrToken.val === 'string' && attrText.includes('=')) {
+                            // the lexer reads the code with `\n` line ends, so the value is found in that text and read from the code
+                            const valStart = toCodeIndex(attrText, attrText.replace(/\r\n?/g, '\n').lastIndexOf(attrToken.val));
+                            let valText = attrText.slice(valStart);
+                            if (valText.startsWith('`') && valText.endsWith('`')) {
+                                const innerContent = valText.slice(1, -1);
+                                if (!innerContent.includes('"')) {
+                                    valText = `"${innerContent}"`;
+                                }
+                                else if (!innerContent.includes("'")) {
+                                    valText = `'${innerContent}'`;
+                                }
+                                else {
+                                    // Both quote types present: convert inner single quotes to double quotes
+                                    // This allows using single quotes as the outer delimiter
+                                    // JavaScript accepts both 'str' and "str" for string literals
+                                    valText = `'${innerContent.replace(/'/g, '"')}'`;
+                                }
+                            }
+                            valText = valText.replace(/ \\(?=\r?\n)/g, '//');
+                            text += attrText.slice(0, valStart) + valText;
+                        }
+                        else {
+                            text += attrText;
+                        }
+                    }
+                    else if (attrToken.type === 'end-attributes') {
+                        blocks.set(getDocOffset(tagStart.loc.start.line, tagStart.loc.start.column), {
+                            offset: getDocOffset(token.loc.end.line, token.loc.end.column),
+                            end: getDocOffset(attrToken.loc.end.line, attrToken.loc.end.column),
+                            text,
+                        });
+                        break;
+                    }
+                    prevToken = attrToken;
+                }
+                function addPrevSpace(currentToken) {
+                    text += pugCode.substring(getDocOffset(prevToken.loc.end.line, prevToken.loc.end.column), getDocOffset(currentToken.loc.start.line, currentToken.loc.start.column)).replace(/,/g, '\n');
+                }
+            }
+        }
+        return blocks;
+    }
+    function getDocOffset(pugLine, pugColumn) {
+        return lines.offsetAt(pugLine - 1, pugColumn - 1);
+    }
+    function getDocRange(pugLine, pugColumn, length) {
+        const start = getDocOffset(pugLine, pugColumn);
+        const end = start + length;
+        return {
+            start,
+            end,
+        };
+    }
+}
+/** The index in `code` of `index` in `code` with `\n` line ends. */
+function toCodeIndex(code, index) {
+    let codeIndex = 0;
+    for (let i = 0; i < index; i++) {
+        if (code[codeIndex] === '\r' && code[codeIndex + 1] === '\n') {
+            codeIndex++;
+        }
+        codeIndex++;
+    }
+    return codeIndex;
+}
+//# sourceMappingURL=parse.js.map

package/package.json

@@ -1,6 +1,30 @@
 {
-  "name": "muggle-pug",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "muggle-pug",
+	"version": "0.1.0-alpha.0",
+	"description": "Pug compiled to HTML as pieces that map to the pug code",
+	"main": "out/index.js",
+	"types": "out/index.d.ts",
+	"license": "MIT",
+	"files": [
+		"out/**/*.js",
+		"out/**/*.d.ts"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/johnsoncodehk/muggle-pug.git"
+	},
+	"scripts": {
+		"build": "tsc",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"pug-lexer": "^5.0.1",
+		"pug-parser": "^6.0.0"
+	},
+	"devDependencies": {
+		"@types/node": "^26.0.1",
+		"@vue/compiler-dom": "^3.5.0",
+		"typescript": "7.1.0-beta",
+		"vitest": "latest"
+	}
+}