cssupgrade 0.0.0-stage → 2026.0.1

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.1",
+  "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,
+  }
+}

package/src/pool.js

@@ -0,0 +1,165 @@
+import os from "os"
+import { Worker } from "worker_threads"
+
+/**
+ * @typedef {(filePath: string, options: Object, worker: TransformWorker) => Promise<{modified: boolean, error: boolean}>} FileProcessorFunction
+ */
+
+/**
+ * Restore an error posted by a transform worker.
+ *
+ * @param {{name: string, message: string, stack: string | undefined}} errorData - Plain error data.
+ * @returns {Error} Error carrying the worker name, message, and stack.
+ */
+function reviveError({ name, message, stack }) {
+  return Object.assign(new Error(message), { name, stack })
+}
+
+/**
+ * Loading the transformation pipeline takes tens of milliseconds, so one worker
+ * transforms many files instead of being spawned for a single file.
+ */
+export class TransformWorker {
+  #worker
+  #pending = null
+  #stopError = null
+
+  /**
+   * @param {string | URL} workerPath - Path of the worker thread module
+   */
+  constructor(workerPath) {
+    this.#worker = new Worker(workerPath)
+    this.#worker.on("message", (message) => this.#settle(message))
+    this.#worker.on("error", (error) => this.#stop(error))
+    this.#worker.on("exit", (code) =>
+      this.#stop(new Error(`Worker stopped with exit code ${code}`)),
+    )
+  }
+
+  get stopped() {
+    return this.#stopError !== null
+  }
+
+  /**
+   * A stopped thread drops posted messages without a response, so requests fail
+   * immediately instead of waiting for a reply that never comes. One request runs
+   * at a time, so a second request fails loudly instead of losing the first.
+   *
+   * @param {{filePath: string, baseline: string, includeOriginal: boolean}} request - File to transform
+   * @returns {Promise<Object>} Worker response message
+   */
+  transform(request) {
+    if (this.#stopError) {
+      return Promise.reject(this.#stopError)
+    }
+
+    if (this.#pending) {
+      return Promise.reject(new Error("Worker already transformed a file"))
+    }
+
+    return new Promise((resolve, reject) => {
+      this.#pending = { resolve, reject }
+      this.#worker.postMessage(request)
+    })
+  }
+
+  /**
+   * @returns {Promise<number>} Exit code of the stopped thread
+   */
+  terminate() {
+    return this.#worker.terminate()
+  }
+
+  /**
+   * @param {Object} message - Worker response message
+   */
+  #settle(message) {
+    this.#pending?.resolve(
+      message.success ? message : { ...message, error: reviveError(message.error) },
+    )
+    this.#pending = null
+  }
+
+  /**
+   * @param {Error} error - Reason the worker stopped
+   */
+  #stop(error) {
+    this.#stopError ??= error
+    this.#pending?.reject(error)
+    this.#pending = null
+  }
+}
+
+/**
+ * Each worker loads the transformation pipeline once and then processes files
+ * until the queue is empty. A worker that stopped is replaced before it takes on
+ * the next file, so one stopped thread cannot fail the remaining files.
+ */
+export class WorkerPool {
+  #fileProcessor
+  #workerPath
+  #maxWorkers
+
+  /**
+   * @param {FileProcessorFunction} fileProcessor - Processor that handles one file
+   * @param {string | URL} workerPath - Path of the worker thread module
+   * @param {number} [maxWorkers] - Upper bound of concurrent workers
+   */
+  constructor(fileProcessor, workerPath, maxWorkers = os.availableParallelism()) {
+    this.#fileProcessor = fileProcessor
+    this.#workerPath = workerPath
+    this.#maxWorkers = maxWorkers
+  }
+
+  /**
+   * The results keep the input order of the given files.
+   *
+   * @param {string[]} files - Files to process
+   * @param {Object} options - Processing options
+   * @returns {Promise<Array<{modified: boolean, error: boolean}>>} Result per file
+   */
+  async processFiles(files, options) {
+    const results = new Array(files.length)
+    let fileIndex = 0
+
+    const processQueue = async () => {
+      let worker = new TransformWorker(this.#workerPath)
+
+      try {
+        while (fileIndex < files.length) {
+          const currentIndex = fileIndex++
+          results[currentIndex] = await this.#fileProcessor(
+            files[currentIndex],
+            options,
+            worker,
+          )
+          worker = await this.#replaceStoppedWorker(worker)
+        }
+      } finally {
+        await worker.terminate()
+      }
+    }
+
+    const workerCount = Math.min(this.#maxWorkers, files.length)
+    const queues = Array.from({ length: workerCount }, processQueue)
+    await Promise.all(queues)
+
+    return results
+  }
+
+  /**
+   * Provide a running worker for the next file.
+   *
+   * @param {TransformWorker} worker - Worker that handled the previous file
+   * @returns {Promise<TransformWorker>} The worker itself, or a replacement
+   */
+  async #replaceStoppedWorker(worker) {
+    if (!worker.stopped) {
+      return worker
+    }
+
+    await worker.terminate()
+
+    return new TransformWorker(this.#workerPath)
+  }
+}

package/src/prefilters.js

@@ -0,0 +1,29 @@
+/**
+ * Source text conditions that decide whether a transformer can match.
+ *
+ * Every transformer parses the whole source, which dominates the runtime of
+ * this package. A transformer can only match when its pattern occurs in the
+ * source text, so testing the text first skips the parse for transformations
+ * that cannot apply.
+ */
+
+/**
+ * Conditions a transformer needs in the source text. A transformer runs when all
+ * of its conditions match. Each condition must be necessary: when the source
+ * text fails a condition, the transformer cannot change the tree.
+ *
+ * @type {Map<string, RegExp[]>}
+ */
+export const prefilters = new Map([
+  // Nesting needs two rules, so the source holds at least two blocks.
+  ["cssNesting", [/\{[\s\S]*\{/]],
+])
+
+/**
+ * @param {string} name - Transformer name
+ * @param {string} code - Source text of the current transformation pass
+ * @returns {boolean} True when the transformer needs to run
+ */
+export function matchesPrefilter(name, code) {
+  return prefilters.get(name).every((condition) => condition.test(code))
+}