Merge branch 'main' of https://github.com/node-projects/css-parser

Author: jogibear9988

README.md

@@ -32,6 +32,16 @@ const formatted = stringify(ast, { indent: '  ' })
 // Minify output
 const minified = stringify(ast, { compress: true })
 // => "body{font-size:12px}"
+
+// Identity mode: round-trip CSS exactly as written
+const original = 'body  { font-size:  12px;  }'
+const ast2 = parse(original, { preserveFormatting: true })
+stringify(ast2, { identity: true }) === original // true
+
+// Remove empty rules
+const ast3 = parse('.empty {} .keep { color: red; }')
+stringify(ast3, { removeEmptyRules: true })
+// => ".keep {\n  color: red;\n}"
 ```
 
 ## API
@@ -45,6 +55,7 @@ Parses CSS code and returns an Abstract Syntax Tree (AST).
 - `options` (object, optional) - Parsing options
   - `silent` (boolean) - Silently fail on parse errors instead of throwing
   - `source` (string) - File path for better error reporting
+  - `preserveFormatting` (boolean) - Insert whitespace AST nodes and store raw formatting properties for identity round-trip (default: `false`)
 
 **Returns:** `CssStylesheetAST` - The parsed CSS as an AST
 
@@ -57,6 +68,8 @@ Converts a CSS AST back to CSS string with configurable formatting.
 - `options` (object, optional) - Stringification options
   - `indent` (string) - Indentation string (default: `'  '`)
   - `compress` (boolean) - Whether to compress/minify the output (default: `false`)
+  - `identity` (boolean) - Reproduce the original CSS exactly as parsed; requires `preserveFormatting` during parsing (default: `false`)
+  - `removeEmptyRules` (boolean) - Remove rules with empty declaration blocks (default: `false`)
 
 **Returns:** `string` - The formatted CSS string
 
@@ -65,7 +78,9 @@ Converts a CSS AST back to CSS string with configurable formatting.
 - **Complete CSS Support**: All standard CSS features including selectors, properties, values, at-rules, and comments
 - **TypeScript Support**: Full type definitions for all AST nodes and functions
 - **Error Handling**: Configurable error handling with detailed position information
-- **Formatting Options**: Pretty print, minify, or custom formatting
+- **Formatting Options**: Pretty print, minify, identity (round-trip), or custom formatting
+- **Identity Round-Trip**: Parse and stringify CSS back to the exact original formatting
+- **Empty Rule Removal**: Optionally strip rules with empty declaration blocks
 - **Performance Optimized**: Efficient parsing and stringification for large CSS files
 - **Source Maps**: Track original source positions for debugging and tooling
 

docs/API.md

@@ -22,6 +22,7 @@ Parses CSS code and returns an Abstract Syntax Tree (AST).
 - `options` (object, optional) - Parsing options
   - `silent` (boolean) - Silently fail on parse errors instead of throwing. When `true`, errors are collected in `ast.stylesheet.parsingErrors`
   - `source` (string) - File path for better error reporting
+  - `preserveFormatting` (boolean) - Insert whitespace AST nodes and store raw formatting properties on nodes for identity round-trip. When `true`, whitespace between siblings is preserved as `CssWhitespaceAST` nodes, and raw formatting properties (`rawPrelude`, `rawBetween`, `rawValue`, `rawSource`) are stored on relevant nodes. Default: `false`
 
 #### Returns
 
@@ -53,6 +54,8 @@ Converts a CSS AST back to CSS string with configurable formatting.
 - `options` (CompilerOptions, optional) - Stringification options
   - `indent` (string) - Indentation string (default: `'  '`)
   - `compress` (boolean) - Whether to compress/minify the output (default: `false`)
+  - `identity` (boolean) - Reproduce the original CSS exactly as parsed. Requires `preserveFormatting: true` during parsing. Walks the AST including whitespace nodes and uses raw formatting properties to reconstruct the original output. Inserted or modified nodes without raw properties are emitted in beautified format. Falls back to beautified output when `preserveFormatting` was not used. Default: `false`
+  - `removeEmptyRules` (boolean) - Remove rules with empty declaration blocks from the output. Works in all modes (beautified, compressed, identity). Default: `false`
 
 #### Returns
 
@@ -92,7 +95,7 @@ type CssStylesheetAST = {
   type: CssTypes.stylesheet;
   stylesheet: {
     source?: string;
-    rules: CssRuleAST[];
+    rules: Array<CssAtRuleAST | CssWhitespaceAST>;
     parsingErrors?: CssParseError[];
   };
 };
@@ -188,8 +191,10 @@ Options for the stringifier.
 
 ```typescript
 type CompilerOptions = {
-  indent?: string;    // Default: '  '
-  compress?: boolean; // Default: false
+  indent?: string;          // Default: '  '
+  compress?: boolean;       // Default: false
+  identity?: boolean;       // Default: false
+  removeEmptyRules?: boolean; // Default: false
 };
 ```
 
@@ -290,6 +295,49 @@ console.log(compressed);
 // Output: .example{color:red;font-size:16px}
 ```
 
