CSS Architecture skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "CSS Architecture"
  short_description: "Let layers decide the cascade, not selector weight"
  default_prompt: "$css-architecture Our CSS is full of !important; give me a plan and start fixing it"

#!/usr/bin/env python3
"""Report selector specificity, ID selectors and !important usage in CSS files.

Usage:
  python3 css_specificity.py [--top N] [--max A,B,C] [--max-important N] [--json] <file-or-dir> [...]

Prints a summary (selector count, specificity histogram, ID selectors, !important
count, deepest selectors) and the N highest-specificity selectors with file:line.
Gating: with --max, exits 1 if any selector exceeds that specificity (compared as a
tuple); with --max-important, exits 1 if more !important declarations exist.
Without gates it exits 0. Exit 2 means bad usage or unreadable input.

Handles plain CSS and native nesting (nested specificity is approximated as parent
plus child). Ignores keyframe selectors. Scans .css/.pcss/.scss (SCSS is parsed as
CSS; mixins and functions are skipped, so treat SCSS numbers as estimates).
Standard library only.
"""
from __future__ import annotations

import json
import os
import re
import sys

EXTS = {".css", ".pcss", ".postcss", ".scss"}
SKIP_DIRS = {"node_modules", ".git", "dist", "build", ".next", ".nuxt", ".output", "coverage", "vendor"}
FORGIVING = {"is", "matches", "not", "has", "-webkit-any", "-moz-any"}
ZERO = {"where"}
LEGACY_PSEUDO_ELEMENTS = {"before", "after", "first-line", "first-letter"}
IDENT = re.compile(r"-?[_a-zA-Z -￿\\][-_a-zA-Z0-9 -￿\\]*")


def _matching_paren(s: str, i: int) -> int:
    depth = 0
    for j in range(i, len(s)):
        if s[j] == "(":
            depth += 1
        elif s[j] == ")":
            depth -= 1
            if depth == 0:
                return j
    return len(s) - 1


def _split_top(s: str, sep: str = ",") -> list[str]:
    parts, depth, cur = [], 0, []
    for ch in s:
        if ch in "([":
            depth += 1
        elif ch in ")]":
            depth -= 1
        if ch == sep and depth == 0:
            parts.append("".join(cur))
            cur = []
        else:
            cur.append(ch)
    parts.append("".join(cur))
    return [p.strip() for p in parts if p.strip()]


def add(x, y):
    return (x[0] + y[0], x[1] + y[1], x[2] + y[2])


def specificity(sel: str) -> tuple[int, int, int]:
    a = b = c = 0
    i, n = 0, len(sel)
    while i < n:
        ch = sel[i]
        if ch == "#":
            m = IDENT.match(sel, i + 1)
            a += 1
            i = m.end() if m else i + 1
        elif ch == ".":
            m = IDENT.match(sel, i + 1)
            b += 1
            i = m.end() if m else i + 1
        elif ch == "[":
            b += 1
            depth = 0
            while i < n:
                if sel[i] == "[":
                    depth += 1
                elif sel[i] == "]":
                    depth -= 1
                    if depth == 0:
                        break
                i += 1
            i += 1
        elif ch == ":":
            is_element = sel.startswith("::", i)
            start = i + (2 if is_element else 1)
            m = IDENT.match(sel, start)
            name = m.group(0).lower() if m else ""
            i = m.end() if m else start
            arg = None
            if i < n and sel[i] == "(":
                close = _matching_paren(sel, i)
                arg = sel[i + 1:close]
                i = close + 1
            if is_element or name in LEGACY_PSEUDO_ELEMENTS:
                c += 1
                if arg and name == "slotted":
                    a2, b2, c2 = max_spec(arg)
                    a, b, c = a + a2, b + b2, c + c2
            elif name in ZERO:
                pass
            elif name in FORGIVING and arg is not None:
                a2, b2, c2 = max_spec(arg)
                a, b, c = a + a2, b + b2, c + c2
            elif name in {"nth-child", "nth-last-child"} and arg and " of " in arg:
                b += 1
                a2, b2, c2 = max_spec(arg.split(" of ", 1)[1])
                a, b, c = a + a2, b + b2, c + c2
            elif name in {"host", "host-context"} and arg:
                b += 1
                a2, b2, c2 = max_spec(arg)
                a, b, c = a + a2, b + b2, c + c2
            else:
                b += 1
        elif ch == "*" or ch == "&" or ch in " >+~|\t\n":
            i += 1
        else:
            m = IDENT.match(sel, i)
            if m:
                c += 1
                i = m.end()
            else:
                i += 1
    return (a, b, c)


def max_spec(selector_list: str) -> tuple[int, int, int]:
    specs = [specificity(s) for s in _split_top(selector_list)]
    return max(specs) if specs else (0, 0, 0)


def strip_comments(text: str) -> str:
    # keep newlines so line numbers stay correct
    return re.sub(r"/\*.*?\*/", lambda m: "\n" * m.group(0).count("\n"), text, flags=re.S)


