cssupgrade 0.0.0-stage → 2026.0.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "cssupgrade",
+  "displayName": "CSSupgrade",
+  "description": "Auto-upgrade CSS syntax to new features based on browser support.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Johannes Maron",
+    "email": "security@codingjoe.dev"
+  },
+  "homepage": "https://github.com/codingjoe/cssupgrade",
+  "repository": "https://github.com/codingjoe/cssupgrade",
+  "license": "BSD-2-Clause",
+  "keywords": [
+    "css",
+    "modernize",
+    "upgrade",
+    "codemod",
+    "ast",
+    "transform",
+    "nesting"
+  ]
+}

package/.editorconfig

@@ -0,0 +1,27 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+charset = utf-8
+end_of_line = lf
+max_line_length = 88
+
+[*.{json,yml,yaml,mjs,js,jsx,vue,toml}]
+indent_size = 2
+ij_javascript_force_semicolon_style = false
+
+[*.{html,htm,svg,xml}]
+indent_size = 2
+max_line_length = 120
+
+[LICENSE]
+insert_final_newline = false
+
+[*.{md,markdown}]
+indent_size = 2
+max_line_length = 80

package/.gitattributes

@@ -0,0 +1 @@
+package-lock.json linguist-generated

package/.github/agents/superjoe.agent.md

@@ -0,0 +1,65 @@
+---
+# For format details, see: https://gh.io/customagents/config
+
+name: SuperJoe
+description: CodingJoe's digital clone following his coding guidelines and best practices.
+---
+
+# SuperJoe
+
+## Planning
+
+You MUST ALWAYS follow the `naming-things` guidelines. Use the following command to access the guidelines:
+
+```console
+curl -sSL https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md | head -n 500
+```
+
+You MUST ALWAYS read the `CONTRIBUTING.md` file before planning or writing any code.
+You MUST ALWAYS search the documentation and amend or update it as necessary.
+You MUST ALWAYS check for pre-commit hooks and run them before committing code.
+You MUST ALWAYS ensure that all new code is fully tested with 100% coverage. Unreachable code branches MUST be removed.
+
+## Writing Code
+
+Less code is more! Use the latest language features and libraries to achieve more with less code.
+
+Do not add new dependencies, but if you do, they must be widely adopted and well-maintained in the open-source community.
+
+You are a strong FOSS advocate with a preference for permissive licenses like BSD or MIT.
+
+Use generators instead of adding items to lists or arrays.
+
+Use class syntax for all object-oriented code.
+Use named functions instead of anonymous functions whenever possible.
+Avoid overly complex functions. Break them into smaller functions if necessary.
+Docstrings should be written in present tense imperative mood.
+They must start with a capital letter and end with a period.
+Docstrings must describe the external behavior of the function, class, or method.
+Docstrings should avoid redundant phrases like "This function" or "This method".
+Class docstrings must not repeat the class name or start with a verb since they don't do anything themselves.
+Avoid code comments unless they describe behavior of 3rd party code or complex algorithms.
+Avoid loops in favor of recursive functions or generator functions.
+Avoid functions or other code inside functions.
+Avoid if-statements in favor of switch/match-statements or polymorphism.
+Do not assign names to objects which are returned in the next line.
+
+## Python
+
+Follow PEP 8 guidelines for code style.
+EAFP (Easier to Ask Forgiveness than Permission) is preferred over LBYL (Look Before You Leap).
+Use type hints for all public functions, classes, and methods.
+Use dataclasses for simple data structures.
+Use context managers for resource management.
+Use list/set/dict comprehensions instead of loops for creating collections.
+Use generators for large data sets to save memory.
+Use the walrus operator (`:=`) for inline assignments when it improves readability.
+
+### JavaScript
+
+Use `#` for private methods.
+Write docstrings with jsdoc type annotations for all functions, classes, and methods.
+
+### TypeScript
+
+Use `#` for private methods.

package/.github/copilot-instructions.md

