"""Template lint: reject JSX and unknown directives in PulsePoint markup.
Why this exists
---------------
`npm run check` validated Python only. A route template could contain JSX --
`{users.map(user => (|
))}`, `class={...}`, `className` -- and the gate stayed
green, because nothing in the toolchain reads `.html` files. The failure then
surfaced only in the browser, and the worst variant surfaced nowhere at all: an
unquoted brace attribute is invalid HTML, so the parser shreds the element, the
component root never compiles, the runtime's reveal step never clears
``, and the route serves a blank page with **no console
error**.
PulsePoint borrows React's hook API inside `` (the component script is JS, `.map()` is correct there)
- `` / `` (documentation examples)
- `` (commented-out markup)
Usage:
python settings/check_templates.py # run standalone
npm run check # runs as part of the gate
"""
from __future__ import annotations
import re
from dataclasses import dataclass
from pathlib import Path
PROJECT_ROOT = Path(__file__).resolve().parents[1]
SCAN_ROOT = PROJECT_ROOT / "src"
# Generated or vendored trees that are not hand-authored markup.
EXCLUDED_PARTS = {"__pycache__", "node_modules", ".venv", "prisma"}
@dataclass
class TemplateIssue:
path: str
line: int
column: int
code: str
message: str
@dataclass
class Rule:
code: str
pattern: re.Pattern[str]
message: str
# Each rule names the JSX/unsupported construct and the PulsePoint replacement,
# so the report is directly actionable without opening the docs.
RULES: list[Rule] = [
Rule(
"jsx-map",
# `{items.map(item => (` and `{items.map((item, i) => (` -- the trailing
# `(` is what distinguishes returning markup from a normal value map.
re.compile(r"\{[^{}\n]*?\.map\s*\(\s*\(?[\w\s,]*\)?\s*=>\s*\(", re.MULTILINE),
'JSX .map() returning markup. Use with key="{item.id}".',
),
Rule(
"jsx-logical",
# `{cond && ()}`. Use hidden="{!cond}" on the element.',
),
Rule(
"jsx-ternary-element",
# `{cond ? : }`. Use two elements with complementary hidden="{...}" bindings.',
),
Rule(
"unquoted-brace-attr",
# `class={...}` / `selected={...}` -- invalid HTML, silently blanks the page.
#
# An attribute only exists *inside an opening tag*, and the rule must say
# so. A bare `\s[\w:.\-]+=\{` also matches `DIR={path}` in a shell script
# and `ENV PORT={port}` in a Dockerfile -- and this repo embeds both in
# triple-quoted strings under `src/lib/aws/`, which the Python scan keeps
# because it cannot tell a heredoc from a template. Requiring the opening
# tag is not a loosening: a real violation is always inside one.
#
# `[^<>]*?` bounds the attribute run to a single tag; it matches newlines
# (negated classes do), so an attribute on its own line is still caught.
re.compile(r"<[a-zA-Z][\w:.\-]*(?:[^<>]*?)?\s[\w:.\-]+=\{"),
"Unquoted brace attribute. This is invalid HTML: the parser splits the "
"value on spaces, the component root never compiles, and the page "
'renders blank with no console error. Quote it: attr="{expr}".',
),
Rule(
"react-attribute",
re.compile(r"\s(className|htmlFor|dangerouslySetInnerHTML)\s*="),
"React DOM property. Use class=, for=, or server-rendered markup.",
),
Rule(
"camelcase-event",
# `onClick="…"` / `onClick={…}` in attribute position. The value-start
# class and the declaration lookbehinds keep ordinary JavaScript out:
# `const onPointerEnter = () => {` is a valid handler name in a component
# script or an injected snippet, not a JSX prop.
re.compile(
r"(?` is unambiguous, and a well-formed fragment always has one. A bare
# `<>` is not: it is SQL's not-equals operator, and this repo runs
# `WHERE pid <> pg_backend_pid()` from a triple-quoted string. So the
# open tag counts only when an element follows it, which is what a
# fragment looks like and what `<> value` in SQL never does.
re.compile(r"|<>\s*<"),
"JSX fragment. A template needs exactly one real root element.",
),
Rule(
"style-object",
re.compile(r"style\s*=\s*\{\{"),
"JSX style object. pp-style takes a CSS *string*: pp-style=\"{'color: red'}\".",
),
Rule(
"unknown-directive",
re.compile(r"\spp-(if|show|else|elif|key|class|text|html|model|bind|on)\s*[=>\s]"),
"Directive does not exist in PulsePoint. Conditionals use "
'hidden="{...}", lists use , keys use plain key="{...}".',
),
]
# `pp-for` is valid only on . Matching the opening tag it sits in is
# enough: the attribute cannot appear before its own tag name.
PP_FOR_TAG = re.compile(r"<\s*([a-zA-Z][\w:-]*)([^>]*?\spp-for\s*=)", re.DOTALL)
SCRIPT_BLOCK = re.compile(r"", re.IGNORECASE | re.DOTALL)
PRE_BLOCK = re.compile(r"<(pre|code)\b.*?", re.IGNORECASE | re.DOTALL)
HTML_COMMENT = re.compile(r"", re.DOTALL)
# Components are imported with Python imports; an `@import` HTML comment does
# not import anything and the compiler refuses it. Matched BEFORE comments are
# blanked out — the construct *is* a comment.
IMPORT_COMMENT = re.compile(r"