@adia-ai/mcp 0.8.37 → 0.8.39

package/factory/vendor/adia-lint

@@ -0,0 +1,396 @@
+#!/usr/bin/env python3
+"""adia-lint — advisory authoring-smell checker for adia-ui apps (the mechanizable slice).
+
+SCOPE (be honest): pattern-matchable STRUCTURAL smells in component/page source — shadow-DOM use,
+raw colors, raw px ≥ 3, the dead `--a-font` token, ::slotted, width on :scope, the SSR context traps
+(top-level kit import + double route-owner — detected only in files carrying a framework signal, so a
+bare registration module won't trip it), hardcoded overlay `open`, native-primitive leaks (raw
+`<button>`/`<input>` where a `*-ui` exists), and retired shell shapes (the ADR-0024 data-attribute
+forms). Foundation/token sheets (under a
+styles/ or tokens/ dir, named tokens/theme/host/palette/…, or marked `/* adia-lint: foundation */`) are
+exempt from the color/px checks. It does NOT judge whether the UI is good, on-spec, or accessible — that
+lives in the skills (screen-composition / host-wiring / surface-qa) and the a2ui MCP's check_anti_patterns.
+A clean adia-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 MAINTAINER plugin's
+adia-ui-forge/scripts/forge-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. adia-lint keeps the consumer/app traps (SSR double-router, top-level
+import, hardcoded overlay open) that forge-lint drops; that divergence is the point.
+
+Usage:
+  adia-lint <file>...        # lint files; exit 1 if any smell found, else 0
+  adia-lint -                # lint stdin as a generic source file
+  adia-lint --hook           # PostToolUse hook mode: read event JSON on stdin, lint the written
+                             #   source file, print advisory findings, ALWAYS exit 0 (never blocks)
+  adia-lint selftest         # run built-in fixtures (seeded smells + a clean file + 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)))
+
+SSR_SIGNAL = re.compile(
+    r"""['"]use client['"]|\buseEffect\b|\bonMounted\b|\bonMount\b|"""
+    r"""from\s+['"](?:react|vue|svelte|next|nuxt|@sveltejs|astro)|"""
+    r"""getServerSideProps|defineNuxtComponent""", re.I)
+
+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*['\"]")
+OVERLAY_OPEN = re.compile(r"<(?:modal|drawer)-ui\b[^>]*?(?<![:.\w])\bopen\b(?!\s*=\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)
+TOPLEVEL_IMPORT = re.compile(r"""^\s*import\s+['"]@adia-ai/web-components['"]\s*;?\s*$""")
+PX_GE = re.compile(r"(?<![\w.-])(\d+)px\b")   # integer px values; fractional (1.5px) deliberately not matched
+FOUNDATION_OPT_IN = re.compile(r"adia-lint:\s*foundation", re.I)
+# Genuine token/foundation SHEETS are exempt from color/px — matched by exact stem or a styles/ dir,
+# NOT a path substring (so a `color-picker` / `theme-toggle` 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 color/px (component sheets are not)."""
+    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_ssr = bool(SSR_SIGNAL.search(text)) or ext in (".vue", ".svelte", ".astro")
+    is_tokenish = _is_foundation_css(path, text)
+
+    for i, line in enumerate(text.splitlines(), 1):
+        s = line.strip()[:90]
+        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) — floor to 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 ATTR_TYPO.search(line):
+                findings.append(("ATTR-TYPO", i, s,
+                                 "did you mean `attribute:`? `attr:` is silently ignored in a property definition"))
+        if is_ssr:
+            if "<router-ui" in line:
+                findings.append(("SSR-DOUBLE-ROUTER", i, s,
+                                 "in SSR the framework router owns routing — don't also mount <router-ui> (two route owners)"))
+            if TOPLEVEL_IMPORT.search(line):
+                findings.append(("SSR-TOPLEVEL-IMPORT", i, s,
+                                 "a top-level kit import throws `HTMLElement is not defined` on the server — defer it into a client hook"))
+        if ext in MARKUP_EXT and OVERLAY_OPEN.search(line):
+            findings.append(("HARDCODED-OPEN", i, s,
+                             "drive overlays via the .open property, not a hardcoded `open` attribute (it bricks the page)"))
+        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,
+                             "use the *-ui primitive (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 … }",
+                             "the component is size-agnostic — let the consumer own width/height; don't set extent on :scope"))
+
+    # ── File-level shell/llm/genui checks (factory-audit Wave 2, gh#259).
+    # Consumer-side rules by design — NOT mirrored into forge-lint (the
+    # vendored-divergence note at the top of this file: adia-lint keeps the
+    # consumer/app traps). Each promotes a previously prose-only gate from
+    # the shell-selection / llm-wiring / gen-ui-wiring skills.
+    if ext in MARKUP_EXT or ext in (".js", ".mjs", ".ts", ".jsx", ".tsx", ".vue", ".svelte", ".astro"):
+        # Tag-boundary anchored (gh#1258): a bare prefix count also matches
+        # <admin-page-header>/<admin-page-body>/<admin-page-footer>, false-positiving
+        # the canonical admin skeleton itself. [\s/>] admits only the real tags.
+        _pages = len(re.findall(r"<admin-page[\s/>]", text))
+        _scrolls = len(re.findall(r"<admin-scroll[\s/>]", text))
+        if _scrolls and _pages > _scrolls:
+            findings.append(("SHELL-NESTING", 1, "<admin-page> × N inside <admin-scroll>",
+                             "each <admin-scroll> hosts exactly one <admin-page> — multiple pages need multiple scroll regions"))
+        for m in re.finditer(r"<(?:col|row)-ui[^>]*>\s*<(?:admin|chat|editor)-", text):
+            ln = text.count("\n", 0, m.start()) + 1
+            findings.append(("SHELL-NESTING", ln, text[m.start():m.start() + 60].strip()[:90],
+                             "shell children are positioned by tag selectors — wrapping them in <col-ui>/<row-ui> breaks the shell grid; generics go inside admin-content/admin-page-body"))
+        if re.search(r"<admin-sidebar[^>]*\bresizable\b", text) and "data-resize" not in text:
+            findings.append(("SHELL-RESIZE", 1, "<admin-sidebar resizable> without [data-resize]",
+                             "[resizable] needs a child <div data-resize> or there is no drag handle"))
+        # server-side files legitimately hold keys — exempt any path whose
+        # segments mention server/api/proxy (the smart-proxy's own home).
+        _segs = path.replace(os.sep, "/").lower().split("/")
+        if not any(("server" in s or "proxy" in s or s == "api") for s in _segs):
+            for m in re.finditer(r"\bapi[-_]?[Kk]ey\b\s*[:=]", text):
+                ln = text.count("\n", 0, m.start()) + 1
+                findings.append(("LLM-KEY-IN-CLIENT", ln, text[m.start():m.start() + 50].strip()[:90],
+                                 "a provider key in client source ships to the browser — production uses a same-origin smart proxy (proxy-url); keys live server-side (llm-wiring)"))
+        doc_assign = re.search(r"\.doc\s*=", text)
+        if doc_assign:
+            ln = text.count("\n", 0, doc_assign.start()) + 1
+            if "validate_schema" not in text and "check_anti_patterns" not in text:
+                findings.append(("GENUI-UNVALIDATED", ln, ".doc = … with no validate in file",
+                                 "A2UI fed to .doc must pass validate_schema + check_anti_patterns first (gen-ui-wiring's hard gate) — validate in the same module or cite where it happened"))
+            if re.search(r"<(?:a2ui-root|gen-root)[^>]*\b(?:src|transport)=", text):
+                findings.append(("GENUI-DOC-CONFLICT", ln, ".doc = … alongside src=/transport=",
+                                 "two feed paths fight — a root is fed EITHER declaratively (src/transport) OR programmatically (.doc), never both"))
+
+    findings.sort(key=lambda f: (f[1], f[0]))
+    return findings
+
+
+def _render(path, findings):
+    out = [f"adia-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 e:
+        return [("READ-ERROR", 0, path, f"failed to read file: {e}")]
+
+
+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 ""
+    segs = (path or "").replace("\\", "/").split("/")
+    if any(s in ("node_modules", "dist", "build", ".next", "coverage") for s in segs):
+        return 0  # generated/vendored trees are never consumer-authored source
+    if _ext(path) not in LINT_EXT:
+        return 0  # only component/page 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  (adia-lint advisory — adia-ui authoring smells; the skills + a2ui MCP 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 = [
+        ("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"}),
+        ("styles/theme.css", ":root { --a-bg: light-dark(#fff, #000); }", set()),
+        ("components/color-picker/color-picker.css",
+         "@scope (color-picker) {\n  :scope { background:#abc; padding:40px; }\n}",
+         {"RAW-COLOR", "RAW-PX"}),
+        ("providers/p.tsx",
+         "'use client';\nimport '@adia-ai/web-components';\n"
+         "export default () => (<admin-shell><router-ui/><modal-ui open>x</modal-ui></admin-shell>);",
+         {"SSR-TOPLEVEL-IMPORT", "SSR-DOUBLE-ROUTER", "HARDCODED-OPEN"}),
+        ("core/clean.js",
+         "import { UIElement } from '@adia-ai/web-components/core/element';\n"
+         "class UIX extends UIElement { connected() { this.innerHTML = '<col-ui></col-ui>'; } }",
+         set()),
+        ("markup/natives.html",
+         "<col-ui>\n  <button>Save</button>\n  <input type=\"text\">\n  <button-ui slot=\"trigger\">ok</button-ui>\n</col-ui>",
+         {"NATIVE-PRIMITIVE"}),
+        ("markup/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"}),
+        # Wave-2 shell/llm/genui rules (gh#259)
+        ("markup/shell-bad.html",
+         "<admin-shell>\n<col-ui> <admin-sidebar resizable></admin-sidebar></col-ui>\n"
+         "<admin-scroll><admin-page>a</admin-page><admin-page>b</admin-page></admin-scroll>\n</admin-shell>",
+         {"SHELL-NESTING", "SHELL-RESIZE"}),
+        ("markup/shell-good.html",
+         "<admin-shell>\n<admin-sidebar resizable><div data-resize></div></admin-sidebar>\n"
+         "<admin-scroll><admin-page>a</admin-page></admin-scroll>\n</admin-shell>",
+         set()),
+        # gh#1258 regression: the CANONICAL admin skeleton (shell-patterns.md's admin
+        # cluster — admin-page-header/body/footer are distinct CSS-only children whose
+        # tag names share the <admin-page prefix) must stay clean.
+        ("markup/shell-canonical.html",
+         "<admin-shell>\n<admin-content>\n<admin-scroll>\n  <admin-page>\n"
+         "    <admin-page-header><header-ui><span slot=\"heading\">Page Title</span></header-ui></admin-page-header>\n"
+         "    <admin-page-body><section-ui>content</section-ui></admin-page-body>\n"
+         "    <admin-page-footer><footer-ui>legal</footer-ui></admin-page-footer>\n"
+         "  </admin-page>\n</admin-scroll>\n</admin-content>\n</admin-shell>",
+         set()),
+        # gh#1258 negative control: a REAL extra <admin-page> nested inside the same
+        # <admin-scroll> must still fire even with -header/-body suffix tags present.
+        ("markup/shell-nested-bad.html",
+         "<admin-scroll>\n  <admin-page>\n    <admin-page-header>h</admin-page-header>\n"
+         "    <admin-page-body><admin-page>nested</admin-page></admin-page-body>\n"
+         "  </admin-page>\n</admin-scroll>",
+         {"SHELL-NESTING"}),
+        ("app/chat-boot.js",
+         "const s = document.querySelector('chat-shell');\ns.apiKey = 'sk-live';\n",
+         {"LLM-KEY-IN-CLIENT"}),
+        ("api/llm-proxy.js",
+         "const key = { apiKey: process.env.ANTHROPIC_API_KEY };\n",
+         set()),
+        ("app/genui-boot.js",
+         "root.doc = generated;\n",
+         {"GENUI-UNVALIDATED"}),
+        ("app/genui-ok.js",
+         "await validate_schema(generated); await check_anti_patterns(generated);\nroot.doc = generated;\n",
+         set()),
+        ("app/genui-conflict.html",
+         "<a2ui-root src=\"/gen.json\"></a2ui-root>\n<script>await validate_schema(d); await check_anti_patterns(d); root.doc = d;</script>",
+         {"GENUI-DOC-CONFLICT"}),
+    ]
+    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": "x.css",
+                                "content": "@scope (x) {\n :scope { color:#f00; }\n}"}}))
+        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)
+
+    # REQ-05 (gh#1136): -h/--help exits 0 and prints usage — never a data payload.
+    for flag in ("-h", "--help"):
+        saved_out = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            rc_help = main([flag])
+            help_out = sys.stdout.getvalue()
+        finally:
+            sys.stdout = saved_out
+        if rc_help != 0:
+            ok = False
+            print(f"selftest: {flag} did not exit 0", file=sys.stderr)
+        if not help_out.startswith("usage:"):
+            ok = False
+            print(f"selftest: {flag} did not print usage", file=sys.stderr)
+
+    print("selftest: PASS" if ok else "selftest: FAIL")
+    return 0 if ok else 1
+
+
+_USAGE = "usage: adia-lint <file>...  |  adia-lint -  |  adia-lint --hook  |  adia-lint selftest"
+
+
+def main(argv):
+    if argv and argv[0] == "selftest":
+        return _selftest()
+    if "--hook" in argv:
+        return _hook()
+    # REQ-05 (gh#1136, factory-dx-ws5-consumer-verify): -h/--help must print
+    # usage and exit 0 — checked BEFORE positional-arg resolution so it can
+    # never fall through into "no files given" (a different contract point,
+    # exit 2). Previously -h/--help fell through to the no-args branch below
+    # and exited 2 with a docstring fragment instead of usage text.
+    if "-h" in argv or "--help" in argv:
+        print(_USAGE)
+        return 0
+    args = [a for a in argv if a == "-" or not a.startswith("-")]
+    if not args:
+        print(_USAGE, 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:]))