+### Identity Round-Trip
+
+Reproduce the original CSS exactly as it was written, preserving all whitespace, comments, and formatting:
+
+```javascript
+import { parse, stringify } from '@adobe/css-tools';
+
+const css = '.example  {  color:  red;  font-size:16px  }';
+
+// Parse with preserveFormatting to store original source
+const ast = parse(css, { preserveFormatting: true });
+
+// Stringify with identity mode to reproduce the original CSS
+const output = stringify(ast, { identity: true });
+console.log(output === css); // true
+```
+
+When `preserveFormatting` was not used during parsing, identity mode falls back to beautified output.
+
+### Removing Empty Rules
+
+Strip rules with empty declaration blocks from the output:
+
+```javascript
+import { parse, stringify } from '@adobe/css-tools';
+
+const css = '.empty {} .keep { color: red; }';
+const ast = parse(css);
+
+// Beautified without empty rules
+const output = stringify(ast, { removeEmptyRules: true });
+console.log(output);
+// Output:
+// .keep {
+//   color: red;
+// }
+
+// Also works with compressed mode
+const compressed = stringify(ast, { compress: true, removeEmptyRules: true });
+console.log(compressed);
+// Output: .keep{color:red;}
+```
+
 ## TypeScript Integration
 
 The library provides comprehensive TypeScript support with full type definitions for all AST nodes and functions:

docs/AST.md

@@ -36,7 +36,7 @@ The root node representing an entire CSS document.
 
 **Properties:**
 - `stylesheet.source` (optional): Source file path
-- `stylesheet.rules`: Array of top-level rules
+- `stylesheet.rules`: Array of top-level rules (may include `whitespace` nodes when `preserveFormatting: true`)
 - `stylesheet.parsingErrors` (optional): Array of parse errors when `silent` option is used
 
 **Example:**
