@r1z4x/tezgah 1.11.0 → 1.14.0

package/bin/tezgah-design

@@ -2,7 +2,7 @@
 """tezgah-design derive|check - the per-repo design contract, and the check that
 can fail.
 
-  tezgah-design derive --repo DIR [--out FILE] [--json]
+  tezgah-design derive --repo DIR [--out FILE] [--suggest] [--json]
   tezgah-design check --contract FILE --measured FILE|- [--json]
   tezgah-design slop --repo DIR [--url URL] [--render] [--measured FILE]
                         [--out FILE] [--json]
@@ -11,7 +11,8 @@ The contract is the floor a UI turn is judged against: the colour roles, the
 type scale, the spacing unit and the state set a repository already uses, plus
 the component inventory it owns. `derive` writes a first `.tezgah/design-contract.md`
 from the repository's own token source (CSS custom properties, a Tailwind config,
-a tokens/theme JSON) and exits 2 rather than invent a palette it did not find.
+a tokens/theme JSON, a JS/TS theme module) and exits 2 rather than invent a
+palette it did not find.
 `slop` runs Hallmark's own gate list (`skills/hallmark/scripts/sloplint.mjs`)
 over the repository or a running URL, writes the verdict to
 `.tezgah/design/slop.json` and exits 1 on any Floor FAIL. It is the Hallmark half
@@ -29,7 +30,8 @@ Stdlib only, deterministic, no network and no credential: the same tree and the
 same measurement print the same bytes, with no clock and no path outside the
 repository in the artifact.
 
-  derive  exit 0 the contract was written; 2 no token source; 1 usage or IO
+  derive  exit 0 the contract was written; 2 no token source, usage or IO
+          --suggest: exit 0 candidates printed, nothing written; 2 none found
   check   exit 0 `0 violations` over at least one component judged; 1 one or
           more violations; 2 usage, IO, a bad contract or nothing judged
 """
@@ -38,6 +40,7 @@ import math
 import os
 import re
 import shutil
+import stat
 import subprocess
 import sys
 
@@ -110,18 +113,59 @@ MOTION_PROPS = ("transition-duration", "animation-duration")
 
 SKIP_DIRS = frozenset((".git", "node_modules", "dist", "build", ".venv", "venv",
                        "vendor", "__pycache__", ".next", ".cache", "coverage",
-                       ".tezgah", ".codegraph"))
+                       ".tezgah", ".codegraph", "Pods", "Carthage", ".build"))
+# `derive --suggest`: a file in one of these directories with one of these
+# suffixes is a candidate component; a test, a story, a mock, a theme file
+# (Compose's `ui/theme/Color.kt`) or a Swift extension (`UIColor+Brand`) is not.
+COMPONENT_DIRS = frozenset(("components", "component", "widgets", "widget", "ui"))
+COMPONENT_EXT = (".tsx", ".jsx", ".vue", ".svelte", ".astro", ".swift", ".kt", ".dart")
+NOT_COMPONENT = re.compile(r"\.(?:test|spec|stories|story)\.|(?:^|/)__(?:tests|mocks)__/"
+                           r"|(?:^|/)theme/[^/]*\.(?:kt|swift)$|\+", re.I)
+# React Native's per-platform files are one component (`Button.ios.tsx`)
+PLATFORM_SUFFIX = re.compile(r"\.(?:ios|android|web|native)$", re.I)
+# The kind a name's head noun says - its last CamelCase, `_` or `-` word, matched
+# whole - and only when it says it: a substring read `FeedbackForm` as data and
+# `DatabaseStatus` as interactive (review of plan 146). Every other kind is the
+# person's.
+INTERACTIVE_HEADS = frozenset((
+    "button", "input", "select", "checkbox", "radio", "toggle", "switch", "link",
+    "tab", "tabs", "menu", "dialog", "modal", "chip", "slider", "picker", "field",
+    "dropdown", "combobox", "textarea", "stepper"))
+DATA_HEADS = frozenset((
+    "table", "list", "chart", "card", "tile", "grid", "feed", "stat", "stats",
+    "skeleton", "badge", "avatar", "progress"))
+NAME_WORDS = re.compile(r"[A-Z]+(?![a-z])|[A-Z]?[a-z0-9]+")
 CSS_SUFFIXES = (".css", ".scss", ".sass", ".less")
 TAILWIND_NAMES = ("tailwind.config.js", "tailwind.config.cjs",
                   "tailwind.config.mjs", "tailwind.config.ts",
                   "tailwind.config.json")
 THEME_NAMES = ("theme.json", "tokens.json", "design-tokens.json")
