splent-cli 1.35.0__tar.gz → 1.36.0__tar.gz

{splent_cli-1.35.0/src/splent_cli.egg-info → splent_cli-1.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.35.0
+Version: 1.36.0
 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.35.0 → splent_cli-1.36.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.35.0"
+version = "1.36.0"
 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.35.0 → splent_cli-1.36.0}/src/splent_cli/commands/check/check_contracts.py

@@ -18,6 +18,7 @@ import tomllib
 
 from splent_cli.services import context, marketplace, spl_store
 from splent_cli.utils import forge
+from splent_cli.utils.feature_requirements import requirement_names
 
 
 def _snapshot_version_key(pyproject_path: Path) -> tuple:
@@ -58,9 +59,10 @@ def _local_contract_requires(workspace: str, package: str) -> list[str] | None:
             .get("contract", {})
             .get("requires", {})
         )
+        # Names only: an entry may carry a version specifier ("auth>=1.20.0").
         return {
-            "features": requires.get("features", []),
-            "optional": requires.get("features_optional", []),
+            "features": requirement_names(requires.get("features", [])),
+            "optional": requirement_names(requires.get("features_optional", [])),
         }
     return None
 

{splent_cli-1.35.0 → splent_cli-1.36.0}/src/splent_cli/commands/export/export_puml.py

@@ -22,6 +22,7 @@ import click
 from splent_cli.commands.uvl.uvl_utils import extract_implications_from_uvl_text
 from splent_cli.services import context
 from splent_cli.utils import proc
+from splent_cli.utils.feature_requirements import requirement_names
 from splent_cli.utils.feature_utils import normalize_namespace
 from splent_framework.utils.pyproject_reader import PyprojectReader
 
@@ -381,7 +382,9 @@ def _generate_feature_puml(product_name: str, uvl_data: dict, contracts: dict) -
             env_vars = requires.get("env_vars", [])
             if env_vars:
                 details.append(f"**Env vars**: {_puml_join(env_vars)}")
-            req_features = requires.get("features", [])
+            # Names only: an entry may carry a version specifier
+            # ("auth>=1.20.0"), which the diagram has no use for.
+            req_features = requirement_names(requires.get("features", []))
             if req_features:
                 details.append(f"**Requires**: {_puml_join(req_features)}")
 

{splent_cli-1.35.0 → splent_cli-1.36.0}/src/splent_cli/commands/feature/feature_add.py

@@ -16,6 +16,7 @@ from splent_cli.utils.feature_utils import (
 from splent_cli.utils.io_utils import load_toml
 from splent_cli.utils.toml_edit import write_toml
 from splent_cli.utils.manifest import feature_key, remove_feature, set_feature_state
+from splent_cli.utils.ci_workflow import keeps_ci_workflows
 
 
 @click.command(
@@ -35,6 +36,7 @@ from splent_cli.utils.manifest import feature_key, remove_feature, set_feature_s
     flag_value="prod",
     help="Add to features_prod (production only).",
 )
+@keeps_ci_workflows
 def feature_add(full_name, env_scope):
     """
     Adds a local feature (no version, no repo) to the current SPLENT product.

{splent_cli-1.35.0 → splent_cli-1.36.0}/src/splent_cli/commands/feature/feature_attach.py

@@ -17,6 +17,7 @@ from splent_cli.utils.feature_utils import (
 from splent_cli.utils.io_utils import load_toml
 from splent_cli.utils.toml_edit import write_toml
 from splent_cli.utils.manifest import feature_key, remove_feature, set_feature_state
+from splent_cli.utils.ci_workflow import keeps_ci_workflows
 
 
 def _target_lists(env_scope, declared):
@@ -50,6 +51,7 @@ def _target_lists(env_scope, declared):
     flag_value="prod",
     help="Add to features_prod (production only).",
 )
+@keeps_ci_workflows
 def feature_attach(feature_identifier, version, env_scope):
     """
     Attach a cached feature version to the current product.

{splent_cli-1.35.0 → splent_cli-1.36.0}/src/splent_cli/commands/feature/feature_compat.py

@@ -11,6 +11,11 @@ import click
 from pathlib import Path
 
 from splent_cli.services import context
+from splent_cli.utils.feature_requirements import (
+    parse_requirement,
+    requirement_names,
+    satisfies,
+)
 from splent_cli.utils.feature_utils import normalize_namespace
 from splent_cli.utils.io_utils import load_toml
 
@@ -118,7 +123,9 @@ def _read_contract(cache_path: Path) -> dict:
             "docker": raw.get("provides", {}).get("docker", []),
         },
         "requires": {
-            "features": raw.get("requires", {}).get("features", []),
+            # Names only: an entry may carry a version specifier
+            # ("auth>=1.20.0"), which version_floor_findings reads.
+            "features": requirement_names(raw.get("requires", {}).get("features", [])),
             "env_vars": raw.get("requires", {}).get("env_vars", []),
         },
     }
