feat: safely parse mangled CSS with safeParser

[joshfester]

Adds a safeParser option to use https://github.com/postcss/postcss-safe-parser when parsing stylesheets. This allows parsing CSS that may contain some errors.

[coderabbitai]

Walkthrough

This PR introduces a new optional safeParser boolean configuration option to the Beasties package. When enabled, it uses PostCSS's safe parser for fault-tolerant CSS parsing of malformed stylesheets. The option is propagated through type definitions, documentation, the parsing pipeline, and includes test coverage.

Changes

Cohort / File(s)	Change Summary
Configuration & Type Definitions packages/beasties/README.md, packages/beasties/src/index.d.ts, packages/beasties/src/types.ts	Added optional safeParser?: boolean property to the Options interface and documented in README.
Parsing Implementation packages/beasties/src/css.ts	Updated parseStylesheet() function signature to accept optional options parameter with safeParser flag; imports postcss-safe-parser and conditionally uses it when options.safeParser is true.
Core Processing Logic packages/beasties/src/index.ts	Modified processStyle() to pass safeParser option from this.options.safeParser to parseStylesheet() calls for both main and inverse AST builds.
Test Coverage packages/beasties/test/parse.test.ts	Added new test suite for safeParser option that verifies fault-tolerant parsing of malformed CSS (missing closing brace) produces expected output without throwing errors.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Homogeneous changes across files following a single pattern (adding new boolean option)
• Straightforward conditional logic in parsing pipeline
• Limited scope with consistent modifications
• Test case provides clear validation of the new feature
• No complex control-flow changes or intricate business logic

Possibly related PRs

• fix: making pruneSource work #138 — Also modifies processStyle() flow in packages/beasties/src/index.ts, adding file-writing and pruneSource logic alongside this PR's safeParser option propagation.
• fix: correctly handle CSS layers #123 — Modifies the same processStyle() function to adjust rule-handling logic (adding @layer support), overlapping with this PR's option propagation.

Suggested reviewers

• danielroe
• alan-agius4

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the safeParser option addition and its purpose for parsing CSS with errors, matching the changeset content.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Title check	✅ Passed	The title clearly and specifically describes the main change: introducing a safeParser option to parse malformed CSS safely using postcss-safe-parser.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/beasties/test/parse.test.ts (1)

78-101: Good basic test coverage.

The test successfully verifies that malformed CSS doesn't throw an error when safeParser is enabled. This provides essential smoke test coverage for the feature.

You could optionally enhance the test to verify that the CSS rule is actually processed (e.g., checking that the style tag contains some CSS), though the current basic coverage is acceptable:

     // Verify the HTML was processed without throwing
     expect(result).toContain('Test')
     expect(result).toContain('data-beasties-container')
+    // Optionally verify CSS was processed
+    expect(result).toContain('<style>')
+    expect(result).toContain('.test')
   })

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9bb8e58 and ea920d2.

⛔ Files ignored due to path filters (3)

• packages/beasties-webpack-plugin/test/fixtures/fs-access/dist/style.css is excluded by !**/dist/**
• packages/beasties/package.json is excluded by !**/package.json
• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml, !pnpm-lock.yaml

📒 Files selected for processing (6)

• packages/beasties/README.md (1 hunks)
• packages/beasties/src/css.ts (1 hunks)
• packages/beasties/src/index.d.ts (1 hunks)
• packages/beasties/src/index.ts (1 hunks)
• packages/beasties/src/types.ts (1 hunks)
• packages/beasties/test/parse.test.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

packages/beasties/src/index.ts (1)

packages/beasties/src/css.ts (1)

• parseStylesheet (30-35)

packages/beasties/test/parse.test.ts (1)

packages/beasties/src/index.ts (1)

• Beasties (34-707)

🔇 Additional comments (6)

packages/beasties/README.md (1)

142-142: Documentation looks good.

The safeParser option is well-documented. The description accurately explains its purpose for fault-tolerant CSS parsing.

packages/beasties/src/index.d.ts (1)

66-66: LGTM!

The type definition is correct and properly positioned in the Options interface.

packages/beasties/src/types.ts (1)

99-102: LGTM!

The type definition with JSDoc is clear and correctly documents the default behaviour.

packages/beasties/src/css.ts (2)

30-34: LGTM!

The implementation correctly uses optional chaining and maintains backward compatibility by making the options parameter optional.

---

22-22: Repository is missing critical package.json files.

The repository structure is incomplete: no package.json exists at root level, nor in any of the package directories (packages/beasties/, packages/beasties-webpack-plugin/, packages/vite-plugin-beasties/). This prevents verification of whether postcss-safe-parser is listed as a dependency. The css.ts import statement is present, but dependency resolution cannot be confirmed without package.json files. Please verify that the repository is in the correct state and that all package.json files are present before this review comment can be resolved.

packages/beasties/src/index.ts (1)

429-430: LGTM!

The safeParser option is correctly propagated to both the main AST and the inverse AST parsing calls, ensuring consistent parsing behaviour throughout the processing pipeline.

[danielroe]

this looks great! any reason not to enable by default? 🤔

it would also be great to add a test 🙏