def parse(path: str):
    text = strip_comments(open(path, encoding="utf-8", errors="replace").read())
    rules, important = [], 0
    stack: list[tuple[str, tuple]] = []  # (kind, parent specificity) kind in rule/at/keyframes
    buf_start, line = 0, 1
    line_at = []
    for ch in text:
        line_at.append(line)
        if ch == "\n":
            line += 1
    for i, ch in enumerate(text):
        if ch == "{":
            prelude = text[buf_start:i].strip()
            prelude_line = line_at[min(buf_start + (len(text[buf_start:i]) - len(text[buf_start:i].lstrip())), len(line_at) - 1)]
            in_keyframes = any(k == "keyframes" for k, _ in stack)
            parent = next((s for k, s in reversed(stack) if k == "rule"), None)
            if prelude.startswith("@"):
                kind = "keyframes" if re.match(r"@(-\w+-)?keyframes\b", prelude) else "at"
                stack.append((kind, parent or (0, 0, 0)))
            elif in_keyframes or not prelude or prelude.startswith("%") or prelude.startswith("@include"):
                stack.append(("at", parent or (0, 0, 0)))
            else:
                selectors = _split_top(prelude)
                best = (0, 0, 0)
                for s in selectors:
                    sp = specificity(s)
                    if parent is not None:
                        sp = add(sp, parent)
                    best = max(best, sp)
                    rules.append({"file": path, "line": prelude_line, "selector": " ".join(s.split()),
                                  "specificity": sp, "has_id": "#" in re.sub(r"\[[^\]]*\]", "", s),
                                  "depth": len(re.findall(r"\s*[>+~]\s*|\s+", s.strip()))})
                stack.append(("rule", best))
            buf_start = i + 1
        elif ch == "}":
            if stack:
                stack.pop()
            buf_start = i + 1
        elif ch == ";":
            decl = text[buf_start:i]
            if "!important" in decl.replace(" ", "").lower() or re.search(r"!\s*important", decl, re.I):
                important += 1
            buf_start = i + 1
    return rules, important


def walk(target: str):
    if os.path.isfile(target):
        yield target
        return
    for root, dirs, files in os.walk(target):
        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
        for f in files:
            if os.path.splitext(f)[1].lower() in EXTS:
                yield os.path.join(root, f)


def main(argv: list[str]) -> int:
    top, gate, gate_imp, as_json, targets = 15, None, None, False, []
    it = iter(argv)
    try:
        for arg in it:
            if arg == "--top":
                top = int(next(it))
            elif arg == "--max":
                gate = tuple(int(x) for x in next(it).split(","))
                if len(gate) != 3:
                    raise ValueError
            elif arg == "--max-important":
                gate_imp = int(next(it))
            elif arg == "--json":
                as_json = True
            else:
                targets.append(arg)
    except (StopIteration, ValueError):
        print("error: bad option value", file=sys.stderr)
        return 2
    if not targets:
        print(__doc__.strip(), file=sys.stderr)
        return 2
    rules, important, files = [], 0, 0
    for t in targets:
        if not os.path.exists(t):
            print(f"error: {t} does not exist", file=sys.stderr)
            return 2
        for p in walk(t):
            r, imp = parse(p)
            rules += r
            important += imp
            files += 1
    rules.sort(key=lambda r: r["specificity"], reverse=True)
    ids = [r for r in rules if r["has_id"]]
    hist: dict[str, int] = {}
    for r in rules:
        a, b, c = r["specificity"]
        bucket = "id" if a else ("0,4+,x" if b >= 4 else f"0,{b},x")
        hist[bucket] = hist.get(bucket, 0) + 1
    over = [r for r in rules if gate and r["specificity"] > gate]
    failed = bool(over) or (gate_imp is not None and important > gate_imp)

    if as_json:
        out = {"files": files, "selectors": len(rules), "important": important,
               "id_selectors": len(ids), "histogram": hist,
               "top": [dict(r, specificity=list(r["specificity"])) for r in rules[:top]],
               "over_max": [dict(r, specificity=list(r["specificity"])) for r in over]}
        print(json.dumps(out, indent=2))
    else:
        print(f"Files: {files}  Selectors: {len(rules)}  !important: {important}  ID selectors: {len(ids)}")
        print("Histogram: " + ", ".join(f"{k}={v}" for k, v in sorted(hist.items())))
        deep = [r for r in rules if r["depth"] >= 3]
        print(f"Selectors with 3+ combinators: {len(deep)}")
        print(f"\nTop {min(top, len(rules))} by specificity:")
        for r in rules[:top]:
            a, b, c = r["specificity"]
            print(f"  ({a},{b},{c})  {r['file']}:{r['line']}  {r['selector']}")
        if gate:
            print(f"\nSelectors above --max {','.join(map(str, gate))}: {len(over)}")
        if gate_imp is not None:
            print(f"!important {important} vs --max-important {gate_imp}: {'FAIL' if important > gate_imp else 'ok'}")
    return 1 if failed else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))