cssupgrade 0.0.0-stage → 2026.0.0

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/

package/bin/cssupgrade.js

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+
+import { Command, Option } from "commander"
+import { diffLines } from "diff"
+import { once } from "events"
+import fs from "fs/promises"
+import process from "node:process"
+import pkg from "../package.json" with { type: "json" }
+import { transform } from "../src/index.js"
+import { WorkerPool } from "../src/pool.js"
+
+/**
+ * CLI tool for cssupgrade.
+ */
+
+/**
+ * Process a file using a worker thread.
+ * @param {string} filePath - Path to the file to process.
+ * @param {Object} options - Processing options.
+ * @param {string} options.baseline - Baseline level for transformations.
+ * @param {boolean} options.check - Whether to only check for changes.
+ * @param {boolean} options.write - Whether to write changes to file.
+ * @param {boolean} options.verbose - The verbosity level for logging.
+ * @param {import("../src/pool.js").TransformWorker} worker - Worker that transforms the file.
+ * @returns {Promise<{modified: boolean, error: boolean}>} Result of processing.
+ */
+async function processFile(filePath, options, worker) {
+  // Validate that the provided path exists and is a file.
+  try {
+    const stats = await fs.stat(filePath)
+    if (!stats.isFile()) {
+      console.error(`Error: '${filePath}' is not a file`)
+      process.exit(1)
+    }
+  } catch (error) {
+    console.error(`Error: Cannot access '${filePath}': ${error.message}`)
+    process.exit(1)
+  }
+
+  try {
+    // The worker only ships the original source when a diff can be printed.
+    const showsDiff = options.check || !options.write
+    const workerResult = await worker.transform({
+      filePath,
+      baseline: options.baseline,
+      includeOriginal: showsDiff,
+    })
+
+    if (!workerResult.success) {
+      if (options.verbose) console.error(workerResult.error)
+      console.error(
+        `\x1b[31m✗\x1b[0m Error: ${filePath}: ${workerResult.error.message}`,
+      )
+      return { modified: false, error: true }
+    }
+
+    const result = workerResult.result
+
+    if (result.modified) {
+      if (showsDiff) {
+        displayDiff(filePath, result.original, result.code)
+      }
+
+      if (options.write) {
+        await fs.writeFile(filePath, result.code, "utf8")
+        if (!options.check) {
+          console.info(`\x1b[32m✓\x1b[0m ${filePath}`)
+        }
+      }
+
+      return { modified: true, error: false }
+    }
+
+    // Show unmodified files unless in check-only mode
+    if (!options.check) {
+      console.debug(`  ${filePath}`)
+    }
+    return { modified: false, error: false }
+  } catch (error) {
+    console.error(`\x1b[31m✗\x1b[0m Error: ${filePath}: ${error.message}`)
+    return { modified: false, error: true }
+  }
+}
+
+/**
+ * Display a diff between original and modified code.
+ * @param {string} filePath - Path to the file being displayed.
+ * @param {string} original - Original code.
+ * @param {string} modified - Modified code.
+ */
+function displayDiff(filePath, original, modified) {
+  const changes = diffLines(original, modified).filter(
+    ({ added, removed }) => added || removed,
+  )
+
+  console.group(`\x1b[31m✗\x1b[0m ${filePath}`)
+  for (const { added, value } of changes) {
+    const prefix = added ? `  \x1b[32m+ ` : `  \x1b[31m- `
+    for (const line of value.split("\n")) {
+      if (line.trim() !== "") {
+        console.info(`${prefix}${line}\x1b[0m`)
+      }
+    }
+  }
+  console.groupEnd()
+}
+
+/**
+ * Process stdin using the configured transformation options.
+ * @param {Object} options - Processing options.
+ * @param {string} options.baseline - Baseline level for transformations.
+ * @param {boolean} options.check - Whether to only check for changes.
+ * @param {boolean} options.write - Whether to write changes to file.
+ * @param {boolean} options.verbose - The verbosity level for logging.
+ * @returns {Promise<void>} Complete when stdin processing finishes.
+ */
+async function processStdin(options) {
+  if (options.write) {
+    console.error("Error: '--write' cannot be used with stdin")
+    process.exit(1)
+  }
+
+  try {
+    const code = await readStdin()
+    const result = transform(code, options.baseline)
+
+    if (options.check) {
+      if (result.modified) {
+        process.exit(1)
+      }
+      return
+    }
+
+    process.stdout.write(result.code)
+  } catch (error) {
+    if (options.verbose) console.error(error)
+    console.error(`\x1b[31m✗\x1b[0m Error: stdin: ${error.message}`)
+    process.exit(128)
+  }
+}
+
+/**
+ * Read source code from stdin.
+ * @returns {Promise<string>} Source code from stdin.
+ */
+async function readStdin() {
+  process.stdin.setEncoding("utf8")
+  let code = ""
+
+  process.stdin.on("data", (chunk) => {
+    code += chunk
+  })
+  await once(process.stdin, "end")
+  return code
+}
+
+/**
+ * Identify a result that changed the file.
+ * @param {{modified: boolean}} result - Result of processing one file.
+ * @returns {boolean} True when the file changed.
+ */
+function isModified({ modified }) {
+  return modified
+}
+
+/**
+ * Identify a result that failed.
+ * @param {{error: boolean}} result - Result of processing one file.
+ * @returns {boolean} True when the file failed to process.
+ */
+function isFailed({ error }) {
+  return error
+}
+
+/**
+ * Describe a number of files.
+ * @param {number} count - Number of files.
+ * @returns {string} Count followed by a singular or plural noun.
+ */
+function formatFileCount(count) {
+  return `${count} file${count === 1 ? "" : "s"}`
+}
+
+/**
+ * Orchestrates the CLI application.
+ */
+class CLIRunner {
+  constructor(workerPath) {
+    this.workerPool = new WorkerPool(processFile, workerPath)
+  }
+
+  /**
+   * Process files and report results.
+   * @param {string[]} patterns - File paths to process (no globbing).
+   * @param {Object} options - Processing options.
+   */
+  async run(patterns, options) {
+    switch (this.#getInputMode(patterns)) {
+      case "stdin":
+        await processStdin(options)
+        return
+      case "mixed":
+        console.error("Error: '-' cannot be combined with file paths")
+        return process.exit(1)
+      default:
+        break
+    }
+
+    console.time("Processing")
+    // Hand CLI-provided names directly to the worker pool; file validation occurs in processFile.
+    const results = await this.workerPool.processFiles(patterns, options)
+    console.timeEnd("Processing")
+
+    this.#reportSummary(results, options)
+  }
+
+  /**
+   * Classify the input mode selected by CLI arguments.
+   * @param {string[]} patterns - File paths to process.
+   * @returns {"files" | "stdin" | "mixed"} Selected input mode.
+   */
+  #getInputMode(patterns) {
+    const stdinCount = patterns.filter((pattern) => pattern === "-").length
+
+    switch (stdinCount) {
+      case 0:
+        return "files"
+      case 1:
+        return patterns.length === 1 ? "stdin" : "mixed"
+      default:
+        return "mixed"
+    }
+  }
+
+  /**
+   * Report the outcome of a file-processing run.
+   *
+   * @param {Array<{modified: boolean, error: boolean}>} results - Result per file.
+   * @param {Object} options - Processing options.
+   */
+  #reportSummary(results, options) {
+    const modifiedCount = results.filter(isModified).length
+    const errorCount = results.filter(isFailed).length
+
+    console.info("")
+
+    switch (modifiedCount) {
+      case 0:
+        if (errorCount === 0) {
+          console.info("All files are up to date")
+        }
+        break
+      default:
+        this.#reportUpgrades(modifiedCount, options)
+        break
+    }
+
+    if (errorCount > 0) {
+      console.info(`${formatFileCount(errorCount)} failed to process`)
+      // Errors take precedence over the --check flag.
+      process.exit(128)
+    }
+
+    if (options.check && modifiedCount > 0) {
+      process.exit(1)
+    }
+  }
+
+  /**
+   * Report how many files were upgraded.
+   *
+   * @param {number} modifiedCount - Number of files with changes.
+   * @param {Object} options - Processing options.
+   */
+  #reportUpgrades(modifiedCount, options) {
+    switch (true) {
+      case options.check:
+        console.info(
+          `${formatFileCount(modifiedCount)} need${modifiedCount === 1 ? "s" : ""} upgrading`,
+        )
+        if (options.write) {
+          console.info("Changes have been written")
+        }
+        break
+      case options.write:
+        console.info(`✓ ${formatFileCount(modifiedCount)} upgraded`)
+        break
+      default:
+        console.info(`${formatFileCount(modifiedCount)} would be upgraded`)
+        break
+    }
+  }
+}
+
+// Initialize CLI
+const program = new Command()
+const cliRunner = new CLIRunner(new URL("../src/worker.js", import.meta.url))
+
+program
+  .name("cssupgrade")
+  .description("Auto-upgrade your CSS syntax")
+  .version(pkg.version)
+  .argument("<files...>", "Files or directories to process, or '-' to read from stdin")
+  .addOption(
+    new Option("--baseline <level>", "Set baseline level for transformations")
+      .choices(["widely-available", "newly-available"])
+      .default("widely-available"),
+  )
+  .option("--verbose, -v", "Show more detailed output.", false)
+  .option(
+    "--check",
+    "Report which files need upgrading and exit with code 1 if any do",
+    false,
+  )
+  .option("--write", "Write changes to files", false)
+  .action(async (files, options) => {
+    await cliRunner.run(files, options)
+  })
+
+program.parse()

