sourcecode 5.2.0__py3-none-any.whl → 5.3.0__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "5.2.0"
+__version__ = "5.3.0"

sourcecode/cache_model.py

@@ -368,6 +368,7 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`no_ris` instead of a snapshot.",
                  "0.2 s either way", analysis_class="core", cold_seconds=0.2, warm_seconds=0.2,
                  field_seconds=0.4, field_cache_state="mixed", field_measured_version="5.1.0"),
+    CommandCache("timeline", (), "none", False, "Each sample is a fresh materialisation of a different commit, so nothing is shared between samples: two commits are two trees, and a cache keyed on a tree state can only ever serve one of them. The per-sample cost is measured and published in the payload.", analysis_class="ir"),
     CommandCache("trend", (), "none", False, "Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`.", analysis_class="none"),
     CommandCache("baseline", ("parse",), "shared", False,
                  "`capture`/`diff`/`trend` over architectural metrics. The field figure is `capture`, "

sourcecode/cli.py

@@ -201,6 +201,9 @@ COMMAND_TIERS: "tuple[tuple[str, str, tuple[str, ...]], ...]" = (
     ("experimental", "shape may change in a minor — do not gate CI on it", (
         "risk", "enrich", "audit-report", "data-exposure", "migrate-recipe",
         "archetype",
+        # F-BJ: the series is one release old and its sampling contract (which
+        # window a transition is attributed to) is the part most likely to move.
+        "timeline",
     )),
     # `retrieve` publishes 15+ intents whose answers the other commands already
     # give better: measured on the battery, `security-surface` merely re-states
@@ -6298,6 +6301,13 @@ def endpoints_cmd(
         help="Where the client lives, when it is not the whole repository "
              "(implies --client-usage).",
     ),
+    consumer: Optional[list[Path]] = typer.Option(
+        None, "--consumer",
+        help="A consumer repository to join against (repeatable). Turns the census "
+             "into a surface-reduction plan: of the routes a rule leaves open, which "
+             "ones somebody calls (fix now) and which nobody calls (delete rather "
+             "than protect).",
+    ),
     progress_mode: Optional[str] = _progress_option(),
     jobs: Optional[int] = _jobs_option(),
 ) -> None:
@@ -6447,6 +6457,17 @@ def endpoints_cmd(
             target, _selected,
             client_dirs=[client_dir] if client_dir is not None else None,
         )
+    # F-BH. The consumers of a monolith are usually other repositories, so the
+    # question that decides the work — what does anybody call — cannot be answered
+    # from this tree alone. Given them, the plan inverts: an open route nobody
+    # calls is surface to delete rather than surface to guard. A third declared
+    # population, never merged into the census or the servlet surface.
+    if not servlets and consumer:
+        from sourcecode.consumer_join import build_consumer_join
+
+        data["consumer_join"] = build_consumer_join(
+            target, _selected, consumer, access=_endpoint_access_index(target),
+        )
     if compact and not servlets:
         from sourcecode.degradation import cap_effect
 
@@ -7984,6 +8005,139 @@ def trend_cmd(
     )
 
 
+def _endpoint_access_index(target: Path) -> "dict[str, str]":
+    """`METHOD path` → the access verdict `posture` publishes, for the consumer join.
+
+    Read from `posture`, which is the authority for it: the plan's whole value is
+    the crossing of *open* with *uncalled*, and deciding "open" a second way here
+    would be a second answer to a question one command already owns. Failure is an
+    empty index rather than an exception — the join still splits called from
+    uncalled, it just cannot say which half is urgent.
+    """
+    try:
+        from sourcecode.posture import access_resolution, access_verdict
+
+        by_endpoint, _decides = access_resolution(target)
+    except Exception:
+        return {}
+    index: "dict[str, str]" = {}
+    for identity, decision in by_endpoint.items():
+        parts = str(identity).split(":")
+        if len(parts) < 2:
+            continue
+        index[f"{parts[0].upper()} {parts[1]}"] = access_verdict(decision)
+    return index
+
+
+# ── timeline: since when, and in which window (F-BJ) ──────────────────────────
+@app.command("timeline")
+def timeline_cmd(
+    path: Path = typer.Argument(
+        Path("."), help="Repository to walk (default: current directory).",
+    ),
+    since: str = typer.Option(
+        ...,
+        "--since",
+        help="The ref the series starts after: a tag, a branch, a sha (e.g. v1.0).",
+    ),
+    watch: str = typer.Option(
+        "posture",
+        "--watch",
+        help="Comma-separated metrics to follow: posture, data-exposure, "
+             "endpoints, spring-audit.",
+    ),
+    max_commits: int = typer.Option(
+        10,
+        "--max-commits",
+        min=1,
+        help="How many commits to analyse. A larger number narrows the window a "
+             "transition is attributed to; at one commit per sample the window "
+             "closes to a single commit.",
+    ),
+    first_parent: bool = typer.Option(
+        True,
+        "--first-parent/--all-parents",
+        help="Walk the trunk only (default). A merge's second parent is another "
+             "branch's history.",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the series to a file instead of stdout.",
+    ),
+    format: str = _format_option(help="Output format: json (default) or yaml."),
+    copy: bool = _copy_option(),
+    progress_mode: Optional[str] = _progress_option(),
+) -> None:
+    """[EXPERIMENTAL] When an exposure appeared, and in which commit window.
+
+    \b
+    EXPERIMENTAL: the sampling contract — which commit window a transition is
+    attributed to — is the part most likely to move in a minor. Do not gate CI
+    on it yet.
+
+    \b
+    `data-exposure` says 2 453 routes reach labelled data and nothing decides
+    access to them. The question that follows — and the one a regulator asks
+    first — is SINCE WHEN. This walks the commit series, runs the analyses that
+    already ship at each sampled tree, and publishes where a number MOVED.
+
+    \b
+    Nothing here is a new analysis: every axis is a projection of a payload
+    another command emits (`metrics_read` names it per metric), measured on a
+    read-only materialisation of each commit — the repository is never written
+    to. Re-run that command at that commit and you get the same number.
+
+    \b
+    A sampled commit that could not be analysed is `null` with a reason, never
+    0. With sampling on, a transition names the commit it was OBSERVED at and
+    publishes the window it could have happened in; it is never attributed to a
+    single commit it was not measured at.
+
+    \b
+    Examples:
+      ask timeline . --since v1.0 --watch posture,data-exposure
+      ask timeline . --since HEAD~50 --watch data-exposure --max-commits 50
+      ask timeline . --since v2.0 --watch spring-audit -o series.json
+    """
+    from sourcecode.timeline import METRICS, TimelineError, build_timeline
+
+    target = _admit_path(path)
+    watched = [name.strip() for name in watch.split(",") if name.strip()]
+    if not watched:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            "--watch names at least one metric.",
+            hint=f"--watch {','.join(sorted(METRICS))}",
+        )
+        raise typer.Exit(code=1)
+
+    # Each sample is a full analysis of one tree, so this is the command in the
+    # catalogue whose wait is longest and least bounded by the repository alone.
+    # The spinner names the commit being sampled, because "which of the ten" is
+    # the only progress fact a caller can act on.
+    _prog = Progress()
+    _prog.start(f"walking {len(watched)} metric(s) since {since}")
+    try:
+        data = build_timeline(
+            target, since, watched,
+            max_samples=max_commits,
+            first_parent=first_parent,
+            progress=lambda line: _prog.update(line),
+        )
+    except TimelineError as exc:
+        _prog.stop()
+        _emit_error_json(exc.code, exc.message, **exc.context)
+        raise typer.Exit(code=1)
+    finally:
+        _prog.stop()
+
+    _emit_command_output(
+        _serialize_dict(data, format),
+        output_path,
+        copy,
+        success_msg=f"timeline written to {output_path}",
+    )
+
+
 # ── Spring Semantic Audit ─────────────────────────────────────────────────────
 
 
