scitex-dev 0.35.0__tar.gz → 0.37.0__tar.gz

{scitex_dev-0.35.0 → scitex_dev-0.37.0}/.github/ci/build-in-sif.sh

@@ -67,3 +67,40 @@ test -n "$(ls -A dist 2>/dev/null)" || {
     echo "::error::python -m build produced no artifacts in dist/"
     exit 1
 }
+
+# --- Release gate: every declared entry point must IMPORT from the WHEEL ---
+#
+# A dangling entry point does not fail the build on its own: the wheel
+# uploads, `pip install` succeeds, and the breakage lands in the USER's
+# tooling. `pytest11` is imported by pytest at startup, so a dangling target
+# aborts EVERY pytest run in the installed environment before collection.
+# This step moves that failure back into the build.
+#
+# The audit runs against the freshly built WHEEL (unpacked to a temp dir),
+# not against pyproject.toml — a correct declaration can still point at a
+# module the build dropped, which is exactly the bug a source-only check
+# would miss. The SIF has scitex-dev's runtime deps installed, so a genuine
+# import failure means the ARTIFACT is broken, not the environment.
+echo "=== entry-point import gate (built wheel) ==="
+WHEEL="$(ls dist/*.whl | head -n 1)"
+test -n "$WHEEL" || {
+    echo "::error::no wheel in dist/ to audit"
+    exit 1
+}
+PYTHONPATH="$PWD/src${PYTHONPATH:+:$PYTHONPATH}" "$PY" - "$WHEEL" <<'PYGATE'
+import sys
+
+from scitex_dev._release.entrypoint_imports import (
+    audit_wheel_entry_point_imports,
+)
+
+report = audit_wheel_entry_point_imports(sys.argv[1], "scitex-dev")
+sys.stdout.write(report.report() + "\n")
+if not report.is_clean:
+    sys.stdout.write(
+        "::error::the built wheel declares entry points that do NOT import; "
+        "publishing it would break `pytest` (and console scripts) for every "
+        "user who installs it\n"
+    )
+    raise SystemExit(1)
+PYGATE

{scitex_dev-0.35.0 → scitex_dev-0.37.0}/CHANGELOG.md