package/images/logo-dark.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="320" font-family="Segoe UI, system-ui, sans-serif" viewBox="0 0 1280 640">
+  <circle cx="260" cy="320" r="200" fill="#2965f1"/>
+  <path fill="none" stroke="#ffffff" stroke-width="48" d="m167 409 95-95 95 95m-190 -95 95-95 95 95m415 50"/>
+  <text x="241" y="148" fill="#c9d1d9" font-size="75" font-weight="bold" transform="matrix(1.6 0 0 1.6 120 120)">
+    CSSupgrade
+  </text>
+  <text x="241" y="192" fill="#c9d1d9" font-size="32" font-style="italic" transform="matrix(1.6 0 0 1.6 120 120)">
+    Auto-upgrade your CSS syntax
+  </text>
+</svg>

package/images/logo-light.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="320" font-family="Segoe UI, system-ui, sans-serif" viewBox="0 0 1280 640">
+  <circle cx="260" cy="320" r="200" fill="#2965f1"/>
+  <path fill="none" stroke="#ffffff" stroke-width="48" d="m167 409 95-95 95 95m-190 -95 95-95 95 95m415 50"/>
+  <text x="241" y="148" font-size="75" font-weight="bold" transform="matrix(1.6 0 0 1.6 120 120)">
+    CSSupgrade
+  </text>
+  <text x="241" y="192" font-size="32" font-style="italic" transform="matrix(1.6 0 0 1.6 120 120)">
+    Auto-upgrade your CSS syntax
+  </text>
+</svg>

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "cssupgrade",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.0.0",
+  "description": "Auto-upgrade your CSS syntax",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "cssupgrade": "./bin/cssupgrade.js"
+  },
+  "scripts": {
+    "test": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=lcov.info --test-coverage-exclude=tests/**/* tests/*.test.js tests/**/*.test.js"
+  },
+  "keywords": [
+    "css",
+    "modernize",
+    "upgrade",
+    "codemod",
+    "ast",
+    "transform",
+    "nesting"
+  ],
+  "author": "Johannes Maron",
+  "license": "BSD-2-Clause",
+  "dependencies": {
+    "commander": ">=14.0.2",
+    "css-tree": "^3.2.1",
+    "diff": ">=8.0.2"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codingjoe/cssupgrade.git"
+  }
+}