@@ -0,0 +1,32 @@
+YOUR PRIORITY IS TO ENSURE THE SAFETY OF ALL TRANSFORMATIONS.
+
+When writing code, you MUST ALWAYS follow the [naming guidelines](https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md).
+
+Usage:
+
+```console
+curl -sL https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md | head -n 500
+```
+
+All code must be fully tested with a 100% coverage. Unreachable code must be removed.
+Follow the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines for testing and linting.
+
+All transformers must be documented in the README.md.
+
+Use class syntax for all object-oriented code.
+Use named functions instead of anonymous functions whenever possible.
+Use `#` for private methods.
+
+Avoid overly complex functions. Break them into smaller functions if necessary.
+
+Write docstrings with jsdoc type annotations for all functions, classes, and methods.
+Docstrings should be written in present tense imperative mood.
+They must start with a capital letter and end with a period.
+Docstrings must describe the external behavior of the function, class, or method.
+Docstrings should avoid redundant phrases like "This function" or "This method".
+Class docstrings must not repeat the class name or start with a verb since they don't do anything themselves.
+Avoid code comments unless they describe behavior of 3rd party code or complex algorithms.
+Avoid loops in favor of recursive functions or generator functions.
+Avoid functions or other code inside functions.
+Avoid if-statements in favor of switch-statements or polymorphism.
+Do not assign names to objects which are returned in the next line.

package/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: daily
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: daily

package/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  readme:
+    name: "Word Weasel / README.md"
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    steps:
+      - uses: actions/checkout@v7
+      - id: read_readme
+        run: |
+          echo "::set-output name=content::$(cat README.md)"
+      - uses: codingjoe/word-weasel@v1
+        with:
+          text: ${{ steps.read_readme.outputs.content }}
+  node-test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: package.json
+      - run: npm ci
+      - run: npm test
+      - uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          flags: css
+          files: lcov.info

package/.github/workflows/pr.yml

@@ -0,0 +1,28 @@
+# Write better PRs and commit messages
+name: "Word Weasel"
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - reopened
+permissions: {}
+jobs:
+  pr-title:
+    name: "PR Title"
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    steps:
+      - uses: codingjoe/word-weasel@v1
+        with:
+          text: ${{ github.event.pull_request.title }}
+  pr-body:
+    name: "PR Body"
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    steps:
+      - uses: codingjoe/word-weasel@v1
+        with:
+          text: ${{ github.event.pull_request.body }}

package/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+on:
+  release:
+    types: [published]
+permissions:
+  id-token: write
+  contents: read
+jobs:
+  npmjs:
+    name: npmjs.org
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: package.json
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install -g npm@latest
+      - run: npm ci
+      - run: npm config set git-tag-version=false
+      - run: npm version ${{ github.event.release.tag_name }}
+      - run: npm publish

package/.oxfmtrc.json

@@ -0,0 +1,3 @@
+{
+  "semi": false
+}

package/.pre-commit-config.yaml

@@ -0,0 +1,52 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: check-json
+      - id: check-yaml
+      - id: destroyed-symlinks
+      - id: check-executables-have-shebangs
+      - id: end-of-file-fixer
+      - id: no-commit-to-branch
+        args: [--branch, main]
+      - id: detect-private-key
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-config
+          - mdformat-footnote
+          - mdformat-gfm
+          - mdformat-gfm-alerts
+          - mdformat-frontmatter
+        args: [--number]
+  - repo: https://github.com/google/yamlfmt
+    rev: v0.21.0
+    hooks:
+      - id: yamlfmt
+  - repo: https://github.com/btford/write-good
+    rev: v1.0.8
+    hooks:
+      - id: write-good
+        args: [--no-passive]
+  - repo: https://github.com/oxc-project/mirrors-oxlint
+    rev: v1.60.0
+    hooks:
+      - id: oxlint
+  - repo: https://github.com/oxc-project/mirrors-oxfmt
+    rev: v0.78.0
+    hooks:
+      - id: oxfmt
+  - repo: https://github.com/codingjoe/esupgrade
+    rev: 2026.1.2 # Use the latest release
+    hooks:
+      - id: esupgrade
+ci:
+  autoupdate_schedule: weekly
+  skip:
+    - no-commit-to-branch
+    - write-good
+    - esupgrade

package/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+- id: cssupgrade
+  name: CSSupgrade
+  description: 'Upgrade your CSS syntax to Baseline.'
+  entry: cssupgrade
+  args: [--check, --write]
+  language: node
+  types_or: [css]
+  require_serial: true

package/AGENTS.md