@@ -7,6 +7,249 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-07-23
+
+### Added
+- **Release gate: a declared entry point that does not import now fails the
+  BUILD (#421).** A dangling entry point does not fail the build on its own —
+  the wheel uploads, `pip install` succeeds, and the breakage lands in the
+  USER's tooling. `pytest11` is imported by pytest at startup, so a dangling
+  target aborts EVERY pytest run in the installed environment before
+  collection. `scitex_dev._release.entrypoint_imports` reads
+  `entry_points.txt` from the BUILT artifact's `.dist-info` and imports each
+  target in a subprocess with the artifact prepended to `PYTHONPATH`. It
+  probes the artifact, not `pyproject.toml`: a correct declaration can still
+  point at a module the build dropped, which is exactly the bug a source-only
+  check would miss. `missing` (target absent — packaging bug) is classified
+  apart from `broken` (target present, import raised — dependency/code bug);
+  the two present identically at pytest startup and route to different fixes.
+  Wired into `.github/ci/build-in-sif.sh`, before upload.
+
+- **PS-222 — the `.scitex/<pkg-short>/` config-layout convention (#416).**
+  New rule plus auditor covering where a package's own config tree lives,
+  with a `runtime/` control arm in the test suite.
+
+- **`ecosystem list --distributions` — enumeration keyed by origin remote
+  (#419).** New `_ecosystem/_enumerate.py` resolves checkout DIRECTORIES into
+  DISTRIBUTIONS by their origin remote rather than by directory name,
+  collapsing duplicate checkouts and linked worktrees into reported aliases
+  and labelling which tree was actually measured. `--org` cross-references a
+  GitHub org listing to surface repos with no local checkout; `--scan-root`
+  enumerates a directory tree, the input shape brand-wide sweeps use and
+  where duplicate checkouts appear. Unreadable paths are recorded as errors,
+  never silently dropped, and an orphaned linked worktree is now diagnosed by
+  name instead of as a generic unreadable path. The flag is OPT-IN: the
+  default `ecosystem list` output shape is unchanged, so existing callers
+  keep working.
+
+### Changed
+- **PS-220 self-migration: scitex-dev's own stderr prints moved to
+  scitex-logging, 132 → 118 findings (#415).** scitex-dev authored the
+  no-bare-print mandate while carrying 132 findings against it. This migrates
+  the STDERR bucket — 14 sites across `trace_env`, the linter
+  (`_cmd_format` / `_health` / `_cmd_completion`), the argparse dispatch
+  modules, `quality/_check.py` and `cron/_task_harvest.py` — where
+  scitex-logging provably cannot move the output, because it already writes
+  every level to `sys.stderr`. Hand-rolled ANSI in `_health` is dropped now
+  that scitex-logging owns the colouring. Stdout prints are deliberately
+  untouched: they need the console API still being designed.
+
+### Fixed
+- **`skills list` and `skills get` were broken and now work again (#423).**
+  The symptom: running `skills list` or `skills get` raised
+  `ModuleNotFoundError: No module named 'scitex_dev._core._ecosystem'` (and
+  the `._docs` equivalent). This hit BOTH front-ends — argparse and Click —
+  in every downstream package using the shared
+  `register_skills_subcommand` / `skills_click_group` surface, because
+  `_skills_click.py` imports `_skills_get` / `_skills_list` FROM
+  `_skills_argparse` and so inherited the fault.
+
+  Cause: the `dispatch.py` → `dispatch/` package split (2026-07-11,
+  CLI-standardization audit pass 4b) added one nesting level. The Click
+  flavors were corrected to `...`, but both argparse flavors kept the
+  flat-module `..` depth, which resolves to the non-existent
+  `scitex_dev._core._ecosystem` / `._docs`. 7 sites: 5 in
+  `_skills_argparse`, 2 in `_docs_argparse`.
+
+  The imports are function-local, so the modules imported cleanly and only
+  exploded when a command actually RAN — which is why import-smoke and the
+  split's own tests stayed green: they asserted argv PARSING and never
+  called `args.func`. The new tests dispatch through `args.func` against the
+  real entry points, plus `find_spec` assertions pinning that the backing
+  modules live under the package root and NOT under `scitex_dev._core`.
+
+- **`audit-project` never prints SUCC over live warning findings (#417).**
+  The success banner was decided from the severity-FLOOR-filtered finding
+  list, so at the default `--severity error` a tree carrying live W findings
+  printed output byte-identical to a genuinely clean tree — measured on
+  scitex-agent-container: 53 live PS-220 findings, `SUCC`, exit 0.
+
+  The consequence is not cosmetic. A mutation proof driven through the CLI
+  could not fail for ANY W-severity rule: planting a bare `print()` did not
+  change one byte of output, so the check meant to detect it was
+  structurally incapable of doing so. Every "mutation-proved" green produced
+  that way was unearned. It also broke the premise PS-220's E→W restage
+  (0.36.0) was granted on — that findings stay FULLY VISIBLE and only stop
+  blocking.
+
+  Reporting only; exit codes untouched:
+  - `SUCC` iff zero findings at ANY severity (was: zero at the floor)
+  - the clean line names the audited tree, as the failure line does
+  - the headline always carries both counts: `N error(s), M warning(s)`
+  - counts are taken over all surviving findings, not the floor-filtered view
+  - `--json` gains `warnings` / `infos` alongside the existing `errors`
+  - below-floor findings get a line naming how to list them
+
+  `exit_code` stays `1 if n_errors > 0 else 0`. W/I still never fail CI —
+  changing that would silently re-break every repo the 0.36.0 restage just
+  unblocked.
+
+- **`audit-django` never prints SUCC over live warning findings (#420).**
+  The same defect, reproduced in the Django auditor and fixed the same way.
+  Measured pre-fix on a fixture tree with one live DJ-107 (W) finding: the
+  dirty and clean trees produced path-normalised output comparing EQUAL, and
+  `--json` masked it identically (`"violations": []`, `"errors": 0` on a tree
+  holding one warning).
+
+- **`scitex_dev.audit` survives the logger-class name race (#422).**
+  `scitex_logging.getLogger` IS `logging.getLogger`; the logger class is
+  fixed by `setLoggerClass` state at first creation of the NAME and cached
+  forever. Anything creating `scitex_dev.audit` through the stdlib first
+  handed `_emit` a plain `Logger` with no `.success`, crashing every auditor
+  (`_project` / `_django` / `_api` / `_summary`) — a hard `AttributeError`
+  reachable purely by import ordering. The eager method table dereferenced
+  `.success` on every call, so even `emit('info', ...)` crashed. The level
+  method is now resolved per call via `getattr`; on a poisoned logger the
+  emit goes through `Logger.log(levelno)` — scitex-logging registers level
+  NUMBERS globally (SUCCESS=31 → `SUCC`), so `levelno`/`levelname` are
+  unchanged, not degraded. The degrade is announced once at WARNING and
+  recorded in `degraded_reason()`, so it cannot pass for a healthy run.
+
+- **`cron list` distinguishes "crontab unreadable" from "zero installed"
+  (#413).** `scitex-dev cron list` printed `installed (0): (none)` when it
+  could not read the crontab AT ALL — cannot-look rendered as
+  looked-and-found-zero. Reads failed soft (`read_crontab` returned `""` on a
+  missing binary) while writes failed loud, and only the read path reported.
+  This nearly caused a false fleet-wide automation-outage escalation: a peer
+  agent ran `cron list` in a container with no `crontab` binary, read "13
+  jobs registered, NONE installed", and was one step from escalating. The
+  jobs were running fine on the host; only the container could not look.
+
+  A third state (`CrontabRead` / `read_crontab_state`) is added at the source
+  and plumbed through both reporting surfaces. Human output:
+  `installed: UNKNOWN ('crontab' not found on PATH)` plus an explicit "this
+  is NOT zero jobs installed" note; `cron status` gains a banner and per-job
+  `installed: unknown` instead of a fabricated `no`. JSON: `cron list`
+  reports `installed: null` — NOT `[]`, so a consumer calling `len()` cannot
+  silently read zero — alongside `installed_state` and
+  `installed_unavailable_reason`; `cron status` gains `crontab_state` and
+  `crontab_unavailable_reason`. A non-zero `crontab -l` whose message is
+  `no crontab for <user>` stays READABLE-and-empty: that is an ordinary empty
+  crontab, not a failure to look. The write path is untouched —
+  `write_crontab` still raises, which is correct.
+
+- **`ecosystem test-remote` derives the xdist worker count from the CPU
+  ALLOCATION, not the node (#412).** `pytest -n auto` over-subscribed an
+  allocated node. The cause is narrower than "auto reads the machine's core
+  count": xdist's `pytest_xdist_auto_num_workers` consults psutil FIRST and
+  returns its count immediately, and psutil ignores cgroup/cpuset
+  confinement; only if psutil is absent does it fall through to the correct
+  `sched_getaffinity`. Measured on spartan-bm155 inside a 48-CPU lease
+  cgroup: `sched_getaffinity` 48, `os.cpu_count()` 128,
+  `psutil.cpu_count()` 128 — i.e. ~128 workers into a 48-CPU allocation, a
+  2.7x continuous over-subscription (corroborated by worker ids reaching
+  gw121 in a scitex-hub run). New `allocated_cpus()` in
+  `_core/test_execution.py` resolves `SLURM_CPUS_PER_TASK`, then
+  `SLURM_JOB_CPUS_PER_NODE` (including the `48(x2)` form), then
+  `sched_getaffinity`, then `os.cpu_count()` — no magic cap and no hardcoded
+  core count, so an unconstrained laptop still gets all its cores.
+  `ecosystem test-remote` keeps `-n auto` and corrects it at its source by
+  exporting `PYTEST_XDIST_AUTO_NUM_WORKERS`, which xdist consults ahead of
+  psutil.
+
+### Documentation
+- **Verification doctrine added to `general/09_quality` (#414).** Every
+  verification failure recorded across the fleet on 2026-07-22/23 is one
+  shape: a failed measurement rendered as a confident value. The leaf states
+  that once and organises the defences by claim type — absence claims need a
+  positive control, causal claims need one varied variable and a hunted
+  counter-example, content claims need a second independent reader, artifact
+  claims need the artifact actually in use, peer claims need corroboration
+  independent in kind. Carries the six-state search-failure taxonomy, the
+  vacuous / inert / layer-blind / sampling control failures, the both-arms
+  rule for fixing a masking bug, and the status words that fuse a failed
+  measurement into a clean one (`skipped`, `declared-masked`, `0`).
+
+- **A degrade branch is where a hard failure hides (#418).** Doctrine on
+  masking: degrade paths swallow hard failures, and a mispositioned probe
+  cannot fail.
+
+## [0.36.0] - 2026-07-23
+
+### Changed
+- **PS-220 restaged: WARNING by default, error per-package opt-in.** 0.35.0
+  (#406) promoted PS-220 to ERROR ecosystem-wide. The measured blast radius
+  — 44 repos newly FAILING on 1856 findings, top-5 repos carrying 64 % of
+  them — led the operator to restage the rollout (Telegram 1691/1692):
+  「とりあえず warning で、移行できたものから red で」. The rule now
+  reports at `W` for every project type, and a package opts IN to an
+  error-level gate when its migration lands:
+
+  ```yaml
+  audit:
+    enforce-logging:
+      level: error
+      reason: "print migration complete (PR #412)"
+  ```
+
+  This is staging, not retreat: every finding stays visible on every audit
+  run, and nothing about what the rule DETECTS changed.
+
+- **`audit.enforce-logging` now demands a written reason.** `error` and
+  `off` deviate from the default and so carry a MANDATORY `reason`;
+  `warning` is accepted bare because it IS the default and changes
+  nothing. A missing or whitespace-only reason is a HARD CONFIG ERROR, not
+  a silent default: the declaration does NOT take effect (the project
+  falls back to `W`) AND the rejection is reported at `E`, so a package
+  can never believe it is gated — or silenced — when it is not. The old
+  bare shorthands `enforce-logging: error` / `enforce-logging: off` (and
+  their YAML 1.1 boolean spellings `on` / `off`) are rejected for exactly
+  this reason. Unrecognised values are now rejected loudly instead of
+  falling back silently. Parsing lives in
+  `_cli/audit/_config/_enforce_logging.py`.
+
+  Config errors are NOT staged: a rejected exemption entry and a rejected
+  enforce-logging declaration are both reported at `E` regardless of the
+  project's PS-220 severity. Staging covers migration debt; a malformed
+  override is not debt.
+
+### Removed
+- **The blanket `# noqa` hatch for PS-220, and its `PS-220-noqa-deprecated`
+  notice.** Deprecated in 0.35.0 for one release. A sweep of all 118 repos
+  under `~/proj` (8956 `src/**.py` files, 4448 flagged sites) found ZERO
+  sites using it, with a planted-user control confirming the sweep could
+  detect one. `audit.exemptions` — pinned to one rule at one file:line,
+  with a mandatory reason — is now the only per-site opt-out.
+
+### Fixed
+- **`--version` no longer answers for another package (#409).** `scitex-ui
+  --version` and `scitex-app --version` printed `scitex-dev <scitex-dev's
+  version>`; 36 downstream packages reported another package's identity.
+  `scitex_dev/_cli/__init__.py` fast-paths a bare `--version` to skip the
+  expensive `._root` import, but the predicate matched on `sys.argv[1:]`
+  alone and never checked WHO was asking. Because `scitex_dev._cli` is a
+  shared primitive that downstream CLIs import (`._completion`, `._root`),
+  the block fired during `import` in any process launched as `<other-cli>
+  --version`: it printed scitex-dev's name and version and raised
+  `SystemExit(0)` before the downstream CLI's own `main()` ran. Exit code 0,
+  so nothing looked broken — and the downstream packages' own `--version`
+  wiring was correct all along. The fast path now additionally requires
+  `sys.argv[0]` to identify scitex-dev's own console script (or `python -m
+  scitex_dev`); an unrecognised `argv[0]` declines the optimisation and
+  falls through to the real Click group — correct, just slower. No path
+  falls back to printing `scitex-dev`; that fallback WAS the defect.
+  A library must never read `sys.argv` or exit at import time.
+
 ## [0.35.0] - 2026-07-22
 
 ### Added

{scitex_dev-0.35.0/src/scitex_dev.egg-info → scitex_dev-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitex-dev
-Version: 0.35.0
+Version: 0.37.0
 Summary: Shared developer utilities for the SciTeX ecosystem
 Author-email: Yusuke Watanabe <ywatanabe@scitex.ai>
 License-Expression: AGPL-3.0-only

{scitex_dev-0.35.0 → scitex_dev-0.37.0}/docs/adr/0004-execution-fabric-unified-jobspec.md

@@ -196,7 +196,19 @@ skipped must never count as clean.
 
 | Phase | Scope | Status | Exit criteria |
 | --- | --- | --- | --- |
-| **P1** | **Tests** | Shipped (#385, v0.33.0; design locked by #388) | (a) recipe + `test_execution` knob + auto-loaded `pytest11` guard live (done); (b) literal `-n auto` replaced by allocated-cpus per backend (`$SLURM_CPUS_PER_TASK` / `ResourceSpec.cpu`); (c) at least one `remote-required` package runs end-to-end through the scitex-hpc `slurm` backend and every run emits a conformant `JobReceipt`. |
+| **P1** | **Tests** | Shipped (#385, v0.33.0; design locked by #388) | (a) recipe + `test_execution` knob + auto-loaded `pytest11` guard live (done); (b) literal `-n auto` resolved from allocated-cpus per backend via `scitex_dev._core.test_execution.allocated_cpus` (done for `ecosystem test-remote`); (c) at least one `remote-required` package runs end-to-end through the scitex-hpc `slurm` backend and every run emits a conformant `JobReceipt`. |
+
+> **P1(b) correction (measured 2026-07-23).** An earlier draft of this row
+> named `$SLURM_CPUS_PER_TASK` as *the* source. It is not sufficient: on the
+> Spartan CI runner that variable is **empty**. The runner is reached by ssh
+> and adopted into the lease cgroup (`job_27144058/step_extern`), so it
+> inherits the **cpuset** but not the step's Slurm environment. Measured on
+> spartan-bm155 inside the 48-CPU lease: `sched_getaffinity`=48,
+> `os.cpu_count()`=128, `psutil.cpu_count()`=128, both `SLURM_*` vars unset.
+> `sched_getaffinity` is therefore the authoritative fallback, and the reason
+> `-n auto` misbehaves at all is that pytest-xdist consults **psutil before**
+> `sched_getaffinity` (`xdist/plugin.py` 3.8.0 L26-34) — not, as first
+> assumed, that `auto` is inherently allocation-blind.
 | **P2** | **CI** | Wave 1 in flight (#400 canonical caller; drift inventory 2026-07-21) | (a) every scitex repo carries the thin org-reusable `ci.yml` caller and nothing else (six generations → one); (b) runner labels unified to ONE vocabulary selected via `vars.CI_RUNS_ON`; (c) zero `ubuntu-latest` / GitHub-hosted jobs in scitex repos (PS-169 at ERROR); (d) auditor rule ERRORs on non-canonical workflow files, so drift cannot silently return. |
 | **P3** | **Agent/fleet jobs** | Design open (federation contract 2026-07-20; this ADR fixes the taxonomy) | (a) `scitex_dev.jobs.JobSpec` carries the intent/mechanism split (intents accepted; mechanism chosen at lowering; back-compat mapping for `service`/`timer`/`cron`); (b) zero leaf-local or hand-rolled host crons — every repetitive job discoverable via `scitex-dev ecosystem` from an entry-point provider; (c) sac's daemon/restart passes declared through the federation (sac keeps the logic, scitex-dev installs the schedule); (d) periodic fleet jobs eligible for pool placement (Spartan backfill) where they don't need host-locality. |
 

{scitex_dev-0.35.0 → scitex_dev-0.37.0}/src/scitex_dev/_cli/__init__.py

@@ -19,6 +19,7 @@ must remain importable.
 
 from __future__ import annotations
 
+import os as _os
 import sys as _sys
 
 
@@ -29,10 +30,62 @@ def _is_bare_version_invocation(argv: list[str]) -> bool:
     without spawning a subprocess. Deliberately narrow — any other
     combination (extra flags, a subcommand, ``--version --json``)
     returns False and falls through to the real Click group unchanged.
+
+    NOTE: this predicate inspects ``argv[1:]`` ONLY. It says nothing
+    about WHICH program is running, so it is NOT sufficient on its own
+    to authorise printing scitex-dev's identity — see
+    :func:`_should_fast_path_version`.
     """
     return argv in (["--version"], ["-V"])
 
 
+#: Basenames the `scitex-dev` console script can legitimately appear as
+#: in ``sys.argv[0]``. Anything else is some OTHER program that merely
+#: imported us.
+_ENTRY_POINT_BASENAMES = frozenset({"scitex-dev", "scitex-dev.exe"})
+
+
+def _is_scitex_dev_entry_point(argv0: str) -> bool:
+    """True iff ``argv0`` identifies THIS package's own console script.
+
+    Pure predicate over ``sys.argv[0]``. Recognises the installed
+    console script (``.../bin/scitex-dev``) and ``python -m scitex_dev``
+    (whose ``argv[0]`` is the package's own ``__main__.py``).
+
+    Deliberately CONSERVATIVE: anything unrecognised returns False, and
+    a False merely declines the optimisation — the caller then falls
+    through to the real Click group, which is the correct (just slower)
+    behaviour. Declining is always safe; asserting wrongly is not.
+    """
+    if not argv0:
+        return False
+    tail = argv0.replace("\\", "/")
+    if _os.path.basename(tail) in _ENTRY_POINT_BASENAMES:
+        return True
+    return tail.endswith("/scitex_dev/__main__.py")
+
+
+def _should_fast_path_version(argv: list[str]) -> bool:
+    """True iff this process is scitex-dev's OWN CLI asked for its version.
+
+    BOTH conditions are required, and the second one is the whole point:
+
+    * ``argv[1:]`` is a bare ``--version``/``-V`` (nothing else to do), and
+    * ``argv[0]`` is scitex-dev's own console script.
+
+    The ``argv[0]`` gate exists because this module is a SHARED
+    primitive: scitex-ui, scitex-app and friends import
+    ``scitex_dev._cli._completion`` / ``._root`` to build THEIR CLIs.
+    Without the gate, `scitex-ui --version` imported this package,
+    matched on ``argv[1:]`` alone, printed *scitex-dev's* name and
+    version, and killed the process with ``SystemExit(0)`` — so every
+    downstream CLI confidently reported another package's identity.
+    """
+    if not argv:
+        return False
+    return _is_bare_version_invocation(argv[1:]) and _is_scitex_dev_entry_point(argv[0])
+
+
 # Fast-path a bare `--version`/`-V` invocation BEFORE importing `._root`.
 # `_root`'s module-level code eagerly registers the ENTIRE subcommand
 # tree (ecosystem, linter, gate, ci-runner, docs, skills, …) as a side
@@ -40,7 +93,10 @@ def _is_bare_version_invocation(argv: list[str]) -> bool:
 # needs none of it. `CliRunner.invoke` in tests bypasses `sys.argv`
 # entirely, so this never affects test behavior — only the real
 # console-script invocation (`scitex-dev --version`) sees it.
-if _is_bare_version_invocation(_sys.argv[1:]):
+#
+# This block is an OPTIMISATION, never an identity oracle: it may fire
+# only when `sys.argv` proves the running program IS `scitex-dev`.
+if _should_fast_path_version(_sys.argv):
     from importlib.metadata import PackageNotFoundError
     from importlib.metadata import version as _version
 

{scitex_dev-0.35.0 → scitex_dev-0.37.0}/src/scitex_dev/_cli/audit/_config/__init__.py

@@ -12,6 +12,11 @@ legitimately use test doubles for external services (HTTP/browser/telegram/
 ssh); PA-307 (test-quality) still applies at full severity.
 """
 
+from ._enforce_logging import (
+    ENFORCE_LOGGING_REASONED_LEVELS,
+    ENFORCE_LOGGING_VALUES,
+    parse_enforce_logging,
+)
 from ._loader import (
     CAPABILITY_RULES,
     KNOWN_CAPABILITIES,
@@ -26,6 +31,8 @@ from ._loader import (
 
 __all__ = [
     "CAPABILITY_RULES",
+    "ENFORCE_LOGGING_REASONED_LEVELS",
+    "ENFORCE_LOGGING_VALUES",
     "KNOWN_CAPABILITIES",
     "PROJECT_TYPES",
     "Exemption",
@@ -33,5 +40,6 @@ __all__ = [
     "capability_for_rule",
     "detect_project_types",
     "load_config",
+    "parse_enforce_logging",
     "write_config",
 ]

scitex_dev-0.37.0/src/scitex_dev/_cli/audit/_config/_enforce_logging.py

@@ -0,0 +1,166 @@
+# -*- coding: utf-8 -*-
+"""`audit.enforce-logging` — PS-220's per-package severity declaration.
+
+PS-220 (no bare `print` in package source) is a STAGED rollout, not a
+flag-day. Operator directive 2026-07-23 (Telegram 1691/1692)::
+
+    「print に関しては順次やっていきましょうか。
+      とりあえず warning で、移行できたものから red で」
+    「red というか、エラー判定ってことですね」
+
+i.e. the rule defaults to **warning** for every package, and each package
+opts IN to **error** as it finishes migrating its prints to scitex-logging.
+The measured blast radius is why: promoting to error ecosystem-wide would
+newly fail 44 repos on 1856 findings (`GITIGNORED/ps220-blast-radius-
+20260722.md`), so enforcement has to arrive per-package, on the schedule of
+whoever does the migrating.
+
+The declaration lives in `.scitex/dev/config.yaml`::
+
+    audit:
+      enforce-logging:
+        level: error
+        reason: "print migration complete (PR #412); all sites on scitex-logging"
+
+A REASON IS MANDATORY on any level that deviates from the `warning` default
+— `error` (opt in to being gated) and `off` (hide the findings entirely).
+This follows the same doctrine as `audit.exemptions` and
+`audit.capabilities` in `._loader`: an override is a written decision with a
+named rationale, never a bare flag. A missing or whitespace-only reason is a
+HARD CONFIG ERROR, not a silent default: the declaration does NOT take
+effect (the project falls back to the staged default) AND the rejection is
+surfaced as a violation, so a package cannot believe it is gated when it is
+not — nor believe it is silenced when it is not.
+
+`warning` needs no reason, because writing it changes nothing: it IS the
+default. It is accepted in bare-scalar form for exactly that reason.
+"""
+
+from __future__ import annotations
+
+# Accepted `level` values.
+ENFORCE_LOGGING_VALUES = frozenset({"error", "warning", "off"})
+
+# Levels that DEVIATE from the staged `warning` default and therefore demand
+# a written reason. See the module docstring.
+ENFORCE_LOGGING_REASONED_LEVELS = frozenset({"error", "off"})
+
+_MAPPING_HINT = (
+    "To deviate from the `warning` default, write the mapping form: "
+    "`audit: {{enforce-logging: {{level: {level}, "
+    'reason: "<why this package is at {level}>"}}}}`'
+)
+
+
+def _coerce_level(value: object) -> str | None:
+    """Normalise one `level` scalar to a lowercase string (or None).
+
+    YAML 1.1 parses bare ``off``/``no`` as boolean False and ``on``/``yes``
+    as boolean True, so the level can arrive as a bool rather than a string.
+    Reading it as a string only would make the knob silently no-op and fall
+    back to the default — the exact class of silent-suppression bug this
+    surface exists to prevent. Map the booleans explicitly.
+    """
+    if value is False:
+        return "off"
+    if value is True:
+        return "error"
+    if value is None:
+        return None
+    return str(value).strip().lower() or None
+
+
+def _unknown_level(level: str, *, where: str) -> tuple[None, None, tuple[str, ...]]:
+    """Reject an unrecognised level loudly rather than defaulting silently."""
+    return (
+        None,
+        None,
+        (
+            f"PS-220: `{where}: {level}` is not a recognised level "
+            f"(expected one of {sorted(ENFORCE_LOGGING_VALUES)}). The "
+            f"declaration does NOT take effect.",
+        ),
+    )
+
+
+def parse_enforce_logging(
+    raw: object,
+) -> tuple[str | None, str | None, tuple[str, ...]]:
+    """Split `audit.enforce-logging` into ``(level, reason, rejections)``.
+
+    ``level`` is None when nothing was declared OR when what was declared was
+    REJECTED — in both cases the caller falls back to PS-220's staged default.
+    ``rejections`` holds human-readable notices for every rejected form; an
+    empty tuple means the block was clean.
+
+    Accepted forms:
+
+    * a mapping ``{level: <error|warning|off>, reason: <non-blank>}`` — the
+      canonical form. ``reason`` is mandatory for ``error`` and ``off``.
+    * a bare scalar ``warning`` — accepted reasonlessly because it is the
+      default and therefore changes nothing.
+
+    Rejected forms (each returns ``level=None`` plus a notice):
+
+    * a bare scalar ``error`` / ``off`` (including the YAML 1.1 booleans
+      ``on`` / ``true`` / ``off`` / ``no``) — carries no reason.
+    * a mapping whose ``level`` is missing or unrecognised.
+    * a mapping declaring ``error`` / ``off`` with a missing, empty, or
+      whitespace-only ``reason``.
+    """
+    if raw is None:
+        return None, None, ()
+
+    if isinstance(raw, dict):
+        level = _coerce_level(raw.get("level"))
+        reason = str(raw.get("reason") or "").strip()
+        if level is None:
+            return (
+                None,
+                None,
+                (
+                    "PS-220: `audit.enforce-logging` mapping is missing `level` "
+                    f"(one of {sorted(ENFORCE_LOGGING_VALUES)}). The "
+                    f"declaration does NOT take effect.",
+                ),
+            )
+        if level not in ENFORCE_LOGGING_VALUES:
+            return _unknown_level(level, where="audit.enforce-logging.level")
+        if level in ENFORCE_LOGGING_REASONED_LEVELS and not reason:
+            return (
+                None,
+                None,
+                (
+                    f"PS-220: `audit.enforce-logging.level: {level}` REJECTED "
+                    f"— `reason` is empty. Declaring `{level}` deviates from "
+                    f"the staged `warning` default and must state WHY. The "
+                    f"declaration does NOT take effect.",
+                ),
+            )
+        return level, (reason or None), ()
+
+    level = _coerce_level(raw)
+    if level is None:
+        return None, None, ()
+    if level not in ENFORCE_LOGGING_VALUES:
+        return _unknown_level(level, where="audit.enforce-logging")
+    if level in ENFORCE_LOGGING_REASONED_LEVELS:
+        return (
+            None,
+            None,
+            (
+                f"PS-220: `audit.enforce-logging: {level}` REJECTED — the bare "
+                f"shorthand carries no reason. " + _MAPPING_HINT.format(level=level)
+                + " The declaration does NOT take effect.",
+            ),
+        )
+    return level, None, ()
+
+
+__all__ = [
+    "ENFORCE_LOGGING_VALUES",
+    "ENFORCE_LOGGING_REASONED_LEVELS",
+    "parse_enforce_logging",
+]
+
+# EOF