package/skills/cssupgrade/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: cssupgrade
+description: CSSupgrade auto-updates CSS syntax to new features based on browser support. Use when the user asks to modernize, upgrade, or clean up CSS syntax.
+allowed-tools: Bash(npx -y cssupgrade *) Read
+---
+
+Use the CLI with `npx` on files or standard input:
+
+```console
+npx -y cssupgrade [--baseline <newly-available|widely-available>] [--check] [--write] <files|->
+```
+
+- Use `--check` to preview changes and fail when updates are needed.
+- Use `-` to read from standard input and write the transformed code to standard output.
+- Use `--write` to apply updates in place for file inputs.
+- Use `--baseline` to choose `newly-available` or `widely-available` (default).

package/src/index.js

@@ -0,0 +1,53 @@
+import * as newlyAvailable from "./newlyAvailable.js"
+import { matchesPrefilter } from "./prefilters.js"
+import * as widelyAvailable from "./widelyAvailable.js"
+
+/**
+ * @typedef {Object} TransformResult
+ * @property {string} code - Transformed CSS source.
+ * @property {boolean} modified - Whether the source changed.
+ */
+
+/**
+ * @typedef {function(string): TransformResult} Transformer
+ */
+
+/**
+ * @typedef {[string, Transformer]} NamedTransformer
+ */
+
+/**
+ * Apply every transformer that passes its pre-filter, then repeat on the result.
+ *
+ * @param {string} code - CSS source text.
+ * @param {NamedTransformer[]} transformers - Transformers to apply.
+ * @param {boolean} globalModified - Whether an earlier pass changed the source.
+ * @returns {TransformResult} Transformed source.
+ */
+function applyTransformersRecursively(code, transformers, globalModified = false) {
+  const passResult = transformers.reduce(
+    (result, [name, transformer]) =>
+      matchesPrefilter(name, result.code) ? transformer(result.code) : result,
+    { code, modified: false },
+  )
+
+  return passResult.modified
+    ? applyTransformersRecursively(passResult.code, transformers, true)
+    : { code: passResult.code, modified: globalModified }
+}
+
+/**
+ * Transform CSS using the transformers of the selected baseline.
+ *
+ * @param {string} code - CSS source text.
+ * @param {string} [baseline] - Baseline level ('widely-available' or 'newly-available').
+ * @returns {TransformResult} Transformed source.
+ */
+export function transform(code, baseline = "widely-available") {
+  const transformers =
+    baseline === "newly-available"
+      ? { ...widelyAvailable, ...newlyAvailable }
+      : widelyAvailable
+
+  return applyTransformersRecursively(code, Object.entries(transformers))
+}

