simple-module-core 0.0.26__tar.gz → 0.0.27__tar.gz

{simple_module_core-0.0.26 → simple_module_core-0.0.27}/.gitignore

@@ -45,6 +45,7 @@ docs/.vitepress/dist/
 host/client_app/modules.manifest.json
 host/client_app/modules.generated.ts
 host/client_app/modules.generated.css
+host/client_app/modules.assets.json
 
 # Worktrees
 .worktrees/

{simple_module_core-0.0.26 → simple_module_core-0.0.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_core
-Version: 0.0.26
+Version: 0.0.27
 Summary: Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python

{simple_module_core-0.0.26 → simple_module_core-0.0.27}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.26"
+version = "0.0.27"
 description = "Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events"
 readme = "README.md"
 license = "MIT"

simple_module_core-0.0.27/simple_module_core/diagnostics/_css.py

@@ -0,0 +1,214 @@
+"""SM022/SM023: module CSS placed in the file with the wrong cascade position.
+
+A module ships its styles in two files, and which one a construct lands in
+decides how it cascades:
+
+* ``theme.css`` is imported **unlayered**, because a ``@theme`` block inside a
+  cascade layer registers no design tokens at all. Unlayered CSS also outranks
+  every layered rule, so a plain rule here would beat any Tailwind utility.
+* ``styles.css`` is imported into ``layer(components)``, so its rules always
+  lose to a utility — which is what you want for component CSS, and useless
+  for ``@theme``.
+
+Both codes are warnings, not errors: the misplaced CSS is legal and builds
+fine, it just cascades in a way the author almost certainly did not intend.
+
+Detection is a line-oriented scan that tracks brace depth, not a CSS parse —
+adding a CSS parser as a runtime dependency to power a lint is not worth it.
+This catches the ordinary mistake of putting a construct in the wrong file; it
+is not a conformance checker, and pathological input (an at-rule assembled by
+preprocessing, say) is out of scope.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+THEME_CSS = "theme.css"
+STYLES_CSS = "styles.css"
+
+# Constructs that only do anything unlayered, so they belong in theme.css.
+THEME_ONLY_AT_RULES = ("@theme", "@custom-variant", "@utility")
+
+
+def _top_level_preludes(text: str) -> list[tuple[str, int]]:
+    """Return ``(prelude, line_number)`` for every top-level construct.
+
+    A "prelude" is the selector or at-rule text preceding a top-level ``{``,
+    or a whole statement at-rule terminated by ``;`` at depth 0. Anything
+    nested inside braces is skipped, which is what keeps a rule inside
+    ``@layer components { ... }`` from being mistaken for a top-level one.
+
+    Comments and quoted strings are consumed inline rather than pre-stripped,
+    because a brace inside either is not structural. ``content: "{"`` in an
+    icon-font rule would otherwise desynchronise the depth counter for the
+    whole rest of the file — every later top-level construct would be read as
+    nested and silently skipped.
+
+    A quote only opens a string when its partner is found before the line
+    ends, which is the rule CSS itself applies (a string cannot contain a raw
+    newline). Treating every quote as an opener is what makes an *unmatched*
+    one dangerous: the lone apostrophe in ``url(it's.png); }`` would swallow
+    the closing brace on that same line and desync the counter permanently.
+    An unmatched quote is therefore just an ordinary character.
+    """
+    out: list[tuple[str, int]] = []
+    depth = 0
+    buf: list[str] = []
+    line = 1
+    buf_line = 1
+    i = 0
+    n = len(text)
+
+    def flush() -> None:
+        prelude = "".join(buf).strip()
+        if prelude:
+            out.append((prelude, buf_line))
+
+    def string_end(start: int, quote: str) -> int | None:
+        """Index just past the closing quote, or None if it never closes."""
+        j = start + 1
+        while j < n:
+            c = text[j]
+            if c == "\\":
+                # An escape consumes the next character whole — including a
+                # newline, the one way a CSS string legitimately spans lines.
+                j += 2
+                continue
+            if c == "\n":
+                return None
+            if c == quote:
+                return j + 1
+            j += 1
+        return None
+
+    while i < n:
+        ch = text[i]
+
+        if ch == "/" and i + 1 < n and text[i + 1] == "*":
+            end = text.find("*/", i + 2)
+            end = n if end == -1 else end + 2
+            line += text.count("\n", i, end)
+            i = end
+            continue
+
+        if ch == "\\" and i + 1 < n:
+            # CSS escapes apply outside strings too — Tailwind leans on this
+            # heavily (`.mt-\[773px\]`). Consuming the pair keeps an escaped
+            # quote from being mistaken for a string opener, which is also
+            # what stops `\'` repeated across a long line from making
+            # string_end re-scan that line once per quote (quadratic).
+            if depth == 0:
+                if not buf:
+                    buf_line = line
+                buf.append(text[i : i + 2])
+            if text[i + 1] == "\n":
+                line += 1
+            i += 2
+            continue
+
+        if ch in "\"'":
+            end = string_end(i, ch)
+            if end is not None:
+                if depth == 0:
+                    if not buf:
+                        buf_line = line
+                    buf.append(text[i:end])
+                line += text.count("\n", i, end)
+                i = end
+                continue
+            # Unmatched: fall through and treat it as an ordinary character.
+
+        if ch == "{":
+            if depth == 0:
+                flush()
+                buf.clear()
+            depth += 1
+        elif ch == "}":
+            depth = max(0, depth - 1)
+            if depth == 0:
+                buf.clear()
+        elif depth == 0:
+            if ch == ";":
+                flush()
+                buf.clear()
+            elif buf:
+                buf.append(ch)
+            elif not ch.isspace():
+                # Start the buffer at the first non-space character, so
+                # buf_line points at the construct rather than at whatever
+                # blank lines preceded it.
+                buf_line = line
+                buf.append(ch)
+
+        if ch == "\n":
+            line += 1
+        i += 1
+    return out
+
+
+def _is_root_selector(prelude: str) -> bool:
+    """True if every comma-separated part of the selector is :root-based.
+
+    ``:root``, ``:root[data-theme="dark"]`` and a comma-separated list of both
+    are the normal way to declare design tokens, so they are legitimate in
+    theme.css even though they are plain rules.
+    """
+    parts = [p.strip() for p in prelude.split(",") if p.strip()]
+    return bool(parts) and all(p.startswith(":root") for p in parts)
+
+
+def check_module_css(mod: ModuleBase, src_dir: Path) -> list[Diagnostic]:
+    """Warn when module CSS sits in the file with the wrong cascade position."""
+    diagnostics: list[Diagnostic] = []
+
+    styles = src_dir / STYLES_CSS
+    if styles.is_file():
+        for prelude, line in _top_level_preludes(styles.read_text("utf-8")):
+            at_rule = prelude.split()[0].lower() if prelude.split() else ""
+            if at_rule in THEME_ONLY_AT_RULES:
+                diagnostics.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.WARNING,
+                        code="SM022",
+                        message=(
+                            f"{at_rule} in {STYLES_CSS} is inert — that file is "
+                            "imported into layer(components)"
+                        ),
+                        module_name=mod.meta.name,
+                        file=f"{styles}:{line}",
+                        suggestion=(
+                            f"Move the {at_rule} block to {src_dir / THEME_CSS}, which is "
+                            "imported unlayered so its tokens actually register"
+                        ),
+                    )
+                )
+
+    theme = src_dir / THEME_CSS
+    if theme.is_file():
+        for prelude, line in _top_level_preludes(theme.read_text("utf-8")):
+            if prelude.startswith("@") or _is_root_selector(prelude):
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    level=DiagnosticLevel.WARNING,
+                    code="SM023",
+                    message=(
+                        f"Unlayered rule '{prelude}' in {THEME_CSS} outranks every Tailwind utility"
+                    ),
+                    module_name=mod.meta.name,
+                    file=f"{theme}:{line}",
+                    suggestion=(
+                        f"Move it to {src_dir / STYLES_CSS}, which is imported into "
+                        "layer(components) so utilities still win"
+                    ),
+                )
+            )
+
+    return diagnostics

{simple_module_core-0.0.26 → simple_module_core-0.0.27}/simple_module_core/diagnostics/_module.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from simple_module_core.diagnostics._coupling import check_framework_module_coupling
+from simple_module_core.diagnostics._css import check_module_css
 from simple_module_core.diagnostics._inertia_api import check_inertia_api_calls
 from simple_module_core.diagnostics._js_workspace import check_js_workspace_files
 from simple_module_core.diagnostics._pages import check_pages, find_render_calls
@@ -37,6 +38,7 @@ class ModuleDiagnostics:
                 diagnostics.extend(check_pages(mod, src_dir, rendered_pages))
                 diagnostics.extend(check_js_workspace_files(mod, src_dir))
                 diagnostics.extend(check_inertia_api_calls(mod, src_dir))
+                diagnostics.extend(check_module_css(mod, src_dir))
 
         return diagnostics
 

simple_module_core-0.0.27/tests/test_css_diagnostics.py

@@ -0,0 +1,97 @@
+"""SM022/SM023 — module CSS placed in the wrong file.
+
+The theme.css / styles.css split is what makes the cascade rules structural
+rather than merely documented, so putting a construct in the wrong file
+produces surprising-but-legal CSS. Both codes are warnings for that reason:
+the build succeeds either way.
+"""
+
+from __future__ import annotations
+
+
+def _mod():
+    from simple_module_core import ModuleBase, ModuleMeta
+
+    class Styled(ModuleBase):
+        meta = ModuleMeta(name="Styled")
+
+    return Styled()
+
+
+class TestSm022ThemeConstructsInStylesCss:
+    def test_theme_at_rule_in_styles_css(self, tmp_path):
+        """@theme inside styles.css is inert — styles.css is imported layered."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text("@theme {\n  --color-x: red;\n}\n")
+
+        diags = check_module_css(_mod(), tmp_path)
+
+        assert [d.code for d in diags] == ["SM022"]
+        assert diags[0].level.value == "warning"
+
+    def test_custom_variant_in_styles_css(self, tmp_path):
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text("@custom-variant dark (&:where(.dark, .dark *));\n")
+
+        assert [d.code for d in check_module_css(_mod(), tmp_path)] == ["SM022"]
+
+    def test_utility_at_rule_in_styles_css(self, tmp_path):
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text("@utility tab-4 {\n  tab-size: 4;\n}\n")
+
+        assert [d.code for d in check_module_css(_mod(), tmp_path)] == ["SM022"]
+
+    def test_reports_the_offending_line(self, tmp_path):
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text(
+            "@layer components {\n  .x { color: red; }\n}\n\n@theme {\n  --a: 1;\n}\n"
+        )
+
+        diags = check_module_css(_mod(), tmp_path)
+
+        assert len(diags) == 1
+        # Line number rides in `file` as path:line, matching _inertia_api.py.
+        assert diags[0].file.endswith("styles.css:5")
+
+
+class TestSm023UnlayeredRulesInThemeCss:
+    def test_plain_rule_in_theme_css(self, tmp_path):
+        """An unlayered rule in theme.css outranks every Tailwind utility."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text(".card {\n  padding: 0;\n}\n")
+
+        diags = check_module_css(_mod(), tmp_path)
+
+        assert [d.code for d in diags] == ["SM023"]
+        assert diags[0].level.value == "warning"
+
+    def test_root_block_allowed(self, tmp_path):
+        """:root custom-property blocks are legitimate in theme.css."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text("@theme {\n  --a: 1;\n}\n:root {\n  --b: 2;\n}\n")
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_root_variants_allowed(self, tmp_path):
+        """Dark-mode token blocks keyed off :root are the normal pattern."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text(':root,\n:root[data-theme="dark"] {\n  --b: 2;\n}\n')
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_font_face_allowed(self, tmp_path):
+        """@font-face is explicitly part of what theme.css is for."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text(
+            "@font-face {\n  font-family: X;\n  src: url(x.woff2);\n}\n"
+        )
+
+        assert check_module_css(_mod(), tmp_path) == []

simple_module_core-0.0.27/tests/test_css_scanner.py

@@ -0,0 +1,242 @@
+"""The CSS scanner behind SM022/SM023.
+
+`check_module_css` is only as good as its ability to find *top-level*
+constructs, and it does that with a hand-rolled brace-depth scan rather than a
+CSS parse — no parser joins the runtime dependencies to power a lint. These
+tests pin the tokenising rules that scan depends on: comments, quoted strings,
+escapes, and the line numbers reported alongside a finding.
+
+Every case here is a bug that shipped at some point during review: each one is
+a way a stray character silently desynced the depth counter and made the lint
+stop reporting anything at all.
+"""
+
+from __future__ import annotations
+
+
+def _mod():
+    from simple_module_core import ModuleBase, ModuleMeta
+
+    class Styled(ModuleBase):
+        meta = ModuleMeta(name="Styled")
+
+    return Styled()
+
+
+class TestScannerRobustness:
+    def test_nested_at_rule_not_flagged(self, tmp_path):
+        """Only top-level constructs count — brace depth is tracked."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text("@layer components {\n  .x { color: red; }\n}\n")
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_nested_rule_in_theme_css_not_flagged(self, tmp_path):
+        """A rule nested inside @theme is not a top-level rule."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text("@theme {\n  --a: 1;\n}\n")
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_commented_out_construct_is_not_a_finding(self, tmp_path):
+        """A commented-out @theme is not a finding."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text("/* @theme { --x: 1; } */\n.y { color: red; }\n")
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_comment_does_not_shift_line_numbers(self, tmp_path):
+        """Newlines inside a skipped comment must still be counted."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text("/* a\n   multi-line\n   comment */\n@theme {\n}\n")
+
+        diags = check_module_css(_mod(), tmp_path)
+
+        assert [d.file.rsplit(":", 1)[1] for d in diags] == ["4"]
+
+    def test_clean_module_has_no_findings(self, tmp_path):
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text("@theme {\n  --color-x: red;\n}\n")
+        (tmp_path / "styles.css").write_text("@layer components {\n  .x { color: red; }\n}\n")
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_missing_files_are_not_findings(self, tmp_path):
+        from simple_module_core.diagnostics._css import check_module_css
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_open_brace_in_a_string_does_not_hide_later_findings(self, tmp_path):
+        """A brace inside a string must not desync the depth counter.
+
+        An icon-font rule like `content: "{"` used to leave the scanner
+        permanently one level deep, so every later top-level construct read as
+        nested — silently swallowing the very @theme SM022 exists to catch.
+        """
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text('.icon { content: "{"; }\n@theme {\n  --a: 1;\n}\n')
+
+        diags = check_module_css(_mod(), tmp_path)
+
+        assert [d.code for d in diags] == ["SM022"]
+        assert diags[0].file.endswith("styles.css:2")
+
+    def test_close_brace_in_a_string_is_not_a_finding(self, tmp_path):
+        """A closing brace inside a string must not end the block early."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text(':root {\n  --icon-close: "}";\n}\n')
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_escaped_quote_in_a_string(self, tmp_path):
+        """A backslash-escaped quote does not terminate the string."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text(':root {\n  --q: "a\\"{b";\n}\n')
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_single_quoted_strings_handled(self, tmp_path):
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text(
+            ".icon { content: '{'; }\n@utility tab-4 {\n  tab-size: 4;\n}\n"
+        )
+
+        assert [d.code for d in check_module_css(_mod(), tmp_path)] == ["SM022"]
+
+    def test_unterminated_string_does_not_swallow_the_file(self, tmp_path):
+        """A stray quote must not disable the lint for everything after it.
+
+        A CSS string cannot contain a raw newline, so an unterminated one ends
+        at end-of-line. Without that bound, a single typo'd quote left the
+        scanner permanently "inside a string" and every later brace stopped
+        counting — silently hiding the rest of the file's findings.
+        """
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text(
+            '.a { color: red; }\n.b {\n  content: "unterminated;\n}\n@theme {\n  --b: 1;\n}\n'
+        )
+
+        diags = check_module_css(_mod(), tmp_path)
+
+        assert [d.code for d in diags] == ["SM022"]
+        assert diags[0].file.endswith("styles.css:5")
+
+    def test_apostrophe_in_unquoted_url_does_not_swallow_the_file(self, tmp_path):
+        """An unquoted url() token may hold a lone apostrophe, e.g. inline SVG."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text(
+            ".icon {\n"
+            "  background: url(data:image/svg+xml,<text>it's here</text>);\n"
+            "}\n"
+            "@theme {\n"
+            "  --a: 1;\n"
+            "}\n"
+        )
+
+        assert [d.code for d in check_module_css(_mod(), tmp_path)] == ["SM022"]
+
+    def test_stray_quote_does_not_eat_a_brace_on_its_own_line(self, tmp_path):
+        """The unmatched-quote case, with the closing brace on the SAME line.
+
+        Bounding strings at newlines was not enough: the `}` here sits on the
+        stray quote's own line, so it was consumed as string content and the
+        depth counter stayed desynced for the rest of the file. A quote only
+        opens a string if its partner appears before the line ends.
+        """
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text(
+            ".icon { background: url(it's.png); }\n@theme {\n  --a: 1;\n}\n"
+        )
+
+        diags = check_module_css(_mod(), tmp_path)
+
+        assert [d.code for d in diags] == ["SM022"]
+        assert diags[0].file.endswith("styles.css:2")
+
+    def test_multiline_quoted_value_is_not_a_finding(self, tmp_path):
+        """grid-template-areas spreads several complete strings over lines."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text(
+            "@layer components {\n"
+            "  .g {\n"
+            "    grid-template-areas:\n"
+            '      "a b"\n'
+            '      "c d";\n'
+            "  }\n"
+            "}\n"
+        )
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_escaped_selector_is_not_a_string_opener(self, tmp_path):
+        """CSS escapes apply outside strings — Tailwind selectors rely on it."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text(
+            ".mt-\\[773px\\] { margin-top: 773px; }\n@theme {\n  --a: 1;\n}\n"
+        )
+
+        diags = check_module_css(_mod(), tmp_path)
+
+        assert [d.code for d in diags] == ["SM022"]
+        assert diags[0].file.endswith("styles.css:2")
+
+    def test_scanner_is_linear_on_pathological_input(self, tmp_path):
+        """A long run of escaped quotes must not make the scan quadratic.
+
+        `doctor` runs this over every installed module, including third-party
+        ones, so a minified or vendored stylesheet must not stall the lint.
+        Before escapes were consumed outside strings, 58KB of `\\'` took ~10s.
+        """
+        import time
+
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text("\\'" * 60_000)
+
+        started = time.perf_counter()
+        check_module_css(_mod(), tmp_path)
+        elapsed = time.perf_counter() - started
+
+        assert elapsed < 2.0, f"scan took {elapsed:.1f}s — likely quadratic again"
+
+    def test_escaped_newline_continues_a_string(self, tmp_path):
+        """A backslash-escaped newline is the one way a string spans lines."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text(':root {\n  --a: "x\\\n  y";\n}\n')
+
+        assert check_module_css(_mod(), tmp_path) == []
+
+    def test_brace_inside_a_comment_is_not_structural(self, tmp_path):
+        """An unbalanced brace in a comment must not shift depth either."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "styles.css").write_text("/* } { */\n@theme {\n  --a: 1;\n}\n")
+
+        diags = check_module_css(_mod(), tmp_path)
+
+        assert [d.code for d in diags] == ["SM022"]
+        assert diags[0].file.endswith("styles.css:2")
+
+    def test_import_statement_allowed_in_either_file(self, tmp_path):
+        """A statement at-rule ending in ; is not a rule block."""
+        from simple_module_core.diagnostics._css import check_module_css
+
+        (tmp_path / "theme.css").write_text('@import "other.css";\n')
+        (tmp_path / "styles.css").write_text('@charset "utf-8";\n')
+
+        assert check_module_css(_mod(), tmp_path) == []