splent-cli 1.47.0__tar.gz → 1.48.1__tar.gz

{splent_cli-1.47.0/src/splent_cli.egg-info → splent_cli-1.48.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.47.0
+Version: 1.48.1
 Summary: SPLENT-CLI is a CLI to be able to work on your development more easily.
 Author-email: DiversoLab <diversolab@us.es>
 License-Expression: LGPL-3.0-or-later

{splent_cli-1.47.0 → splent_cli-1.48.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.47.0"
+version = "1.48.1"
 description = "SPLENT-CLI is a CLI to be able to work on your development more easily."
 readme = "README.md"
 requires-python = ">=3.13"

{splent_cli-1.47.0 → splent_cli-1.48.1}/src/splent_cli/commands/check/check_deps.py

@@ -152,6 +152,34 @@ def _scan_feature_imports(
     return python_imports, template_deps
 
 
+def _optional_features(feature_path: str) -> set[str]:
+    """The packages a feature's contract names in requires.features_optional.
+
+    A feature reaches those only when the product has them (a tolerant
+    import, a has_endpoint guard), so its reference to one needs no UVL
+    constraint: the model leaves the other feature optional, and nothing
+    breaks without it. Version ranges ("hubfile>=0.5.0") are dropped.
+    """
+    import tomllib
+
+    try:
+        with open(os.path.join(feature_path, "pyproject.toml"), "rb") as fh:
+            data = tomllib.load(fh)
+    except (OSError, tomllib.TOMLDecodeError):
+        return set()
+    requires = (
+        data.get("tool", {}).get("splent", {}).get("contract", {}).get("requires", {})
+    )
+    names = set()
+    for entry in requires.get("features_optional") or []:
+        name = re.split(r"[<>=!~\s]", str(entry), maxsplit=1)[0]
+        if name:
+            names.add(
+                name if name.startswith("splent_feature_") else f"splent_feature_{name}"
+            )
+    return names
+
+
 # ---------------------------------------------------------------------------
 # Feature path resolver
 # ---------------------------------------------------------------------------
@@ -271,6 +299,7 @@ def check_deps():
 
         py_imports, tpl_deps = _scan_feature_imports(fpath, pkg_name, all_packages)
         allowed = allowed_deps.get(pkg_name, set())
+        optional = _optional_features(fpath)
         all_deps = py_imports | tpl_deps
 
         if not all_deps:
@@ -296,6 +325,17 @@ def check_deps():
                     )
                 )
                 ok += 1
+            elif imp in optional:
+                click.echo(
+                    click.style("  [✔] ", fg="green")
+                    + click.style(f"{short}", bold=True)
+                    + f" {source} {imp_short}"
+                    + click.style(
+                        f"  (optional: {short}'s contract lists it in features_optional)",
+                        fg="bright_black",
+                    )
+                )
+                ok += 1
             else:
                 reverse_allowed = allowed_deps.get(imp, set())
                 if pkg_name in reverse_allowed:

{splent_cli-1.47.0 → splent_cli-1.48.1}/src/splent_cli/commands/feature/feature_release.py

@@ -237,6 +237,68 @@ def _extract_templates(src_dir: Path) -> list[str]:
 
 
 _SLOT_CALL = re.compile(r"""(?:get|render)_template_hooks\s*\(\s*['"]([^'"]+)['"]""")
+_SLOT_FUNCTIONS = ("get_template_hooks", "render_template_hooks")
+_MACRO = re.compile(
+    r"\{%-?\s*macro\s+(\w+)\s*\(\s*(\w+)(.*?)\{%-?\s*endmacro", re.DOTALL
+)
+
+
+def _python_slot_helpers(source: str) -> set[str]:
+    """The functions of SOURCE that open the slot their first argument
+    names: they hand it to get_template_hooks or render_template_hooks."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set()
+    helpers = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        params = [arg.arg for arg in node.args.posonlyargs + node.args.args]
+        if params[:1] in (["self"], ["cls"]):
+            params = params[1:]
+        if not params:
+            continue
+        for call in ast.walk(node):
+            if not isinstance(call, ast.Call) or not call.args:
+                continue
+            called = call.func
+            if isinstance(called, ast.Attribute):
+                name = called.attr
+            elif isinstance(called, ast.Name):
+                name = called.id
+            else:
+                name = None
+            first = call.args[0]
+            if (
+                name in _SLOT_FUNCTIONS
+                and isinstance(first, ast.Name)
+                and first.id == params[0]
+            ):
+                helpers.add(node.name)
+                break
+    return helpers
+
+
+def _template_slot_helpers(source: str) -> set[str]:
+    """The macros of SOURCE that open the slot their first argument names."""
+    helpers = set()
+    for name, param, body in _MACRO.findall(source):
+        opens = re.compile(
+            r"(?:get|render)_template_hooks\s*\(\s*" + re.escape(param) + r"\s*[,)]"
+        )
+        if opens.search(body):
+            helpers.add(name)
+    return helpers
+
+
+def _helper_calls(helpers: set[str]) -> re.Pattern | None:
+    """A call of one of HELPERS with a slot name as its first argument, as
+    a template writes it: ``hub.slot_of("x.y", …)`` or ``slot_of('x.y')``."""
+    if not helpers:
+        return None
+    names = "|".join(re.escape(name) for name in sorted(helpers))
+    return re.compile(r"""\b(?:""" + names + r""")\s*\(\s*['"]([^'"]+)['"]""")
 
 
 def _extract_template_hook_slots(src_dir: Path) -> list[str]:
@@ -250,19 +312,38 @@ def _extract_template_hook_slots(src_dir: Path) -> list[str]:
     that slot is as much the feature's: a scan of the templates alone left
     it out of ``extensible.hooks``. Tests are not the feature's code, and a
     layout.* slot the code reads is the product's.
+
+    A helper may also take the slot's name from its caller: a function of
+    the feature's Python, or a macro of its templates, that hands its first
+    argument to one of the two. Then the slot is the literal a template
+    (or the code) passes it, ``shell.slot_of("layout.sidebar", …)``.
     """
     if not src_dir.exists():
         return []
     slots: set[str] = set()
     templates_dir = src_dir / "templates"
+    templates = {}
     if templates_dir.exists():
         for html_file in templates_dir.rglob("*.html"):
-            slots.update(_SLOT_CALL.findall(html_file.read_text()))
+            templates[html_file] = html_file.read_text()
+    sources = {}
     for py_file in _feature_sources(src_dir):
         try:
-            found = _SLOT_CALL.findall(py_file.read_text())
+            sources[py_file] = py_file.read_text()
         except (OSError, UnicodeDecodeError):
             continue
+    helpers = set()
+    for text in sources.values():
+        helpers |= _python_slot_helpers(text)
+    for text in templates.values():
+        helpers |= _template_slot_helpers(text)
+    calls = _helper_calls(helpers)
+    for text in templates.values():
+        slots.update(_SLOT_CALL.findall(text))
+        if calls:
+            slots.update(calls.findall(text))
+    for text in sources.values():
+        found = _SLOT_CALL.findall(text) + (calls.findall(text) if calls else [])
         slots.update(s for s in found if not s.startswith(_PRODUCT_SLOT_PREFIX))
     return sorted(slots)
 

{splent_cli-1.47.0 → splent_cli-1.48.1}/src/splent_cli/commands/product/product_validate.py

@@ -19,8 +19,9 @@ product:validate checks a product in seven phases.
   7. Frontend (bundles). Does the shell provide, at a version in range,
      what each feature with frontend/ takes from the page? Does each bundle
      match its manifest, ship what its licence allows and no singleton
-     another one ships? What legacy features use, and what anything loads
-     from other origins, is said (splent_cli.utils.frontend_check).
+     another one ships, and load nothing from another origin? Does the
+     product approve what each one asks to add to the CSP? What legacy
+     features use and load is said (splent_cli.utils.frontend_check).
 """
 
 import os
@@ -206,6 +207,7 @@ def _run_deps_check(workspace, product, data=None, uvl_path=None):
     a model to check against instead (--model).
     """
     from splent_cli.commands.check.check_deps import (
+        _optional_features,
         _parse_uvl_deps,
         _resolve_feature_paths,
         _scan_feature_imports,
@@ -258,6 +260,8 @@ def _run_deps_check(workspace, product, data=None, uvl_path=None):
 
         py_imports, tpl_deps = _scan_feature_imports(fpath, pkg_name, all_packages)
         allowed = allowed_deps.get(pkg_name, set())
+        # What the feature reaches only when the product has it.
+        optional = _optional_features(fpath)
         all_deps = py_imports | tpl_deps
 
         if not all_deps:
@@ -266,7 +270,7 @@ def _run_deps_check(workspace, product, data=None, uvl_path=None):
 
         for imp in sorted(all_deps):
             imp_short = pkg_to_short.get(imp, imp)
-            if imp in allowed:
+            if imp in allowed or imp in optional:
                 ok_count += 1
             else:
                 reverse_allowed = allowed_deps.get(imp, set())
@@ -610,7 +614,8 @@ def _run_frontend_check(workspace, product_dir, data, env=None):
     from splent_cli.utils.frontend_check import check_product
 
     entries = read_features_from_data(data, env or os.getenv("SPLENT_ENV", "dev"))
-    return check_product(workspace, product_dir, entries)
+    approvals = ((data.get("tool") or {}).get("splent") or {}).get("csp")
+    return check_product(workspace, product_dir, entries, csp_approvals=approvals)
 
 
 def _report_frontend(check) -> bool:
@@ -619,10 +624,12 @@ def _report_frontend(check) -> bool:
     What the shell provides comes first, and where it was read. A peer or
     capability nothing provides, or at a version out of its range, a
     singleton two bundles ship, a licence the feature cannot ship, a
-    release whose bundle is not the one it built and a global a template
-    takes without declaring it are errors. A legacy feature, a working copy
-    built before its sources changed and anything loaded from another
-    origin are warnings.
+    release whose bundle is not the one it built, a global a template
+    takes without declaring it, a feature with frontend/ that loads from
+    another origin and a CSP source the policy never takes are errors. A
+    legacy feature, a working copy built before its sources changed, what
+    a legacy feature or the product loads from another origin and a CSP
+    request the product does not approve are warnings.
     """
     from splent_cli.utils.frontend_check import FRONTEND
 

{splent_cli-1.47.0 → splent_cli-1.48.1}/src/splent_cli/services/frontend.py

@@ -12,8 +12,11 @@ legacy: its ``assets/js/webpack.config.js`` builds against the product's
 node_modules in the product's web container, exactly as before, until CLI
 2.0.
 
-A build writes ``assets/dist`` and ``assets/meta/manifest.json``, the files
-it wrote and the packages it put in them. A production build adds
+A build lints the feature's own code first, with eslint's ``no-undef``
+against the globals of the page it declares (toolchain/frontend/splent/
+lint.js), and fails on a name it never declared. It writes ``assets/dist``
+and ``assets/meta/manifest.json``, the files it wrote, the packages it put
+in them and the page globals its code reads. A production build adds
 ``assets/meta/third_party.json``, their licence texts, and a release
 (:func:`release_build`) adds ``assets/meta/sbom.cdx.json`` and gates on
 the licences (utils/frontend_licenses.py) and on ``npm audit``.
@@ -31,9 +34,12 @@ import datetime
 import hashlib
 import json
 import os
+import re
 import shutil
 import socket
 import subprocess
+import sys
+import tempfile
 import uuid
 from pathlib import Path
 
@@ -408,14 +414,20 @@ def npm(
 
 
 def install(feature_root, *, image=None, force=False, echo=click.echo) -> None:
-    """Install frontend/node_modules from the lock, unless it already is.
+    """Install what the build takes from the network: frontend/node_modules
+    from the lock, and the files splent.vendored fetches
+    (:func:`fetch_vendored`), each unless it already is. FORCE installs
+    anyway, as a release does."""
+    _install_node_modules(feature_root, image=image, force=force, echo=echo)
+    fetch_vendored(feature_root, force=force, echo=echo)
 
-    ``npm ci --omit=peer --ignore-scripts``: exactly the lock, no peer (the
+
+def _install_node_modules(feature_root, *, image, force, echo) -> None:
+    """``npm ci --omit=peer --ignore-scripts``: exactly the lock, no peer (the
     shell provides those, so a peer the bundle forgot to declare fails as
     "Module not found" instead of shipping a second copy) and no install
     script. The sha256 of the lock it installed is sealed into node_modules,
-    so the next build installs only when the lock changed. FORCE installs
-    anyway, as a release does.
+    so the next build installs only when the lock changed.
     """
     frontend = Path(feature_root) / FRONTEND_DIR
     lock = frontend / LOCK
@@ -452,6 +464,136 @@ def install(feature_root, *, image=None, force=False, echo=click.echo) -> None:
     _give_back(seal)
 
 
+# ── Vendored files ────────────────────────────────────────────────────
+
+# What a feature serves that is not npm's (the Python wheels an in-browser
+# runtime installs), as splent.vendored declares it: {name, version,
+# license, source, path, sha256}, ``path`` being where it is served, below
+# assets/. One served from assets/dist is copied there by the build, from
+# the feature's repository when it names ``from`` (a file of frontend/,
+# such as a wheel the feature builds itself), or else from what this step
+# fetched into frontend/vendored/, which no repository keeps.
+VENDORED_DIR = "vendored"
+
+# name-version(-build)?-python-abi-platform.whl
+_WHEEL = re.compile(
+    r"^(?P<name>[^-]+)-(?P<version>[^-]+)(?:-\d[^-]*)?"
+    r"-(?P<python>[^-]+)-(?P<abi>[^-]+)-(?P<platform>[^-]+)\.whl$"
+)
+
+
+def vendored(pkg: dict) -> list[dict]:
+    """splent.vendored of PKG, the entries it declares as dicts."""
+    entries = (pkg.get("splent") or {}).get("vendored") or []
+    return [entry for entry in entries if isinstance(entry, dict)]
+
+
+def _pip_download_args(entry: dict, filename: str, dest: Path) -> list[str]:
+    """``pip download`` of exactly FILENAME: a wheel, from PyPI when the
+    entry's source is ``pypi``, or from its https URL, for the platform its
+    tags name (``any`` for a pure one, ``pyodide_2024_0_wasm32`` for one
+    built for Pyodide)."""
+    name = entry.get("name") or "?"
+    tags = _WHEEL.match(filename)
+    if tags is None:
+        raise FrontendError(
+            f"splent.vendored {name}: {filename} is no wheel, and only wheels are "
+            "fetched. Keep the file in frontend/ and name it in from."
+        )
+    source = str(entry.get("source") or "pypi")
+    if source == "pypi":
+        requirement = f"{entry.get('name')}=={entry.get('version')}"
+    elif source.startswith("https://"):
+        requirement = source
+    else:
+        raise FrontendError(
+            f"splent.vendored {name}: source is pypi or the https URL of the "
+            f"wheel, not {source!r}; a file the feature keeps names it in from."
+        )
+    args = [
+        sys.executable,
+        "-m",
+        "pip",
+        "download",
+        "--no-deps",
+        "--quiet",
+        "--disable-pip-version-check",
+        "--only-binary",
+        ":all:",
+        "--dest",
+        str(dest),
+        "--platform",
+        tags["platform"],
+    ]
+    python = tags["python"].split(".")[0]
+    if python.startswith("cp") and python[2:].isdigit():
+        version = f"{python[2]}.{python[3:]}"
+        args += ["--implementation", "cp", "--python-version", version]
+        args += ["--abi", tags["abi"].split(".")[0]]
+    return [*args, requirement]
+
+
+def fetch_vendored(feature_root, *, force=False, echo=click.echo) -> None:
+    """Fetch the wheels splent.vendored serves from assets/dist into
+    frontend/vendored/, with ``pip download``, and check each against the
+    sha256 the entry declares; and check the files the feature keeps for
+    it (``from``). A file already there with its sha256 is not fetched
+    again, unless FORCE, as a release does."""
+    if not declares(feature_root):
+        return
+    entries = vendored(package(feature_root))
+    frontend = Path(feature_root) / FRONTEND_DIR
+    target = frontend / VENDORED_DIR
+    for entry in entries:
+        name = entry.get("name") or "?"
+        expected = entry.get("sha256")
+        if not str(entry.get("path") or "").startswith("dist/"):
+            continue
+        if not expected:
+            raise FrontendError(f"splent.vendored {name} needs a sha256")
+        if entry.get("from"):
+            kept = (frontend / str(entry["from"])).resolve()
+            if not kept.is_relative_to(frontend.resolve()) or not kept.is_file():
+                raise FrontendError(
+                    f"splent.vendored {name}: from names {entry['from']}, which is "
+                    "not a file in frontend/"
+                )
+            if _sha256(kept) != expected:
+                raise FrontendError(
+                    f"splent.vendored {name}: frontend/{entry['from']} is not the "
+                    "file its sha256 names"
+                )
+            continue
+        filename = Path(str(entry["path"])).name
+        path = target / filename
+        if not force and path.is_file() and _sha256(path) == expected:
+            continue
+        echo(f"  pip      fetching {filename} (splent.vendored)...")
+        target.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory(dir=target) as scratch:
+            args = _pip_download_args(entry, filename, Path(scratch))
+            result = subprocess.run(
+                args, capture_output=True, text=True, timeout=INSTALL_TIMEOUT
+            )
+            got = Path(scratch) / filename
+            if result.returncode != 0 or not got.is_file():
+                said = _head(result.stderr or result.stdout, 4) or "     (no output)"
+                found = ", ".join(sorted(p.name for p in Path(scratch).iterdir()))
+                raise FrontendError(
+                    f"pip download did not fetch {filename}"
+                    + (f" (it fetched {found})" if found else "")
+                    + f":\n{said}"
+                )
+            if _sha256(got) != expected:
+                raise FrontendError(
+                    f"splent.vendored {name}: the {filename} pip fetched has another "
+                    "sha256 than the one the entry declares"
+                )
+            got.replace(path)
+        _give_back(target)
+        _give_back(path)
+
+
 def _give_back(path: Path) -> None:
     """A file this process wrote as root goes to the workspace's owner."""
     if os.geteuid() != 0:

{splent_cli-1.47.0 → splent_cli-1.48.1}/src/splent_cli/templates/feature/feature_.gitignore.j2

@@ -26,6 +26,9 @@ app.log.*
 /dist/
 src/*/*/assets/dist/
 src/*/*/assets/meta/
+# The wheels splent.vendored names, which feature:compile and the release
+# fetch into frontend/vendored/ and check against their sha256.
+frontend/vendored/
 {% else %}# Build artifacts: the package build's, at the root, and the bundles and
 # source maps webpack writes to assets/dist. Only those: the dist/ of a
 # vendored npm package is its source here, webpack resolves the package

{splent_cli-1.47.0 → splent_cli-1.48.1}/src/splent_cli/toolchain/Dockerfile.frontend

@@ -2,7 +2,9 @@
 #
 # A feature declares its JavaScript dependencies in frontend/package.json,
 # and this image brings everything else: Node, npm, webpack, the loaders and
-# plugins, the SPLENT preset and the registry of singletons. webpack is no
+# plugins, eslint (every build lints the feature's own code for globals of
+# the page it never declared), the SPLENT preset and the registry of
+# singletons. webpack is no
 # devDependency of any feature, so a feature's node_modules holds what its
 # bundle ships and nothing more, and every feature builds with the same
 # toolchain, the way a Python package builds in an isolated [build-system].