+# A JS/TS module that holds a React Native / Expo app's floor in code, read
+# after the three stylesheet-shaped sources (`module_tokens`).
+MODULE_NAMES = tuple("%s.%s" % (stem, ext)
+                     for stem in ("theme", "tokens", "colors", "colours", "palette")
+                     for ext in ("ts", "js", "mjs"))
+MODULE_CAP = 20
 FILE_CAP = 4000
 CSS_CAP = 200
 
 DECL = re.compile(r"(--[A-Za-z0-9_-]+)\s*:\s*([^;{}]+)")
 BLOCK = re.compile(r"\b%s\s*:\s*\{")
 PAIR = re.compile(r"^\s*['\"]?([A-Za-z0-9_-]+)['\"]?\s*:\s*(.+?)\s*$")
+# A config entry whose value is an object: a colour scale, read through `_pairs`
+# under the flattened name rather than skipped, at most NEST_CAP levels deep.
+NESTED = re.compile(r"^\s*['\"]?([A-Za-z0-9_-]+)['\"]?\s*:\s*\{(.*)\}\s*,?\s*$",
+                    re.S)
+NEST_CAP = 4
+READ_CAP = 1 << 20
+# `const name = {` / `export const name: Type = {` at a line's start - a module's
+# top-level object in formatted code, not one inside a function. The annotation
+# is bounded and stays on its line: an unbounded one made `var a:` repeated
+# quadratic (128 KiB took 26 s), and `const p: { ink: string } = {` is not read.
+CONST_BLOCK = re.compile(r"^(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)"
+                         r"\s*(?::[^=;{\n]{0,200})?=\s*\{", re.M)
+FONT_SIZE = re.compile(r"\bfontSize\s*:\s*(\d+(?:\.\d+)?)\b")
+NUMBER = re.compile(r"^-?\d*\.?\d+$")
 HEX3 = re.compile(r"^#([0-9a-f])([0-9a-f])([0-9a-f])$", re.I)
 HEX6 = re.compile(r"^#([0-9a-f]{6})$", re.I)
 RGB = re.compile(r"^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)"
@@ -309,12 +353,41 @@ def walk(root):
 
 
 def read_text(root, rel):
+    """The file's text, or "" for one a token reader will not open: a symlink
+    that resolves outside `root`, anything that is not a regular file (a FIFO
+    blocks `read` forever), or one over READ_CAP - a token source is a small
+    text file, and every Tailwind config in the tree is read. The checks are
+    made on what was opened, not on the path: each component under `root` is
+    opened relative to its parent's descriptor with `O_NOFOLLOW`, so a file or
+    a parent directory swapped for a link or a FIFO after `realpath` is refused
+    too. A platform with no `dir_fd` support opens the resolved path whole."""
+    real, base = os.path.realpath(os.path.join(root, rel)), os.path.realpath(root)
+    if not real.startswith(base + os.sep):
+        return ""
+    nofollow = getattr(os, "O_NOFOLLOW", 0)
+    flags = os.O_RDONLY | nofollow | getattr(os, "O_NONBLOCK", 0)
     try:
-        with open(os.path.join(root, rel), encoding="utf-8",
-                  errors="replace") as fh:
-            return fh.read()
+        if os.open in os.supports_dir_fd:
+            parts = os.path.relpath(real, base).split(os.sep)
+            parent = os.open(base, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+            try:
+                for part in parts[:-1]:
+                    child = os.open(part, os.O_RDONLY | nofollow
+                                    | getattr(os, "O_DIRECTORY", 0), dir_fd=parent)
+                    os.close(parent)
+                    parent = child
+                fd = os.open(parts[-1], flags, dir_fd=parent)
+            finally:
+                os.close(parent)
+        else:
+            fd = os.open(real, flags)
     except OSError:
         return ""
+    with os.fdopen(fd, "rb") as fh:
+        st = os.fstat(fd)
+        if not stat.S_ISREG(st.st_mode) or st.st_size > READ_CAP:
+            return ""
+        return fh.read(READ_CAP).decode("utf-8", errors="replace")
 
 
 def css_declarations(root, files):
@@ -340,8 +413,17 @@ def css_declarations(root, files):
 
 def _block_body(text, key):
     """Every `key: { ... }` body in `text`, brace-balanced, in file order."""
-    out = []
-    for m in re.finditer(BLOCK.pattern % re.escape(key), text):
+    return [body for _, body in _bodies(text, BLOCK.pattern % re.escape(key))]
+
+
+def _bodies(text, pattern):
+    """(match, body) for every `pattern` that opens a `{`, brace-balanced, in
+    file order. A match inside a body already taken is skipped: each body is
+    scanned once, so `colors:{` repeated n times costs n steps, not n squared."""
+    out, end = [], 0
+    for m in re.finditer(pattern, text):
+        if m.start() < end:
+            continue
         i, depth = m.end(), 1
         while i < len(text) and depth:
             if text[i] == "{":
@@ -349,73 +431,119 @@ def _block_body(text, key):
             elif text[i] == "}":
                 depth -= 1
             i += 1
-        out.append(text[m.end():i - 1])
+        out.append((m, text[m.end():i - 1]))
+        end = i
     return out
 
 
-def _pairs(body):
-    """The `key: value` pairs at the top level of a config block. A nested
-    object is skipped, not flattened: its leaves are a scale of their own and
-    this reader does not claim to know its shape."""
-    items, depth, buf = [], 0, []
+def _items(body):
+    """The comma-separated entries at the top level of a config block. A
+    bracket or a parenthesis opens a level, so `rgba(0, 0, 0, 0.5)` is one
+    value; one inside a quoted string (`':)'`, `'a, b'`) opens nothing."""
+    items, depth, buf, quote, escaped = [], 0, [], None, False
     for ch in body:
-        if ch in "{[":
+        if quote:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == quote:
+                quote = None
+        elif ch in "'\"`":
+            quote = ch
+        elif ch in "{[(":
             depth += 1
-        elif ch in "}]":
+        elif ch in "}])":
             depth -= 1
-        if ch == "," and depth == 0:
+        if ch == "," and depth == 0 and not quote:
             items.append("".join(buf))
             buf = []
         else:
             buf.append(ch)
     items.append("".join(buf))
+    return items
+
+
+def _pairs(body, prefix="", nested=False, depth=0):
+    """The `key: value` pairs at the top level of a config block. With `nested`
+    (the `colors` block, the one Tailwind documents as nestable) a nested object
+    is flattened under the class name Tailwind generates for it: `brand: {50:
+    ..., 500: ..., DEFAULT: ...}` is `brand-50`, `brand-500` and `brand`. That
+    is how a palette with more than one step is written, and skipping it left
+    two of the four UI repositories on this machine with no derivable token.
+    Elsewhere a nested object is skipped, as its leaves are not a scale this
+    reader knows; past NEST_CAP levels it is skipped too."""
     out = []
-    for item in items:
+    for item in _items(body):
+        inner = NESTED.match(item) if nested and depth < NEST_CAP else None
+        if inner:
+            out.extend(_pairs(inner.group(2), _name(prefix, inner.group(1)),
+                              nested, depth + 1))
+            continue
         if "{" in item:
             continue
         m = PAIR.match(item)
         if m:
-            out.append((m.group(1), m.group(2).strip().strip("'\"")))
+            out.append((_name(prefix, m.group(1)), m.group(2).strip().strip("'\"")))
     return out
 
 
+def _name(prefix, key):
+    if not prefix:
+        return key
+    return prefix if key == "DEFAULT" else prefix + "-" + key
+
+
 def tailwind_tokens(root, files):
-    """The tokens a Tailwind config declares, read from its `colors`, `spacing`
-    and `fontSize` blocks."""
-    rel = next((f for f in files if os.path.basename(f) in TAILWIND_NAMES), None)
-    if rel is None:
+    """The tokens the Tailwind configs declare, read from their `colors`,
+    `spacing` and `fontSize` blocks. Every config is read, not the first one
+    found: a monorepo keeps one per app (`apps/<name>/tailwind.config.js`), and
+    the floor has to hold for each of them. So a colour name a second app gives
+    another value is kept under `<name>@<config>` rather than overwritten (the
+    palette is judged by value), and the space unit is the one every app's unit
+    is a multiple of."""
+    rels = [f for f in files if os.path.basename(f) in TAILWIND_NAMES]
+    if not rels:
         return {}, []
-    text = read_text(root, rel)
-    colours, space, scale = {}, [], []
-    for body in _block_body(text, "colors"):
-        for key, value in _pairs(body):
-            hexed = normalise_colour(value)
-            if hexed:
+    colours, units, scale = {}, [], []
+    for rel in rels:
+        text = read_text(root, rel)
+        for body in _block_body(text, "colors"):
+            for key, value in _pairs(body, nested=True):
+                hexed = normalise_colour(value)
+                if not hexed:
+                    continue
+                if colours.get(key, hexed) != hexed:
+                    key = "%s@%s" % (key, rel)
                 colours[key] = hexed
-    for body in _block_body(text, "spacing"):
-        for key, value in _pairs(body):
-            px = length_px(value)
-            if px:
-                space.append((key in ("unit", "base"), px))
-    for body in _block_body(text, "fontSize"):
-        for _, value in _pairs(body):
-            for token in re.findall(r"['\"]?([\d.]+(?:px|rem|pt))", value):
-                px = length_px(token)
+        space = []
+        for body in _block_body(text, "spacing"):
+            for key, value in _pairs(body):
+                px = length_px(value)
                 if px:
-                    scale.append(int(round(px)))
+                    space.append((key in ("unit", "base"), px))
+        # A key named `unit`/`base` states the unit; otherwise the greatest
+        # common divisor of the scale the config declares is the unit it is
+        # built on.
+        named = sorted(px for explicit, px in space if explicit)
+        if named:
+            units.append(named[0])
+        elif space:
+            units.append(_gcd([px for _, px in space]))
+        for body in _block_body(text, "fontSize"):
+            for _, value in _pairs(body):
+                for token in re.findall(r"['\"]?([\d.]+(?:px|rem|pt))", value):
+                    px = length_px(token)
+                    if px:
+                        scale.append(int(round(px)))
     out = {}
-    # A key named `unit`/`base` states the unit; otherwise the greatest common
-    # divisor of the scale the config declares is the unit it is built on.
-    named = sorted((px for explicit, px in space if explicit))
-    if named:
-        out["space_unit"] = int(named[0])
-    elif space:
-        out["space_unit"] = int(_gcd([px for _, px in space]))
+    if units:
+        out["space_unit"] = int(_gcd(units))
     if scale:
         out["type_scale"] = sorted(set(scale))
     if colours:
         out["colors"] = colours
-    return out, [rel]
+    return out, rels
 
 
 def theme_tokens(root, files):
@@ -467,8 +595,83 @@ def theme_tokens(root, files):
     return out, [rel]
 
 
+def module_tokens(root, files):
+    """The tokens a JS/TS theme module declares - the floor a React Native or
+    Expo app keeps in code (`src/config/theme.ts`: `export const palette =
+    {...}`, `spacing`, `typography`), where there is no stylesheet to read.
+    Every top-level object's colour literals are the palette (by value, under
+    `<object>-<key>`; a name two modules give different values keeps both, as
+    `<name>@<module>`); the `spacing`/`space` object's numbers are the scale, a
+    unitless number read as px (React Native's dp); every non-zero `fontSize:`
+    number is a type step. Comments are dropped first, so a commented-out
+    example is not a token and a commented key does not hide the next one."""
+    rels = [f for f in files if os.path.basename(f) in MODULE_NAMES][:MODULE_CAP]
+    colours, space, scale, read = {}, [], [], []
+    for rel in rels:
+        text = _strip_comments(read_text(root, rel))
+        found = False
+        for m, body in _bodies(text, CONST_BLOCK):
+            name = m.group(1)
+            for key, value in _pairs(body, name, nested=True):
+                hexed = normalise_colour(value)
+                if not hexed:
+                    continue
+                if colours.get(key, hexed) != hexed:
+                    key = "%s@%s" % (key, rel)
+                colours[key] = hexed
+                found = True
+            if name.lower() in ("spacing", "space"):
+                for _, value in _pairs(body):
+                    px = length_px(value + "px" if NUMBER.match(value) else value)
+                    if px and px > 0:
+                        space.append(px)
+        scale.extend(int(round(float(v))) for v in FONT_SIZE.findall(text) if float(v) > 0)
+        if found:
+            read.append(rel)
+    out = {}
+    if space:
+        out["space_unit"] = int(_gcd(space))
+    if scale:
+        out["type_scale"] = sorted(set(scale))
+    if colours:
+        out["colors"] = colours
+    return out, read
+
+
+def _strip_comments(text):
+    """`text` with its `/* */` and `//` comments removed, in one linear pass
+    that knows a quoted string: `'a // b'`, `'src/**/*.ts'` and `https://` in a
+    string are kept. An unclosed `/*` drops the rest; a regex for the block form
+    re-scanned the tail from every `/*` (quadratic on a run of them)."""
+    out, i, n, quote = [], 0, len(text), None
+    while i < n:
+        ch = text[i]
+        if quote:
+            out.append(ch)
+            if ch == "\\" and i + 1 < n:
+                out.append(text[i + 1])
+                i += 1
+            elif ch == quote:
+                quote = None
+        elif ch in "'\"`":
+            quote = ch
+            out.append(ch)
+        elif text.startswith("//", i):
+            end = text.find("\n", i)
+            i = n if end < 0 else end
+            continue
+        elif text.startswith("/*", i):
+            end = text.find("*/", i + 2)
+            i = n if end < 0 else end + 2
+            continue
+        else:
+            out.append(ch)
+        i += 1
+    return "".join(out)
+
+
 def _gcd(values):
-    values = [int(round(v)) for v in values if v]
+    values = [abs(int(round(v))) for v in values if v]
     if not values:
         return 0
     out = values[0]
@@ -578,7 +781,7 @@ def design_md_tokens(root):
         path = os.path.join(root, name)
         if not os.path.isfile(path):
             continue
-        text = open(path, encoding="utf-8", errors="replace").read()
+        text = read_text(root, name)
         block = re.search(r"```css\s*(.*?)```", text, re.S)
         if not block:
             continue
@@ -612,12 +815,14 @@ def derive(root):
     files = walk(root)
     for name, reader in (("css-custom-properties", css_tokens),
                          ("tailwind-config", tailwind_tokens),
-                         ("theme-json", theme_tokens)):
+                         ("theme-json", theme_tokens),
+                         ("theme-module", module_tokens)):
         tokens, sources = reader(root, files)
         if tokens.get("colors"):
             return tokens, name, sources
     return None, ("no token source: looked for CSS custom properties, a "
-                  "Tailwind config and a tokens/theme JSON"), []
+                  "Tailwind config, a tokens/theme JSON and a JS/TS theme "
+                  "module"), []
 
 
 def contract_data(tokens, source):
