quoll-cli 0.2.0__py3-none-any.whl

quoll/cd/__init__.py

@@ -0,0 +1 @@
+"""Continuous delivery: build the Docker image, scan it, push it to a registry."""

quoll/cd/config.py

@@ -0,0 +1,75 @@
+"""The [cd] section of quoll.toml — the single source of truth for the generated delivery workflow."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+from pydantic import Field, model_validator
+
+from quoll.config.quoll_toml import CONFIG_FILE, ConfigError, PlatformField, Section, load_section, save_section
+from quoll.platforms import get as get_platform
+
+__all__ = ["CONFIG_FILE", "CDConfig", "ConfigError", "load_config", "save_config"]
+
+SEVERITIES = ("UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL")
+
+
+class CDConfig(Section, PlatformField):
+    shared_fields = ("platform",)
+
+    # The platform's own registry, authenticated with the pipeline's token (no secret to set):
+    #   ghcr (GitHub Container Registry) on GitHub, gitlab (the project's container registry) on GitLab.
+    # dockerhub: Docker Hub, with the DOCKERHUB_USERNAME and DOCKERHUB_TOKEN secrets / CI/CD variables.
+    registry: str = ""
+    # Full image name, e.g. "ghcr.io/acme/api", "registry.gitlab.com/acme/api" or "acme/api" on Docker Hub.
+    image: str
+    # Every push to these branches publishes :<branch>, :sha-<sha> and :latest for the default branch.
+    branches: List[str] = Field(default_factory=lambda: ["main"])
+    # Git tags v1.2.3 publish :1.2.3 and :1.2.
+    release_tags: bool = True
+    platforms: List[str] = Field(default_factory=lambda: ["linux/amd64"])
+    # Trivy scans the image before it is pushed; findings of these severities block the push.
+    scan: bool = True
+    severity: List[str] = Field(default_factory=lambda: ["CRITICAL", "HIGH"])
+    # Only block on vulnerabilities that have a fix available.
+    ignore_unfixed: bool = True
+    # SBOM (CycloneDX) of the published image: a pipeline artifact, attached to the v* releases.
+    sbom: bool = True
+    # Sign the image and its SBOM with Sigstore: GitHub artifact attestations (public repositories, or GitHub
+    # Enterprise Cloud for private ones) / cosign keyless on gitlab.com. Verify with `gh attestation verify` / `cosign
+    # verify`.
+    sign: bool = True
+
+    @model_validator(mode="after")
+    def _check(self) -> "CDConfig":
+        registries = get_platform(self.platform).registries
+        if not self.registry:
+            self.registry = registries[0]
+        if self.registry not in registries:
+            raise ValueError(
+                f"unknown registry '{self.registry}' for {self.platform} (expected one of: {', '.join(registries)})"
+            )
+        if self.registry == "ghcr" and not self.image.startswith("ghcr.io/"):
+            raise ValueError("image must start with ghcr.io/ when registry is ghcr")
+        if self.registry == "gitlab" and "/" not in self.image.split("/", 1)[-1]:
+            raise ValueError("image must include the registry host, e.g. registry.gitlab.com/group/project")
+        if self.image != self.image.lower():
+            raise ValueError("image names must be lowercase")
+        unknown = [s for s in self.severity if s not in SEVERITIES]
+        if unknown:
+            raise ValueError(f"unknown severity '{unknown[0]}' (expected some of: {', '.join(SEVERITIES)})")
+        if self.scan and not self.severity:
+            raise ValueError("severity must list at least one level when scan is true")
+        if not self.branches and not self.release_tags:
+            raise ValueError("nothing would publish the image: set branches or release_tags")
+        if not self.platforms:
+            raise ValueError("platforms must contain at least one platform")
+        return self
+
+
+def load_config(project_dir: Path) -> CDConfig:
+    return load_section(project_dir, "cd", CDConfig)
+
+
+def save_config(project_dir: Path, config: CDConfig) -> Path:
+    return save_section(project_dir, "cd", config)

quoll/ci/config.py

@@ -0,0 +1,213 @@
+"""The [ci] section of quoll.toml — the single source of truth for the generated workflow."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List
+
+from pydantic import ConfigDict, Field, field_validator, model_validator
+
+from quoll.config.quoll_toml import CONFIG_FILE, ConfigError, ProjectConfig, Section, load_section, save_section
+
+__all__ = ["CONFIG_FILE", "CIConfig", "ConfigError", "load_config", "save_config"]
+
+
+SEVERITIES = ("UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL")
+
+
+class LintConfig(Section):
+    enabled: bool = True
+    tools: List[str] = Field(default_factory=list)
+
+
+class TestConfig(Section):
+    __test__ = False  # not a pytest test class
+
+    enabled: bool = True
+    runner: str = ""
+    coverage: bool = True
+    coverage_threshold: int = Field(default=80, ge=0, le=100)
+    codecov: bool = False
+    # Test results (JUnit) and coverage (Cobertura) shown in pull/merge requests, where the runner produces them.
+    reports: bool = True
+    # Run the tests with AddressSanitizer and UndefinedBehaviorSanitizer (C/C++).
+    sanitizers: bool = False
+    env_secrets: List[str] = Field(default_factory=list)
+
+
+class SecurityConfig(Section):
+    # Known vulnerabilities in the dependencies.
+    audit: bool = True
+    # Credentials committed anywhere in the git history (gitleaks).
+    secrets: bool = True
+    # Static analysis of the code for bugs and vulnerabilities (Semgrep), every language.
+    sast: bool = True
+    # GitHub CodeQL; results in the Security tab (needs GitHub Advanced Security on private repositories).
+    codeql: bool = False
+    # Software bill of materials of the dependencies (CycloneDX), kept as a pipeline artifact.
+    sbom: bool = True
+    # Fail on dependencies whose license falls in these Trivy categories: CRITICAL = forbidden (AGPL, SSPL...),
+    # HIGH = restricted (GPL, LGPL), MEDIUM = reciprocal (MPL, EPL), LOW = notice (MIT, Apache, BSD).
+    licenses: bool = True
+    license_severity: List[str] = Field(default_factory=lambda: ["CRITICAL"])
+    sonar: bool = False
+    sonar_organization: str = ""
+    sonar_project_key: str = ""
+
+
+class BuildConfig(Section):
+    enabled: bool = False
+    command: str = ""
+    docker: bool = False
+    # The project's Helm chart (directory): linted, checked against Kubernetes' schemas, scanned.
+    chart: str = ""
+    # What the build produces, kept a week (paths or globs in the project, e.g. "dist/", "target/*.jar").
+    artifacts: List[str] = []
+
+
+# Generated jobs custom steps can extend.
+EXTENSIBLE_JOBS = ("lint", "test", "build", "audit", "sbom")
+# Jobs the scheduled pipeline runs: new vulnerabilities appear without any code change.
+SECURITY_JOBS = ("audit", "secrets", "sast", "codeql", "sbom", "docker")
+
+
+class CustomStep(Section):
+    """A step added to one of the generated jobs. For anything bigger, write plain CI next to quoll's: GitHub
+    workflows using the quoll-setup action, GitLab jobs in .gitlab/custom-ci.yml."""
+
+    job: str
+    # before: once the dependencies are installed, before the job's own commands; after: at the end.
+    when: str = "before"
+    name: str
+    # A shell command...
+    run: str = ""
+    # ...or a GitHub Action (GitHub only), with its inputs.
+    uses: str = ""
+    with_: Dict[str, Any] = Field(default_factory=dict, alias="with")
+    env: Dict[str, str] = Field(default_factory=dict)
+    # CI secrets / variables the step reads.
+    secrets: List[str] = Field(default_factory=list)
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True, serialize_by_alias=True)
+
+    @model_validator(mode="after")
+    def _check(self) -> "CustomStep":
+        if self.job not in EXTENSIBLE_JOBS:
+            raise ValueError(f"unknown job '{self.job}' (expected one of: {', '.join(EXTENSIBLE_JOBS)})")
+        if self.when not in ("before", "after"):
+            raise ValueError(f"when must be 'before' or 'after', not '{self.when}'")
+        if bool(self.run) == bool(self.uses):
+            raise ValueError(f"step '{self.name}' needs either run or uses")
+        if self.with_ and not self.uses:
+            raise ValueError(f"step '{self.name}': with only goes with uses")
+        return self
+
+
+class ScheduleConfig(Section):
+    # Re-run the security jobs on a schedule (GitHub: in the workflow; GitLab: a pipeline schedule).
+    enabled: bool = True
+    # Cron expression, UTC. Default: Mondays at 06:00.
+    cron: str = "0 6 * * 1"
+
+    @field_validator("cron")
+    @classmethod
+    def _five_fields(cls, value: str) -> str:
+        if len(value.split()) != 5:
+            raise ValueError(f"cron '{value}' must have 5 fields (minute hour day month weekday)")
+        return value
+
+
+class CIConfig(ProjectConfig):
+    omit_when_empty = ("steps", "build.artifacts", "build.chart")
+
+    # Exact versions to test against. More than one turns the test job into a matrix.
+    versions: List[str] = Field(default_factory=list)
+    # Used when `versions` is empty: let the setup action read .python-version, .nvmrc, go.mod... (GitHub only:
+    # GitLab jobs run in images chosen by version).
+    version_file: str = ""
+    install: str
+    cache: bool = True
+    source_dir: str = "."
+    branches: List[str] = Field(default_factory=lambda: ["main"])
+    # Dependabot on GitHub, Renovate on GitLab. Their config is only created, never overwritten.
+    dependency_updates: bool = True
+    lint: LintConfig = Field(default_factory=LintConfig)
+    test: TestConfig = Field(default_factory=TestConfig)
+    security: SecurityConfig = Field(default_factory=SecurityConfig)
+    build: BuildConfig = Field(default_factory=BuildConfig)
+    schedule: ScheduleConfig = Field(default_factory=ScheduleConfig)
+    # Your own steps in the generated jobs ([[ci.steps]]), kept across `quoll ci update`.
+    steps: List[CustomStep] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check_consistency(self) -> "CIConfig":
+        lang = self.language
+        for tool in self.lint.tools:
+            if not self.is_lint_tool(tool):
+                raise ValueError(
+                    f"unknown lint tool '{tool}' for {self.target} (expected one of: {', '.join(self.lint_tools)})"
+                )
+        if self.test.enabled and not (lang.is_test_runner(self.test.runner) or self.is_framework_runner):
+            raise ValueError(
+                f"unknown test runner '{self.test.runner}' for {self.target} "
+                f"(expected one of: {', '.join(self.test_runners)})"
+            )
+        if self.security.codeql and self.platform != "github":
+            raise ValueError("security.codeql is only available on GitHub (GitLab: security.sast)")
+        if self.security.codeql and not lang.ci.codeql_language:
+            raise ValueError(f"CodeQL does not analyze {lang.name}: use security.sast")
+        unknown = [s for s in self.security.license_severity if s not in SEVERITIES]
+        if unknown:
+            raise ValueError(
+                f"unknown security.license_severity '{unknown[0]}' (expected some of: {', '.join(SEVERITIES)})"
+            )
+        if self.security.licenses and not self.security.license_severity:
+            raise ValueError("security.license_severity must list at least one level when licenses is true")
+        if self.security.sonar and not self.security.sonar_organization:
+            raise ValueError("security.sonar_organization is required when security.sonar is enabled")
+        if self.build.enabled and not self.build.command:
+            raise ValueError("build.command is required when build.enabled is true")
+        if not self.branches:
+            raise ValueError("branches must contain at least one branch")
+        actions = [s.name for s in self.steps if s.uses]
+        if actions and self.platform != "github":
+            raise ValueError(
+                f"step '{actions[0]}' uses a GitHub Action: on GitLab, write it as a job in .gitlab/custom-ci.yml"
+            )
+        if self.platform == "gitlab" and not self.versions:
+            raise ValueError(
+                "versions is required on GitLab: jobs run in images chosen by version "
+                "(version_file only works with GitHub's setup actions)"
+            )
+        return self
+
+    @property
+    def lint_tools(self) -> List[str]:
+        """Lint tools available to this project: the language's, then the framework's."""
+        framework = self.get_framework()
+        return [*self.language.lint_tools, *(framework.lint_tools if framework else ())]
+
+    @property
+    def test_runners(self) -> List[str]:
+        framework = self.get_framework()
+        return [*self.language.test_runners, *(framework.test_runners if framework else ())]
+
+    def is_lint_tool(self, tool: str) -> bool:
+        return self.language.is_lint_tool(tool) or tool in self.lint_tools
+
+    @property
+    def is_framework_runner(self) -> bool:
+        framework = self.get_framework()
+        return framework is not None and self.test.runner in framework.test_runners
+
+    @property
+    def matrix(self) -> bool:
+        return len(self.versions) > 1
+
+
+def load_config(project_dir: Path) -> CIConfig:
+    return load_section(project_dir, "ci", CIConfig)
+
+
+def save_config(project_dir: Path, config: CIConfig) -> Path:
+    """Write [project] and [ci], preserving any other section already in quoll.toml."""
+    return save_section(project_dir, "ci", config)

