surfaceplate 0.16.0__py3-none-any.whl

surfaceplate/adopt/defaults.py

@@ -0,0 +1,278 @@
+"""Proposed answers, each with the origin it will be recorded under.
+
+`DR-40` created this module to propose what the adopter chose not to type; `DR-47` makes it the
+rule for every value the wizard writes. This module **proposes**; it never decides. Every value it
+produces is shown on the review with where it came from, the human can change any of them, and
+the origin is recorded in `governance/application-profile.provenance.yaml` exactly as proposed -
+never as typed (`provenance.py`).
+
+**A proposal is only made where there is something honest to propose.** The sources `DR-47` (2)
+names, and nothing else:
+
+- **discovered** - a real path, directory or CI step read out of this repository (`discover.py`),
+  never one this framework installed (`F61`);
+- **example** - the worked prose this framework already ships for that control or gate
+  (`example_answers.py`);
+- **computed** - a value derived from a fact or from an answer already given: today's date, the
+  review horizon, a maintainer taken from the owner already given, a classification copied from
+  the one already chosen;
+- **fact of record** and **scaffolded** are recorded by `provenance.py` and `flow.py` rather
+  than proposed here.
+
+**What is never proposed.** A scope decision: a gate's status - `not_applicable` included - is a
+key a human presses, singly or in one recorded bulk act (`DR-47` (4)). `F62` is what proposing
+those cost: fifteen example rationales made true by assertion under a header claiming human
+authorship. A field with no honest source is **left unanswered and still asked**.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from surfaceplate.adopt import catalogue, detect, discover, example_answers, plan, provenance
+
+# The framework's own sentence for a prose field the human left blank on the decisions form. It
+# is written as computed - from the fact that nothing was stated - and is one edit on the review.
+# `DR-47` accepted the prototype that wrote exactly this (report Part II §II.1).
+NOT_STATED = "Not stated at adoption."
+
+
+@dataclass(frozen=True)
+class Proposal:
+    """One proposed answer, and where it came from - the origin is shown, never just the value."""
+
+    field: str  # "<section>.<field id>"
+    value: object
+    origin: str  # one of provenance.KINDS other than "typed"
+    detail: str  # the human-readable reason, shown on the review
+
+    def describe(self) -> str:
+        return f"{self.field} = {self.value!r}  ({self.detail})"
+
+    def as_origin(self) -> provenance.Origin:
+        return provenance.Origin(self.origin, self.detail)
+
+
+def slug(name: str) -> str:
+    """A directory name as an `application_id` the schema accepts, or `""` if nothing survives."""
+    text = re.sub(r"[^a-z0-9_-]+", "-", name.strip().lower()).strip("-")
+    text = re.sub(r"-{2,}", "-", text)
+    if len(text) < 2 or not re.match(r"^[a-z0-9]", text):
+        return ""
+    return text
+
+
+# ---------------------------------------------------------------------------------------------
+# Before the decisions form: what the form can show pre-filled
+# ---------------------------------------------------------------------------------------------
+
+
+def propose_identity(repo: Path) -> list[Proposal]:
+    """The directory's own name, as the id and the display name. Both are one edit."""
+    out: list[Proposal] = []
+    name = repo.resolve().name
+    ident = slug(name)
+    if ident:
+        out.append(
+            Proposal("identity.application_id", ident, provenance.COMPUTED, "= the directory name")
+        )
+    if name.strip():
+        out.append(
+            Proposal("identity.display_name", name, provenance.COMPUTED, "= the directory name")
+        )
+    return out
+
+
+def propose_stack(repo: Path) -> list[Proposal]:
+    languages = detect.detect_languages(repo)
+    if not languages:
+        return []
+    return [
+        Proposal(
+            "stack.language",
+            ", ".join(languages),
+            provenance.DISCOVERED,
+            "language markers found in this repository",
+        )
+    ]
+
+
+# ---------------------------------------------------------------------------------------------
+# After the decisions form and the level: everything else
+# ---------------------------------------------------------------------------------------------
+
+
+def propose_risk(risk_answers: dict) -> list[Proposal]:
+    """The two prose fields the decisions form leaves optional. `NOT_STATED` where blank."""
+    out: list[Proposal] = []
+    if not str(risk_answers.get("risk_profile") or "").strip():
+        out.append(
+            Proposal(
+                "risk.risk_profile", NOT_STATED, provenance.COMPUTED, "left blank on the decisions form"
+            )
+        )
+    if not str(risk_answers.get("materiality_definition") or "").strip():
+        out.append(
+            Proposal(
+                "risk.materiality_definition",
+                NOT_STATED,
+                provenance.COMPUTED,
+                "not asked before the review; one edit here",
+            )
+        )
+    return out
+
+
+def propose_controls(*, level: str, mode: str, found: discover.Discovered) -> list[Proposal]:
+    """Rationales from the worked examples; references from what is really in the repository."""
+    out: list[Proposal] = []
+    section = plan.controls_plan(level=level, mode=mode, found=found)
+    floor = catalogue.CONFORMANCE_LEVELS[level]
+
+    for spec in section.fields:
+        key = f"controls.{spec.id}"
+        if spec.id == "above_floor":
+            # Nothing above the floor unless a human ticks it: a level is a floor, and quietly
+            # opting an adopter into controls they did not ask for would be the tool choosing
+            # their scope. Presented on the remainder form, so this is the value when left unticked.
+            out.append(
+                Proposal(key, [], provenance.COMPUTED, "nothing beyond this level's floor is declared")
+            )
+            continue
+        if spec.id.endswith(".rationale"):
+            control_id = spec.id.rsplit(".", 1)[0]
+            example = example_answers.rationale_example(control_id)
+            if example and (control_id in floor or control_id in plan.BASELINE_CONTROL_IDS):
+                out.append(
+                    Proposal(key, example, provenance.EXAMPLE, "this framework's own worked example")
+                )
+            continue
+        if spec.id.endswith(".implementation_reference"):
+            # `DR-54` (1): the first row may be the seed's "create it"; a proposal comes only from
+            # something discovery found. With nothing found, the field is asked and the human
+            # may choose the row - the tool never proposes to create a file.
+            found_only = [v for v, _label in spec.choices if v != spec.seed and v not in found.rejected and not discover.is_archived(v)]
+            control_id = spec.id.rsplit(".", 1)[0]
+            if control_id in catalogue.PATTERN_A_CONTROLS and control_id != "dependency_lock":
+                # `F40`, `F84`: the offer ranks every artefact, but a proposal needs a match.
+                found_only = [v for v in found_only if any(w in v.lower() for w in plan.FINDINGS_WORDS)]
+            elif control_id in catalogue.PATTERN_C_CONTROLS:
+                # `F93`: a record directory is proposed only where its name matches the control
+                # and its records pass the control's schema - never merely because it holds YAML.
+                found_only = [v for v in found_only if v in found.register_fit.get(control_id, ())]
+            if found_only:
+                out.append(Proposal(key, found_only[0], provenance.DISCOVERED, f"found: {found_only[0]}"))
+            continue
+        if spec.id == "scanner.name":
+            out.append(Proposal(key, spec.default, provenance.EXAMPLE, "the scanner the examples name"))
+        elif spec.id == "scanner.wired_in" and spec.choices:
+            found_only = [v for v, _label in spec.choices if v != spec.seed]
+            if found_only:
+                out.append(Proposal(key, found_only[0], provenance.DISCOVERED, f"found: {found_only[0]}"))
+    return out
+
+
+def propose_gates(
+    *, level: str, builds_ui: bool, mode: str, found: discover.Discovered, adoption_date: str
+) -> list[Proposal]:
+    """A precondition for every gate that could be `required`, and nothing for any status.
+
+    `DR-47` (4): the tool never supplies a scope decision, `not_applicable` included. `DR-47` (5):
+    `effective_from` is proposed as the adoption date and recorded as computed unless changed - the
+    value is shown, and a human can only widen the audit window from it (`SP033`, `SP034`).
+    """
+    out: list[Proposal] = []
+    for spec in plan.gate_plan(level=level, builds_ui=builds_ui, mode=mode, found=found):
+        prefix = f"gates.{spec.id}"
+        # A gate settled `not_applicable` by an earlier answer needs no precondition.
+        if spec.auto_status:
+            continue
+        # `F40`: MATCHED, not merely ranked - a proposal comes only from a candidate that matched
+        # the gate. No match -> no proposal, and the field is asked.
+        # `F84` / `DR-51` (5): and never one the checker's content rules would reject; `F94`:
+        # nor an archived document, whatever its name matched.
+        matched = [c for c in discover.matched_for_gate(found.artefacts, spec.id) if c not in found.rejected and not discover.is_archived(c)]
+        if matched:
+            out.append(
+                Proposal(
+                    f"{prefix}.artefact",
+                    matched[0],
+                    provenance.DISCOVERED,
+                    f"the closest match in this repository: {matched[0]}",
+                )
+            )
+        # `F61`: only when discovery found a directory of the adopter's own.
+        if found.paths:
+            out.append(
+                Proposal(
+                    f"{prefix}.paths",
+                    found.paths[0],
+                    provenance.DISCOVERED,
+                    "this repository's main source directory",
+                )
+            )
+        out.append(
+            Proposal(
+                f"{prefix}.effective_from",
+                adoption_date,
+                provenance.COMPUTED,
+                "= the adoption date; an earlier date audits more history",
+            )
+        )
+    return out
+
+
+def propose_adoption(*, owner: str, data_classification: str) -> list[Proposal]:
+    """Only what can be derived from a fact or an answer already given."""
+    return [
+        Proposal(
+            "adoption.review_by",
+            (_dt.date.today() + _dt.timedelta(days=180)).isoformat(),
+            provenance.COMPUTED,
+            "180 days from today, the interval this framework suggests",
+        ),
+        Proposal("adoption.framework_maintainer", owner, provenance.COMPUTED, "= owner"),
+        Proposal(
+            "adoption.repository_classification",
+            data_classification,
+            provenance.COMPUTED,
+            "= data_classification",
+        ),
+        Proposal(
+            "adoption.adoption_status",
+            "in_progress",
+            provenance.COMPUTED,
+            "adopt has just written the profile; the checker has not yet passed against it",
+        ),
+        Proposal(
+            "adoption.needs_validator", False, provenance.COMPUTED, "no independent review declared"
+        ),
+    ]
+
+
+def propose_wrap() -> list[Proposal]:
+    return [
+        Proposal("wrap.human_roles", "", provenance.COMPUTED, "none stated; one edit here"),
+    ]
+
+
+def propose_after_level(
+    state: dict, *, found: discover.Discovered, adoption_date: str
+) -> list[Proposal]:
+    """Everything proposable once the level is known."""
+    level = state["level"]["conformance_level"]
+    builds_ui = bool(state["stack"]["builds_user_interface"])
+    mode = state["mode"]["mode"]
+    owner = str(state["identity"].get("owner") or "")
+    classification = str(state["risk"].get("data_classification") or "")
+    return [
+        *propose_controls(level=level, mode=mode, found=found),
+        *propose_gates(
+            level=level, builds_ui=builds_ui, mode=mode, found=found, adoption_date=adoption_date
+        ),
+        *propose_adoption(owner=owner, data_classification=classification),
+        *propose_wrap(),
+    ]