package/src/newlyAvailable.js

@@ -0,0 +1 @@
+export {}

package/src/parser.js

@@ -0,0 +1,43 @@
+import * as csstree from "css-tree"
+
+/**
+ * @typedef {Object} SourceRange
+ * @property {number} start - Offset of the first character.
+ * @property {number} end - Offset after the last character.
+ */
+
+/**
+ * @typedef {Object} ParsedCss
+ * @property {import("css-tree").CssNode} ast - Parsed CSS syntax tree.
+ * @property {SourceRange[]} comments - Comment ranges in source order.
+ */
+
+/**
+ * Record the range of every comment in the source text.
+ *
+ * @param {SourceRange[]} comments - Collected comment ranges.
+ * @param {string} _value - Comment text without delimiters.
+ * @param {{start: {offset: number}, end: {offset: number}}} loc - Comment location.
+ * @returns {void}
+ */
+function recordComment(comments, _value, loc) {
+  comments.push({ start: loc.start.offset, end: loc.end.offset })
+}
+
+/**
+ * Parse CSS and collect its comments, which the syntax tree does not include.
+ *
+ * @param {string} css - CSS source text.
+ * @returns {ParsedCss} Syntax tree and comment ranges.
+ */
+export function parseCss(css) {
+  const comments = []
+
+  return {
+    ast: csstree.parse(css, {
+      positions: true,
+      onComment: recordComment.bind(null, comments),
+    }),
+    comments,
+  }
+}