@@ -106,6 +106,21 @@ A CSS comment.
 }
 ```
 
+### `whitespace`
+
+A whitespace node that preserves original formatting between sibling nodes. Only present when `preserveFormatting: true` is used during parsing.
+
+**Properties:**
+- `value`: The whitespace text (spaces, newlines, tabs, etc.)
+
+**Example:**
+```json
+{
+  "type": "whitespace",
+  "value": "\n\n"
+}
+```
+
 ### `media`
 
 A `@media` rule.
@@ -364,3 +379,39 @@ This is useful for:
 - Source mapping
 - Code analysis tools
 - IDE integration
+
+## Formatting Properties (`preserveFormatting: true`)
+
+When parsing with `preserveFormatting: true`, the parser stores additional formatting metadata on AST nodes to support exact round-trip via identity mode. These properties are optional and only present when formatting is preserved.
+
+### Whitespace Nodes
+
+`CssWhitespaceAST` nodes are inserted between sibling nodes in all arrays (rules, declarations, keyframes) to preserve the original whitespace and line breaks.
+
+### Raw Properties on Nodes
+
+- **`rawPrelude`** (on rules, at-rules with blocks): The exact original text before `{`, preserving whitespace between selector/condition and brace
+- **`rawBetween`** (on declarations): The text between the property name and value, including `:` and any surrounding whitespace (e.g., `": "` or `":  "`)
+- **`rawValue`** (on declarations): The untrimmed original value text
+- **`rawSource`** (on statement at-rules: import, charset, namespace, custom-media, layer statement): The exact original text of the entire at-rule
+
+### AST Modification with Identity Mode
+
+Because formatting data is stored per-node rather than as a single cached string, you can freely insert, remove, or modify AST nodes and identity mode will reflect the changes:
+
+```typescript
+const ast = parse(css, { preserveFormatting: true });
+
+// Insert a new rule — it will be beautified since it has no raw properties
+ast.stylesheet.rules.push({
+  type: CssTypes.rule,
+  selectors: ['.new'],
+  declarations: [{ type: CssTypes.declaration, property: 'color', value: 'blue' }]
+});
+
+// Remove a rule — the surrounding whitespace nodes naturally adapt
+ast.stylesheet.rules.splice(1, 1);
+
+// Identity mode outputs original formatting for untouched nodes + beautified for new nodes
+stringify(ast, { identity: true });
+```

docs/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Add `preserveFormatting` parser option to insert whitespace AST nodes and store raw formatting properties for identity round-trip
+- Add `CssTypes.whitespace` node type (`CssWhitespaceAST`) to represent whitespace between sibling nodes
+- Add `identity` compiler option to reproduce original CSS exactly as parsed (round-trip fidelity), with support for AST modifications
+- Add `removeEmptyRules` compiler option to strip rules with empty declaration blocks
+- Add raw formatting properties: `rawPrelude`, `rawBetween`, `rawValue`, `rawSource` on relevant AST nodes
+- Export `CompilerOptions`, `ParseOptions`, and `CssWhitespaceAST` types from the public API
+
 ## [4.4.4] - 2025-07-22
 
 ### Changed

docs/EXAMPLES.md

@@ -245,6 +245,53 @@ console.log(formatted);
 // }
 ```
 
+### Identity Round-Trip
+
+Reproduce the original CSS exactly as it was written, preserving all whitespace,
+comments, and formatting:
+
+```javascript
+import { parse, stringify } from '@adobe/css-tools';
+
+const css = `body  {
+  font-size:  12px;
+  color:  #333;
+}`;
+
+// Parse with preserveFormatting to store original source
+const ast = parse(css, { preserveFormatting: true });
+
+// Stringify with identity mode
+const output = stringify(ast, { identity: true });
+console.log(output === css); // true — exact round-trip
+```
+
+### Removing Empty Rules
+
+```javascript
+import { parse, stringify } from '@adobe/css-tools';
+
+const css = `
+  .unused {}
+  .active { color: red; }
+`;
+
+const ast = parse(css);
+
+// Remove empty rules in beautified output
+const output = stringify(ast, { removeEmptyRules: true });
+console.log(output);
+// Output:
+// .active {
+//   color: red;
+// }
+
+// Also works with compressed mode
+const compressed = stringify(ast, { compress: true, removeEmptyRules: true });
+console.log(compressed);
+// Output: .active{color:red;}
+```
+
 ## Working with Complex CSS
 
 ### Nested Rules and At-Rules

src/CssPosition.ts

@@ -2,13 +2,13 @@
  * Store position information for a node
  */
 export default class Position {
-  start: { line: number; column: number };
-  end: { line: number; column: number };
+  start: { line: number; column: number; offset?: number };
+  end: { line: number; column: number; offset?: number };
   source?: string;
 
   constructor(
-    start: { line: number; column: number },
-    end: { line: number; column: number },
+    start: { line: number; column: number; offset?: number },
+    end: { line: number; column: number; offset?: number },
     source: string,
   ) {
     this.start = start;

src/index.ts

@@ -4,5 +4,7 @@ export const parse = parseFn;
 export const stringify = stringifyFn;
 export * from './CssParseError';
 export * from './CssPosition';
+export type { ParseOptions } from './parse';
+export type { CompilerOptions } from './stringify';
 export * from './type';
 export default { parse, stringify };