surfaceplate/adopt/detect.py

@@ -0,0 +1,141 @@
+"""What can be seen without asking - and only that.
+
+Detection exists to save typing, never to answer for the human. Every value this module returns is
+shown back to them in section 2 as something to *confirm or correct*, never written silently. In
+particular `builds_user_interface` is never set from here: `core/CONFORMANCE_LEVELS.md` states
+plainly that it "is NOT descriptive... a reviewer can falsify a wrong answer in seconds," and a
+detector that got it wrong would be exactly that wrong answer, arrived at automatically instead of
+by a human's mistake.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# (label, marker files) - a files-exist check, not a dependency graph walk. Enough to save someone
+# typing "Python" when a pyproject.toml is sitting right there; not a claim to be exhaustive.
+_LANGUAGE_MARKERS: list[tuple[str, tuple[str, ...]]] = [
+    ("Python", ("pyproject.toml", "setup.py", "requirements.txt")),
+    ("Node.js / TypeScript", ("package.json",)),
+    ("Rust", ("Cargo.toml",)),
+    ("Go", ("go.mod",)),
+    ("Java", ("pom.xml", "build.gradle", "build.gradle.kts")),
+    ("Ruby", ("Gemfile",)),
+]
+
+# UI-framework dependency names worth a glance inside package.json, if one exists. Presence only -
+# not a claim about how the framework is used.
+_UI_DEPENDENCY_HINTS = ("react", "vue", "svelte", "@angular/core", "next", "nuxt", "solid-js")
+
+
+# R7: widen what discovery looks for, because each hit removes a question. A repository with no
+# manifest file but source files at its root is still recognisably one language.
+_LANGUAGE_SUFFIXES: list[tuple[str, tuple[str, ...]]] = [
+    ("Python", (".py",)),
+    ("Node.js / TypeScript", (".ts", ".js", ".tsx")),
+    ("Rust", (".rs",)),
+    ("Go", (".go",)),
+    ("Java", (".java", ".kt")),
+    ("Ruby", (".rb",)),
+]
+
+
+def detect_languages(repo: Path) -> list[str]:
+    found = [label for label, markers in _LANGUAGE_MARKERS if any((repo / m).is_file() for m in markers)]
+    try:
+        suffixes = {p.suffix for p in repo.iterdir() if p.is_file()}
+    except OSError:
+        suffixes = set()
+    for label, exts in _LANGUAGE_SUFFIXES:
+        if label not in found and any(ext in suffixes for ext in exts):
+            found.append(label)
+    return found
+
+
+def detect_ui_hint(repo: Path) -> str | None:
+    """A package.json dependency that suggests a UI framework, or None. A hint, not a verdict."""
+    package_json = repo / "package.json"
+    if not package_json.is_file():
+        return None
+    try:
+        import json
+
+        data = json.loads(package_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+    for hint in _UI_DEPENDENCY_HINTS:
+        if hint in deps:
+            return hint
+    return None
+
+
+# Marker paths for the level-choice screen's detected signals (DR-35). Files-exist checks, in the
+# same spirit as _LANGUAGE_MARKERS above: enough to show the honest starting cost of a level before
+# it's chosen, never a claim to detect every possible shape a repository might already have. Shown,
+# never acted on - the level choice itself stays a human decision either way (DR-35: "they are
+# tool/repo dependent", the maintainer's own words for why this framework does not steer it).
+_CI_WORKFLOW_DIRS = (".github/workflows", ".gitlab-ci.d")
+_DECISIONS_FOLDER_MARKERS = ("docs/decisions", "docs/adr", "decisions", "adr")
+_CHANGELOG_MARKERS = ("CHANGELOG.md", "CHANGELOG.rst", "CHANGELOG")
+
+
+def detect_ci_workflows(repo: Path) -> list[str]:
+    """Existing CI workflow files, repository-relative - a candidate home for a control's CI-step
+    `implementation_reference` (`deterministic_tests`, `contract_tests`) or a gate's `enforcement:
+    [ci]`. Returns paths, not a verdict: this module never tells whether a step in one of them
+    actually fails the build, which only `check_conformance.py`'s own pattern-B check can."""
+    from surfaceplate.adopt import discover
+
+    installed, _steps = discover.framework_paths(repo)
+    found: list[str] = []
+    for directory in _CI_WORKFLOW_DIRS:
+        d = repo / directory
+        if not d.is_dir():
+            continue
+        found.extend(
+            p.relative_to(repo).as_posix()
+            for p in sorted(d.glob("*.y*ml"))
+            # `F61`: the workflow this framework installed is not one the adopter "appears to have".
+            if p.is_file() and p.relative_to(repo).as_posix() not in installed
+        )
+    return found
+
+
+def detect_decisions_folder(repo: Path) -> str | None:
+    """A decisions/ADR-shaped folder that already exists, or None. A candidate precondition
+    artefact for `decision_before_implementation` - never asserted to already satisfy that gate,
+    since satisfying it also depends on real content and, for the gate itself, on git history."""
+    for marker in _DECISIONS_FOLDER_MARKERS:
+        d = repo / marker
+        if d.is_dir():
+            return marker
+    return None
+
+
+def detect_changelog(repo: Path) -> str | None:
+    """An existing CHANGELOG file, or None - a candidate precondition artefact for
+    `change_record_before_completion`."""
+    for marker in _CHANGELOG_MARKERS:
+        f = repo / marker
+        if f.is_file():
+            return marker
+    return None
+
+
+def detect_git_state(repo: Path) -> tuple[str | None, bool]:
+    """(current branch, working tree is clean) - best-effort, never raises."""
+    import subprocess
+
+    def run(*args: str) -> tuple[int, str]:
+        try:
+            result = subprocess.run(
+                ["git", "-C", str(repo), *args], capture_output=True, text=True, timeout=5
+            )
+            return result.returncode, result.stdout.strip()
+        except (OSError, subprocess.TimeoutExpired):
+            return 1, ""
+
+    code, branch = run("branch", "--show-current")
+    code2, status = run("status", "--porcelain")
+    return (branch if code == 0 and branch else None, code2 == 0 and status == "")