@@ -8478,6 +8632,14 @@ def spring_audit_cmd(
     `summary.total_defects` is the number of things to fix. Measured:
     openmrs-core 38 findings / 29 defects, BroadleafCommerce 19 / 14.
 
+    \b
+    Waivers: a repository can adjudicate a finding as not-a-defect-here in
+    `.ask/waivers.yml`, keyed on the stable `finding_id`/`defect_id` with a
+    required reason (optional `by`, `expires`). Waived rows leave `findings` and
+    are published in full under `waived`, with `summary.waived_findings` and a
+    `waivers` block naming what was declared, applied, expired and matched
+    nothing. A rule family cannot be waived. See docs/contracts.md.
+
     \b
     CI/CD usage — this gate is ABSOLUTE (any finding fails, including debt that
     was already there). For a baseline-relative gate that fails only on findings
@@ -8677,6 +8839,27 @@ def spring_audit_cmd(
 
             combined = SpringAuditResult.merge(results, scope=scope)
 
+            # F-BI: adjudication, applied over the whole population and never
+            # inside one scope. A malformed waivers file stops the command
+            # rather than reading as "nothing was waived" — a broken file must
+            # not decide a gate in either direction.
+            from sourcecode.waivers import WaiversError as _WaiversError
+            from sourcecode.waivers import apply_to_result as _apply_waivers
+
+            try:
+                combined = _apply_waivers(combined, target)
+            except _WaiversError as _exc:
+                _prog.stop()
+                _emit_error_json(
+                    INVALID_INPUT_CODE,
+                    f"The waivers this repository declares could not be read: {_exc}",
+                    hint=(
+                        "Each entry needs one of `finding_id`/`defect_id` and a "
+                        "`reason`. See docs/contracts.md."
+                    ),
+                )
+                raise typer.Exit(code=1)
+
             # C2-31: a phase that never *started* is a cut this envelope cannot
             # learn from its own scopes — no auditor ran to record it. The run
             # knows, so it says so here, and `finalize()` applies the same ceiling
@@ -9005,6 +9188,13 @@ def verify_cmd(
     Contracts live in `.ask/contracts.yml` (see `ask verify-edit --help` for the
     rule kinds). No contracts declared → nothing was verified, exit 2.
 
+    \b
+    Waivers: `.ask/waivers.yml` adjudicates a finding as not-a-defect-here, keyed
+    on its stable finding/defect id with a required reason. A waived finding does
+    not hold this gate red; `ask spring-audit` publishes what was waived, by whom
+    and why. A baseline records accepted DEBT — a waiver says it was never a
+    defect. See docs/contracts.md.
+
     \b
     Exit codes (with --ci, the default): 0 = pass, 1 = violations blocked,
     2 = unverified (no contracts declared, contracts unreadable, or the
@@ -9973,6 +10163,16 @@ def posture_cmd(
             "spring.profiles.active from an explicit deployment env/dotenv file."
         ),
     ),
+    profile_from: Optional[list[Path]] = typer.Option(
+        None,
+        "--profile-from",
+        help=(
+            "Take the active profile set from the artefact that decides it — a "
+            "Kubernetes manifest, compose file, WebLogic deployment plan, "
+            "Dockerfile, dotenv or launch script (repeatable). If it decides "
+            "nothing, the repository's own verdict stands."
+        ),
+    ),
     property_overrides: Optional[list[str]] = typer.Option(
         None,
         "--property",
@@ -10107,6 +10307,44 @@ def posture_cmd(
         )
         raise typer.Exit(code=1)
 
+    # F-BG. `--profile-from` names the artefact that decides the profile set, which
+    # is the hop the flagship used to end at. It cannot be combined with a flag
+    # that *states* the set: --profile and --diff both name one, and reading a
+    # manifest to then ignore it would be a payload that describes two answers and
+    # gives one.
+    profile_from_block: "Optional[dict]" = None
+    decided_profiles: "Optional[set[str]]" = None
+    artefact_signals: list = []
+    if profile_from:
+        if profile or diff:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                "--profile-from reads the profile set from a deployment artefact; "
+                "--profile and --diff state one. Pass one or the other.",
+                hint="ask posture . --profile-from k8s/deployment-prod.yaml",
+            )
+            raise typer.Exit(code=1)
+        from sourcecode.environment_resolution import (
+            collect_deployment_artefact_signals,
+            decide_profiles_from_artefacts,
+        )
+
+        for artefact in profile_from:
+            artefact_path = Path(artefact).expanduser()
+            if not artefact_path.is_file():
+                _emit_error_json(
+                    INVALID_INPUT_CODE,
+                    f"--profile-from must name a readable file (got {str(artefact)!r}).",
+                    hint="ask posture . --profile-from k8s/deployment-prod.yaml",
+                )
+                raise typer.Exit(code=1)
+            artefact_signals.extend(
+                collect_deployment_artefact_signals(artefact_path, root=path)
+            )
+        profile_from_block = decide_profiles_from_artefacts(profile_from, root=path)
+        if profile_from_block.get("decided"):
+            decided_profiles = set(profile_from_block["profiles"] or [])
+
     # One spinner over the whole dispatch: every branch below resolves the
     # conditional bean graph, and `--diff-ref` resolves it twice (once per ref).
     # try/finally, because several branches leave through typer.Exit and a
@@ -10124,7 +10362,7 @@ def posture_cmd(
                          "`--env-file prod.env` as deployment evidence.",
                 )
                 raise typer.Exit(code=1)
-            deployment_signals = None
+            deployment_signals = list(artefact_signals)
             if env_file is not None:
                 from sourcecode.environment_resolution import collect_env_file_signals
 
@@ -10136,7 +10374,8 @@ def posture_cmd(
                         hint="ask posture . --resolve-environments --env-file prod.env",
                     )
                     raise typer.Exit(code=1)
-                deployment_signals = collect_env_file_signals(env_path, root=path)
+                deployment_signals.extend(collect_env_file_signals(env_path, root=path))
+            deployment_signals = deployment_signals or None
             data = resolve_environments(
                 path, overrides, deployment_signals=deployment_signals,
             )
@@ -10165,7 +10404,8 @@ def posture_cmd(
             try:
                 data = diff_posture_refs(
                     path,
-                    _parse_set(profile) if profile else set(),
+                    decided_profiles if decided_profiles is not None
+                    else (_parse_set(profile) if profile else set()),
                     base_ref.strip(),
                     head_ref.strip() if head_ref is not None else None,
                     overrides,
@@ -10194,10 +10434,22 @@ def posture_cmd(
             left_raw, right_raw = diff.split(":", 1)
             data = diff_posture(path, _parse_set(left_raw), _parse_set(right_raw), overrides)
         else:
-            data = build_posture(path, _parse_set(profile) if profile else set(), overrides)
+            data = build_posture(
+                path,
+                decided_profiles if decided_profiles is not None
+                else (_parse_set(profile) if profile else set()),
+                overrides,
+            )
     finally:
         _prog.stop()
 
+    # F-BG. The block travels with every shape the command can answer in, and it
+    # says whether it changed the answer: a `decided: false` block beside an
+    # unchanged verdict is the honest outcome of pointing at a file that does not
+    # decide, not a silent no-op.
+    if profile_from_block is not None and isinstance(data, dict):
+        data["profile_from"] = profile_from_block
+
     _emit_command_output(
         _serialize_dict(data, format),
         output_path,
@@ -14178,7 +14430,7 @@ HELP_PANELS: "tuple[tuple[str, tuple[str, ...]], ...]" = (
     )),
     ("Experimental — shape may change", (
         "risk", "enrich", "audit-report", "data-exposure", "migrate-recipe",
-        "archetype", "retrieve",
+        "archetype", "timeline", "retrieve",
     )),
 )