@@ -0,0 +1,54 @@
+# CSSupgrade
+
+The package includes transformers for upgrading CSS syntax.
+
+## Categories
+
+- [Widely Available](./src/widelyAvailable/): Transformers for features available in all major browsers for at least 30 months.
+- [Newly Available](./src/newlyAvailable/): Transformers for features available in all major browsers for 0-30 months.
+
+For a full list of transformations, see [README.md](./README.md).
+
+## Package Structure
+
+- [bin/](./bin/): Command-line interface script.
+- [src/](./src/): Source code and transformers.
+- [tests/](./tests/): Test suite.
+
+For contributing guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Instructions
+
+Use EOF syntax to run node scripts directly from the command line. For example:
+
+```bash
+node --input-type=module <<'EOF'
+import { transform } from './src/index.js';
+
+const sample = '.a { color: red } .a .b { color: blue }';
+const res = transform(sample);
+console.log('modified:', res.modified);
+console.log('code:\n' + res.code);
+EOF
+```
+
+## Writing Transformers
+
+The pipeline parses CSS with `parseCss` from `src/parser.js`, which returns the
+css-tree syntax tree and the ranges of all comments.
+
+Every transformer declares a pre-filter in `src/prefilters.js`, so files that
+cannot contain the pattern skip the parse. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Writing Docs
+
+### README.md
+
+We add one new section per transformation:
+
+1. Headline + MDN link
+2. One diff-based example.
+3. Notable exception, which are not transformed.
+
+We MUST NOT add any comments about "what it does".
+The functionality documentation is fully covered by the diff-based example.

package/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+To run tests locally, follow these steps:
+
+```console
+npm ci
+npm test
+```
+
+We use pre-commit hooks to lint and format code before committing.
+
+To install the pre-commit hooks, run:
+
+```console
+uvx pre-commit install
+```
+
+Or instead run the linters once with:
+
+```console
+uvx pre-commit run --all-files
+```
+
+## Naming conventions
+
+When writing code, please follow the [naming guidelines](https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md).
+
+## Baseline release dates
+
+The baseline date can be found on
+https://github.com/web-platform-dx/web-features named `baseline_low_date`.
+
+## Pre-filters
+
+Every transformer needs a pre-filter in `src/prefilters.js` and a sample in
+`tests/prefilters.test.js`. A pre-filter lists conditions on the source text,
+and each condition must be necessary: when the source text misses a condition,
+the transformer cannot change the tree. The test suite transforms every sample
+with and without pre-filters and compares the results, so an unsound condition
+fails the tests.

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Johannes Maron
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./images/logo-dark.svg?v=2">
+    <source media="(prefers-color-scheme: light)" srcset="./images/logo-light.svg?v=2">
+    <img alt="CSSupgrade: Auto-upgrade your CSS syntax" src="./images/logo-light.svg?v=2">
+  </picture>
+</p>
 
