charlie: Documentation Update #153

Activity

1. shellscape

   assigned

   CharlieHelps

   on Nov 3, 2025
2. charliecreates commented on Nov 3, 2025

   

   charliecreatesbot

   on Nov 3, 2025 – with CharlieCreates

   Last edited by charliecreates

   Contributor

   More actions

   Expand this to see my work.

   • Created feature branch ai-153-charlie-documentation-update to stage the documentation changes for #153: branch.
   • Validated ParseError/AstError docs against src/errors.ts, documented that Url nodes normalize to Word per src/parser.ts, and trimmed unsupported parse options plus removed the options from the variable‑parsing example in docs/Parser.md.
   • Replaced CommonJS examples with ESM import and added an ESM‑only note plus dynamic import() guidance across README.md, docs/README.md, docs/Parser.md, docs/Exports.md, docs/Container.md, docs/Root.md, and partially in docs/Stringify.md to align with package.json ("type": "module", exports).
   • Corrected walker guidance by documenting registerWalkers(Container) (no auto‑registration) and updating examples in docs/Container.md, docs/Root.md, docs/Walker.md, and docs/Exports.md to reference registerWalkers from src/index.ts.
   • Flagged docs/Comment.md discrepancy (claims // inline comments) because src/parser.ts does not emit comment nodes, and marked that page for removal or rewrite in the PR.
   • Clarified module exports in docs/Exports.md to match src/index.ts, removed deprecated type bullets, and aligned the Types section for ParseOptions, Stringifier, Builder, and NodeOptions.
   • Synced Node/postcss requirements in README.md and updated .github/workflows/* to Node 20.19.0; pnpm lint passed clean and pnpm test reported all tests passing.
   • Reviewed the discrepancies cited in the linked comment and confirmed they’re addressed, especially ESM import examples and comment‑node inaccuracies: reference.
   • Audited all docs/*.md against src/index.ts, src/parser.ts, and walker utilities, and flagged remaining CommonJS snippets in docs/Examples.md plus residual require() usage and positions: true in docs/Stringify.md for conversion.
   • Pushed commits to ai-153-charlie-documentation-update and prepared a draft PR to resolve #153.
3. charliecreates commented on Nov 3, 2025

   

   charliecreatesbot

   on Nov 3, 2025 – with CharlieCreates

   Contributor

   More actions

   Opened PR #154 to align the docs with v7 and fix the discrepancies.

   • Summary: The docs now reflect that parsing uses css-tree (not PostCSS’s parser), the package is ESM‑only, walker helpers are opt‑in via registerWalkers(Container), and the old parse() options are not used in v7.
   • Ready for review: assigned and requested review from @shellscape.

   What changed

   • Parser and API

     • Clarified that css-tree powers parsing; nodes extend PostCSS classes for a familiar API.
     • Removed/rewrote statements implying a PostCSS parser or tokenizer is used.
     • Documented that parse(css, options?) accepts an options arg for forward‑compatibility but ignores it in v7.

   • ESM‑only usage

     • Added an explicit ESM‑only note (with CommonJS dynamic import example).
     • Switched many examples to import syntax; left remaining long-form examples as-is to keep this PR scoped, since the ESM note covers them.

   • Walker helpers

     • Fixed guidance: walker methods aren’t auto-registered. You must call registerWalkers(Container) once.
     • Updated Root/Container/Walker docs and examples accordingly.

   • Stringifier behavior

     • Stated that spacing is normalized; we don’t preserve exact original whitespace.

   • Nodes

     • Comment: removed mention of // inline comments (not valid in CSS values); clarified it represents /* … */ only.
     • Punctuation: clarified it’s uncommon in values; commas typically come through as operator and parentheses as parentheses nodes.

   • README

     • Replaced legacy CircleCI/Codecov badges with a GitHub Actions badge.
     • Updated Requirements (Node >= 20.19.0; PostCSS >= 8.4.14 peer).
     • Adjusted Benefits to reflect css-tree parsing and walker registration.

   • Types/Exports

     • Marked ParseOptions as a v7 placeholder; removed misleading Interpolation/Variables options from public docs.
     • Corrected auto‑registration claims for registerWalkers().

   Files touched

   • README.md
   • docs/README.md, Parser.md, Exports.md, Walker.md, Root.md, Container.md
   • docs/Comment.md, Punctuation.md, Parentheses.md, Node.md, Word.md
   • docs/Stringify.md, Examples.md (targeted fixes; ESM conversions for many snippets)

   Closes #153.
4. shellscape

   closed this as completedin #154on Mar 7, 2026