colors-le: Instructions file for Codex

AGENTS.md — Colors-LE

Technical source of truth for this repo. README.md is the user-facing doc; this file is for anyone (human or agent) changing the code.

This repo hosts two products: the extension at the root (this document's scope) and the Rust CLI in crate/ (its own AGENTS.md + SPEC.md), which ports extraction only. The shared corpus lives at crate/fixtures/; scripts/check-extraction-parity.ts fails CI when this extension drifts from it.

The Rust CLI also ships a second way, through npm: src/cli/ is its terminal surface rebuilt over this extension's extraction engine, bundled to cli/cli.js as the npm package colors-le. Both install a command named colors-le, so the npm one is held to the crate's surface byte for byte, which is a different contract from the extraction parity above. src/cli/ follows crate/src/cli.rs, scan.rs, walk.rs and extract/palette.rs, not the extension's commands, and scripts/check-cli-parity.ts runs both binaries over one generated tree and fails on any difference in stdout, stderr or exit code, and in what colors-le mcp answers. scripts/check-cli-pipes.ts, shared with every port, closes stdout or stderr before either binary writes and fails on any difference in what follows, on all three operating systems. A change to the crate's surface changes src/cli/ in the same commit.

What this is

A VS Code extension that extracts colors from the active document (CSS/SCSS/LESS/Stylus, HTML, JS/TS, SVG) into a results editor, with dedupe/sort/convert/filter/analyze/validate post-processing. No network access, no filesystem writes.

Architecture

extension.ts            activate(): createServices() -> registerCommands()
services/serviceFactory createServices(context) -> { telemetry, notifier, statusBar }
commands/               one file per command; extract/dedupe/sort/help take the
                        frozen deps bag; analyze/convert/filter/validate are
                        self-contained (vscode UI + performance.now timing)
extraction/extract.ts   dispatcher: languageId -> FileType -> extractor
extraction/heuristics.ts  THE color patterns/validators: hex + functional
                        regexes, NAMED_COLORS set, comment blanking,
                        declaration-value segmentation, string-literal spans
extraction/position.ts    offset -> {line, column} via newline index (1-based)
extraction/formats/     stylesheet.ts (css/scss/less/stylus), markup.ts
                        (html/svg), javascript.ts — all offset-based
analysis/colorAnalysis  statistics/clusters/patterns for the Analyze command
conversion/colorConverter  convert/validate engines (hex/rgb/hsl, contrast)
ui/                     notifier (window messages, gated by notificationsLevel:
                        all -> everything, important -> warn+error, silent -> error only),
                        statusBar
utils/                  errors (sanitizeErrorMessage), safety (size guards),
                        colorConversion (parse/convert primitives), dedupe,
                        sort, format (formatDuration)
config/config.ts        getConfiguration() snapshot; CONFIG_DEFAULTS table
types.ts                shared types only — no logic
cli/                    the npm command line: args, walk + ignoreRules
                        (ripgrep's precedence), palette, scan, run, and
                        scanTool for `colors-le mcp`. No `vscode`, ever