-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.
+# CSSupgrade [![npm version](https://img.shields.io/npm/v/cssupgrade.svg?style=flat-square)](https://www.npmjs.com/package/cssupgrade) [![coverage status](https://img.shields.io/codecov/c/github/codingjoe/cssupgrade/main.svg?style=flat-square)](https://codecov.io/gh/codingjoe/cssupgrade) [![license](https://img.shields.io/npm/l/cssupgrade.svg?style=flat-square)](https://github.com/codingjoe/cssupgrade/blob/main/LICENSE)
+
+Keeping your CSS up to date with full browser compatibility.
+
+## Sponsors
+
+[![Sponsors](https://django.the-box.sh/sponsors/codingjoe/cssupgrade.svg)](https://github.com/sponsors/codingjoe)
+
+## Usage
+
+CSSupgrade is safe and meant to be used automatically on your codebase.
+We recommend integrating it into your development workflow using [pre-commit], [husky], or as an agent skill.
+
+### CLI
+
+To try it out on a repository without writing changes, run:
+
+```bash
+npx -y cssupgrade $(git ls-files '*.css')
+```
+
+To transform code from standard input, pass `-` as the input path:
+
+```bash
+echo '.a { .b { color: red } }' | npx cssupgrade -
+```
+
+For help with available options:
+
+```bash
+npx cssupgrade --help
+```
+
+### pre-commit
+
+```bash
+uvx pre-commit install
+```
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/codingjoe/cssupgrade
+    rev: 2026.1.0 # Use the latest release
+    hooks:
+      - id: cssupgrade
+```
+
+```bash
+pre-commit run cssupgrade --all-files
+```
+
+### Husky
+
+Assuming Husky is already initialized and `.husky/pre-commit` already contains `set -e`, append:
+
+```bash
+echo "git diff --cached --name-only --diff-filter=ACMR -z -- '*.css' | xargs -0 sh -c 'test \"\$#\" -eq 0 && exit 0; npx -y cssupgrade --write -- \"\$@\"' sh" >> .husky/pre-commit
+echo "git diff --cached --name-only --diff-filter=ACMR -z -- '*.css' | xargs -0 sh -c 'test \"\$#\" -eq 0 && exit 0; git add -- \"\$@\"' sh" >> .husky/pre-commit
+```
+
+### Agent Skill
+
+CSSupgrade is available as a skill in [Claude Code]. The plugin is distributed via the [codingjoe/claude-plugins](https://github.com/codingjoe/claude-plugins) marketplace. To use it:
+
+1. Run `/plugin marketplace add codingjoe/claude-plugins`
+2. Run `/plugin install cssupgrade@codingjoe`
+
+The skill will analyze your selected styles and suggest transformations based on the Baseline browser support policy.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://web-platform-dx.github.io/assets/img/baseline-wordmark-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://web-platform-dx.github.io/assets/img/baseline-wordmark.svg">
+  <img alt="Baseline: widely available" src="https://web-platform-dx.github.io/assets/img/baseline-wordmark.svg" height="32" align="right">
+</picture>
+
+## Browser Support & Baseline
+
+All transformations are based on [Web Platform Baseline][baseline] features. Baseline tracks which web platform features are safe to use across browsers.
+
+By default, CSSupgrade uses **widely available** features, meaning they work in all major browsers (Chrome, Edge, Safari, Firefox) for at least 30 months. This ensures full compatibility while keeping your styles modern.
+
+You can opt into **newly available** features (available in all browsers for 0-30 months) with:
+
+```bash
+npx cssupgrade --baseline newly-available <files>
+```
+
+For more information about Baseline browser support, visit [web.dev/baseline][baseline].
+
+## Supported File Types & Languages
+
+- `.css` - CSS stylesheets
+
+## Transformations
+
+> [!NOTE]
+> A transformation applies only to CSS that the parser accepts. Unknown at-rules
+> and invalid declarations stay unchanged.
+
+Rules that cannot nest keep their original text.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://web-platform-dx.github.io/assets/img/baseline-widely-word-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://web-platform-dx.github.io/assets/img/baseline-widely-word.svg">
+  <img alt="Baseline: widely available" src="https://web-platform-dx.github.io/assets/img/baseline-widely-word.svg" height="32" align="right">
+</picture>
+
+### Widely available
+
+#### Flat rules → [CSS nesting][mdn-nesting]
+
+```diff
+ .card {
+   padding: 1rem;
+-}
+-.card .title { font-weight: bold; }
+-.card:hover { color: red; }
++  .title { font-weight: bold; }
++  &:hover { color: red; }
++}
+```
+
+Only adjacent rules are nested, so the cascade order stays the same.
+Every child selector must repeat a parent selector, and all parent selectors must have the same specificity.
+Rules inside `@media`, `@supports`, `@container`, `@layer`, `@scope`, and `@starting-style` blocks are nested as well.
+
+```css
+/* Not transformed - `@keyframes` children are keyframe selectors */
+@keyframes fade {
+  from { opacity: 0 }
+}
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://web-platform-dx.github.io/assets/img/baseline-newly-word-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://web-platform-dx.github.io/assets/img/baseline-newly-word.svg">
+  <img alt="Baseline: Newly available" src="https://web-platform-dx.github.io/assets/img/baseline-newly-word.svg" height="32" align="right">
+</picture>
+
+### Newly available
+
+No transformations are available yet.
+
+## Versioning
+
+CSSupgrade uses the [calver] `YYYY.MINOR.PATCH` versioning scheme.
+
+The year indicates the baseline version. New transformations are added in minor releases, while patches are reserved for bug fixes.
+
+## Related Projects
+
+Thanks to [esupgrade] for inspiring CSSupgrade.
+
+### Distinction
+
+[esupgrade] upgrades JavaScript and TypeScript syntax.
+CSSupgrade applies the same Baseline policy to CSS.
+
+[baseline]: https://web.dev/baseline/
+[calver]: https://calver.org/
+[claude code]: https://code.claude.com
+[esupgrade]: https://github.com/codingjoe/esupgrade
+[husky]: https://typicode.github.io/husky/
+[mdn-nesting]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_nesting
+[pre-commit]: https://pre-commit.com/