@adia-ai/adia-ui-forge 0.8.56 → 0.8.58

package/scripts/forge-lint

@@ -1,315 +0,0 @@
-#!/usr/bin/env python3
-"""forge-lint — advisory authoring-smell checker for the adia-ui FRAMEWORK source (maintainer slice).
-
-This is the producer-side counterpart to the consumer plugin's app-lint: it checks the framework's
-OWN component source as a maintainer authors it (primitives in packages/web-components, composites in
-packages/web-modules) for the framework's structural invariants — light-DOM only (no attachShadow,
-no ::slotted), component CSS is `@scope`-wrapped and token-only (no raw colors, no raw px >= 3, no
-extent on :scope, no dead `--a-font`), property definitions are well-formed (no `default: true`, no
-`attr:` typo), composites use `*-ui` primitives (no native-primitive leak), and no retired shell
-shapes (ADR-0024 data-attribute forms). Foundation/token sheets (a styles/ or tokens/ dir, a
-tokens/theme/host/palette/… stem, or `/* forge-lint: foundation */`) are exempt from the CSS-literal
-and scope checks.
-
-It deliberately does NOT carry the consumer/app traps (SSR double-router, top-level kit import,
-hardcoded overlay open) — those are about CONSUMING the framework in an app and live in the
-consumer plugin. forge-lint judges only authoring structure, never whether a component is good,
-accessible, or on-spec — that lives in the skills (adia-ui-authoring / -a2ui / -gen-review / -dogfood).
-A clean forge-lint says "no structural tells," never "this is right."
-
-Shared core: the regex bank below (RAW-COLOR/PX, SCOPE-EXTENT, NATIVE-PRIMITIVE, LEGACY-SHELL,
-the _is_foundation_css exemption) is mirrored in the sibling CONSUMER plugin's
-adia-ui-factory/scripts/adia-lint. They are deliberate VENDORED copies — the catalog forbids
-cross-plugin imports (each plugin installs copy-alone) — so any change to a shared rule must be
-reconciled in BOTH files. forge-lint drops the consumer/app traps (SSR double-router, top-level
-import, hardcoded overlay open) and adds MISSING-SCOPE; that divergence is the point.
-
-Usage:
-  forge-lint <file>...        # lint files; exit 1 if any smell found, else 0
-  forge-lint -                # lint stdin as a generic source file
-  forge-lint --hook           # PostToolUse hook mode: read event JSON on stdin, lint the written
-                              #   source file, print advisory findings, ALWAYS exit 0 (never blocks)
-  forge-lint selftest         # run built-in fixtures (seeded smells + clean files + the hook exit-0 invariant)
-Stdlib only (Python 3.8+).
-"""
-import json
-import os
-import re
-import sys
-
-CODE_EXT = (".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx")
-STYLE_EXT = (".css",)
-MARKUP_EXT = (".html", ".htm", ".vue", ".svelte", ".astro", ".tsx", ".jsx")
-LINT_EXT = tuple(sorted(set(CODE_EXT + STYLE_EXT + MARKUP_EXT)))
-
-HEXCOLOR = re.compile(r"#[0-9a-fA-F]{3,8}\b")
-FUNCCOLOR = re.compile(r"\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\s*\(")
-DEAD_FONT = re.compile(r"var\(\s*--a-font\s*[,)]")
-SCOPE_EXTENT = re.compile(
-    r":scope(?:\[[^\]]*\])?\s*\{[^{}]*?\b(?:width|height|inline-size|block-size)\s*:", re.S)
-BOOL_TRUE = re.compile(r"\bdefault:\s*true\b")
-ATTR_TYPO = re.compile(r"\battr:\s*['\"]")
-NATIVE_PRIMITIVE = re.compile(r"<(?:button|input|select|textarea|dialog)(?![\w-])")  # raw native, not a *-ui
-LEGACY_SHELL = re.compile(
-    r"data-chat-(?:messages|input|empty|name)|data-editor-body|data-canvas\b|data-sidebar="
-    r"|data-pane-(?:side|grow)|<aside-ui\b|<dialog\s+data-command")  # retired shell shapes (ADR-0024)
-PX_GE = re.compile(r"(?<![\w.-])(\d+)px\b")   # integer px; fractional (1.5px) deliberately not matched
-SELECTOR_RULE = re.compile(r"(?m)^\s*[.#:\[&\w][^{}\n]*\{")  # a selector opening a rule block
-FOUNDATION_OPT_IN = re.compile(r"forge-lint:\s*foundation", re.I)
-# Genuine token/foundation SHEETS are exempt from the CSS-literal + scope checks — matched by exact
-# stem or a styles/tokens dir, NOT a path substring (so a `color-picker` component is still linted).
-FOUNDATION_STEMS = {"tokens", "token", "theme", "themes", "foundation", "foundations",
-                    "palette", "palettes", "host", "reset", "resets", "scheme", "schemes",
-                    "color", "colors"}
-
-
-def _ext(path):
-    return os.path.splitext(path or "")[1].lower()
-
-
-def _is_foundation_css(path, text):
-    """A genuine token/foundation sheet — exempt from the CSS-literal + scope checks."""
-    segs = (path or "").replace("\\", "/").split("/")
-    if "styles" in segs or "tokens" in segs:
-        return True
-    stem = os.path.splitext(segs[-1])[0].lower() if segs else ""
-    if stem in FOUNDATION_STEMS:
-        return True
-    return bool(FOUNDATION_OPT_IN.search(text[:1000]))
-
-
-def lint_text(text, path=""):
-    """Return a list of (NAME, line, snippet, why) advisory findings."""
-    ext = _ext(path)
-    findings = []
-    is_tokenish = _is_foundation_css(path, text)
-
-    # Comment stripping (gh#976): the v0.8.34 session logged ~30 RAW-PX /
-    # RAW-COLOR / LEGACY-SHELL findings whose "literal" lived inside a
-    # comment (px values and hex codes QUOTED in prose). Track /* */ state
-    # across lines and match rules against the code that remains; JS line
-    # comments (//) are stripped for CODE_EXT files too.
-    in_block = False
-
-    def _strip_comments(raw):
-        nonlocal in_block
-        out, j, n = [], 0, len(raw)
-        while j < n:
-            if in_block:
-                k = raw.find("*/", j)
-                if k == -1:
-                    return "".join(out)
-                in_block = False
-                j = k + 2
-                continue
-            k = raw.find("/*", j)
-            m = raw.find("//", j) if ext in CODE_EXT else -1
-            if m != -1 and (k == -1 or m < k):
-                out.append(raw[j:m])
-                return "".join(out)
-            if k == -1:
-                out.append(raw[j:])
-                return "".join(out)
-            out.append(raw[j:k])
-            in_block = True
-            j = k + 2
-        return "".join(out)
-
-    for i, line in enumerate(text.splitlines(), 1):
-        s = line.strip()[:90]
-        line = _strip_comments(line)
-        if not line.strip():
-            continue
-        if "attachShadow" in line:
-            findings.append(("SHADOW-DOM", i, s,
-                             "adia-ui is light-DOM — never attachShadow; it breaks the token cascade + @scope"))
-        if "::slotted(" in line:
-            findings.append(("SLOTTED", i, s,
-                             "light DOM has no ::slotted — style projected content via :scope > [slot=\"x\"]"))
-        if ext in STYLE_EXT:
-            if DEAD_FONT.search(line):
-                findings.append(("DEAD-FONT-TOKEN", i, s,
-                                 "--a-font is not a real token (resolves to UA serif) — use var(--a-font-family-ui)"))
-            if not is_tokenish:
-                for decl in line.split(";"):  # per-declaration: a literal on a line that also has a var() still counts
-                    d = decl.strip()
-                    if not d or d.startswith(("//", "/*", "*")) or "var(" in decl or "light-dark(" in decl:
-                        continue
-                    if HEXCOLOR.search(decl) or FUNCCOLOR.search(decl):
-                        findings.append(("RAW-COLOR", i, s,
-                                         "component CSS is token-only — replace the literal with var(--a-*) (foundation/token files excepted)"))
-                        break
-            if not is_tokenish and not line.lstrip().startswith("@"):  # skip @media/@container/@scope at-rules
-                for decl in line.split(";"):
-                    if "/*" in decl:                                   # author-annotated carve-out
-                        continue
-                    if any(int(v) >= 3 for v in PX_GE.findall(decl)):
-                        findings.append(("RAW-PX", i, s,
-                                         "no raw px >= 3 in component CSS — use var(--a-space-*); 1-2px hairlines exempt, annotate a deliberate exception with a comment"))
-                        break
-        if ext in CODE_EXT:
-            if BOOL_TRUE.search(line):
-                findings.append(("BOOL-DEFAULT-TRUE", i, s,
-                                 "a boolean prop defaulting true can't be turned off by absence — flip the name so absent = false; if the shape is deliberate, note that UIElement stamps the attribute on connect since gh#961 (attribute-keyed CSS is safe), and the attribute reflects truth"))
-            if ATTR_TYPO.search(line):
-                findings.append(("ATTR-TYPO", i, s,
-                                 "did you mean `attribute:`? `attr:` is silently ignored in a property definition"))
-        if (ext in MARKUP_EXT and "slot=" not in line and not s.startswith(("<!--", "//", "*", "/*"))
-                and NATIVE_PRIMITIVE.search(line)):
-            findings.append(("NATIVE-PRIMITIVE", i, s,
-                             "a composite must build from *-ui primitives (button-ui / input-ui / select-ui / textarea-ui / modal-ui) — raw natives skip focus rings, theming, and form association; a deliberate slotted trigger (with slot=) is the exception"))
-        if LEGACY_SHELL.search(line):
-            findings.append(("LEGACY-SHELL", i, s,
-                             "retired shell shape (ADR-0024, v0.4.0) — use the bespoke tag (chat-thread / chat-composer / chat-empty · admin-sidebar / admin-command · editor-canvas · pane-ui)"))
-
-    if ext in STYLE_EXT:
-        for m in SCOPE_EXTENT.finditer(text):
-            ln = text.count("\n", 0, m.start()) + 1
-            findings.append(("SCOPE-EXTENT", ln, ":scope { … width/height … }",
-                             "a primitive is size-agnostic — let the consumer own width/height; don't set extent on :scope"))
-        # MISSING-SCOPE (maintainer-authoring): a component sheet with rules but no @scope wrapper.
-        if not is_tokenish and "@scope" not in text and SELECTOR_RULE.search(text):
-            findings.append(("MISSING-SCOPE", 1, "(file has CSS rules but no @scope block)",
-                             "component CSS must be wrapped in `@scope (<tag>) { … }` so styles don't leak in light DOM (foundation/token sheets excepted; opt out with /* forge-lint: foundation */)"))
-
-    findings.sort(key=lambda f: (f[1], f[0]))
-    return findings
-
-
-def _render(path, findings):
-    out = [f"forge-lint: {len(findings)} structural smell(s) in {path or '<stdin>'}"]
-    for name, ln, snip, why in findings:
-        out.append(f"  [{name}] line {ln}: {snip}")
-        out.append(f"      → {why}")
-    return "\n".join(out)
-
-
-def _lint_path(path):
-    try:
-        with open(path, encoding="utf-8", errors="replace") as f:
-            return lint_text(f.read(), path)
-    except OSError as err:
-        msg = getattr(err, "strerror", None) or str(err)
-        return [("READ-ERROR", 1, path[:90], f"failed to read file: {msg}")]
-
-
-def _hook():
-    try:
-        event = json.load(sys.stdin)
-    except (json.JSONDecodeError, ValueError):
-        return 0
-    ti = event.get("tool_input", {}) or {}
-    path = ti.get("file_path", "") or ""
-    norm = path.replace("\\", "/")
-    if "packages/web-components/" not in norm and "packages/web-modules/" not in norm:
-        return 0  # scope anchor: framework component source only (the docstring's claim)
-    if _ext(path) not in LINT_EXT:
-        return 0  # only component source; stay quiet otherwise
-    text = ti.get("content")
-    if text is None:
-        if not os.path.isfile(path):
-            return 0
-        try:
-            with open(path, encoding="utf-8", errors="replace") as f:
-                text = f.read()
-        except OSError:
-            return 0
-    findings = lint_text(text, path)
-    if findings:
-        # PostToolUse exit-0 stdout is NOT fed to the model — only structured
-        # JSON reaches it. additionalContext delivers the advisory repair loop
-        # while preserving the never-block invariant.
-        context = (
-            _render(path, findings)
-            + "\n  (forge-lint advisory — adia-ui framework authoring smells; the skills own the judgment)"
-        )
-        print(json.dumps({
-            "hookSpecificOutput": {
-                "hookEventName": "PostToolUse",
-                "additionalContext": context,
-            }
-        }))
-    return 0  # NEVER block
-
-
-def _selftest():
-    """Built-in fixtures: each seeded smell must fire, clean files must stay quiet, --hook must exit 0."""
-    import io
-    cases = [
-        ("packages/web-components/components/x/x.css",
-         "@scope (x) {\n"
-         "  :scope { color:#f00; width:100%; font-family:var(--a-font); padding:24px; }\n"
-         "  :scope > [slot=a]::slotted(p) { margin:0; }\n"
-         "}",
-         {"RAW-COLOR", "SCOPE-EXTENT", "DEAD-FONT-TOKEN", "SLOTTED", "RAW-PX"}),
-        ("packages/web-components/styles/theme.css", ":root { --a-bg: light-dark(#fff, #000); }", set()),
-        ("packages/web-components/components/y/y.css",
-         ".y-thing { margin: 0; }\n.y-thing__row { gap: 4px; }",
-         {"MISSING-SCOPE"}),
-        ("packages/web-components/components/z/z.js",
-         "class Z extends UIElement {\n  static props = { open: { default: true }, label: { attr: 'label' } };\n"
-         "  connected() { this.attachShadow({ mode: 'open' }); }\n}",
-         {"SHADOW-DOM", "BOOL-DEFAULT-TRUE", "ATTR-TYPO"}),
-        ("packages/web-components/components/clean/clean.js",
-         "import { UIElement } from '../../core/element.js';\n"
-         "class Clean extends UIElement { connected() { this.innerHTML = '<col-ui></col-ui>'; } }",
-         set()),
-        ("packages/web-modules/shell/markup.html",
-         "<admin-shell>\n  <button>Save</button>\n  <input type=\"text\">\n  <button-ui slot=\"trigger\">ok</button-ui>\n</admin-shell>",
-         {"NATIVE-PRIMITIVE"}),
-        ("packages/web-modules/chat/legacy.html",
-         "<chat-shell>\n  <section data-chat-messages></section>\n  <chat-input-ui data-chat-input></chat-input-ui>\n</chat-shell>",
-         {"LEGACY-SHELL"}),
-    ]
-    ok = True
-    for name, text, expected in cases:
-        got = {f[0] for f in lint_text(text, name)}
-        if expected - got:
-            ok = False
-            print(f"selftest: {name} MISSING {sorted(expected - got)} (got {sorted(got)})", file=sys.stderr)
-        if not expected and got:
-            ok = False
-            print(f"selftest: {name} expected clean, got {sorted(got)}", file=sys.stderr)
-    saved_in, saved_out = sys.stdin, sys.stdout    # never-block invariant: --hook exits 0 even on smelly input
-    try:
-        sys.stdin = io.StringIO(json.dumps({"tool_input": {"file_path": "c.css",
-                                "content": ".a { color:#f00; }"}}))
-        sys.stdout = io.StringIO()
-        rc = _hook()
-        hook_out = sys.stdout.getvalue()
-    finally:
-        sys.stdin, sys.stdout = saved_in, saved_out
-    if rc != 0:
-        ok = False
-        print("selftest: --hook did not exit 0 on smelly input", file=sys.stderr)
-    if rc == 0 and hook_out and '"hookSpecificOutput"' not in hook_out:
-        ok = False
-        print("selftest: --hook stdout is not structured hookSpecificOutput JSON", file=sys.stderr)
-    print("selftest: PASS" if ok else "selftest: FAIL")
-    return 0 if ok else 1
-
-
-def main(argv):
-    if argv and argv[0] == "selftest":
-        return _selftest()
-    if "--hook" in argv:
-        return _hook()
-    args = [a for a in argv if a == "-" or not a.startswith("-")]
-    if not args:
-        print(__doc__.strip().split("\n\n", 1)[0], file=sys.stderr)
-        return 2
-    total = 0
-    for path in args:
-        if path == "-":
-            findings = lint_text(sys.stdin.read(), "<stdin>")
-            path = "<stdin>"
-        else:
-            findings = _lint_path(path)
-        if findings:
-            total += len(findings)
-            print(_render(path, findings))
-    return 1 if total else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))