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

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

@@ -7,6 +7,72 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitex-dev
-Version: 0.35.0
+Version: 0.36.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.36.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.36.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.36.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

{scitex_dev-0.35.0 → scitex_dev-0.36.0}/src/scitex_dev/_cli/audit/_config/_loader.py

@@ -69,9 +69,15 @@ CAPABILITY_RULES: dict[str, frozenset[str]] = {
 
 KNOWN_CAPABILITIES = frozenset(CAPABILITY_RULES)
 
-# Accepted values for the `audit.enforce-logging` knob (PS-220). See
-# `ProjectConfig.enforce_logging` and `_check_no_print.resolve_ps220_severity`.
-ENFORCE_LOGGING_VALUES = frozenset({"error", "warning", "off"})
+# `audit.enforce-logging` — PS-220's per-package severity declaration. The
+# parsing (and the MANDATORY-reason rule on any level that deviates from the
+# staged `warning` default) lives in `._enforce_logging`; re-exported here so
+# existing importers of the loader keep working.
+from ._enforce_logging import (  # noqa: E402
+    ENFORCE_LOGGING_REASONED_LEVELS,
+    ENFORCE_LOGGING_VALUES,
+    parse_enforce_logging,
+)
 
 
 # Per-SITE rule EXEMPTION with a MANDATORY written reason (operator directive
@@ -179,14 +185,20 @@ class ProjectConfig:
     capabilities: frozenset[str] = frozenset()
     exemptions: tuple[Exemption, ...] = ()
     exemption_errors: tuple[str, ...] = ()
-    # `audit.enforce-logging` — explicit knob for the PS-220 no-bare-print
-    # mandate: "error" | "warning" | "off". None means "use the project-type
-    # default" (see `_check_no_print.resolve_ps220_severity`): ERROR for
-    # ecosystem packages, WARNING for research projects, because the operator
-    # has NOT yet decided whether the logging mandate binds paper-producing
-    # research trees. Any unrecognised value is ignored (falls back to the
-    # default) rather than silently disabling the gate.
+    # `audit.enforce-logging` — the PS-220 no-bare-print STAGED-ROLLOUT knob:
+    # "error" | "warning" | "off". None means "use the default" (see
+    # `_check_no_print.resolve_ps220_severity`), which is WARNING for every
+    # project type: the operator staged the rollout so each package opts IN to
+    # `error` once its print migration is done.
+    #
+    # `error` and `off` deviate from that default and so carry a MANDATORY
+    # written `reason` (kept in `enforce_logging_reason`). A declaration that
+    # was rejected — bare shorthand, unknown level, blank reason — leaves this
+    # None and records why in `enforce_logging_errors`, so a rejected opt-in
+    # never silently reads as either enforced or silenced.
     enforce_logging: str | None = None
+    enforce_logging_reason: str | None = None
+    enforce_logging_errors: tuple[str, ...] = ()
     whitelist_path: Path | None = None
     metadata: dict = field(default_factory=dict)
     source: str = "config"  # "config" | "heuristic" | "override"
@@ -422,19 +434,11 @@ def load_config(
         wl = audit.get("whitelist")
         exemptions, exemption_errors = _parse_exemptions(audit.get("exemptions"))
         raw_enforce = audit.get("enforce-logging", audit.get("enforce_logging"))
-        # YAML 1.1 parses bare `off`/`no` as boolean False and `on`/`yes` as
-        # True, so `enforce-logging: off` arrives as a bool, not the string.
-        # Reading it as a string would make the knob silently no-op and fall
-        # back to the default — the exact class of silent-suppression bug this
-        # whole change is about. Map the booleans explicitly.
-        if raw_enforce is False:
-            enforce_logging = "off"
-        elif raw_enforce is True:
-            enforce_logging = "error"
-        else:
-            enforce_logging = str(raw_enforce).strip().lower() if raw_enforce else None
-        if enforce_logging not in ENFORCE_LOGGING_VALUES:
-            enforce_logging = None
+        (
+            enforce_logging,
+            enforce_logging_reason,
+            enforce_logging_errors,
+        ) = parse_enforce_logging(raw_enforce)
         return ProjectConfig(
             project_types=types,
             skip=frozenset(skip),
@@ -442,6 +446,8 @@ def load_config(
             exemptions=exemptions,
             exemption_errors=exemption_errors,
             enforce_logging=enforce_logging,
+            enforce_logging_reason=enforce_logging_reason,
+            enforce_logging_errors=enforce_logging_errors,
             whitelist_path=Path(wl) if wl else None,
             metadata=raw.get("metadata") or {},
             source=source,
@@ -488,6 +494,8 @@ __all__ = [
     "CAPABILITY_RULES",
     "KNOWN_CAPABILITIES",
     "ENFORCE_LOGGING_VALUES",
+    "ENFORCE_LOGGING_REASONED_LEVELS",
+    "parse_enforce_logging",
     "capability_for_rule",
     "Exemption",
     "ProjectConfig",