@@ -266,8 +273,16 @@ def _resolve_all_product_features(
     if not features_raw:
         raise SystemExit("  No features declared in pyproject.toml.")
 
+    return _resolve_entries(features_raw, product_dir, workspace)
+
+
+def _resolve_entries(
+    entries: list[str], product_dir: str, workspace: str
+) -> list[tuple[str, Path]]:
+    """Feature entries of the product as ``(label, path)``, skipping, with a
+    warning, those that are not in the workspace."""
     resolved = []
-    for entry in features_raw:
+    for entry in entries:
         ns, name, version = _parse_pyproject_entry(entry)
         label = f"{name}@{version}" if version else name
         if version:
@@ -546,16 +561,173 @@ def naming_findings(workspace: str, product_dir: str) -> list[dict]:
     return findings
 
 
-def run_all_product_check(workspace: str, product_dir: str) -> list[dict]:
-    """Run the full product compatibility check. Returns findings list."""
+def _written_requires(path: Path) -> dict[str, list]:
+    """The requires lists of a feature's contract, entries as written."""
+    pyproject = path / "pyproject.toml"
+    if not pyproject.exists():
+        return {}
+    data = load_toml(pyproject, what=f"pyproject.toml for {path.name}")
+    requires = (
+        data.get("tool", {}).get("splent", {}).get("contract", {}).get("requires", {})
+    )
+    if not isinstance(requires, dict):
+        return {}
+    return {
+        key: requires.get(key)
+        for key in ("features", "features_manual", "features_optional")
+        if isinstance(requires.get(key), list)
+    }
+
+
+def _project_version(path: Path) -> str | None:
+    pyproject = path / "pyproject.toml"
+    if not pyproject.exists():
+        return None
+    data = load_toml(pyproject, what=f"pyproject.toml for {path.name}")
+    version = data.get("project", {}).get("version")
+    return str(version) if version else None
+
+
+def version_floor_findings(labeled_paths: list[tuple[str, Path]]) -> list[dict]:
+    """Requirements whose version specifier the product's copy does not meet.
+
+    A requires entry may say which releases of another feature it works with
+    (``auth>=1.20.0``), because it calls an API that release added. Against
+    a version the product pins, a miss is an error: the product would run a
+    release the feature was never written for. Against an editable feature
+    it is a warning, read from the working copy's ``[project].version``,
+    since that copy is not released yet. A specifier that is not PEP 440 is
+    an error, and a feature the product lacks is reported elsewhere.
+    """
+    present: dict[str, tuple[str, Path, str | None]] = {}
+    for label, path in labeled_paths:
+        name, _, version = label.partition("@")
+        present[name.removeprefix("splent_feature_")] = (label, path, version or None)
+
+    findings: list[dict] = []
+    for label, path in labeled_paths:
+        short = label.split("@", 1)[0].removeprefix("splent_feature_")
+        seen: set[tuple[str, str]] = set()
+        for key, entries in _written_requires(path).items():
+            for entry in entries:
+                try:
+                    req = parse_requirement(entry)
+                except ValueError as e:
+                    findings.append(
+                        {
+                            "severity": "error",
+                            "field": "requires",
+                            "values": [str(entry)],
+                            "features": [label],
+                            "message": f"In {short}'s requires.{key}, {e}.",
+                        }
+                    )
+                    continue
+                if not req.specifier or (req.name, req.specifier) in seen:
+                    continue
+                seen.add((req.name, req.specifier))
+                target = present.get(req.name)
+                if target is None:
+                    continue
+                target_label, target_path, pinned = target
+                if pinned:
+                    met = satisfies(req.specifier, pinned)
+                    if met is None:
+                        findings.append(
+                            {
+                                "severity": "warning",
+                                "field": "requires",
+                                "values": [str(req)],
+                                "features": [label, target_label],
+                                "message": (
+                                    f"{short} requires {req}, and the product pins "
+                                    f"{req.name} at {pinned}, which is not a "
+                                    "version that can be compared."
+                                ),
+                            }
+                        )
+                    elif not met:
+                        findings.append(
+                            {
+                                "severity": "error",
+                                "field": "requires",
+                                "values": [str(req)],
+                                "features": [label, target_label],
+                                "message": (
+                                    f"{short} requires {req}, but the product pins "
+                                    f"{req.name} at {pinned}. Pin a release of "
+                                    f"{req.name} that satisfies it."
+                                ),
+                            }
+                        )
+                    continue
+                working = _project_version(target_path)
+                met = satisfies(req.specifier, working) if working else None
+                if met is False or met is None:
+                    found = (
+                        f"the working copy of {req.name} is {working}"
+                        if working
+                        else f"the version of the working copy of {req.name} "
+                        "cannot be read"
+                    )
+                    findings.append(
+                        {
+                            "severity": "warning",
+                            "field": "requires",
+                            "values": [str(req)],
+                            "features": [label, target_label],
+                            "message": (
+                                f"{short} requires {req}, and {found} "
+                                f"([project].version). Release {req.name} at a "
+                                "version that satisfies it before the product "
+                                "pins it."
+                            ),
+                        }
+                    )
+    return findings
+
+
+def _environment_only_features(
+    product_dir: str, workspace: str, env: str | None
+) -> list[tuple[str, Path]]:
+    """The features ``features_<env>`` adds to the base list, resolved."""
+    from splent_framework.utils.pyproject_reader import PyprojectReader
+
+    env = context.normalize_env(env)
+    if not env:
+        return []
+    try:
+        reader = PyprojectReader.for_product(product_dir)
+        base = set(reader.features)
+        extra = [e for e in reader.features_for_env(env) if e not in base]
+    except (FileNotFoundError, ValueError):
+        return []
+    return _resolve_entries(extra, product_dir, workspace)
+
+
+def run_all_product_check(
+    workspace: str, product_dir: str, env: str | None = None
+) -> list[dict]:
+    """Run the full product compatibility check. Returns findings list.
+
+    The collisions are checked between the base features. The version
+    floors are checked across the features the product loads in ``env``
+    (SPLENT_ENV when None, ``dev`` when that is unset too), base plus
+    ``features_dev`` or ``features_prod``, the selection phase 1 checks.
+    """
     try:
         labeled_paths = _resolve_all_product_features(product_dir, workspace)
     except SystemExit:
         return []
     if not labeled_paths:
         return []
+    if env is None:
+        env = os.getenv("SPLENT_ENV") or "dev"
     labeled_contracts = [(lbl, _read_contract(path)) for lbl, path in labeled_paths]
-    return _analyse_all(labeled_contracts)
+    findings = _analyse_all(labeled_contracts) + version_floor_findings(
+        labeled_paths + _environment_only_features(product_dir, workspace, env)
+    )
+    return sorted(findings, key=lambda f: SEVERITY_ORDER[f["severity"]])
 
 
 # ─────────────────────────────────────────────────────────────────────────────

{splent_cli-1.35.0 → splent_cli-1.36.0}/src/splent_cli/commands/feature/feature_contract.py

@@ -20,7 +20,13 @@ import click
 from pathlib import Path
 
 from splent_cli.services import context
-from splent_cli.commands.feature.feature_release import infer_contract, write_contract
+from splent_cli.commands.feature.feature_release import (
+    infer_contract,
+    merge_preserved,
+    requirement_problems,
+    write_contract,
+)
+from splent_cli.utils.feature_resolution import package_identifier, resolve_feature_ref
 from splent_cli.utils.feature_utils import normalize_namespace
 from splent_cli.utils.contract_freshness import mark_contract_fresh
 from splent_cli.utils.io_utils import load_toml
@@ -51,39 +57,24 @@ def update_contract(feature_path: str, namespace: str, feature_name: str) -> dic
 
 
 def _resolve_feature(feature_ref: str, workspace: str) -> tuple[Path, str, str]:
-    """Resolve a feature: workspace root first, then cache."""
-    if "/" in feature_ref:
-        ns_raw, rest = feature_ref.split("/", 1)
-        ns = normalize_namespace(ns_raw)
-    else:
-        ns = DEFAULT_NAMESPACE
-        rest = feature_ref
-
-    name, _, version = rest.partition("@")
-
-    # 1. Workspace root (editable features)
-    workspace_path = Path(workspace) / name
-    if workspace_path.exists():
-        return workspace_path, ns, name
-
-    # 2. Cache (pinned features)
-    cache_base = Path(workspace) / ".splent_cache" / "features" / ns
-
-    if version:
-        cache_path = cache_base / f"{name}@{version}"
-    else:
-        cache_path = cache_base / name
-        if not cache_path.exists():
-            candidates = sorted(cache_base.glob(f"{name}@*"))
-            if candidates:
-                cache_path = candidates[-1]
-
-    if not cache_path.exists():
+    """Resolve a feature as feature:drift does, see
+    :mod:`splent_cli.utils.feature_resolution`, or exit naming where it was
+    looked for."""
+    found = resolve_feature_ref(feature_ref, Path(workspace))
+    if found is None:
+        identifier = package_identifier(feature_ref)
+        base, at, version = identifier.partition("@")
+        ns_raw, slash, name = base.rpartition("/")
+        ns = normalize_namespace(ns_raw) if slash else DEFAULT_NAMESPACE
+        wanted = f"{name}@{version}" if at else name
         raise SystemExit(
-            f"❌ Feature not found: {cache_path}\n"
+            f"❌ Feature not found: {wanted}\n"
+            f"   Looked for it at the workspace root and in "
+            f".splent_cache/features/{ns}/.\n"
             f"   Run: splent feature:clone {ns.replace('_', '-')}/{name}"
         )
-    return cache_path, ns, name
+    path, ns, name = found
+    return path, ns, name
 
 
 def _in_cache(path: Path, workspace: str) -> bool:
@@ -101,6 +92,15 @@ def _in_cache(path: Path, workspace: str) -> bool:
     return True
 
 
+def _written_contract(pyproject_path: Path) -> dict:
+    """The ``[tool.splent.contract]`` table as written, or empty."""
+    if not pyproject_path.exists():
+        return {}
+    data = load_toml(pyproject_path, what="pyproject.toml")
+    raw = data.get("tool", {}).get("splent", {}).get("contract", {})
+    return raw if isinstance(raw, dict) else {}
+
+
 def _read_current_contract(pyproject_path: Path) -> dict:
     """Read the contract block currently written in pyproject.toml."""
     if not pyproject_path.exists():
@@ -116,6 +116,7 @@ def _read_current_contract(pyproject_path: Path) -> dict:
         "blueprints": raw.get("provides", {}).get("blueprints", []),
         "models": raw.get("provides", {}).get("models", []),
         "commands": raw.get("provides", {}).get("commands", []),
+        "commands_help": raw.get("provides", {}).get("commands_help", {}),
         "hooks": raw.get("provides", {}).get("hooks", []),
         "services": raw.get("provides", {}).get("services", []),
         "signals": raw.get("provides", {}).get("signals", []),
@@ -153,6 +154,44 @@ def _diff_field(label: str, old: list, new: list) -> list[str]:
     return lines
 
 
+def _help_entries(table) -> dict[str, tuple[str, str]]:
+    """``provides.commands_help`` as ``{name: (usage, help)}``."""
+    if not isinstance(table, dict):
+        return {}
+    entries = {}
+    for name, entry in table.items():
+        entry = entry if isinstance(entry, dict) else {}
+        entries[str(name)] = (
+            str(entry.get("usage", "") or ""),
+            str(entry.get("help", "") or ""),
+        )
+    return entries
+
+
+def _diff_commands_help(old_table, new_table) -> list[str]:
+    """What a rewrite changes in ``provides.commands_help``: the usage and
+    the help line of each command, which come from its decorators and its
+    docstring."""
+    old, new = _help_entries(old_table), _help_entries(new_table)
+    label = "provides.commands_help"
+    lines = []
+    for name in sorted(set(old) | set(new)):
+        if name not in old:
+            lines.append(click.style(f"    + {label}: {name}", fg="green"))
+        elif name not in new:
+            lines.append(click.style(f"    - {label}: {name}", fg="red"))
+        else:
+            for field, before, after in zip(("usage", "help"), old[name], new[name]):
+                if before != after:
+                    lines.append(
+                        click.style(
+                            f"    ~ {label}.{name}.{field}: {before!r} → {after!r}",
+                            fg="green",
+                        )
+                    )
+    return lines
+
+
 def _print_contract(contract: dict, feature_name: str) -> None:
     """Pretty-print an inferred contract dict."""
 
@@ -264,6 +303,13 @@ def _print_diff(current: dict, inferred: dict) -> bool:
         diff_lines.extend(
             _diff_field(label, current.get(key, []), inferred.get(key, []))
         )
+    # A changed docstring changes only this table, which --write rewrites
+    # too: compared here, or the contract never got it.
+    diff_lines.extend(
+        _diff_commands_help(
+            current.get("commands_help", {}), inferred.get("commands_help", {})
+        )
+    )
 
     if not diff_lines:
         return False
@@ -304,9 +350,14 @@ def feature_contract(feature_ref, write):
     Use --write to update [tool.splent.contract] in pyproject.toml without
     touching version, git tags, or publishing anything.
 
+    \b
+    FEATURE_REF is a short name (notes), a package name
+    (splent_feature_notes), either one under a namespace (splent-io/notes),
+    or a pinned snapshot (splent-io/notes@v1.2.0).
+
     \b
     Examples:
-      splent feature:contract splent_feature_notes
+      splent feature:contract notes
       splent feature:contract splent_feature_notes --write
       splent feature:contract splent-io/splent_feature_notes --write
     """
@@ -333,33 +384,42 @@ def feature_contract(feature_ref, write):
     click.echo("  🔍 Scanning source code…")
     inferred = infer_contract(str(cache_path), ns, name)
 
-    # Deps declared in requires.features_manual are preserved by
-    # write_contract; merge them here too so the dry-run diff shows exactly
-    # what --write would produce (including real drops of stale inferred deps).
+    # What --write keeps from the written contract (features_manual,
+    # routes_manual, features_optional) is merged here the same way, so the
+    # dry-run diff shows exactly what --write would produce, including real
+    # drops of stale inferred deps.
     current = _read_current_contract(pyproject_path)
-    manual = sorted(set(current.get("requires_features_manual", [])))
-    if manual:
-        inferred["requires_features"] = sorted(
-            set(inferred["requires_features"]) | set(manual)
-        )
-        click.echo(
-            click.style("  Preserving requires.features_manual: ", fg="bright_black")
-            + ", ".join(manual)
-        )
+    scanned_optional = set(inferred.get("requires_features_optional", []))
+    inferred = merge_preserved(inferred, _written_contract(pyproject_path))
+    for label, values in (
+        ("requires.features_manual", inferred["requires_features_manual"]),
+        ("provides.routes_manual", inferred["routes_manual"]),
+        (
+            "requires.features_optional the scan does not find",
+            sorted(set(inferred["requires_features_optional"]) - scanned_optional),
+        ),
+    ):
+        if values:
+            click.echo(
+                click.style(f"  Preserving {label}: ", fg="bright_black")
+                + ", ".join(values)
+            )
 
-    # Routes a feature builds at registration time, from configuration, are
-    # invisible to a source scan: the rule is assembled from app.config, so
-    # there is no literal path to find. A feature that serves its pages
-    # under a word the product chooses would otherwise publish a contract
-    # claiming it serves nothing, or only its admin screens, which is worse
-    # than an empty contract because it reads as complete.
-    manual_routes = sorted(set(current.get("routes_manual", [])))
-    if manual_routes:
-        inferred["routes"] = sorted(set(inferred["routes"]) | set(manual_routes))
+    # A version specifier is written by hand after a name. One that is not
+    # PEP 440 would break every reader of the contract, so it is refused
+    # here, in the dry run too, before anyone publishes it.
+    problems = requirement_problems(inferred)
+    if problems:
+        click.secho(
+            "  ❌ These requirements are not valid, so the contract cannot be written:",
+            fg="red",
+        )
+        for problem in problems:
+            click.secho(f"     {problem}", fg="red")
         click.echo(
-            click.style("  Preserving provides.routes_manual: ", fg="bright_black")
-            + ", ".join(manual_routes)
+            '     Write a short name with an optional PEP 440 specifier, such as "auth>=1.20.0".'
         )
+        raise SystemExit(1)
 
     # Show inferred contract
     click.echo(click.style("  Inferred contract:", bold=True))