quoll/ci/custom.py

@@ -0,0 +1,32 @@
+"""The project's own steps from quoll.toml ([[ci.steps]]), merged into the generated jobs."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+from quoll.ci.steps import Item, Step, step
+
+if TYPE_CHECKING:
+    from quoll.ci.config import CIConfig, CustomStep
+
+
+def extend(cfg: CIConfig, job: str, items: List[Item]) -> List[Item]:
+    """`items` of a generated job with the custom steps of `job`: "before" ones right after the dependency
+    installation (the language's `install` steps), "after" ones at the end."""
+    before = [_step(s) for s in cfg.steps if s.job == job and s.when == "before"]
+    after = [_step(s) for s in cfg.steps if s.job == job and s.when == "after"]
+    if not before and not after:
+        return items
+    installed = cfg.language.ci.install(cfg)
+    last = max((i for i, item in enumerate(items) if item in installed), default=-1)
+    return [*items[: last + 1], *before, *items[last + 1 :], *after]
+
+
+def _step(custom: CustomStep) -> Step:
+    return step(
+        custom.name,
+        run=custom.run.strip(),
+        uses=custom.uses,
+        with_=custom.with_,
+        env=custom.env,
+        secrets=custom.secrets,
+    )

quoll/ci/detect.py

@@ -0,0 +1,139 @@
+"""Inspect a project and infer everything the CI needs, so the user only answers real questions.
+
+Toolchain detection is delegated to the language and framework plugins; this module adds what every project shares
+(git, .env.example, Dockerfile).
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Dict
+
+from quoll import languages, platforms
+from quoll.ci.config import CIConfig
+from quoll.config import quoll_toml
+from quoll.languages.base import Detection
+from quoll.project import Project
+
+__all__ = ["Detection", "configured_platform", "default_config", "detect", "parse_env_file"]
+
+
+def detect(project_dir: Path) -> Detection:
+    project = Project(project_dir)
+    found = languages.matching(project)
+    if found:
+        language = found[0]
+        det = language.detect(project)
+        det.stack = language.name
+        for framework in languages.frameworks(language.name):
+            if framework.detect(project, det):
+                det.framework = framework.name
+                break
+        det.other_stacks = [lang.name for lang in found[1:]]
+        if det.other_stacks:
+            det.warnings.insert(
+                0,
+                f"Also found {', '.join(det.other_stacks)} files — quoll configures one stack per repository for now.",
+            )
+    else:
+        det = Detection()
+    det.warnings.extend(project.warnings)
+
+    det.has_dockerfile = project.exists("Dockerfile")
+    try:
+        k8s = quoll_toml.read(project_dir).get("k8s")
+    except quoll_toml.ConfigError:
+        k8s = None
+    det.chart = k8s.get("chart", "chart") if k8s is not None else ""
+    if project.exists(".env.example"):
+        det.env_vars = parse_env_file(project_dir / ".env.example")
+    det.default_branch = default_branch(project_dir)
+    det.remote = platforms.remote(project_dir)
+    det.platform = configured_platform(project_dir) or platforms.detect(project_dir, det.remote)
+    return det
+
+
+def configured_platform(project_dir: Path) -> str:
+    """The platform quoll.toml already names: it wins over the detection."""
+    try:
+        platform = quoll_toml.read(project_dir).get(quoll_toml.PROJECT_SECTION, {}).get("platform", "")
+    except quoll_toml.ConfigError:
+        return ""
+    return platform if platform in platforms.NAMES else ""
+
+
+def default_config(det: Detection) -> CIConfig:
+    if det.stack is None:
+        raise ValueError("cannot build a CI config without a detected stack")
+    # GitLab jobs run in images picked by version: they can't read a version file.
+    version_file = det.version_file if det.platform == "github" else ""
+    language = languages.get(det.stack)
+    artifacts = language.ci.build_artifacts(det) if det.build_command else []
+    return CIConfig.model_validate(
+        {
+            "platform": det.platform,
+            "stack": det.stack,
+            "framework": det.framework,
+            "package_manager": det.package_manager,
+            "package_manager_version": det.package_manager_version,
+            "services": det.services,
+            "versions": [] if version_file else [det.version],
+            "version_file": version_file,
+            "install": det.install,
+            "cache": det.cache,
+            "source_dir": det.source_dir,
+            "branches": [det.default_branch],
+            "lint": {"enabled": bool(det.lint_tools), "tools": det.lint_tools},
+            "test": {
+                "enabled": bool(det.test_runner),
+                "runner": det.test_runner,
+                "coverage": det.coverage,
+                "sanitizers": det.sanitizers,
+            },
+            "security": {"audit": det.audit},
+            "build": {
+                "enabled": bool(det.build_command),
+                "command": det.build_command,
+                "docker": det.has_dockerfile,
+                "chart": det.chart,
+                "artifacts": artifacts,
+            },
+        }
+    )
+
+
+# --------------------------------------------------------------------------- git
+
+
+def _git(project_dir: Path, *args: str) -> str:
+    try:
+        result = subprocess.run(["git", *args], cwd=project_dir, capture_output=True, text=True, timeout=5)
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def default_branch(project_dir: Path) -> str:
+    remote_head = _git(project_dir, "symbolic-ref", "--short", "refs/remotes/origin/HEAD")
+    if remote_head:
+        return remote_head.split("/", 1)[-1]
+    return _git(project_dir, "branch", "--show-current") or "main"
+
+
+# --------------------------------------------------------------------------- helpers
+
+
+def parse_env_file(path: Path) -> Dict[str, str]:
+    """Return {key: value} from a .env-style file. Value is empty when unset."""
+    result: Dict[str, str] = {}
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):]
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if key:
+            result[key] = value.strip().strip("\"'")
+    return result

quoll/ci/steps.py

@@ -0,0 +1,85 @@
+"""Platform-neutral CI steps.
+
+Languages and frameworks describe their jobs with `Step` and `Cache`; each platform (see quoll/platforms) renders
+them. GitHub Actions runs a step's `uses` action when it has one; GitLab CI runs its `run` command in the
+language's container image.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Sequence, Tuple, Union
+
+# Stands for the absolute project directory in `Cache.env` values.
+ROOT = "{root}"
+# The job summary file in shell commands: GitHub's, or /dev/null on platforms without one.
+SUMMARY_FILE = '"${GITHUB_STEP_SUMMARY:-/dev/null}"'
+
+
+@dataclass(frozen=True)
+class Step:
+    name: str
+    # Shell command. Required unless the step is a GitHub-only setup step (see CISteps.setup).
+    run: str = ""
+    # GitHub Action doing the same as `run`, used instead of it on GitHub.
+    uses: str = ""
+    with_: Mapping[str, Any] = field(default_factory=dict)
+    id: str = ""
+    env: Mapping[str, str] = field(default_factory=dict)
+    # CI secrets (GitHub) / variables (GitLab) the step reads, as environment variables of the same name.
+    secrets: Tuple[str, ...] = ()
+    # Also runs when an earlier step failed (reports, uploads).
+    always: bool = False
+    # Its failure does not fail the job.
+    optional: bool = False
+    # Only feeds the job summary page: dropped on platforms without one.
+    summary: bool = False
+
+
+@dataclass(frozen=True)
+class Cache:
+    """Directories kept between runs, invalidated when `key_files` change."""
+
+    key: str
+    paths: Tuple[str, ...]
+    # At most two on GitLab.
+    key_files: Tuple[str, ...] = ()
+    # GitHub caches are immutable: a change in these files saves a fresh one (restored from the previous).
+    revision_files: Tuple[str, ...] = ()
+    # Variables pointing the tools at `paths`; ROOT stands for the project directory.
+    env: Mapping[str, str] = field(default_factory=dict)
+    name: str = ""
+
+
+Item = Union[Step, Cache]
+
+
+def step(
+    name: str,
+    run: str = "",
+    *,
+    uses: str = "",
+    with_: Optional[Mapping[str, Any]] = None,
+    id_: str = "",
+    env: Optional[Mapping[str, str]] = None,
+    secrets: Sequence[str] = (),
+    always: bool = False,
+    optional: bool = False,
+    summary: bool = False,
+) -> Step:
+    return Step(
+        name=name,
+        run=run,
+        uses=uses,
+        with_=dict(with_ or {}),
+        id=id_,
+        env=dict(env or {}),
+        secrets=tuple(secrets),
+        always=always,
+        optional=optional,
+        summary=summary,
+    )
+
+
+def on_github(cfg: Any, text: str) -> str:
+    """`text` when the project's CI runs on GitHub, e.g. a linter flag printing GitHub annotations."""
+    return text if cfg.platform == "github" else ""

quoll/ci/tools.py

@@ -0,0 +1,104 @@
+"""Language-independent CI tools (secret scanning, static analysis, image checks), shared by the platforms.
+
+Images are pinned; both platforms run the same commands, GitHub in a container job or on the runner, GitLab in a
+container job.
+"""
+from __future__ import annotations
+
+from typing import List
+
+from quoll.ci.steps import Step, step
+from quoll.platforms.github.actions import ACTIONS
+
+GITLEAKS_IMAGE = "ghcr.io/gitleaks/gitleaks:v8.30.1"
+SEMGREP_IMAGE = "semgrep/semgrep:1.185.0"
+TRIVY_VERSION = "0.76.2"
+TRIVY_IMAGE = f"aquasec/trivy:{TRIVY_VERSION}"
+SBOM_FILE = "sbom.cdx.json"
+
+# Fixable vulnerabilities of these severities fail the image scan (same defaults as [cd]).
+IMAGE_SCAN_SEVERITY = "CRITICAL,HIGH"
+
+
+_OSV_SCANNER = """arch=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
+curl -sSfL -o /usr/local/bin/osv-scanner \\
+  "https://github.com/google/osv-scanner/releases/latest/download/osv-scanner_linux_$arch"
+chmod +x /usr/local/bin/osv-scanner"""
+
+
+def install_osv_scanner() -> Step:
+    """osv-scanner reads lock files of many ecosystems (Maven, Gradle, Conan...)."""
+    return step("Install osv-scanner", run=_OSV_SCANNER, uses=ACTIONS["install-tool"], with_={"tool": "osv-scanner"})
+
+
+# The release binary, pinned (no install script fetched from a branch); curl comes from apt in slim images.
+_TRIVY_INSTALL = """if ! command -v curl >/dev/null; then
+  apt-get update -qq && apt-get install -y -qq curl ca-certificates
+fi
+arch=$(uname -m | sed 's/x86_64/64bit/; s/aarch64/ARM64/')
+mkdir -p /tmp/trivy
+curl -sSfL "https://github.com/aquasecurity/trivy/releases/download/v{v}/trivy_{v}_Linux-$arch.tar.gz" \\
+  | tar -xz -C /tmp/trivy trivy"""
+
+
+# Tool caches the container jobs keep in the project (see CISteps.cache): not dependencies of the project.
+_TOOL_CACHES = (".go", ".cargo", ".m2", ".gradle", ".cache", ".npm", ".pnpm-store", ".yarn/cache", ".yarn-cache",
+                ".nuget", ".sonar", "build")
+
+
+def dependency_checks(sbom: bool, licenses: bool, severities: List[str]) -> List[Step]:
+    """SBOM and license gate, run once the dependencies are installed: `trivy rootfs` reads the installed packages
+    (node_modules, .venv, vendor/, jars...), where the licenses are; lock files alone don't carry them."""
+    trivy = f"/tmp/trivy/trivy rootfs --quiet --skip-dirs {','.join(_TOOL_CACHES)}"
+    steps = [step("Install Trivy", run=_TRIVY_INSTALL.format(v=TRIVY_VERSION))]
+    if sbom:
+        steps.append(step("SBOM (CycloneDX)", run=f"{trivy} --format cyclonedx --output {SBOM_FILE} ."))
+    if licenses:
+        # Trivy's categories: CRITICAL = forbidden (AGPL, SSPL...), HIGH = restricted (GPL, LGPL),
+        # MEDIUM = reciprocal (MPL, EPL), LOW = notice (MIT, Apache, BSD).
+        steps.append(
+            step(
+                "License check",
+                # Every license is listed; only the configured categories fail. Free-text licenses Trivy can't
+                # classify are UNKNOWN.
+                run=f"{trivy} --scanners license --severity {','.join(severities)} --exit-code 1 .",
+            )
+        )
+    return steps
+
+
+def image_sbom() -> str:
+    """Shell command writing the SBOM of the pushed image $IMAGE@$DIGEST (registry credentials in
+    TRIVY_USERNAME / TRIVY_PASSWORD) to SBOM_FILE. Trivy runs as a container: works on runners and in dind."""
+    return (
+        f"docker run --rm -e TRIVY_USERNAME -e TRIVY_PASSWORD {TRIVY_IMAGE} image --quiet --format cyclonedx "
+        f'"$IMAGE@$DIGEST" > {SBOM_FILE}'
+    )
+
+
+def secret_scan() -> Step:
+    """Every commit of the history, so a secret removed later is still caught (allow-list: .gitleaksignore)."""
+    return step("Secret scanning", run="gitleaks git --redact --verbose .")
+
+
+def sast(report: str = "") -> Step:
+    """Semgrep's default rules for every language of the repository; `report` also writes GitLab's SAST report."""
+    # Blocking: ERROR rules only; WARNING ones are mostly low-confidence "audit" rules, noise in a gate.
+    command = "semgrep scan --config p/default --severity ERROR --error --metrics off"
+    if report:
+        command += f" --text --gitlab-sast-output={report}"
+    # An explicit target: without one, semgrep's image expects the code mounted at /src.
+    return step("Static analysis", run=command + " .")
+
+
+def image_checks(tag: str) -> List[Step]:
+    """Lint the Dockerfile (BuildKit's checks), build the image, scan it with Trivy before anyone ships it."""
+    scan = (
+        f"docker run --rm -v /var/run/docker.sock:/var/run/docker.sock {TRIVY_IMAGE} image --no-progress "
+        f'--exit-code 1 --severity {IMAGE_SCAN_SEVERITY} --ignore-unfixed "{tag}"'
+    )
+    return [
+        step("Lint Dockerfile", run="docker build --check ."),
+        step("Build image", run=f'docker build --tag "{tag}" .'),
+        step("Scan image", run=scan),
+    ]