@gram-lang/format 1.0.0-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,73 @@
1
+ # @gram-lang/format
2
+
3
+ [![npm version](https://badge.fury.io/js/@gram-lang%2Fformat.svg)](https://www.npmjs.com/package/@gram-lang/format)
4
+ [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
5
+
6
+ *Part of the [Gram monorepo](https://codeberg.org/abiwab/gram).*
7
+
8
+ Canonical `.gram` source code formatter, shared by the CLI (`gram format`) and Language Server (`format on save`).
9
+
10
+ ---
11
+
12
+ ## šŸ“š General Documentation
13
+
14
+ For full syntax specifications, command reference, and best practices, please refer to the **[Gram Documentation](https://gram-lang.org/)**.
15
+
16
+ ---
17
+
18
+ ## šŸ› ļø Installation
19
+
20
+ ```bash
21
+ npm install @gram-lang/format
22
+ # or
23
+ bun add @gram-lang/format
24
+ ```
25
+
26
+ ---
27
+
28
+ ## ⚔ Usage
29
+
30
+ ```typescript
31
+ import { formatGram, hasChanges, summarizeChanges } from '@gram-lang/format';
32
+
33
+ const unformatted = `
34
+ ---
35
+ title: 'Crepes'
36
+ ---
37
+ ## Batter
38
+ Mix @flour{200g} and @milk{200ml}.
39
+ `;
40
+
41
+ const { content, changes } = formatGram(unformatted);
42
+
43
+ if (hasChanges(changes)) {
44
+ console.log("Summary:", summarizeChanges(changes));
45
+ console.log("Formatted content:\n", content);
46
+ }
47
+ ```
48
+
49
+ ---
50
+
51
+ ## šŸ—ļø Structure & Rules
52
+
53
+ * `src/index.ts`: Exports `formatGram`, `hasChanges`, and `summarizeChanges`.
54
+
55
+ The package enforces canonical formatting rules across `.gram` files (preserving frontmatter boundary integrity):
56
+ 1. Lowercase ingredient IDs (`@Farine` → `@farine`)
57
+ 2. Remove space between `@id` and `{` (`@ing {10g}` → `@ing{10g}`)
58
+ 3. Trim spaces inside braces (`{ 10g }` → `{10g}`)
59
+ 4. Remove trailing decimal zeros (`{500.0g}` → `{500g}`)
60
+ 5. Normalize temperature unit spacing (`{180 °C}` → `{180°C}`)
61
+ 6. Normalize composite ingredient separator spacing (`<@`)
62
+ 7. Normalize arrow declaration spacing (`->&name{}`)
63
+ 8. Normalize section header spacing (`## Header`)
64
+ 9. Convert tabs to 4 spaces
65
+ 10. Trim trailing whitespace line by line
66
+ 11. Collapse consecutive blank lines to single blank lines
67
+ 12. Ensure single newline at end of file
68
+
69
+ ---
70
+
71
+ ## šŸ“„ License
72
+
73
+ This project is licensed under the GPL-3.0 License.
@@ -0,0 +1,31 @@
1
+ interface FormatterChanges {
2
+ lowercasedIds: number;
3
+ spacesBeforeBrace: number;
4
+ spacesInsideBraces: number;
5
+ trailingZeros: number;
6
+ temperatureSpacing: number;
7
+ compositeSeparatorSpacing: number;
8
+ arrowDeclarationSpacing: number;
9
+ headerSpacing: number;
10
+ tabsToSpaces: number;
11
+ consecutiveBlankLines: number;
12
+ trailingWhitespace: number;
13
+ eofNewline: boolean;
14
+ }
15
+ declare function hasChanges(changes: FormatterChanges): boolean;
16
+ declare function summarizeChanges(changes: FormatterChanges): string;
17
+ /**
18
+ * The CLI (`gram format`, 9 rules, whole-body regexes) and the
19
+ * language server (`format on save`, ~6 rules, line-by-line) used to be two
20
+ * independent implementations with disjoint rule sets — a recipe formatted
21
+ * by one and re-opened by the other could still show further changes,
22
+ * defeating the point of a formatter (no fixed point between the two
23
+ * surfaces). This is the single canonical implementation both now call:
24
+ * every rule either tool had is here, exactly once.
25
+ */
26
+ declare function formatGram(source: string): {
27
+ content: string;
28
+ changes: FormatterChanges;
29
+ };
30
+
31
+ export { type FormatterChanges, formatGram, hasChanges, summarizeChanges };
package/dist/index.js ADDED
@@ -0,0 +1,147 @@
1
+ // src/index.ts
2
+ function hasChanges(changes) {
3
+ return changes.lowercasedIds > 0 || changes.spacesBeforeBrace > 0 || changes.spacesInsideBraces > 0 || changes.trailingZeros > 0 || changes.temperatureSpacing > 0 || changes.compositeSeparatorSpacing > 0 || changes.arrowDeclarationSpacing > 0 || changes.headerSpacing > 0 || changes.tabsToSpaces > 0 || changes.consecutiveBlankLines > 0 || changes.trailingWhitespace > 0 || changes.eofNewline;
4
+ }
5
+ function summarizeChanges(changes) {
6
+ const parts = [];
7
+ const p = (n, word) => `${n} ${word}${n > 1 ? "s" : ""}`;
8
+ if (changes.lowercasedIds > 0)
9
+ parts.push(`${p(changes.lowercasedIds, "ID")} lowercased`);
10
+ if (changes.spacesBeforeBrace > 0)
11
+ parts.push(`${p(changes.spacesBeforeBrace, "space")} before brace removed`);
12
+ if (changes.spacesInsideBraces > 0)
13
+ parts.push(`${p(changes.spacesInsideBraces, "brace")} interior trimmed`);
14
+ if (changes.trailingZeros > 0)
15
+ parts.push(`${p(changes.trailingZeros, "trailing zero")} removed`);
16
+ if (changes.temperatureSpacing > 0)
17
+ parts.push(`${p(changes.temperatureSpacing, "temperature")} spacing fixed`);
18
+ if (changes.compositeSeparatorSpacing > 0)
19
+ parts.push(
20
+ `${p(changes.compositeSeparatorSpacing, "composite separator")} normalized`
21
+ );
22
+ if (changes.arrowDeclarationSpacing > 0)
23
+ parts.push(
24
+ `${p(changes.arrowDeclarationSpacing, "declaration")} spacing fixed`
25
+ );
26
+ if (changes.headerSpacing > 0)
27
+ parts.push(`${p(changes.headerSpacing, "header")} spacing normalized`);
28
+ if (changes.tabsToSpaces > 0)
29
+ parts.push(`${p(changes.tabsToSpaces, "tab")} converted to spaces`);
30
+ if (changes.consecutiveBlankLines > 0)
31
+ parts.push(
32
+ `${p(changes.consecutiveBlankLines, "blank line group")} collapsed`
33
+ );
34
+ if (changes.trailingWhitespace > 0)
35
+ parts.push(
36
+ `${p(changes.trailingWhitespace, "line")} trailing whitespace removed`
37
+ );
38
+ if (changes.eofNewline) parts.push("EOF newline added");
39
+ return parts.join(" \xB7 ");
40
+ }
41
+ function splitFrontmatter(source) {
42
+ const firstLineEnd = source.indexOf("\n");
43
+ const firstLine = firstLineEnd === -1 ? source : source.slice(0, firstLineEnd);
44
+ if (firstLineEnd === -1 || firstLine.trimEnd() !== "---") {
45
+ return { frontmatter: "", body: source };
46
+ }
47
+ let cursor = firstLineEnd + 1;
48
+ while (cursor <= source.length) {
49
+ const nextLineEnd = source.indexOf("\n", cursor);
50
+ const line = nextLineEnd === -1 ? source.slice(cursor) : source.slice(cursor, nextLineEnd);
51
+ if (line.trimEnd() === "---") {
52
+ const boundary = nextLineEnd === -1 ? source.length : nextLineEnd + 1;
53
+ return {
54
+ frontmatter: source.slice(0, boundary),
55
+ body: source.slice(boundary)
56
+ };
57
+ }
58
+ if (nextLineEnd === -1) break;
59
+ cursor = nextLineEnd + 1;
60
+ }
61
+ return { frontmatter: "", body: source };
62
+ }
63
+ function formatGram(source) {
64
+ const changes = {
65
+ lowercasedIds: 0,
66
+ spacesBeforeBrace: 0,
67
+ spacesInsideBraces: 0,
68
+ trailingZeros: 0,
69
+ temperatureSpacing: 0,
70
+ compositeSeparatorSpacing: 0,
71
+ arrowDeclarationSpacing: 0,
72
+ headerSpacing: 0,
73
+ tabsToSpaces: 0,
74
+ consecutiveBlankLines: 0,
75
+ trailingWhitespace: 0,
76
+ eofNewline: false
77
+ };
78
+ const { frontmatter, body: originalBody } = splitFrontmatter(source);
79
+ let body = originalBody;
80
+ body = body.replace(/(?<=@)([a-zA-Z][a-zA-Z0-9_-]*)/g, (match) => {
81
+ const lower = match.toLowerCase();
82
+ if (lower !== match) changes.lowercasedIds++;
83
+ return lower;
84
+ });
85
+ body = body.replace(/@([a-zA-Z][a-zA-Z0-9_-]*)\s+\{/g, (_, id) => {
86
+ changes.spacesBeforeBrace++;
87
+ return `@${id}{`;
88
+ });
89
+ body = body.replace(/\{([^}]*)\}/g, (_, inner) => {
90
+ const trimmed = inner.trim();
91
+ if (trimmed !== inner) changes.spacesInsideBraces++;
92
+ return `{${trimmed}}`;
93
+ });
94
+ body = body.replace(/\{(\d+)\.0+([a-zA-Z°%]*)\}/g, (_, n, u) => {
95
+ changes.trailingZeros++;
96
+ return `{${n}${u}}`;
97
+ });
98
+ body = body.replace(/\{(\d+\.\d*[1-9])0+([a-zA-Z°%]*)\}/g, (_, n, u) => {
99
+ changes.trailingZeros++;
100
+ return `{${n}${u}}`;
101
+ });
102
+ body = body.replace(/\{([^}]*)\}/g, (_, inner) => {
103
+ const fixed = inner.replace(/(\d+)\s+°/g, (_m, n) => {
104
+ changes.temperatureSpacing++;
105
+ return `${n}\xB0`;
106
+ });
107
+ return `{${fixed}}`;
108
+ });
109
+ body = body.replace(/ *< *@/g, (match) => {
110
+ if (match !== "<@") changes.compositeSeparatorSpacing++;
111
+ return "<@";
112
+ });
113
+ body = body.replace(/->&([^{\n]+?)\s+\{\}/g, (_, name) => {
114
+ changes.arrowDeclarationSpacing++;
115
+ return `->&${name}{}`;
116
+ });
117
+ body = body.replace(/^(##(?!#))[ \t]*(?=\S)/gm, (match, hashes) => {
118
+ const normalized = `${hashes} `;
119
+ if (match !== normalized) changes.headerSpacing++;
120
+ return normalized;
121
+ });
122
+ body = body.replace(/\t/g, () => {
123
+ changes.tabsToSpaces++;
124
+ return " ";
125
+ });
126
+ let content = frontmatter + body;
127
+ content = content.split("\n").map((line) => {
128
+ const trimmed = line.trimEnd();
129
+ if (trimmed !== line) changes.trailingWhitespace++;
130
+ return trimmed;
131
+ }).join("\n");
132
+ content = content.replace(/\n{3,}/g, () => {
133
+ changes.consecutiveBlankLines++;
134
+ return "\n\n";
135
+ });
136
+ const trimmedEnd = content.trimEnd();
137
+ const withEof = `${trimmedEnd}
138
+ `;
139
+ if (withEof !== content) changes.eofNewline = true;
140
+ content = withEof;
141
+ return { content, changes };
142
+ }
143
+ export {
144
+ formatGram,
145
+ hasChanges,
146
+ summarizeChanges
147
+ };
package/package.json ADDED
@@ -0,0 +1,37 @@
1
+ {
2
+ "name": "@gram-lang/format",
3
+ "version": "1.0.0-beta.4",
4
+ "description": "Canonical .gram source formatter, shared by the CLI and language server",
5
+ "main": "dist/index.js",
6
+ "types": "dist/index.d.ts",
7
+ "sideEffects": false,
8
+ "files": [
9
+ "dist"
10
+ ],
11
+ "keywords": [
12
+ "gram",
13
+ "recipe",
14
+ "formatter"
15
+ ],
16
+ "author": "abiwab",
17
+ "license": "GPL-3.0-or-later",
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "https://codeberg.org/abiwab/gram.git",
21
+ "directory": "packages/format"
22
+ },
23
+ "bugs": {
24
+ "url": "https://codeberg.org/abiwab/gram/issues"
25
+ },
26
+ "homepage": "https://codeberg.org/abiwab/gram/src/branch/main/packages/format#readme",
27
+ "publishConfig": {
28
+ "access": "public"
29
+ },
30
+ "scripts": {
31
+ "build": "tsup src/index.ts --format esm --dts --tsconfig ../../tsconfig.build.json",
32
+ "typecheck": "tsc --noEmit",
33
+ "test": "bun test",
34
+ "prepublishOnly": "npm run build"
35
+ },
36
+ "type": "module"
37
+ }