@@ -949,8 +1154,8 @@ def parse(argv, names):
         arg = argv[i]
         if arg == "--json":
             out["json"] = True
-        elif arg == "--render":
-            out["render"] = True
+        elif arg in ("--render", "--suggest"):
+            out[arg.lstrip("-")] = True
         elif arg in names:
             if i + 1 >= len(argv):
                 raise Usage("%s wants a value" % arg)
@@ -966,6 +1171,71 @@ def _print_json(payload):
     sys.stdout.write(json.dumps(payload, indent=2, sort_keys=True) + "\n")
 
 
+def suggest_components(files):
+    """[(name, kind, path)]: the candidate inventory rows a repository's
+    component files suggest - a `.tsx/.jsx/.vue/.svelte/.astro/.swift/.kt/
+    .dart` file under a `components`/`widgets`/`ui` directory, named by its
+    file (an `index` file by its directory, `Button.ios.tsx` as `Button`), first
+    path per name. `kind` is `interactive` or `data` only when the name's head
+    noun says so (`IconButton`, `StatCard`), else None. A suggestion, never the
+    inventory: which of these the repository owns, and every kind, is the
+    person's call (skills/design-contract/SKILL.md, the inventory)."""
+    out, seen = [], set()
+    for rel in files:
+        parts = rel.split("/")
+        stem, ext = os.path.splitext(parts[-1])
+        if (ext.lower() not in COMPONENT_EXT or NOT_COMPONENT.search(rel)
+                or not COMPONENT_DIRS.intersection(p.lower() for p in parts[:-1])):
+            continue
+        stem = PLATFORM_SUFFIX.sub("", stem)
+        name = parts[-2] if stem.lower() == "index" else stem
+        if name.lower() in COMPONENT_DIRS or name in seen:
+            continue
+        seen.add(name)
+        words = [w for chunk in re.split(r"[_\-]", name) for w in NAME_WORDS.findall(chunk)]
+        head = words[-1].lower() if words else ""
+        kind = ("interactive" if head in INTERACTIVE_HEADS else
+                "data" if head in DATA_HEADS else None)
+        out.append((name, kind, rel))
+    return out
+
+
+def suggest_cli(root, contract, opts):
+    """Print the candidate rows, minus the names the contract already lists.
+    Writes nothing: the inventory is edited by the person who owns it."""
+    listed = set()
+    if os.path.exists(contract):
+        data, reason = read_contract(contract)
+        comps = (data or {}).get("components") or []
+        if reason or not isinstance(comps, list):
+            # a contract the reader cannot use would make every name look new
+            sys.stderr.write("tezgah-design: %s: %s\n" % (
+                os.path.abspath(contract),
+                reason or "its `components` is not a list"))
+            return 2
+        listed = {str(c.get("name")) for c in comps if isinstance(c, dict)}
+    rows = [r for r in suggest_components(walk(root)) if r[0] not in listed]
+    if opts.get("json"):
+        _print_json({"ok": bool(rows), "candidates": [
+            {"name": n, "kind": k, "path": p} for n, k, p in rows]})
+    elif rows:
+        # absolute: from a worktree the contract is the main checkout's
+        sys.stdout.write(
+            "%d candidate(s) for the component inventory; nothing was written. Add "
+            "the ones this repository owns to `components` in %s. Every `kind` is "
+            "a guess from the name's last word - check each one, and set the "
+            "`null` ones (interactive|data):\n" % (len(rows), os.path.abspath(contract)))
+        for name, kind, rel in rows:
+            sys.stdout.write("  %-28s %-12s %s\n" % (name, kind or "?", rel))
+        sys.stdout.write("[\n%s\n]\n" % ",\n".join(
+            "  " + json.dumps({"name": n, "kind": k}) for n, k, _ in rows))
+    else:
+        sys.stderr.write("tezgah-design: no candidate component: no new "
+                         ".tsx/.jsx/.vue/.svelte/.astro/.swift/.kt/.dart file "
+                         "under a components/widgets/ui directory\n")
+    return 0 if rows else 2
+
+
 def derive_cli(opts):
     root = project_top(os.path.abspath(opts.get("repo") or ""))
     if not os.path.isdir(root):
@@ -975,6 +1245,8 @@ def derive_cli(opts):
     # removal does not take with it
     ws = linked_main(root) or root
     out = opts.get("out") or os.path.join(ws, ".tezgah", "design-contract.md")
+    if opts.get("suggest"):
+        return suggest_cli(root, out, opts)
     if os.path.exists(out):
         # A contract that exists is the repository's own decision: it carries
         # the component inventory someone filled in, so overwriting it would
@@ -1239,6 +1511,9 @@ def main(argv):
     if verb in ("derive", "check") and "--render" in rest:
         sys.stderr.write("tezgah-design: --render belongs to `slop`, not %s\n" % verb)
         return 2
+    if verb != "derive" and "--suggest" in rest:
+        sys.stderr.write("tezgah-design: --suggest belongs to `derive`, not %s\n" % verb)
+        return 2
     try:
         if verb == "derive":
             return derive_cli(parse(rest, ("--repo", "--out")))