Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature/Log-call-conventions · L-260927-f00d9b (#1393)
Louis Choquela3e0fce983ab
diff --git a/.github/workflows/lint-check.yml b/.github/workflows/lint-check.ymlindex 691654abf..c73711812 100644--- a/.github/workflows/lint-check.yml+++ b/.github/workflows/lint-check.yml@@ -208,6 +208,39 @@ jobs:- name: Run Actions allowlist checkrun: make check-actions-allowlist+# --------------------------------------------------------------------------+# 6c. Log calls — single job, version-independent (the guard renders each+# call's signature the same on every supported Python). A message at INFO+# and above is a literal with its values in fields, and no message holds+# Rich markup, against the committed log_call_baseline.toml, which only+# shrinks: the check compares it with the baseline at the pull request's+# base, fetched here since the checkout holds only the merge commit, and+# refuses an entry the base does not list.+# --------------------------------------------------------------------------+ lint-log-calls:+ name: Lint (log calls)+ runs-on: ubuntu-latest+ env:+ VIRTUAL_ENV: ${{ github.workspace }}/.venv++ steps:+ - uses: actions/checkout@v4++ - name: Install uv (with cache)+ uses: astral-sh/setup-uv@v7+ with:+ enable-cache: true+ cache-dependency-glob: "uv.lock"++ - name: Install dependencies+ run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install++ - name: Fetch the pull request's base+ run: git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.sha }}"++ - name: Run log-call check+ run: make check-log-calls LOG_CALL_BASELINE_REF="${{ github.event.pull_request.base.sha }}"+# --------------------------------------------------------------------------# 7. Drift contracts — single job, version-independent# BLOCKING, but through the ruleset rather than through lint-all: `Lint@@ -309,14 +342,14 @@ jobs:# 10. Aggregator job — the required status check that covers every lint job,# including the ones the rulesets do not name individually# (`Lint (hub layering)`, `Lint (rich imports)`, `Lint (actions allowlist)`,-# `Lint (agent-rules)`, `Lint (api)`). It is not the only required lint check: the rulesets name+# `Lint (log calls)`, `Lint (agent-rules)`, `Lint (api)`). It is not the only required lint check: the rulesets name# several of the jobs above by name as well. Anything added to `needs`# becomes blocking through here.# --------------------------------------------------------------------------lint-all:name: Lint (all)runs-on: ubuntu-latest- needs: [lint-ruff-plxt, lint-typecheck, lint-config-sync, lint-keyword-only, lint-hub-layering, lint-rich-imports, lint-actions-allowlist, lint-agent-rules, lint-api]+ needs: [lint-ruff-plxt, lint-typecheck, lint-config-sync, lint-keyword-only, lint-hub-layering, lint-rich-imports, lint-actions-allowlist, lint-log-calls, lint-agent-rules, lint-api]if: always()steps:@@ -329,6 +362,7 @@ jobs:[ "${{ needs.lint-hub-layering.result }}" != "success" ] || \[ "${{ needs.lint-rich-imports.result }}" != "success" ] || \[ "${{ needs.lint-actions-allowlist.result }}" != "success" ] || \+ [ "${{ needs.lint-log-calls.result }}" != "success" ] || \[ "${{ needs.lint-agent-rules.result }}" != "success" ] || \[ "${{ needs.lint-api.result }}" != "success" ]; thenecho "::error::At least one lint job failed."diff --git a/.github/workflows/lint-fresh-check.yml b/.github/workflows/lint-fresh-check.ymlindex 6afb812c9..24f5e2567 100644--- a/.github/workflows/lint-fresh-check.yml+++ b/.github/workflows/lint-fresh-check.yml@@ -70,6 +70,21 @@ jobs:- name: Run Rich import checkrun: make check-rich-imports+ # The baseline only shrinks: a pull request is compared with the baseline at+ # its base, fetched since the checkout holds only the merge commit. A manual+ # run has no base to compare with, and says so.+ - name: Run log-call check+ env:+ BASE_SHA: ${{ github.event.pull_request.base.sha }}+ run: |+ if [ -n "$BASE_SHA" ]; then+ git fetch --no-tags --depth=1 origin "$BASE_SHA"+ make check-log-calls LOG_CALL_BASELINE_REF="$BASE_SHA"+ else+ echo "A ${{ github.event_name }} run has no pull request base: the log-call baseline is checked against the tree, without the comparison that refuses an added entry."+ make check-log-calls+ fi+- name: Run drift contracts checkrun: make drift-checkdiff --git a/AGENTS.md b/AGENTS.mdindex 89d9a7213..b98e4cb68 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -9,7 +9,7 @@```bashmake agent-check# If the current system doesn't have the `make` command,- # lookup the "agent-check" target in the Makefile and run the commands one by one (targets fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist drift-check api-agent-check)+ # lookup the "agent-check" target in the Makefile and run the commands one by one (targets fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check)```This runs multiple code quality tools:@@ -202,6 +202,7 @@pretty_print(output_object, title="Your first Pipelex output")```- Both handle formatting json using Rich, pretty_print makes it prettier.+- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.#### StrEnum and Self typediff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8c8f95d0a..0d8ef44ba 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,10 +4,12 @@### Added-- **The console shows a log call's fields and renders named layouts**: the `console` sink prints a record's fields after its message as a `key=value` suffix, `Scanned the inputs files=7`, each value on one line and cut short when long, leaving out the run identifiers, and colours a value by its field's name, a pipe code red and a concept bold green, with any other field dimmed. A call can name a console layout with `layout=`, a Rich template over its fields in which every value is escaped, starting with `LogLayout.PIPE_RUN` for the pipe-run tree; every other sink writes the plain message and the fields.+- **The console shows a log call's fields and renders named layouts**: the `console` sink prints a record's fields after its message as a `key=value` suffix, `Scanned the inputs files=7`, each value on one line and cut short past 80 characters, a handled exception's `error.message` only past 2000, leaving out the run identifiers, and colours a value by its field's name, a pipe code red and a concept bold green, with any other field dimmed. A call can name a console layout with `layout=`, a Rich template over its fields in which every value is escaped, starting with `LogLayout.PIPE_RUN` for the pipe-run tree; every other sink writes the plain message and the fields.+- **Log-call conventions and their guard**: the logging documentation states how Pipelex's own log calls are written, a fixed message with its values in `fields` named from a shared vocabulary, an exception carried by the record rather than spliced into the text, no run identifier, payload, markup or emoji, and what each level promises. `make check-log-calls` (`pipelex-dev check-log-calls`), part of `make agent-check` and CI, refuses an interpolated or non-literal message at `INFO` and above and a Rich markup tag in a message at any level, against a committed baseline of the existing calls that only shrinks: `--against <ref>` and `--against-merge-base <ref>` refuse an entry the baseline at the base revision does not list, which CI runs against a pull request's base and `make` against the merge base with `origin/dev`. `pipelex.tools.log.error_fields` gives a handled exception's class and text as the `error.type` and `error.message` fields of a warning, which carries no traceback.### Changed+- **Library-loading warnings carry their values as fields**: the warnings logged while a library loads, for an unparseable `METHODS.toml`, an unsatisfied or unparseable `mthds_version`, a dependency with no valid bundle or a pipe that would not load, an unresolvable method package and the teardown of a stale library, each have one fixed message and carry the package address, the dependency alias, the pipe code and the error as fields, where they used to splice those values into the text.- **The pipe announcement is a plain message with fields**: every live pipe run logs `Pipe run starts` with `pipe_type`, `pipe_code`, `output_concept` and `pipe_depth` as fields, where the `json`, `otlp` and `gcp` sinks used to receive Rich markup inside the message, and the console draws the same coloured pipe tree from those fields through `LogLayout.PIPE_RUN`. The warning that a model's fixed temperature replaced the requested one carries its values as fields in the same way: `model_handle`, `backend_name`, `sdk`, the model's handle under `gen_ai.request.model` and the provider's model id under `gen_ai.response.model` as on the LLM call's span, the requested temperature under `gen_ai.request.temperature`, and `fixed_temperature`; the verbose line saying a model's settings were not checked, since its backend's SDK is not installed, carries the same model fields.### Fixeddiff --git a/CLAUDE.md b/CLAUDE.mdindex 78ae86133..f505697bf 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -4,7 +4,7 @@`make` targets activate the virtual environment themselves; anything else (`pytest`, `pipelex`, `pipelex-dev`) runs from `.venv/bin/` (`.venv\Scripts\` on Windows), never bare. The Makefile is the reference for every target and alias; without `make`, read the target there and run its prerequisites one by one.-- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist drift-check api-agent-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check, the Rich import check (`cri`: Rich is the `cli` extra, so no module outside `pipelex/cli/` imports it at module level or reaches it through a CLI module), the Actions allowlist check (`caa`: every workflow action must be one `.github/actions-allowlist.toml` allows), the drift contracts, and the server's own gate. The drift digest reads the git index, so stage your changes before the check.+- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check, the Rich import check (`cri`: Rich is the `cli` extra, so no module outside `pipelex/cli/` imports it at module level or reaches it through a CLI module), the Actions allowlist check (`caa`: every workflow action must be one `.github/actions-allowlist.toml` allows), the log-call check (`clc`: a log message at INFO and above is a literal with its values in `fields=`, and no log message holds Rich markup, against `log_call_baseline.toml`, which only shrinks: the check refuses an entry the baseline at the merge base with `origin/dev` does not list; see `docs/contribute/log-calls.md`), the drift contracts, and the server's own gate. The drift digest reads the git index, so stage your changes before the check.- **The Pipelex API server is the `api/` workspace member** (the `pipelex-api` distribution, package `pipelex_api`; its guide is `api/CLAUDE.md`). It runs the pipelex of the same commit from its own environment, `api/.venv`, which its targets provision themselves. `make agent-check` ends with `api-agent-check` (`make -C api agent-check`: its install, ruff, pyright, mypy, and the drift checks of its OpenAPI artifact and of its vendored inference tree) and `make agent-test` with `api-agent-test`, so a library change that breaks the server, moves its wire or leaves its inference tree behind fails in the same change. A kit change reaches the server's tree through `make up-kit-configs` (`ukc`); a change to the server's wire is committed with `make -C api openapi-export`.- **Keyword-only arguments** (the convention is in the standards and in `docs/contribute/keyword-only-arguments.md`): `make check-keyword-only` (`cko`) is the gate, `make fix-keyword-only` (`fko`) inserts the bare `*` where it can — on ungranted subjects too — and reports the shapes it cannot fix, and `make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"` (`sgr`) grants a positional subject. Grant before `make agent-check`, which runs the fixer.- **Drift contracts.** When `make drift-check` reports an open contract: `make drift-plan`, review and fix the stale targets, `git add` the trigger files, then `make drift-ack CONTRACT=<id> RATIONALE="<verdict>: …"`, the rationale opening with its verdict, `real-catch`, `clean-pass` or `friction`. No bypass flag; "clean-pass: reviewed, no doc change needed" is a legitimate rationale. See `docs/contribute/drift-contracts.md` and the `/drift-review` skill.diff --git a/Makefile b/Makefileindex e670554a1..2af1104c8 100644--- a/Makefile+++ b/Makefile@@ -185,6 +185,8 @@ make check-rich-imports - Refuse a module-level Rich import or reach outsimake cri - Shorthand -> check-rich-importsmake check-actions-allowlist - Refuse a workflow action outside the committed Actions allowlistmake caa - Shorthand -> check-actions-allowlist+make check-log-calls - Refuse an interpolated log message at INFO+ and Rich markup in any log message, against a baseline that only shrinks from origin/dev's merge base (LOG_CALL_BASELINE_REF=<ref> to compare with another)+make clc - Shorthand -> check-log-callsmake check-TODOs - Check for TODOsmake docs - Serve documentation locally with mkdocs@@ -224,7 +226,7 @@ export HELP.PHONY: \all help env env-verbose check-uv check-uv-verbose lock install update build \format lint ruff-format ruff-lint pyright mypy pylint plxt plxt-format plxt-lint \- rules rules-claude-standalone up-kit-configs ukc check-config-sync ccs check-keyword-only cko fix-keyword-only fko subject-grant sgr check-hub-layering chl check-rich-imports cri check-actions-allowlist caa check-rules check-urls cu insert-skeleton \+ rules rules-claude-standalone up-kit-configs ukc check-config-sync ccs check-keyword-only cko fix-keyword-only fko subject-grant sgr check-hub-layering chl check-rich-imports cri check-actions-allowlist caa check-log-calls clc check-rules check-urls cu insert-skeleton \drift-plan dp drift-check dc drift-ack da \cleanderived cleanenv cleanall \test test-xdist t test-quiet tq test-with-prints tp test-inference ti \@@ -417,6 +419,17 @@ check-actions-allowlist: envcaa: check-actions-allowlist@echo "> done: caa = check-actions-allowlist"+# The revision the log-call baseline may only shrink from. Empty, the default, it is the merge base of HEAD and+# origin/dev, and the check says so when that does not resolve; CI sets it to the pull request's base.+LOG_CALL_BASELINE_REF ?=++check-log-calls: env+ $(call PRINT_TITLE,"Holding log calls to the log-call conventions against the shrinking baseline")+ $(VENV_PIPELEX_DEV) check-log-calls --quiet $(if $(LOG_CALL_BASELINE_REF),--against "$(LOG_CALL_BASELINE_REF)",--against-merge-base origin/dev)++clc: check-log-calls+ @echo "> done: clc = check-log-calls"+drift-plan: env$(VENV_PIPELEX_DEV) drift plan $(CONTRACT)@@ -1283,10 +1296,10 @@ cc: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet generaup: generate-mthds-schema-quiet generate-corpus-vocabulary-quiet up-kit-configs rules@echo "> done: up = generate-mthds-schema generate-corpus-vocabulary up-kit-configs rules"-check: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet check-unused-imports check-config-sync check-rules check-urls check-mthds-schema check-ledger check-migration-schemas check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist drift-check format lint pyright mypy pylint+check: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet check-unused-imports check-config-sync check-rules check-urls check-mthds-schema check-ledger check-migration-schemas check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check format lint pyright mypy pylint@echo "> done: check"-agent-check: fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist drift-check api-agent-check+agent-check: fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check@echo "> done: agent-check"v: validatediff --git a/docs/api-server/logging.md b/docs/api-server/logging.mdindex 290fcc252..531c5ddc3 100644--- a/docs/api-server/logging.md+++ b/docs/api-server/logging.md@@ -53,7 +53,7 @@ A key whose value is not set for this request is **absent** from the line rather`detail` is the one field whose absence follows the failure's origin rather than the request's shape, and it is worth knowing which way round. A failure this API authored itself — a validation error, an unknown model category — carries `detail` on the record. A failure that arrives as a Pipelex `ErrorReport`, which is most `5xx` and every domain error, does not: the response body still carries a `detail`, but the record does not, because the body's text has been through disclosure redaction and the cause has not. So a `4xx` from that path logs as `API error 422: SomeError` with no explanation and no traceback, and the response is where the explanation is. Build an operator query on `error_type` and `route`, which every line carries, rather than on `detail`.-Every field in that table is a **record attribute**, which is a different thing from the message. A structured sink — `json` here, and the OTLP sink — writes them beside the message as keys. The Rich console sink shows them after the message as a `key=value` suffix, each value on one line and cut short when long, and leaves out the run identifiers (`request_id`, `pipeline_run_id`), which a person at a terminal does not need on every line, so `API error 500: PipelexConfigError` is followed by the route, the status and the rest of the fields above. That rendering is for a person reading a terminal; keep `sink = "json"` wherever the lines are read by anything else.+Every field in that table is a **record attribute**, which is a different thing from the message. A structured sink — `json` here, and the OTLP sink — writes them beside the message as keys. The Rich console sink shows them after the message as a `key=value` suffix, each value on one line and cut short when long, a handled exception's `error.message` at a far more generous length, and leaves out the run identifiers (`request_id`, `pipeline_run_id`), which a person at a terminal does not need on every line, so `API error 500: PipelexConfigError` is followed by the route, the status and the rest of the fields above. That rendering is for a person reading a terminal; keep `sink = "json"` wherever the lines are read by anything else.Disposition follows the HTTP status, not the error domain: a `4xx` is a caller mistake and logs at `WARNING` without a traceback; a `5xx` is a server fault and logs at `ERROR` with one. See [Error Responses](error-responses.md) for the response side of the same failure.diff --git a/docs/contribute/log-calls.md b/docs/contribute/log-calls.mdnew file mode 100644index 000000000..157973dc0--- /dev/null+++ b/docs/contribute/log-calls.md@@ -0,0 +1,110 @@+---+title: "Log-Call Guard"+description: "The guard that holds Pipelex's own log calls to the log-call conventions: what it reads, what it refuses, and the baseline that only shrinks."+---++# Log-call guard++Pipelex's log calls follow the [log-call conventions](../tools/logging.md#log-call-conventions): a fixed message, its values in `fields`, no markup. Most of them are for review; the ones that can be read off the source are held by `make check-log-calls` on every call: a message at INFO and above is a literal written at the call, and no message holds Rich markup at any level. This page is the guard's specification. The calls that broke the rules when the guard arrived are listed in a committed baseline that can only shrink, so that new code is held to the conventions from the start while the existing calls are converted.++## What it reads++The guard parses every Python module in `pipelex/`, except the facade's own package `pipelex/tools/log/`, and in the API server's `api/pipelex_api/`, which logs through the same facade. It reads the calls of the `log` facade, however a module reaches it: the name it imports `log` under, from `pipelex` or from `pipelex.tools.log.log`, an alias, a relative import and a star import included, or an attribute path through a module it imports, `pipelex.log.warning(...)` after `import pipelex`, `m.log.info(...)` after `from pipelex.tools.log import log as m`, `x.log.info(...)` after `import pipelex.tools.log.log as x`. The receiver is read where the call is made, through the bindings of its name that can reach the call, as a message's names are below: it is the facade when one of them imports the facade, so a parameter or a local named `log`, a stdlib logger say, is not the facade, and neither is a `log` imported in another function. A call's message is its first positional argument, or its `content=` keyword, and its `title=` and `inline=` keywords count as part of it, since the dispatch renders both into the message. A title or an inline title that is statically `None`, `title=None` or a name bound only to `None` and literals, is no message text at all. A `**` expansion of a dict literal whose keys are all strings passes its `content`, `title` and `inline` entries like keywords, `log.warning(**{"content": f"Value {value}"})` being read as `log.warning(content=f"Value {value}")`; any other `**` expansion in a facade call, `log.warning(**params)`, could carry the message or a title, so the call is refused as `non-literal`, at every level, since neither rule can read through it.++## The rules++### A literal message at INFO and above++On `log.info`, `log.warning`, `log.error` and `log.critical`, the message is a literal written at the call. These are accepted:++- a string constant, implicit concatenation of constants included;+- an f-string without a placeholder;+- a `+` between literals, or a conditional expression between literals;+- a name whose every binding that can reach the call is one of the above, `msg += " the library"` and `msg = msg + " the library"` included when what is added is a literal.++Anything else is refused, under the name of its form:++| Rule | What it refuses |+| --- | --- |+| `f-string` | An f-string with a placeholder, `f"Loaded '{alias}'"` |+| `percent-format` | A `%` format, `"Loaded %s" % alias`, or a name formatted with `%=` |+| `concatenation` | A `+` with a side that is not a literal, `"Loaded " + alias`, or a name extended with `+=` by something that is not |+| `format-call` | A `.format()` call, `"Loaded {}".format(alias)` |+| `non-literal` | Any other expression: a parameter, an attribute, a call's result, a mapping or a model, and a `**` expansion the guard cannot read |++A name is resolved by Python's own scoping. The scope the call is made in comes first, a comprehension reading as part of the scope it is written in; then the enclosing functions, a class body never being one; then the module.++Within that scope, only the bindings that can reach the read count, by the scope's control flow: along straight-line code, the nearest binding before the read; across the branches of an `if`, a `try` or a `match`, the nearest on each path, a handler seeing whatever its `try` body had bound by then; in a loop, a binding later in its body too, which the next pass carries back; and after a `return`, a `raise`, a `break` or a `continue`, nothing. So `msg = "Loaded"`, `log.info(msg)`, then `msg = f"Could not load {alias}"` and `raise ValueError(msg)` passes: the later binding cannot reach the call, and stays out of its signature. A binding's own value is read where that binding stands, so in `msg = msg + "red]Loaded"` the `msg` added to is the one bound before. Where the flow depends on what runs, the guard counts what may: a `with` body may stop at any line, since its context manager may swallow an exception, and a comprehension's body may run any number of times. A module name read from a class body counts the module's bindings that reach the class statement; read from a function, also every module binding made after the function's definition, since the function may be called at any later point. A `global` or `nonlocal` assignment counts as a binding of the scope that owns the name, and reaches every read of it, since the function making it may run at any time. One index of every scope's bindings and control flow is built per module, in one walk, then each scope's flow is run once, so a lookup never reads a scope again.++A binding is what Python counts as one: an assignment to the name itself or through a tuple, a list or a starred target, an annotated or augmented assignment, a `:=`, a `for`, `with` or `except ... as` target, a comprehension target, a `match` capture, a parameter of a function or a lambda, an import and a definition. An assignment that only mentions the name, `cache[msg] = 1` or `msg.attr = value`, does not rebind it. A name bound to an f-string is refused as an `f-string`, the report naming the line of the binding; a name bound by anything the guard does not read, a parameter, a loop or comprehension target, a `with` or `except` target, a `match` capture, an unpacking, an import, or not bound at all, is `non-literal`. A name bound in an enclosing function is not followed, and is `non-literal` too, whatever the module binds under the same name.++The `non-literal` rule is the guard's choice rather than the conventions' letter: it refuses a message built elsewhere and passed in, by a helper or a caller, because nothing can tell that such a message is fixed, and every one the first census found was in fact built from values. A message that must vary is a fixed message with fields. A structured content, a mapping or a model logged as the message, is `non-literal` at INFO and above for the same reason: its values belong in fields, and its payload belongs nowhere.++`log.debug` and `log.verbose` are outside this rule: a person at a terminal reads them, and an f-string is allowed there.++### No markup at any level++On every method, `log.verbose` and `log.debug` included, no literal text of a message, its title or its inline title holds a Rich markup tag. The literal text is the string constants written at the call, the literal parts of an f-string, the format string of a `%` or a `.format()`, and the literals a name read as above is bound to. It is read the way it reaches the console: a `+` whose operands are known, named literals, `+=` extensions and a name rebuilt from itself included, is folded into one text before the scan, so `"[" + "red]Loaded"` holds `[red]`, while a value the guard cannot read keeps the texts around it apart.++A markup tag is what Rich reads as one, matched with Rich's own tag pattern:++- a closing tag, `[/red]` or `[/]`;+- an `@` handler, `[@click=app.bell]`;+- an opening tag whose text Rich parses as a style, `[red]`, `[bold green]`, `[on blue]`, `[link=https://pipelex.com]`, or names a style of Rich's default theme, `[repr.number]`.++A bracketed word that is no style, `list[int]`, `[Errno 2]` or `items[index]`, is text and passes, and so does a tag escaped with a backslash. The tests that check the messages a live run logs, described under [Messages are plain text](../tools/logging.md#messages-are-plain-text), read tags by this same rule, the guard's `find_markup_tags`, so the source and the run are held to one definition.++## The baseline++`log_call_baseline.toml`, at the repo root, lists every call that broke a rule when the guard arrived. Its key is the call's file and enclosing qualified name, `<relative_path>::<qualified_name>`, the classes and functions joined by dots, or `<module>` for a call made at module level. Under the key, each call is listed by its **signature**, once per call that carries it. A signature is the call's method, its message's source text with any `**` expansion it cannot read, the rules it breaks between brackets, and, after `where`, every binding the guard read to judge it, sorted, which is every binding that can reach the names it read, a binding it does not read written as what binds it (`<parameter>`, `<for target>`, `<enclosing function>`, `<unbound>`):++```toml+version = 1++["pipelex/methods/fetch_on_miss.py::resolve_address_based_method"]+calls = [+ "info: f\"Fetched method '{fetched.full_address}' at commit {fetched.commit_sha} and installed it into '{installed.path}'\" [f-string]",+]++["pipelex/pipe_run/pipe_run.py::PipeRun._build_pipe_io_artifacts_on_output"]+calls = [+ "warning: message [f-string] where message = f\"Failed to build the I/O artifacts for pipeline_run_id={pipeline_run_id}: {build_error}\"",+]+```++So the identity of a call is what it logs, not only how the call is written: rewording the f-string a grandfathered `log.warning(message)` is bound to, or adding markup to a module constant its message concatenates, changes its signature, and the exemption is spent. A line number never enters the baseline, so an edit elsewhere in a file moves nothing. A signature is rendered the same on every Python the check runs on: `ast.unparse` writes an f-string by quoting rules that changed with Python 3.12, so the guard writes f-strings itself, and everything else through `ast.unparse`, whose output for other expressions does not move. The file is written through the repo's TOML writer (`pipelex/tools/misc/toml_utils.py`, tomlkit), laid out exactly as `make format` leaves it, so a prune moves nothing else.++The comparison is exact, both ways:++- **A call the baseline does not list fails the check.** That is every new call that breaks a rule, and a second identical call beside a listed one.+- **A listed signature no call carries any more fails the check too**, until it is removed from the file: the call now complies, or it moved to another function, or its message, a binding of it or the rules it breaks changed. The check names the stale signature.++So changing a listed call's message, or moving the call, is converting it: its old signature goes stale, and the new form must comply, since nothing lists it.++### It only shrinks++Agreeing with the tree is not enough, since a change could add a violating call and its entry together. So the check also holds the baseline to the one committed at a trusted revision, the base the change merges into, read with `git show <ref>:log_call_baseline.toml`: a signature the working baseline lists more times than the trusted one, a new entry or a higher count, fails, named under its key with both counts. Removing an entry, or a call, always passes. A trusted revision that runs the guard but holds no baseline file has an empty one; a revision from before the guard existed has nothing to compare with, and the check says so and runs against the tree alone. A trusted revision that does not resolve, or whose baseline is of another `version`, fails the check: a gate that cannot compare does not pass. A future change to the signature's format bumps `version` and has to teach the comparison to read the previous one.++The baseline is never added to. It is the debt the conversion of the existing calls pays off, and it ends empty.++## Running it++`make check-log-calls`, alias `make clc`, runs `pipelex-dev check-log-calls --quiet --against-merge-base origin/dev`, so a local run holds the baseline to the one at the merge base of `HEAD` and `origin/dev`, and says plainly when that merge base does not resolve, `origin/dev` not fetched for instance. `make check-log-calls LOG_CALL_BASELINE_REF=<ref>` compares with another revision. It is part of `make agent-check` and `make check`. CI runs it as the `Lint (log calls)` job, which `Lint (all)` requires, fetching the pull request's base and passing it as `LOG_CALL_BASELINE_REF`, and in the pre-main fresh check the same way; a manual run of the fresh check has no pull request base, and says it checks the tree alone. Run directly, the command takes these options:++- `--quiet` keeps a pass to one line, which says how many calls the baseline still lists and, when it compared, that it adds nothing to the trusted revision; a failure always prints in full.+- `--prune` removes the stale signatures from the baseline, then checks. It never adds one, so a call the baseline does not list still fails.+- `--report` prints the baseline's calls by package area, the largest first, and gates nothing: the measure of what is left to convert.+- `--against <ref>` holds the baseline to the one committed at `<ref>`, which must resolve.+- `--against-merge-base <ref>` holds it to the one at the merge base of `HEAD` and `<ref>`, and skips the comparison, saying so, when that merge base does not resolve. It and `--against` are exclusive.++A failure lists each call the baseline does not list, at its file and line, with its enclosing qualified name and every rule it breaks, then each rule's remedy, then each stale signature under its key, then each signature added since the trusted revision.++## Converting a call++1. Rewrite the call by the [conventions](../tools/logging.md#log-call-conventions): a fixed message, its values in `fields` under the names of the vocabulary table, a handled exception through `error_fields` at WARNING and below or `include_exception=True` at ERROR and above.+2. Run `make check-log-calls`. It reports the call's signature as stale; editing what a listed call logs without converting it reports the old signature as stale and the new one as unlisted.+3. Remove the signature, by hand or with `.venv/bin/pipelex-dev check-log-calls --prune`, and commit the file with the change.++`pipelex/libraries/library_manager.py` is the worked example: every one of its calls follows the conventions, its warnings as fixed messages with fields, and it has no baseline entry.++There is no escape hatch, no comment that exempts a call: a message that has to vary is a fixed message with fields.diff --git a/docs/tools/logging.md b/docs/tools/logging.mdindex ff364a6b2..ce6f22954 100644--- a/docs/tools/logging.md+++ b/docs/tools/logging.md@@ -1,6 +1,6 @@---title: "Logging"-description: "Explore Pipelex logging: named fields, the run-scoped context, module-named loggers, custom log levels, the console, json and otlp sinks and structured data logging."+description: "Explore Pipelex logging: named fields, the run-scoped context, module-named loggers, custom log levels, the console, json and otlp sinks, structured data logging and the log-call conventions."---# Pipelex Logging System@@ -34,7 +34,7 @@ from pipelex import loglog.info("Simple message")# Named fields ride the record as attributes; the message stays narrative-log.info("Scanned the inputs", fields={"files": 7, "bytes": 12_288})+log.info("Scanned the inputs", fields={"file_count": 7, "byte_count": 12_288})# A named console layout; every sink but the console writes the plain message and the fieldsfrom pipelex.tools.log.console_layouts import LogLayout@@ -69,7 +69,7 @@ Each level's method (`verbose`, `debug`, `info`, `warning`, `error`, `critical`)## Fields-`fields` is a mapping of named values. Each entry becomes an attribute of the emitted `LogRecord`, which is where a formatter or a sink reads it: `record.files` for the example above, or `%(files)s` in a stdlib format string. Nothing from `fields` is written into the message, so `record.getMessage()` is exactly the text you passed.+`fields` is a mapping of named values. Each entry becomes an attribute of the emitted `LogRecord`, which is where a formatter or a sink reads it: `record.file_count` for the example above, or `%(file_count)s` in a stdlib format string. Nothing from `fields` is written into the message, so `record.getMessage()` is exactly the text you passed.A value can be anything. It rides the record by reference and the sink serializes it on emit, on the calling thread, so what leaves the process is the value as it was at the call, and mutating it afterwards changes nothing already emitted. The `console` sink shows it after the message on one line, as [Fields after the message](#fields-after-the-message) describes, the `json` sink dumps a pydantic model in JSON mode and falls back to `str` for a value JSON does not know, and the `otlp` sink carries a scalar or a sequence of scalars as an attribute and anything else as JSON text; prefer plain JSON-ready values (strings, numbers, booleans, lists and dictionaries of those) for anything meant to be queried later. A value JSON refuses outright, a circular reference or a mapping with a non-string key, is written by the `json` sink as its `repr`, and that costs the value alone: every other field on the line keeps its JSON type, so a number or a boolean beside it is still queried as one.@@ -224,7 +224,7 @@ log.error("Expected list[int], got [red]str[/red]")ERROR 🧠: Expected list[int], got [red]str[/red]```-A tag-shaped span in a message is text like any other: a `list[int]` in a type complaint, a bracketed path, the `[cycle]` marker in the rendering of a circular content, and the `[name]: ` prefix the console puts before a line from a logger with no emoji, such as `[myapp.jobs.nightly]: `. Colour is the console's own: it styles the [fields after the message](#fields-after-the-message) by their names and draws the few [layouts](#layouts), so a call is coloured by naming its fields, never by writing markup into its message. No sink but the console has ever read markup, so a message carrying a tag would reach the `json`, `otlp` and `gcp` sinks with the tag in it, and the rule for a Pipelex log call is to write none. A test checks the messages of one run against it: it runs the pipes of one test bundle live, a sequence nesting a structuring step, parallel summaries and a condition, with a stand-in worker answering every model call, and fails on any message the run logs, at any level, that holds a tag Rich would apply as styling: a closing tag, an `@` handler, or a tag naming a style, `[bold]` or `[link=https://pipelex.com]`. A bracketed word that names no style, `list[int]` or `[openai]`, passes, since it prints as written. A message logged only on a path that run does not take is not covered by it.+A tag-shaped span in a message is text like any other: a `list[int]` in a type complaint, a bracketed path, the `[cycle]` marker in the rendering of a circular content, and the `[name]: ` prefix the console puts before a line from a logger with no emoji, such as `[myapp.jobs.nightly]: `. Colour is the console's own: it styles the [fields after the message](#fields-after-the-message) by their names and draws the few [layouts](#layouts), so a call is coloured by naming its fields, never by writing markup into its message. No sink but the console has ever read markup, so a message carrying a tag would reach the `json`, `otlp` and `gcp` sinks with the tag in it, and the rule for a Pipelex log call is to write none. Two checks hold the calls to it, by one reading of what a tag is: a tag Rich would apply as styling, a closing tag, an `@` handler, or a tag naming a style, `[bold]` or `[link=https://pipelex.com]`. A bracketed word that names no style, `list[int]` or `[openai]`, passes, since it prints as written. The [log-call guard](../contribute/log-calls.md), `make check-log-calls`, reads the source of every call: it refuses such a tag in the literal text of a message, its title or its inline title, at every level, that text folded across concatenations and named literals the way it reaches the console. A test checks the messages of one run: it runs the pipes of one test bundle live, a sequence nesting a structuring step, parallel summaries and a condition, with a stand-in worker answering every model call, and fails on any message the run logs, at any level, that holds such a tag, whatever built it. A message the guard cannot read, a value built at run time, is covered only when that run logs it.Rich still honours its own per-record `markup` attribute, which a third-party library may set on a record it logs to ask for markup. No Pipelex call can set it: a field of that name is [reserved](#names-that-are-not-yours-to-give) and lands under `field_markup`.@@ -233,15 +233,15 @@ Rich still honours its own per-record `markup` attribute, which a third-party liThe console shows the fields a call gave after its message, as a `key=value` suffix, the way structlog's console renderer and pino-pretty do:```python-log.info("Scanned the inputs", fields={"files": 7, "source": "inbox/march"})+log.info("Scanned the inputs", fields={"file_count": 7, "source": "inbox/march"})``````text-INFO 🧠: Scanned the inputs files=7 source=inbox/march+INFO 🧠: Scanned the inputs file_count=7 source=inbox/march```- **What is shown.** The fields the call attached, in the order it gave them, under the name each landed on (`field_name` for a field called `name`). The run identifiers (`request_id`, `pipeline_run_id`, `pipe_run_id`) are left out, since they are the same on every line of a run and would drown the message, and so is `data`, the structured content the message already renders. Nothing else on the record is shown: neither the stdlib's own attributes, nor Pipelex's marks, nor what a record factory or a third-party library stamped on it.-- **How a value is written.** On one line: a string bare, or quoted when it is empty or holds a space, an `=`, a `"`, a `\` or a character a terminal would act on. Inside the quotes a backslash is written `\\`, a quote `\"` and any character a terminal would act on as its escape (`"line\nbreak"`), so `fields={"a": "b=c"}` prints `a="b=c"` rather than a second pair. A number, a boolean, `None`, a mapping, a list or a pydantic model is written as compact JSON (`true`, `null`, `{"key":"value"}`, `["a","b"]`), and anything else as its text. A value longer than 80 characters is cut short and ends with `…`. A key is written the same way, so a field whose name holds a line break, a space, an `=` or an escape sequence is quoted and escaped rather than forging a line or a second pair: `fields={"x=1": 2}` prints `"x=1"=2`. The [redaction](#redaction) has run before the console renders, so a secret is already `[REDACTED]`.+- **How a value is written.** On one line: a string bare, or quoted when it is empty or holds a space, an `=`, a `"`, a `\` or a character a terminal would act on. Inside the quotes a backslash is written `\\`, a quote `\"` and any character a terminal would act on as its escape (`"line\nbreak"`), so `fields={"a": "b=c"}` prints `a="b=c"` rather than a second pair. A number, a boolean, `None`, a mapping, a list or a pydantic model is written as compact JSON (`true`, `null`, `{"key":"value"}`, `["a","b"]`), and anything else as its text. A value longer than 80 characters is cut short and ends with `…`, except `error.message`, a handled exception's text, which is cut only past 2000 characters, quoted and escaped the same way: its diagnosis, a cause chain or a parse error's location, is what a fragment would lose, while a dependency's raw output, a validation error's every line or git's stderr, would flood the terminal uncut. A key is written the same way, so a field whose name holds a line break, a space, an `=` or an escape sequence is quoted and escaped rather than forging a line or a second pair: `fields={"x=1": 2}` prints `"x=1"=2`. The [redaction](#redaction) has run before the console renders, so a secret is already `[REDACTED]`.- **Never markup.** The suffix is built as styled Rich `Text`, not as a markup string, so a value carrying `[red]x[/red]` prints exactly that.There is no setting to hide the suffix: it carries the values a message used to interpolate, so hiding it would hide what the line is about.@@ -308,39 +308,90 @@ Optional inclusion of caller information in logs, prefixed to the console line:- Module name- Customizable format templates-## Best Practices+## Log-call conventions-1. **Log Level Selection**:+Pipelex's own log calls, in `pipelex/` and in the API server's `api/pipelex_api/`, follow these conventions, so that a line written today can be grouped, counted and filtered in a log store tomorrow. The [log-call guard](../contribute/log-calls.md), `make check-log-calls`, holds every call to the ones that can be read off the source, the fixed message at INFO and above and the absence of markup; the rest is for review. Code of your own that logs through `log` is welcome to follow them too.- - Use VERBOSE for step-level tracing only Pipelex's own developers read- - Use DEBUG for what a diagnosis from a user's log would need- - Use INFO for the few lifecycle milestones- - Use WARNING for a handled degradation or a misconfiguration the user can fix- - Use ERROR when a run failed or data was lost- - Use CRITICAL when the process cannot go on- - Log what a value is about, never the value's payload: no base64 data, prompt or raw response+### A fixed message-2. **Fields over interpolation**:+A message is a sentence that reads the same on every emission. A log store groups and counts lines by their message, and an interpolated value makes a different string of every line, so a question as plain as "how many of these today" needs a regular expression. The message is the key a query, a dashboard or an alert selects a line by, and Pipelex carries no separate `event` field beside it, so rewording a message is a change made on purpose.- - Put a value a reader might filter or aggregate on in `fields`, and keep the message a sentence; the console shows it after the message, coloured by its name- - Name a field after the thing it carries, in `snake_case`, or after its OpenTelemetry key when one exists- - Leave the run identifiers to the context; bind them at the process entry, never per call- - Never write Rich markup in a message: the console prints it as written and every other sink carries the tags; colour comes from the fields and the layouts+At INFO and above, the message is a literal written at the call: no f-string, no `%`, no `+` and no `.format()`, and no message built elsewhere and passed in, since nothing can tell that one is fixed. DEBUG and VERBOSE may keep an f-string, because a person at a terminal reads them; fields are welcome there too.-3. **Structured Data**:-- - Log complex data structures directly; they reach the console as JSON and a sink as `data`- - Use titles for context- - Include problem IDs for trackable issues+```python+# Not this: the alias makes every line a different message, and the exception is buried in the text+log.warning(f"Could not load dependency '{alias}' pipe '{pipe_code}': {exc}")-4. **Exception Handling**:+# This: one message, the values in fields, the exception's class and text as fields of their own+log.warning(+ "A pipe of a dependency could not be loaded",+ fields={"dependency_alias": alias, "pipe_code": pipe_code, **error_fields(exc=exc)},+)+```- - Use `include_exception=True` inside the `except` block, and let the sink render the traceback its own way- - Include relevant data in error logs- - Use appropriate log levels for exceptions+### Values in fields++What varies goes in `fields`, named by the [naming convention](#naming-convention), and one concept has one name across the codebase, so that a query written for one line finds every line about the same thing. Pipelex's own concepts take the names in the table below. A concept the OpenTelemetry semantic conventions define takes their key verbatim: `file.path` for a path on disk, `url.full` for a URL, `user.id` for a user, `error.type` for the class of an error, and the `gen_ai.*` keys for inference, such as `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.request.temperature`, `gen_ai.operation.name`, `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. A `gen_ai.*` key means on a log line what it means on Pipelex's LLM span: `gen_ai.request.model` is the model's handle and `gen_ai.response.model` the provider's id of the model serving it. A line about an inference call carries them beside `model_handle`, `backend_name` and `sdk`, so it joins its span in a log store, while `model_handle` names the handle on every line about a model, inference or not. A count is named `<what>_count` (`concept_count`) and a duration `duration_ms`, in milliseconds.++| Field | What it names |+| --- | --- |+| `pipe_code` | The pipe a line is about, bare or qualified by its domain, as the call site holds it: `compose_company`, `company.compose_company` |+| `pipe_type` | The pipe's class: `PipeLLM`, `PipeCompose` |+| `pipe_depth` | How deep a pipe run is nested, `0` at the top level |+| `is_dry_run` | Whether the run is a dry run |+| `output_concept` | The concept a pipe produces |+| `concept_ref` | A concept's qualified reference, `<domain>.<Code>`: `company.Company` |+| `concept_code` | A concept's code alone, where the call site has no domain for it: `Company` |+| `domain_code` | A domain's code: `company` |+| `stuff_name` | The name a stuff has in working memory |+| `variable_path` | A dotted path into working memory, as a pipe's inputs name it: `invoice.total` |+| `library_id` | The library a load or a lookup runs in |+| `package_address` | A method package's address, as its manifest declares it or a bundle's reference names it: `github.com/acme/methods/invoices` |+| `dependency_alias` | The alias under which a package's manifest declares a dependency; a dependency a bundle names by address has its address as its alias |+| `method_ref` | The address a caller names a method by, selector and tag included, as the run routes and the CLI take it: `github.com/acme/methods/[email protected]` |+| `commit_sha` | The commit a fetched method package was cloned at |+| `mthds_version_constraint` | The MTHDS standard versions a package accepts, as the `mthds_version` of its `METHODS.toml` declares them: `^4.0.0` |+| `mthds_standard_version` | The MTHDS standard version this runtime implements |+| `mthds_paths` | The `.mthds` files a load reads, as a list of paths |+| `crate_fingerprint` | The fingerprint that identifies a normalized crate in the library it is loaded into |+| `model_handle` | The handle a pipe or the model deck names a model by, an alias included: `gpt-image-2`, `@default-premium` |+| `backend_name` | The inference backend serving a model, as the backends configuration names it: `anthropic`, `bedrock` |+| `sdk` | The SDK a backend reaches a model through, as the backends configuration names it: `openai`, `bedrock_anthropic` |+| `fixed_temperature` | The one temperature a model accepts, as its constraints declare it, used in place of the one requested |+| `node_id` | A node of a run's execution graph, as the graph tracer names it |+| `env_var` | The name of an environment variable, never its value |+| `error.type`, `error.message` | A handled exception's class name and its text, as [Exceptions](#exceptions) describes |++`pipe_code`, `pipe_type`, `output_concept`, `concept_ref`, `concept_code`, `domain_code` and `stuff_name` are in the console's [style map](#the-style-map), which colours their values wherever they appear. A concept missing from the table is added to it in the change that first logs it.++### Exceptions++An exception rides the record, never the message. Spliced into the text, `{exc}` makes the message vary, loses the exception's type and traceback, and gets only the pattern half of the [redaction](#redaction), where a field also has its control characters escaped. So:++- **At ERROR and CRITICAL**, inside the `except` block, pass `include_exception=True`: the record carries the exception, and each sink writes its type and its traceback its own way.+- **At WARNING and below**, an exception the code expected and handled rides as two fields, `error.type`, its class's name, and `error.message`, its text, with no traceback, through `error_fields` (`pipelex.tools.log.error_fields`): `fields={"package_address": address, **error_fields(exc=exc)}`. A warning promises a degradation that was handled, and a traceback of Pipelex's own frames repeated on every emission of an expected failure says nothing a reader can act on; the facade's `warning` takes no `include_exception` for that reason. Where the diagnosis is the cause chain rather than the exception's own text, as when a fetch fails in git underneath, `error_fields(exc=exc, text=...)` carries the chain instead. The console cuts `error.message` only past 2000 characters, where it cuts every other field's value at 80, so the chain reaches the terminal whole without a dependency's raw output flooding it.++`error.type` is the OpenTelemetry key for the class of error an operation ended with. `error.message` is the key OpenTelemetry gave an error's text before deprecating that general attribute in favour of domain-specific ones; Pipelex keeps it as `error.type`'s companion because the `exception.*` keys belong to the sinks, which write them for a record that carries the exception itself and prefix a field spelling one.++### What a line never carries++- **No run identifier in the text.** `request_id`, `pipeline_run_id` and `pipe_run_id` are stamped on every record by the [run-scoped context](#the-run-scoped-context); a message repeating one is noise, and a field passing one is only for a call that speaks about a run it is not running under.+- **No payload contents, at any level.** No prompt text, no base64 data, no raw response and no whole object: a size, a count, a hash or a code instead, as the [level table](#log-levels) already says of every level.+- **No markup and no emoji in a message.** Colour is the console sink's job: it colours a value by its field's name and draws the few [layouts](#layouts), and its emoji are its own per-logger decoration. Markup in a message travels to every sink as literal tags, the console's included, since it reads no message as markup (see [Messages are plain text](#messages-are-plain-text)). Markup keeps its place in the CLI's own output and in the pretty-print channel, which are presentation to a person and not log records.++### Choosing a level++The [level table](#log-levels) states what a line at each level means, and choosing the level of a call follows from it. There is no DEV level.++- **ERROR** says a run failed or data was lost, and that somebody should look; it carries the exception with `include_exception=True` when there is one.+- **WARNING** must be actionable: a degradation that was handled, or a misconfiguration the user can fix. A warning nobody can act on moves down to DEBUG, or up to ERROR when something was in fact lost.+- **INFO** marks a lifecycle milestone, and there are few of them, because Pipelex is also a library and a library is quiet at INFO.+- **DEBUG** answers a question you would ask on reading a log a user sent: which file was read, which fallback was taken, why a model was left out.+- **VERBOSE** follows the runtime step by step, for Pipelex's own developers.## Related Documentation- [Logging Configuration](../configuration/config-practical/logging-config.md) - Configure log behavior and select the sink in `pipelex.toml`- [Log Sink Plugins](../under-the-hood/log-sink-plugins.md) - The sink seam, the built-in sinks and how to write one- [CLI](./cli/index.md) - Commands that surface runtime logs during development+- [Log-Call Guard](../contribute/log-calls.md) - The check that holds Pipelex's own log calls to the conventions above, and its baselinediff --git a/log_call_baseline.toml b/log_call_baseline.tomlnew file mode 100644index 000000000..f7139fa78--- /dev/null+++ b/log_call_baseline.toml@@ -0,0 +1,543 @@+# The log calls that broke the log-call conventions when the guard arrived (pipelex-dev check-log-calls).+# Keyed by <relative_path>::<qualified_name>, each call listed by its method, its message's source,+# the rules it breaks and the bindings its message was read through.+# It only shrinks: convert a call, then remove its signature (pipelex-dev check-log-calls --prune).+# Never add an entry: the check refuses a baseline that lists more than its base. See docs/contribute/log-calls.md.++version = 1++["api/pipelex_api/bundle.py::_entries_from_zip"]+calls = [+ "warning: f\"bundle: corrupt zip ({zip_error})\" [f-string]",+ "warning: f\"bundle: invalid base64 ({decode_error})\" [f-string]",+]++["api/pipelex_api/exception_handlers.py::_emit_api_error"]+calls = [+ "error: summary [non-literal] where summary = _error_summary(attributes)",+ "warning: summary [non-literal] where summary = _error_summary(attributes)",+]++["api/pipelex_api/limits.py::_read_positive_int"]+calls = [+ "warning: f\"Invalid {env_var}={raw!r}, falling back to {default}\" [f-string]",+ "warning: f\"{env_var} must be positive (got {parsed}), falling back to {default}\" [f-string]",+]++["api/pipelex_api/method_source.py::_fetch_package"]+calls = [+ "info: f\"Resolved method_ref '{ref.ref_str}': address={package.provenance.address} tag={package.provenance.tag} commit_sha={package.provenance.commit_sha}\" [f-string]",+]++["api/pipelex_api/security.py::get_auth_mode"]+calls = [+ "warning: f\"Unknown AUTH_MODE '{raw}', falling back to 'none'\" [f-string]",+]++["api/pipelex_api/security.py::no_auth"]+calls = [+ "warning: f\"Forwarded X-User-Id is not a path-safe segment, rejecting: {user_id!r}\" [f-string]",+]++["api/pipelex_api/security.py::verify_jwt"]+calls = [+ "warning: f\"JWT user_id claim is not a path-safe segment: {user_id!r}\" [f-string]",+ "warning: f\"JWT validation failed: {exc!s}\" [f-string]",+]++["pipelex/cli/agent_cli/commands/run/_run_core.py::run_pipeline_core"]+calls = [+ "warning: f\"Cost summary generation failed (run succeeded): {cost_summary_error}\" [f-string]",+]++["pipelex/cli/commands/doctor_cmd.py::setup_doctor_runtime"]+calls = [+ "warning: stale_warning [non-literal] where stale_warning = config_manager.take_stale_configuration_warning()",+]++["pipelex/cli/commands/graph_cmd.py::graph_render_cmd"]+calls = [+ "error: f\"Error rendering graph: {exc}\" [f-string]",+]++["pipelex/cli/commands/run/_run_core.py::execute_run"]+calls = [+ "error: f\"Error executing pipeline: {exc}\" [f-string]",+]++["pipelex/cli/commands/which_cmd.py::which_cmd"]+calls = [+ "info: f\"No library directories to load ({source_label})\" [f-string]",+]++["pipelex/cogt/content_generation/generated_content_factory.py::GeneratedContentFactory.make_image_content"]+calls = [+ "warning: f\"Failed to fetch a remote image: {exc}\" [f-string]",+]++["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_inference"]+calls = [+ "warning: f\"Number of inference steps {num_inference_steps} for SDXL Lightning must be one of {acceptable_steps}\" [f-string]",+]++["pipelex/cogt/img_gen/img_gen_args_factory.py::ImgGenArgsFactory.make_args_from_prompt"]+calls = [+ "warning: f\"A negative prompt was provided but the model's prompt taxonomy is '{PromptTaxonomy.POSITIVE_ONLY}', which does not support negative prompts. The negative prompt will be silently ignored.\" [f-string]",+]++["pipelex/cogt/img_gen/img_gen_gpt_mapping.py::ImgGenGptMapping.validate_gpt_image_2_size"]+calls = [+ "warning: msg [f-string] where msg = f\"Size '{size_string}' is valid for OpenAI image model '{model_name}', but it is above the 2560x1440 reliability boundary.\"",+]++["pipelex/cogt/llm/llm_prompt.py::LLMPrompt.validate_before_execution"]+calls = [+ "error: f\"Prompt template system_text should be None or contain text. system_text = '{self.system_text}'\" [f-string]",+ "warning: f\"system_text should be None or contain text. system_text = '{self.system_text}'\" [f-string]",+ "warning: f\"system_text should be None or contain text. system_text = '{self.system_text}'\" [f-string]",+]++["pipelex/cogt/model_backends/backend_library.py::InferenceBackendLibrary.load"]+calls = [+ "info: f\"Inference backends read from {library_paths_description}\" [f-string]",+]++["pipelex/cogt/model_routing/routing_profile_loader.py::load_active_routing_profile"]+calls = [+ "info: f\"Routing profiles read from {library_description}\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck._get_optional_inference_model"]+calls = [+ "warning: f\"Model handle '{ref.name}' is served as {served_types_description} but was requested as '{model_type}'. Skipping.\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck._resolve_alias"]+calls = [+ "warning: f\"Circular model reference detected: alias '{alias_name}' leads back to itself\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck._resolve_waterfall"]+calls = [+ "info: msg [f-string] where msg += f\" Please see our docs for more details about setting up inference backends:\\n{URLs.backend_provider_docs}\"; msg = f\"Inference model fallback: '{ideal_model_handle}' was not found in the model deck, so it was replaced by '{fallback}'. As a consequence, the results of the method may not have the expected quality, and the method might fail due to feature limitations such as context window size, etc. Consider getting access to '{ideal_model_handle}'.\"",+ "warning: f\"Circular model reference detected: waterfall '{waterfall_name}' leads back to itself\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_doc_gen"]+calls = [+ "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_extract"]+calls = [+ "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_img_gen"]+calls = [+ "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_judgment"]+calls = [+ "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_llm"]+calls = [+ "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck._warn_if_ambiguous_search"]+calls = [+ "warning: f\"Bare string '{name}' matches: {', '.join(matches)}. Using it as a direct model handle. Add explicit prefix to avoid ambiguity.\" [f-string]",+]++["pipelex/cogt/models/model_deck.py::ModelDeck.validate_registered_models"]+calls = [+ "warning: f\"DocGen handle not found: {exc}\" [f-string]",+ "warning: f\"Extract handle not found: {exc}\" [f-string]",+ "warning: f\"ImgGen handle not found: {exc}\" [f-string]",+ "warning: f\"Judgment handle not found: {exc}\" [f-string]",+ "warning: f\"LLM handle not found: {exc}\" [f-string]",+ "warning: f\"Search handle not found: {exc}\" [f-string]",+]++["pipelex/cogt/models/model_manager.py::ModelManager.setup"]+calls = [+ "warning: stale_warning [non-literal] where stale_warning = self.inference_backend_library.take_stale_configuration_warning()",+]++["pipelex/cogt/usage/cost_registry.py::CostRegistry.generate_report"]+calls = [+ "warning: f\"No report to generate for pipeline '{pipeline_run_id}'\" [f-string]",+]++["pipelex/config.py::is_method_fetch_on_miss_enabled"]+calls = [+ "warning: f\"Unrecognized {METHODS_FETCH_ON_MISS_ENV_VAR}={raw_env!r} (expected 1/0, true/false); falling back to the config\" [f-string]",+]++["pipelex/core/concepts/concept_factory.py::_is_valid_structure_class"]+calls = [+ "warning: f\"Concept class '{structure_class_name}' is registered but it's not a subclass of StuffContent\" [f-string]",+]++["pipelex/core/memory/working_memory.py::WorkingMemory.add_new_stuff"]+calls = [+ "warning: f\"Key '{name}' already exists in WorkingMemory and will be replaced by something different\" [f-string]",+ "warning: f\"Key '{name}' already exists in WorkingMemory with the same stuff\" [f-string]",+]++["pipelex/core/memory/working_memory.py::WorkingMemory.validate_stuff_names"]+calls = [+ "warning: f\"Stuff key '{key}' starts with '_', which is reserved for params\" [f-string]",+ "warning: f\"Stuff name '{stuff.stuff_name}' does not match the key '{key}'\" [f-string]",+ "warning: f\"Stuff name '{stuff.stuff_name}' starts with '_', which is reserved for params\" [f-string]",+]++["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.convert_to_working_memory_format"]+calls = [+ "warning: f\"Error getting structure class for concept '{named_stuff_spec.concept.code}': {exc}, falling back to TextContent\" [f-string]",+]++["pipelex/core/memory/working_memory_factory.py::WorkingMemoryFactory.make_mock_inputs"]+calls = [+ "warning: f\"Failed to create mock for '{typed_named_stuff_spec.variable_name}' ({typed_named_stuff_spec.concept.code}): {exc}. Using fallback text content.\" [f-string]",+]++["pipelex/graph/graph_factory.py::save_graph_outputs_to_dir"]+calls = [+ "warning: f\"Removed {file_name} at {file_path}: the graphspec written beside it carries no I/O artifacts of its own\" [f-string]",+]++["pipelex/graph/graph_tracer_manager.py::GraphTracerManager.open_tracer"]+calls = [+ "warning: f\"Stale tracer teardown for key '{key}' failed; replacing anyway: {stale_teardown_exc}\" [f-string]",+ "warning: f\"Tracer for key '{key}' already exists; replacing stale tracer left by a prior interrupted execution\" [f-string]",+]++["pipelex/kernel/judgment_ops.py::run_judgment"]+calls = [+ "warning: f\"Judgment '{job_metadata.pipe_code or 'unnamed step'}' declares a threshold of {threshold}, but model '{judgment_setting.model}' reported no probability, so its own verdict stands.\" [f-string]",+]++["pipelex/kernel/llm_ops.py::concrete_llm_model_handle"]+calls = [+ "warning: f\"Cycle resolving model reference '{model}' at '{current}'; reporting it unresolved\" [f-string]",+ "warning: f\"Model reference '{model}' did not resolve within {_MAX_MODEL_RESOLUTION_HOPS} hops\" [f-string]",+]++["pipelex/libraries/domain/domain_metadata_merge.py::merge_domain_metadata_field"]+calls = [+ "warning: f\"Domain '{domain_code}' declared with different {field_label}s. Keeping the first.\" [f-string]",+ "warning: f\"Domain '{domain_code}' declared with different {field_label}s: '{established}' vs '{incoming}'. Keeping the first.\" [f-string]",+]++["pipelex/libraries/library_utils.py::get_pipelex_mthds_files_from_package._find_mthds_in_traversable"]+calls = [+ "warning: f\"Could not access {traversable}: {exc}\" [f-string]",+]++["pipelex/libraries/library_utils.py::get_pipelex_package_dir_for_imports"]+calls = [+ "warning: f\"Could not convert importlib.resources Traversable to filesystem Path: {exc}\" [f-string]",+]++["pipelex/methods/fetch_limits.py::_read_positive_int"]+calls = [+ "warning: f\"Invalid {env_var}={raw!r}, falling back to {default}\" [f-string]",+ "warning: f\"{env_var} must be positive (got {parsed}), falling back to {default}\" [f-string]",+]++["pipelex/methods/fetch_on_miss.py::_warn_on_tag_mismatch"]+calls = [+ "warning: f\"Method '{ref.address}' is already installed at '{installed.path}' ({installed_desc}) while the reference pins '@{ref.tag}'; using the installed copy. Remove '{installed.path}' to re-fetch at the pinned tag.\" [f-string]",+]++["pipelex/methods/fetch_on_miss.py::find_vendored_method"]+calls = [+ "warning: f\"Method '{lookup.ref.address}' is shipped with the request at version {version} while the reference pins '@{lookup.ref.tag}'; using the shipped copy.\" [f-string]",+]++["pipelex/methods/fetch_on_miss.py::resolve_address_based_method"]+calls = [+ "info: f\"Fetched method '{fetched.full_address}' at commit {fetched.commit_sha} and installed it into '{installed.path}'\" [f-string]",+ "warning: f\"Method '{fetched.full_address}' declares Python structure classes ({details}). It runs locally, but {STRUCTURES_REFUSAL_RULE} — hosted execution would refuse it. {STRUCTURES_REFUSAL_REMEDY}\" [f-string]",+]++["pipelex/migration/runner.py::_discard_backup"]+calls = [+ "warning: f\"the backup '{backup.path}' was made for a write that did not happen and could not be removed: {exc.strerror or exc}\" [f-string]",+]++["pipelex/migration/runner.py::_discard_created_backup"]+calls = [+ "warning: f\"the backup '{backup.path}' was made for a removal that did not happen and could not be removed: {exc.strerror or exc}\" [f-string]",+]++["pipelex/migration/runner.py::_prune_older_backups"]+calls = [+ "warning: f\"'{snapshot.path}' was migrated and backed up to '{backup.path}', but an older backup could not be pruned: {exc.strerror or exc}\" [f-string]",+]++["pipelex/migration/runner.py::write_file_with_backup"]+calls = [+ "warning: f\"'{snapshot.path}' was migrated, but the write left something behind: {exc}\" [f-string]",+]++["pipelex/pipe_controllers/batch/pipe_batch.py::PipeBatch._live_run_controller_pipe"]+calls = [+ "warning: f\"PipeBatch '{self.code}' is fanning out over {item_count} items. Bounded fan-out (max_concurrency={max_concurrency if max_concurrency is not None else 'unbounded'}) is a basic backpressure effort, not durable execution — for a workload this size, consider a durable execution backend for rate-limited, resumable runs: {URLs.durable_execution}\" [f-string]",+]++["pipelex/pipe_controllers/condition/pipe_condition.py::PipeCondition._dry_run_controller_pipe"]+calls = [+ "error: f\"Dry run failed: could not detect required variables from expression template: {exc}\" [f-string]",+]++["pipelex/pipe_machinery/pipe_abstract.py::PipeAbstract._make_lifted_output"]+calls = [+ "info: f\"Skipping {self.type} '{self.code}': absent input(s): {absent_names}\" [f-string]",+]++["pipelex/pipe_machinery/pipe_abstract.py::PipeAbstract.validate_pipe_code_syntax"]+calls = [+ "warning: f\"Runtime pipe code '{code}' contains a namespace prefix, stripped to '{bare_code}'\" [f-string]",+]++["pipelex/pipe_operators/doc_gen/pipe_doc_gen.py::PipeDocGen.check_template_file"]+calls = [+ "warning: f\"PipeDocGen '{self.code}', template file '{self.template_file}'{location}: {finding.message}\" [f-string]",+]++["pipelex/pipe_operators/func/pipe_func.py::PipeFunc._dry_run_operator_pipe"]+calls = [+ "info: f\"🚨 For your information, the dry run of PipeFunc '{self.code}' is not actually running the python function but only validating the inputs and return type.\" [f-string]",+]++["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._get_raw_main_absence"]+calls = [+ "warning: f\"Malformed main-output absence record in raw working memory, treating as missing: {exc}\" [f-string]",+]++["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._notify_webhook"]+calls = [+ "info: f\"Webhook delivery completed: pipeline_run_id={pipeline_run_id}, url={webhook.url}{request_id_suffix}\" [f-string]",+]++["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._resolve_concept_locally"]+calls = [+ "warning: f\"Concept ref '{concept_ref}' is ambiguous in the current library, rendering the delivery raw: {exc}\" [f-string]",+ "warning: f\"Concept ref '{concept_ref}' is not a valid concept ref, rendering the delivery raw: {exc}\" [f-string]",+ "warning: f\"The current library is no longer reachable, rendering the delivery raw: {exc}\" [f-string]",+]++["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._store_results"]+calls = [+ "info: f\"Storage delivery completed: pipeline_run_id={pipeline_run_id}, files={len(result_files)}{request_id_suffix}\" [f-string]",+]++["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor._try_add_rendered_file"]+calls = [+ "warning: f\"Failed to render {filename}\" [f-string]",+]++["pipelex/pipe_run/delivery_executor.py::DeliveryExecutor.try_local_hydrate_stuff"]+calls = [+ "warning: f\"Local hydration failed for delivery main stuff, falling back to raw render: 'concept' must be the concept ref string, got {type(concept_ref).__name__}\" [f-string]",+ "warning: f\"Local hydration failed for delivery main stuff, falling back to raw render: class '{concept.structure_class_name}' not registered locally\" [f-string]",+ "warning: f\"Local hydration failed for delivery main stuff, falling back to raw render: concept '{concept_ref}' not known locally\" [f-string]",+ "warning: f\"Local hydration failed for delivery main stuff, falling back to raw render: {exc}\" [f-string]",+]++["pipelex/pipe_run/dry_run_in_process.py::best_effort_graph_spec"]+calls = [+ "warning: f\"{log_context}: graph dry-run of '{pipe_ref}' did not produce a graph ({type(graph_error).__name__}: {graph_error}); returning validation result without graph_spec\" [f-string]",+]++["pipelex/pipe_run/pipe_run.py::PipeRun._build_pipe_io_artifacts_on_output"]+calls = [+ "warning: message [f-string] where message = f\"Failed to build the I/O artifacts for pipeline_run_id={pipeline_run_id}: {build_error}\"",+]++["pipelex/pipe_run/pipe_run.py::PipeRun._run_bound"]+calls = [+ "error: f\"Delivery also failed for pipeline_run_id={pipeline_run_id} after pipe execution failure; raising original execution error. Suppressed delivery error: {delivery_error}\" [f-string]",+ "error: f\"Pipe execution failed for pipeline_run_id={pipeline_run_id}: {exc}\" [f-string]",+ "error: f\"close_tracer also failed for pipeline_run_id={pipeline_run_id} after pipe execution failure; raising original execution error. Suppressed tracer close error: {tracer_close_error}\" [f-string]",+]++["pipelex/pipe_run/pipe_run_params.py::PipeRunParams.pop_pipe_from_stack"]+calls = [+ "error: f\"Pipe code '{pipe_code}' was not the last pipe in the stack, it was '{popped_pipe_code}'\" [f-string]",+]++["pipelex/pipe_run/tracing_assembly.py::assemble_tracing"]+calls = [+ "warning: message [f-string] where message = f\"Graph assembly failed for pipeline_run_id={pipeline_run_id}: {validation_error}\"",+ "warning: message [f-string] where message = f\"Tracing assembly failed to read events for pipeline_run_id={pipeline_run_id}: {read_error}\"",+]++["pipelex/pipeline/pipeline_run_setup.py::pipeline_run_setup"]+calls = [+ "error: f\"close_tracer also failed for pipeline_run_id={pipeline_run_id} during setup-failure cleanup; raising original setup error. Suppressed tracer close error: {tracer_close_error}\" [f-string]",+]++["pipelex/pipeline/validate_in_process.py::_validate_bundles_in_scope"]+calls = [+ "error: f\"{log_context}: library teardown also failed after a body error; raising the original error. Suppressed teardown error: {teardown_error}\" [f-string]",+]++["pipelex/plugins/discovery.py::_skip_if_disabled"]+calls = [+ "info: f\"Plugin '{name}' is disabled via runtime.plugins.disabled; skipping.\" [f-string]",+]++["pipelex/providers/pypdfium2/pypdfium2_worker.py::Pypdfium2Worker._extract_pages"]+calls = [+ "warning: f\"Pypdfium2 does not support native image limiting. Extracted all images then truncated to {max_nb_images}.\" [f-string]",+ "warning: f\"Pypdfium2 extracted {original_count} images on page {page_number}, truncated to {len(page_images)} (max_nb_images={max_nb_images})\" [f-string]",+]++["pipelex/providers/typesafe/typesafe_judgment_worker.py::TypesafeJudgmentWorker._warn_if_another_model_answered"]+calls = [+ "warning: f\"TypeSafe was asked for judgment model '{self.inference_model.model_id}' and answered as '{response.model}': verdicts and their thresholds may not mean what they meant under the pinned model\" [f-string]",+]++["pipelex/reporting/cost_report_renderer.py::render_run_cost_report"]+calls = [+ "warning: f\"Cost report generation failed (run succeeded): {cost_report_error}\" [f-string]",+]++["pipelex/reporting/reporting_manager.py::ReportingManager._emit_best_effort"]+calls = [+ "warning: f\"Usage event emit failed; dropping: {exc}\" [f-string]",+]++["pipelex/reporting/reporting_manager.py::ReportingManager._emit_usage_event_runner_fallback"]+calls = [+ "warning: f\"Runner-side activity event log construction failed; dropping usage event: {exc}\" [f-string]",+]++["pipelex/reporting/reporting_manager.py::ReportingManager.report_inference_job"]+calls = [+ "warning: f\"ReportingManager does not support reporting for inference job type: {type(inference_job).__name__}\" [f-string]",+]++["pipelex/runtime_boot.py::RuntimeBoot.__init__"]+calls = [+ "warning: stale_warning [non-literal] where stale_warning = config_manager.take_stale_configuration_warning()",+]++["pipelex/runtime_boot.py::RuntimeBoot._release_after_failed_boot"]+calls = [+ "error: f\"Telemetry teardown failed while releasing a failed boot: {telemetry_exc}\" [f-string]",+]++["pipelex/runtime_boot.py::RuntimeBoot._teardown_plugin_callbacks"]+calls = [+ "error: f\"A plugin teardown callback failed and was skipped: {teardown_exc}\" [f-string]",+]++["pipelex/system/registries/class_registry_utils.py::ClassRegistryUtils.import_modules_in_folder"]+calls = [+ "warning: f\"Syntax error in {python_file}: {exc}\" [f-string]",+]++["pipelex/system/registries/func_registry_utils.py::FuncRegistryUtils._register_funcs_in_file"]+calls = [+ "warning: f\"Could not import '{file_path}' while registering PipeFuncs; its functions are unavailable: {exc}\" [f-string]",+ "warning: f\"Function '{func_name}' in '{file_path}' has @pipe_func() decorator but is not eligible: {eligibility_error}\" [f-string]",+ "warning: f\"Syntax error in {file_path}: {exc}\" [f-string]",+]++["pipelex/system/registries/func_registry_utils.py::FuncRegistryUtils.register_pipe_funcs_from_package"]+calls = [+ "warning: f\"Function '{func_name}' in '{modname}' has @pipe_func() decorator but is not eligible: {eligibility_error}\" [f-string]",+ "warning: f\"Package {package_name} has no __path__ attribute, cannot walk modules\" [f-string]",+]++["pipelex/system/telemetry/telemetry_loader.py::_telemetry_config_the_ledger_can_explain"]+calls = [+ "warning: stale_configuration_warning(plans=replayed.plans, walked_dirs=config_manager.existing_config_dirs) [non-literal]",+]++["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager._handle_transmission_error"]+calls = [+ "error: f\"Telemetry transmission error: {error}\" [f-string]",+]++["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager.is_custom_portkey_logging_enabled"]+calls = [+ "warning: f\"Disabling Custom Portkey logging (debug mode) because '{OTelConstants.DO_NOT_TRACK_ENV_VAR_KEY}' is set and that setting takes precedence\" [f-string]",+]++["pipelex/system/telemetry/telemetry_manager.py::TelemetryManager.track_event"]+calls = [+ "error: f\"Could not track event '{event_name}' as identified because user_id is not set, tracking as anonymous\" [f-string]",+]++["pipelex/tools/misc/dict_utils.py::substitute_nested_in_context"]+calls = [+ "error: extra_params, title='extra_params' [non-literal] where extra_params = <parameter>",+ "error: extra_params, title='extra_params' [non-literal] where extra_params = <parameter>",+ "error: original_context, title='original_context' [non-literal] where original_context = context.copy()",+ "error: original_context, title='original_context' [non-literal] where original_context = context.copy()",+]++["pipelex/tracing/activity_event_log.py::ActivityEventLogCache.log_once_runner_fallback_engaged"]+calls = [+ "info: f\"Activity-side usage event emission engaged (workflow_id={workflow_id}, writer_id={writer_id}). Activities always emit through the per-process activity event log, by design: activity emissions must never land in the workflow's replay-rebuilt buffer (replay determinism), whether the activity runs co-located with the workflow router or on a separate worker pool.\" [f-string]",+]++["pipelex/tracing/dynamodb_event_log.py::DynamoDBEventLog.read_events"]+calls = [+ "warning: f\"Skipping DynamoDB item with missing payload: PK={item.get('PK')}, SK={item.get('SK')}\" [f-string]",+ "warning: f\"Skipping unparseable DynamoDB item PK={item.get('PK')} SK={item.get('SK')}: {format_pydantic_validation_error(exc)}\" [f-string]",+]++["pipelex/tracing/graphspec_assembler.py::_AssemblerState._attribute_usage"]+calls = [+ "warning: f\"UsageReportEvent for unknown node: {reported_node_id}\" [f-string]",+]++["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_controller_output"]+calls = [+ "warning: f\"ControllerOutputEvent for unknown node: {event.node_id}\" [f-string]",+]++["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_execution_data"]+calls = [+ "warning: f\"ExecutionDataEvent for unknown node: {event.node_id}\" [f-string]",+]++["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_end_error"]+calls = [+ "warning: f\"PipeEndErrorEvent for unknown node: {event.node_id}\" [f-string]",+]++["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_end_skipped"]+calls = [+ "warning: f\"PipeEndSkippedEvent for unknown node: {event.node_id}\" [f-string]",+]++["pipelex/tracing/graphspec_assembler.py::_AssemblerState._handle_pipe_end_success"]+calls = [+ "warning: f\"PipeEndSuccessEvent for unknown node: {event.node_id}\" [f-string]",+]++["pipelex/tracing/graphspec_assembler.py::_AssemblerState.pass_one"]+calls = [+ "warning: f\"Unknown event type: {type(event).__name__}\" [f-string]",+]++["pipelex/tracing/ndjson_event_log.py::NdjsonEventLog.read_events"]+calls = [+ "warning: f\"Skipping corrupt line in {ndjson_path}:{line_number} — {validation_error}\" [f-string]",+]++["pipelex/tracing/usage_attribution.py::_walk_subtree"]+calls = [+ "warning: f\"Cycle in graph node parentage at '{node_id}'; subtree usage rollup will be incomplete\" [f-string]",+]diff --git a/mkdocs.yml b/mkdocs.ymlindex 9c15e13b1..dbb2b8d2f 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -368,6 +368,7 @@ plugins:- contribute/hub-layering.md: "Hub Layering"- contribute/rich-imports.md: "Rich Imports"- contribute/actions-allowlist.md: "Actions Allowlist"+ - contribute/log-calls.md: "Log-Call Guard"- contribute/test-duration-map.md: "Test Duration Map"- contribute/registration-surface.md: "Registration Surface"- contribute/inference-family-surface.md: "Inference Family Surface"@@ -626,6 +627,7 @@ nav:- Hub Layering: contribute/hub-layering.md- Rich Imports: contribute/rich-imports.md- Actions Allowlist: contribute/actions-allowlist.md+ - Log-Call Guard: contribute/log-calls.md- Test Duration Map: contribute/test-duration-map.md- Registration Surface: contribute/registration-surface.md- Inference Family Surface: contribute/inference-family-surface.mddiff --git a/pipelex/cli/dev_cli/_dev_cli.py b/pipelex/cli/dev_cli/_dev_cli.pyindex f22ea2d40..c1f1a2897 100644--- a/pipelex/cli/dev_cli/_dev_cli.py+++ b/pipelex/cli/dev_cli/_dev_cli.py@@ -15,6 +15,7 @@ from pipelex.cli.dev_cli.commands.check_config_sync_cmd import LeadingConfig, chfrom pipelex.cli.dev_cli.commands.check_hub_layering_cmd import check_hub_layering_cmdfrom pipelex.cli.dev_cli.commands.check_keyword_only_cmd import check_keyword_only_cmdfrom pipelex.cli.dev_cli.commands.check_ledger_cmd import check_ledger_cmd+from pipelex.cli.dev_cli.commands.check_log_calls_cmd import check_log_calls_cmdfrom pipelex.cli.dev_cli.commands.check_migration_schemas_cmd import check_migration_schemas_cmdfrom pipelex.cli.dev_cli.commands.check_mthds_schema_cmd import check_mthds_schema_cmdfrom pipelex.cli.dev_cli.commands.check_rich_imports_cmd import check_rich_imports_cmd@@ -51,6 +52,7 @@ class PipelexDevCLI(TyperGroup):"check-hub-layering","check-keyword-only","check-ledger",+ "check-log-calls","check-migration-schemas","check-mthds-schema","check-rich-imports",@@ -423,6 +425,49 @@ def check_rich_imports_command(sys.exit(1)[email protected](name="check-log-calls", help="Refuse an interpolated log message at INFO and above, and Rich markup in any log message")+def check_log_calls_command(+ prune: Annotated[+ bool,+ typer.Option("--prune", help="Remove the baseline signatures no call matches any more, then check; never adds one"),+ ] = False,+ report: Annotated[bool, typer.Option("--report", help="Print the baseline's calls by package area (no pass/fail gating)")] = False,+ quiet: Annotated[+ bool, typer.Option("--quiet", "-q", help="Light output on success (single line); the full violation list still prints on failure")+ ] = False,+ against: Annotated[+ str | None,+ typer.Option(+ "--against",+ metavar="REF",+ help="Fail when the baseline lists a signature more times than the one committed at REF does (REF must resolve)",+ ),+ ] = None,+ against_merge_base: Annotated[+ str | None,+ typer.Option(+ "--against-merge-base",+ metavar="REF",+ help="Like --against, at the merge base of HEAD and REF; when that merge base does not resolve, say so and skip the comparison",+ ),+ ] = None,+) -> None:+ """Hold log calls to the log-call conventions against the committed baseline, which only shrinks."""+ try:+ check_log_calls_cmd(prune=prune, report=report, quiet=quiet, against=against, against_merge_base=against_merge_base)+ except (typer.Exit, typer.Abort):+ # Typer control-flow exits carry an intended exit code — not a failure. Let them through.+ raise+ except Exception: # ruff: ignore[blind-except]+ # Dev CLI command root: print a traceback for any unexpected failure and exit non-zero.+ console = get_console()+ console.print()+ console.print("[bold red]Unexpected error occurred[/bold red]")+ console.print()+ console.print(Traceback())+ sys.exit(1)++@app.command(name="check-keyword-only", help="Enforce the keyword-only-arguments convention across pipelex/ source")def check_keyword_only_command(report: Annotated[bool, typer.Option("--report", help="Print the full violation inventory grouped by package")] = False,diff --git a/pipelex/cli/dev_cli/commands/check_log_calls_cmd.py b/pipelex/cli/dev_cli/commands/check_log_calls_cmd.pynew file mode 100644index 000000000..47b6d88ea--- /dev/null+++ b/pipelex/cli/dev_cli/commands/check_log_calls_cmd.py@@ -0,0 +1,241 @@+"""Command holding log calls to the log-call conventions against a baseline that only shrinks.++The AST collection and the baseline logic live in the ``log_call_guard`` module; this module is the presentation+layer wired into the ``pipelex-dev`` Typer app (``make check-log-calls`` / ``make agent-check`` / ``make check`` /+CI). The conventions are in ``docs/tools/logging.md`` and the guard's specification in ``docs/contribute/log-calls.md``.+"""++from __future__ import annotations++import sys+from collections import Counter+from pathlib import Path++from rich.markup import escape+from rich.panel import Panel++from pipelex.cli.dev_cli.commands.log_call_guard import (+ BASELINE_FILE,+ BaselineComparison,+ BaselineGrowth,+ LogCallGuardError,+ LogCallRule,+ OffendingCall,+ StaleEntry,+ collect_offending_calls,+ compare_with_baseline,+ compare_with_trusted_baseline,+ load_baseline,+ load_trusted_baseline,+ package_area_of,+ prune_baseline,+ resolve_merge_base,+ write_baseline,+)+from pipelex.runtime_hub import get_console++SPEC_DOC = "docs/contribute/log-calls.md"+++def check_log_calls_cmd(+ *,+ prune: bool = False,+ report: bool = False,+ quiet: bool = False,+ against: str | None = None,+ against_merge_base: str | None = None,+) -> None:+ """Refuse a log call that breaks the conventions unless the baseline lists it, a baseline entry no call matches, and a baseline that grew.++ Args:+ prune: If True, rewrite the baseline without its stale signatures, then check. Pruning never adds an entry,+ so a call the baseline does not list still fails.+ report: If True, print the baseline's calls by package area and exit 0, with no gating.+ quiet: If True, keep the success output to a single line (for Make targets / CI). Quiet only trims the+ happy path: a failure still prints every offending call and every stale entry.+ against: A trusted revision whose committed baseline the working one may only shrink from: a signature it+ lists more times than that revision does fails. A revision that does not resolve is an error.+ against_merge_base: A ref whose merge base with ``HEAD`` is the trusted revision; when that merge base does+ not resolve, the comparison is skipped and the output says so.+ """+ console = get_console()+ repo_root = Path.cwd()++ try:+ offending = collect_offending_calls(repo_root=repo_root)+ baseline = load_baseline(repo_root=repo_root)+ except LogCallGuardError as exc:+ # An error is always loud: quiet only trims success output, never failures.+ _print_error(message=str(exc))+ sys.exit(1)++ if report:+ _print_report(baseline=baseline)+ return++ if prune:+ pruned = prune_baseline(baseline=baseline, offending=offending)+ nb_removed = sum(len(calls) for calls in baseline.values()) - sum(len(calls) for calls in pruned.values())+ if nb_removed:+ write_baseline(baseline=pruned, repo_root=repo_root)+ console.print(f"[green]✓ Removed {nb_removed} stale signature(s) from {escape(BASELINE_FILE.as_posix())}[/green]")+ baseline = pruned++ comparison = compare_with_baseline(offending=offending, baseline=baseline)+ nb_listed = sum(len(calls) for calls in baseline.values())++ try:+ trusted_ref, growth = _shrink_comparison(repo_root=repo_root, baseline=baseline, against=against, against_merge_base=against_merge_base)+ except LogCallGuardError as exc:+ _print_error(message=str(exc))+ sys.exit(1)++ if comparison.is_clean and not growth:+ shrink_note = f", none added since {escape(trusted_ref)}" if trusted_ref is not None else ""+ if quiet:+ console.print(f"[green]✓ Log-call check: PASSED[/green] ({nb_listed} baselined call(s) left{shrink_note})")+ else:+ console.print()+ console.print(+ Panel(+ "[green]✓[/green] Every log call follows the conventions or is listed in the baseline, "+ f"and every listed call still needs its entry.\n\n[dim]{nb_listed} baselined call(s) left to convert{shrink_note}.[/dim]",+ title="[bold green]Log-call Check: PASSED[/bold green]",+ border_style="green",+ padding=(1, 2),+ )+ )+ console.print()+ return++ _print_failure(comparison=comparison, growth=growth, trusted_ref=trusted_ref, quiet=quiet)+ sys.exit(1)+++def _shrink_comparison(+ *,+ repo_root: Path,+ baseline: dict[str, list[str]],+ against: str | None,+ against_merge_base: str | None,+) -> tuple[str | None, list[BaselineGrowth]]:+ """The trusted revision the baseline was compared with, and what it grew by since; ``None`` and nothing when there was none.++ Says plainly, whatever the verbosity, why a comparison that was asked for did not run.++ Raises:+ LogCallGuardError: When both options are given, or the trusted revision cannot be read.+ """+ console = get_console()+ trusted_commit: str+ trusted_label: str+ if against is not None and against_merge_base is not None:+ msg = "Give `--against` or `--against-merge-base`, not both"+ raise LogCallGuardError(msg)+ if against is not None:+ trusted_commit = against+ trusted_label = f"'{against}'"+ elif against_merge_base is not None:+ merge_base = resolve_merge_base(repo_root=repo_root, ref=against_merge_base)+ if merge_base is None:+ console.print(+ f"[yellow]! Log-call baseline not compared:[/yellow] no merge base of HEAD and '{escape(against_merge_base)}' resolves "+ f"(fetch '{escape(against_merge_base)}' to compare), so nothing here refuses an entry added to the baseline."+ )+ return None, []+ trusted_commit = merge_base+ trusted_label = f"the merge base with {against_merge_base} ({merge_base[:12]})"+ else:+ return None, []+ trusted = load_trusted_baseline(repo_root=repo_root, ref=trusted_commit)+ if trusted is None:+ console.print(+ f"[yellow]! Log-call baseline not compared:[/yellow] the log-call guard does not exist at {escape(trusted_label)}, "+ "so there is no baseline to hold this one to; the comparison applies from the change that introduces it."+ )+ return None, []+ return trusted_label, compare_with_trusted_baseline(baseline=baseline, trusted=trusted)+++def _print_error(*, message: str) -> None:+ get_console().print(f"[red]✗ Log-call check: FAILED[/red] - {escape(message)}")+++def _print_failure(*, comparison: BaselineComparison, growth: list[BaselineGrowth], trusted_ref: str | None, quiet: bool) -> None:+ console = get_console()+ summary = f"{len(comparison.unlisted)} call(s) break the conventions, {len(comparison.stale)} baseline signature(s) are stale"+ if trusted_ref is not None:+ summary += f", {len(growth)} baseline signature(s) were added since {trusted_ref}"+ if quiet:+ console.print(f"[red]✗ Log-call check: FAILED[/red] - {escape(summary)}:")+ else:+ console.print()+ console.print(+ Panel(+ f"[red]✗[/red] {escape(summary)}.\n\n"+ "[dim]A message at INFO and above is a literal with its values in `fields=`, and no message holds Rich markup. "+ "The baseline only shrinks.[/dim]",+ title="[bold red]Log-call Check: FAILED[/bold red]",+ border_style="red",+ padding=(1, 2),+ )+ )+ console.print()+ if comparison.unlisted:+ _print_unlisted(calls=comparison.unlisted)+ if comparison.stale:+ _print_stale(entries=comparison.stale)+ if growth and trusted_ref is not None:+ _print_growth(growth=growth, trusted_ref=trusted_ref)+ console.print(f"[dim]See {SPEC_DOC} and the log-call conventions in docs/tools/logging.md[/dim]")+++def _print_unlisted(*, calls: list[OffendingCall]) -> None:+ console = get_console()+ console.print("[bold]Calls the baseline does not list[/bold] — convert them; the baseline never grows:")+ rules: set[LogCallRule] = set()+ for call in calls:+ console.print(f" [red]{escape(call.relative_path)}:{call.lineno}[/red] [dim]{escape(call.qualified_name)}[/dim]")+ for breach in call.breaches:+ rules.add(breach.rule)+ console.print(f" [yellow]{escape(breach.rule)}[/yellow]: {escape(breach.detail)}")+ for rule in sorted(rules):+ console.print(f" [bold]{escape(rule)}[/bold] — [dim]{escape(rule.remedy)}[/dim]")+++def _print_stale(*, entries: list[StaleEntry]) -> None:+ console = get_console()+ console.print(+ f"[bold]Stale baseline signatures[/bold] — no call matches them any more (converted, moved or changed): "+ f"remove them from {escape(BASELINE_FILE.as_posix())}, by hand or with `pipelex-dev check-log-calls --prune`:"+ )+ for entry in entries:+ console.print(f" [red]{escape(entry.key)}[/red]")+ console.print(f" [dim]{escape(entry.signature)}[/dim]")+++def _print_growth(*, growth: list[BaselineGrowth], trusted_ref: str) -> None:+ console = get_console()+ console.print(+ f"[bold]Baseline signatures added since {escape(trusted_ref)}[/bold] — the baseline only shrinks: "+ "remove these entries and convert the calls they would exempt:"+ )+ for entry in growth:+ console.print(f" [red]{escape(entry.key)}[/red] [dim]listed {entry.working_count} time(s), {entry.trusted_count} at the base[/dim]")+ console.print(f" [dim]{escape(entry.signature)}[/dim]")+++def _print_report(*, baseline: dict[str, list[str]]) -> None:+ """Print the baseline's calls by package area, the largest first, for planning the conversion."""+ console = get_console()+ by_area: Counter[str] = Counter()+ for key, calls in baseline.items():+ by_area[package_area_of(key=key)] += len(calls)+ console.print()+ console.print("[bold]Log-call baseline by package area[/bold]")+ console.print()+ for area, nb_calls in by_area.most_common():+ console.print(f" [bold cyan]{escape(area)}[/bold cyan] {nb_calls} call(s)")+ console.print()+ console.print(f"[bold]Total baselined calls:[/bold] {by_area.total()}")+ console.print()diff --git a/pipelex/cli/dev_cli/commands/log_call_guard.py b/pipelex/cli/dev_cli/commands/log_call_guard.pynew file mode 100644index 000000000..f763d3d44--- /dev/null+++ b/pipelex/cli/dev_cli/commands/log_call_guard.py@@ -0,0 +1,1953 @@+"""AST core for the log-call guard.++Pipelex's log-call conventions, written for contributors in ``docs/tools/logging.md`` ("Log-call conventions"), say+that a line's message is a fixed sentence and that its values ride in ``fields``. This module checks the ones that+can be read off the source, on every call of the ``log`` facade in ``pipelex/`` outside ``pipelex/tools/log/``+and in the ``api/`` member's ``api/pipelex_api/``:++1. **The interpolation rule, at INFO and above** (``info``, ``warning``, ``error``, ``critical``). The message is a+ literal written at the call: a string constant, an f-string without a placeholder, a ``+`` of literals, a+ conditional between literals, or a name whose bindings that can reach the call are all literals, a ``+=`` of a+ literal included. A message built by an f-string, by ``%``, by ``+`` or by ``.format()`` is refused under that+ form's name, and so is a name bound to one of those, the binding's line given. Any other expression, a parameter,+ an attribute, a call's result, a mapping, a name captured from an enclosing function, is refused as+ ``non-literal``: the guard cannot tell that it is fixed, and every such message the first census found was built+ from values.+2. **The markup rule, at every level.** No literal text of a message, its title or its inline title holds a Rich+ markup tag: a closing tag (``[/red]``, ``[/]``), an ``@`` handler, or a tag whose text Rich reads as a style+ (``[red]``, ``[bold green]``, ``[link=https://…]``) or as one of its theme's style names. The text is read the way+ it reaches the console: a ``+`` of literals, named ones included, is folded into one text before it is scanned. A+ bracketed word that is no style, ``list[int]``, is text and passes. A tag escaped with a backslash passes.++The title and the inline title join the message (the dispatch renders them into it), so both rules read them too,+and a title or an inline title that is statically ``None`` is no text at all. A ``**`` expansion of a dict literal+with string keys passes its entries as keywords; any other ``**`` expansion could carry the message, so it is refused+as ``non-literal`` at every level. DEBUG and VERBOSE may keep an f-string; the markup rule holds there as everywhere.++**Names** are read by Python's own scoping: the scope the call is made in (a comprehension reading as part of the+scope it is written in), then the enclosing functions, class bodies never among them, then the module. Of a name's+bindings there, only those that can reach the read count, by the scope's control flow: the nearest along+straight-line code, the nearest on each path through an ``if``, a ``try`` or a ``match``, those a loop's later passes+carry back, and none past a ``return``, a ``raise``, a ``break`` or a ``continue``. A name bound in an enclosing+function is not followed. The facade itself is found the same way: a call's receiver is the facade where an import+of the facade reaches it. One index of every scope's bindings and flow is built per module, in one walk.++**The baseline.** The calls that broke the rules when the guard arrived are listed in the committed+``log_call_baseline.toml`` at the repo root, under the key ``<relative_path>::<qualified_name>`` of the function that+makes them, ``<module>`` for a module-level call, each by its signature: the method, the message's source text, the+rules the call breaks and every binding that reaches the names the guard read to judge it+(``warning: msg [f-string] where msg = f"Loaded {alias}"``), rendered the same on every supported Python. Line+numbers never enter it. The comparison with the tree is exact both ways: a call the baseline does not list fails,+and so does a listed signature no call matches any more, whether the call now complies, moved to another function,+or had its message, a binding of it or the rules it breaks change, until its entry is removed. Changing a listed+call's message is therefore converting it. ``prune_baseline`` removes stale signatures and never adds one; nothing+here adds one.++**The baseline only shrinks.** ``compare_with_trusted_baseline`` holds the working baseline to the one committed at+a trusted revision, the base a change merges into, read through git: a signature it does not list, or lists fewer+times, is growth, and fails.++There is no escape hatch: a message that must vary is a fixed message with fields.++The presentation layer wired into the ``pipelex-dev`` Typer app lives in ``check_log_calls_cmd.py``.+"""++from __future__ import annotations++import ast+import copy+import itertools+import json+import subprocess # ruff: ignore[suspicious-subprocess-import]+import tomllib+from collections import Counter+from contextlib import contextmanager+from enum import StrEnum+from pathlib import Path+from typing import TYPE_CHECKING, Any, NamedTuple, TypeAlias, cast++import tomlkit+from rich.default_styles import DEFAULT_STYLES+from rich.errors import StyleSyntaxError+from rich.markup import RE_TAGS+from rich.style import Style+from typing_extensions import override++from pipelex.tools.misc.toml_utils import save_toml_to_path++if TYPE_CHECKING:+ from collections.abc import Generator, Iterable, Iterator, Mapping, Sequence++#: The trees the guard scans, relative to the repo root: the runtime and the API server, which logs through the same facade.+SCAN_ROOTS: tuple[Path, ...] = (Path("pipelex"), Path("api") / "pipelex_api")++#: The directory a scan root's packages are imported from, when it is not the repo root itself.+IMPORT_ROOTS: tuple[Path, ...] = (Path("api"),)++#: The facade's own package, whose internals build messages for the sinks and are not call sites.+EXCLUDED_ROOTS: tuple[Path, ...] = (Path("pipelex") / "tools" / "log",)++#: The committed baseline of the calls that broke the rules when the guard arrived, relative to the repo root.+BASELINE_FILE = Path("log_call_baseline.toml")++#: This module, relative to the repo root: a revision that holds it runs the guard, so a baseline missing there is empty.+GUARD_MODULE_FILE = Path("pipelex") / "cli" / "dev_cli" / "commands" / "log_call_guard.py"++#: The only version of the baseline's shape.+BASELINE_VERSION = 1++#: The dotted paths the ``log`` facade is reachable at: the package's re-export and the object in its own module.+FACADE_PATHS = frozenset({"pipelex.log", "pipelex.tools.log.log.log"})++#: The modules whose ``import *`` binds the facade under its own name.+FACADE_STAR_MODULES = frozenset({"pipelex", "pipelex.tools.log.log"})+FACADE_NAME = "log"++#: The facade's methods at INFO and above, where a message is a literal.+INTERPOLATION_BOUND_METHODS = frozenset({"info", "warning", "error", "critical"})++#: Every method of the facade that emits a line, where a literal message holds no markup.+MARKUP_BOUND_METHODS = frozenset({"verbose", "debug", *INTERPOLATION_BOUND_METHODS})++#: The keyword a call may pass its message under instead of positionally.+CONTENT_KEYWORD = "content"++#: The keywords whose text the dispatch renders into the message.+TITLE_KEYWORDS = ("title", "inline")++#: The qualified name of a call made outside any function or class.+MODULE_SCOPE_NAME = "<module>"++#: How long a git command reading the trusted baseline may take.+GIT_TIMEOUT_SECONDS = 30+++class LogCallGuardError(Exception):+ """The guard cannot run as configured: a missing scan root, a malformed baseline or an unreadable revision, never a violation.++ Kept local to this module rather than derived from ``PipelexError``, for the reason ``hub_layering_guard``+ gives for its own.+ """+++class LogCallRule(StrEnum):+ """A rule a log call breaks, each naming its remedy."""++ F_STRING = "f-string"+ PERCENT_FORMAT = "percent-format"+ CONCATENATION = "concatenation"+ FORMAT_CALL = "format-call"+ NON_LITERAL = "non-literal"+ MARKUP = "markup"++ @property+ def remedy(self) -> str:+ match self:+ case LogCallRule.F_STRING | LogCallRule.PERCENT_FORMAT | LogCallRule.CONCATENATION | LogCallRule.FORMAT_CALL:+ return "write a fixed message and pass its values in `fields=` (DEBUG and VERBOSE may keep an f-string)"+ case LogCallRule.NON_LITERAL:+ return "write the message as a literal at the call and pass what varies in `fields=`"+ case LogCallRule.MARKUP:+ return "drop the tag: the console colours a value by its field's name, or draws a named layout"+++class RuleBreach(NamedTuple):+ """One rule a call breaks, with what the reader needs to find it."""++ rule: LogCallRule+ detail: str+++class OffendingCall(NamedTuple):+ """One facade call that breaks at least one rule.++ Attributes:+ relative_path: The source file, posix, relative to the repo root.+ qualified_name: The enclosing classes and functions joined by dots, or ``<module>``.+ lineno: The call's line, for the report only: it never enters the baseline.+ signature: The call's identity in the baseline: its method, its message's source text, the rules it breaks+ and the bindings the guard read to judge it.+ breaches: Every rule the call breaks.+ """++ relative_path: str+ qualified_name: str+ lineno: int+ signature: str+ breaches: tuple[RuleBreach, ...]++ @property+ def key(self) -> str:+ """The baseline key: ``<relative_path>::<qualified_name>``."""+ return f"{self.relative_path}::{self.qualified_name}"+++class StaleEntry(NamedTuple):+ """A baseline signature that no call matches any more."""++ key: str+ signature: str+++class BaselineComparison(NamedTuple):+ """What the tree and the baseline disagree on; both lists empty is a pass."""++ unlisted: list[OffendingCall]+ stale: list[StaleEntry]++ @property+ def is_clean(self) -> bool:+ return not self.unlisted and not self.stale+++class BaselineGrowth(NamedTuple):+ """A signature the working baseline lists more times than the trusted one does: an entry added since."""++ key: str+ signature: str+ trusted_count: int+ working_count: int+++# --------------------------------------------------------------------------------------+# Markup: what Rich would read as console markup in a piece of text+#+# The one reading of a markup tag in the repo's checks: the guard applies it to a call's literal text, and the+# live-run tests to the messages a run logs. A tag-shaped span is not markup by its shape alone. Rich's tag pattern+# also matches the `[int]` of `list[int]`, a `[cycle]` marker and a backend's table, `[openai]`, yet none of them+# names a style, and a message holding one prints as written. So a tag counts as markup only when Rich would style+# with it: a closing tag, `[/]` or `[/red]`; an `@` handler, `[@click=app.bell]`; or an opening tag whose text Rich+# parses as a style, `[bold]`, `[on blue]`, `[link=https://pipelex.com]`, or that names a style of Rich's default+# theme, `[repr.number]`. A tag escaped with a backslash is text, since Rich prints it as written.+# --------------------------------------------------------------------------------------+++def _reads_as_style(*, tag_text: str) -> bool:+ """Whether Rich renders a tag's text as markup rather than leaving the reader a bracketed word.++ A closing tag and an ``@`` handler are markup whatever they name. An opening tag is markup when Rich parses its+ text as a style, ``name=parameters`` read the way Rich's own ``Tag`` reads it, or when it names a style of Rich's+ default theme.+ """+ if tag_text.startswith(("/", "@")):+ return True+ if tag_text in DEFAULT_STYLES:+ return True+ name, separator, parameters = tag_text.partition("=")+ style_text = f"{name} {parameters}" if separator else name+ try:+ Style.parse(style_text)+ except StyleSyntaxError:+ return False+ return True+++def find_markup_tags(*, text: str) -> list[str]:+ """The unescaped tags in the text that Rich would apply as markup, in order, each as written.++ Tags are found by Rich's own pattern, ``rich.markup.RE_TAGS``: a run of backslashes, then a bracketed tag whose+ text opens with a lowercase letter, ``#``, ``/`` or ``@``.+ """+ if "[" not in text:+ return []+ tags: list[str] = []+ for match in RE_TAGS.finditer(text):+ full_text, escapes, tag_text = match.groups()+ # An odd run of backslashes escapes the tag, which then prints as written.+ if len(escapes) % 2 == 1:+ continue+ if _reads_as_style(tag_text=tag_text):+ tags.append(full_text[len(escapes) :])+ return tags+++# --------------------------------------------------------------------------------------+# Source text, the same on every supported Python+# --------------------------------------------------------------------------------------+++def _escape_literal_part(*, text: str) -> str:+ """A literal part of an f-string as the signature writes it: JSON's escapes, braces doubled."""+ return json.dumps(text, ensure_ascii=False)[1:-1].replace("{", "{{").replace("}", "}}")+++def _render_joined_parts(*, values: list[ast.expr]) -> str:+ rendered: list[str] = []+ for value in values:+ match value:+ case ast.Constant(value=str() as text):+ rendered.append(_escape_literal_part(text=text))+ case ast.FormattedValue(value=inner, conversion=conversion, format_spec=format_spec):+ conversion_text = "" if conversion == -1 else f"!{chr(conversion)}"+ spec_text = ""+ if isinstance(format_spec, ast.JoinedStr):+ spec_text = ":" + _render_joined_parts(values=format_spec.values)+ rendered.append("{" + render_source(expr=inner) + conversion_text + spec_text + "}")+ case _:+ rendered.append("{" + render_source(expr=value) + "}")+ return "".join(rendered)+++class _JoinedStrFlattener(ast.NodeTransformer):+ """Replaces each f-string by a name whose text is the f-string's canonical rendering.++ An f-string is the one node whose ``ast.unparse`` rendering follows the parser's quoting rules, which PEP 701+ changed in Python 3.12, so the guard renders f-strings itself and a signature never depends on the interpreter+ the check runs on. Every other node ``ast.unparse`` renders through ``repr`` and fixed punctuation.+ """++ @override+ def visit_JoinedStr(self, node: ast.JoinedStr) -> ast.AST: # pylint: disable=invalid-name # ast.NodeTransformer dispatch name+ return ast.Name(id='f"' + _render_joined_parts(values=node.values) + '"', ctx=ast.Load())+++def render_source(*, expr: ast.expr) -> str:+ """An expression's source text, rendered the same on every supported Python."""+ if isinstance(expr, ast.JoinedStr):+ return 'f"' + _render_joined_parts(values=expr.values) + '"'+ flattened = _JoinedStrFlattener().visit(copy.deepcopy(expr))+ return ast.unparse(cast("ast.AST", flattened))+++_OPERATOR_SYMBOLS: dict[type[ast.operator], str] = {+ ast.Add: "+",+ ast.Sub: "-",+ ast.Mult: "*",+ ast.MatMult: "@",+ ast.Div: "/",+ ast.Mod: "%",+ ast.Pow: "**",+ ast.LShift: "<<",+ ast.RShift: ">>",+ ast.BitOr: "|",+ ast.BitXor: "^",+ ast.BitAnd: "&",+ ast.FloorDiv: "//",+}+++def _operator_symbol(*, operator: ast.operator) -> str:+ return _OPERATOR_SYMBOLS.get(type(operator), type(operator).__name__)+++# --------------------------------------------------------------------------------------+# Scopes, bindings and the flow between them, indexed once per module+# --------------------------------------------------------------------------------------+++class _ScopeKind(StrEnum):+ MODULE = "module"+ FUNCTION = "function"+ CLASS = "class"+ COMPREHENSION = "comprehension"++ @property+ def is_module(self) -> bool:+ match self:+ case _ScopeKind.MODULE:+ return True+ case _ScopeKind.FUNCTION | _ScopeKind.CLASS | _ScopeKind.COMPREHENSION:+ return False++ @property+ def is_class(self) -> bool:+ match self:+ case _ScopeKind.CLASS:+ return True+ case _ScopeKind.MODULE | _ScopeKind.FUNCTION | _ScopeKind.COMPREHENSION:+ return False++ @property+ def is_comprehension(self) -> bool:+ match self:+ case _ScopeKind.COMPREHENSION:+ return True+ case _ScopeKind.MODULE | _ScopeKind.FUNCTION | _ScopeKind.CLASS:+ return False++ @property+ def runs_when_called(self) -> bool:+ """Whether the scope's code runs whenever it is called, rather than once, where it is written."""+ match self:+ case _ScopeKind.FUNCTION:+ return True+ case _ScopeKind.MODULE | _ScopeKind.CLASS | _ScopeKind.COMPREHENSION:+ return False+++class _OpaqueBinding(StrEnum):+ """What binds a name to a value the guard does not read, each written in a signature as ``<kind>``."""++ PARAMETER = "parameter"+ FOR_TARGET = "for target"+ WITH_TARGET = "with target"+ EXCEPT_TARGET = "except target"+ COMPREHENSION_TARGET = "comprehension target"+ MATCH_CAPTURE = "match capture"+ UNPACKING = "unpacking"+ IMPORT = "import"+ DEFINITION = "definition"+ ASSIGNMENT_TARGET = "assignment target"++ @property+ def placeholder(self) -> str:+ return f"<{self}>"+++#: What a name the guard does not follow is written as in a signature: one captured from an enclosing function,+#: and one bound nowhere it is read from.+_CAPTURED_PLACEHOLDER = "<enclosing function>"+_UNBOUND_PLACEHOLDER = "<unbound>"+++class _Binding:+ """One binding of a name: the value bound, the scope that value is read in, and how it binds.++ Compared by identity: two bindings of the same text on two lines are two bindings.++ Attributes:+ serial: The binding's rank in the walk, which orders the bindings of one line.+ value: The bound expression, ``None`` for an opaque binding.+ scope: The scope the value is evaluated in, which is where the names it reads resolve: the function a+ ``global`` assignment is written in, or the comprehension holding a ``:=``, rather than the scope the+ name lands in.+ lineno: The line, for the report only.+ operator: The operator of an augmented assignment, ``None`` for a plain one.+ prior: The target of an augmented assignment, the read of the value it updates.+ opaque: What binds the name when the guard does not read the value: a parameter, a loop target, an import.+ import_path: The dotted path an import binds the name to, which tells the facade apart.+ """++ def __init__(+ self,+ *,+ serial: int,+ value: ast.expr | None,+ scope: _Scope,+ lineno: int,+ operator: ast.operator | None = None,+ prior: ast.Name | None = None,+ opaque: _OpaqueBinding | None = None,+ import_path: str | None = None,+ ) -> None:+ self.serial = serial+ self.value = value+ self.scope = scope+ self.lineno = lineno+ self.operator = operator+ self.prior = prior+ self.opaque = opaque+ self.import_path = import_path++ def render(self, *, name: str) -> str:+ """The binding as a signature writes it: its source text, never its line."""+ if self.opaque is not None or self.value is None:+ return f"{name} = {(self.opaque or _OpaqueBinding.ASSIGNMENT_TARGET).placeholder}"+ if self.operator is not None:+ return f"{name} {_operator_symbol(operator=self.operator)}= {render_source(expr=self.value)}"+ return f"{name} = {render_source(expr=self.value)}"+++class _EntryPoint:+ """Where a scope written in the module starts to run in the module's flow, and the module bindings it can see.++ A class body runs once, where its statement stands, and sees ``at_entry``. A function may be called at any time+ once it is defined, and also sees ``after``: every module binding made from then on, in any order.+ """++ def __init__(self) -> None:+ self.at_entry: dict[str, set[_Binding]] = {}+ self.after: dict[str, set[_Binding]] = {}+++class _Scope:+ """One scope of a module: the names it binds, by Python's rules, and the flow of its statements."""++ def __init__(self, *, kind: _ScopeKind, parent: _Scope | None) -> None:+ self.kind = kind+ self.parent = parent+ self.bindings: dict[str, list[_Binding]] = {}+ # Every name a binding operation targets here, `del` and a bare annotation included: those make a name+ # local without giving it a value.+ self.bound_names: set[str] = set()+ self.global_names: set[str] = set()+ self.nonlocal_names: set[str] = set()+ # The bindings another scope makes here through `global` or `nonlocal`, which run whenever it is called.+ self.moved_bindings: dict[str, list[_Binding]] = {}+ # The flow of a scope that is not a comprehension: the events of its statements, and the stack of event lists+ # the walk is filling. A comprehension's flow is part of the scope it is written in.+ self.events: list[_Event] = []+ self.sinks: list[list[_Event]] = [self.events]+ # Where the scope starts to run in the module's flow, and whether it runs there or whenever it is called.+ self.entry: _EntryPoint | None = None+ self.runs_later = False++ def bind(self, *, name: str, binding: _Binding) -> None:+ self.bindings.setdefault(name, []).append(binding)+ self.bound_names.add(name)++ def owns(self, *, name: str) -> bool:+ """Whether the name is local to this scope: bound here and declared neither ``global`` nor ``nonlocal``."""+ return name in self.bound_names and name not in self.global_names and name not in self.nonlocal_names++ @property+ def statement_scope(self) -> _Scope:+ """The nearest scope that is not a comprehension: where a ``:=`` in a comprehension binds its name."""+ scope = self+ while scope.kind.is_comprehension and scope.parent is not None:+ scope = scope.parent+ return scope+++#: Where a name read in a scope resolves: the scope whose bindings it reads, or the placeholder of a name not followed.+_Location: TypeAlias = _Scope | str++#: What a name read resolves to: the placeholder of a name not followed, or the bindings that can reach the read, in+#: source order, none when no binding does.+_Reach: TypeAlias = str | list[_Binding]+++# ---- the flow of a scope, as events ------------------------------------------------+++class _JumpKind(StrEnum):+ RETURN = "return"+ RAISE = "raise"+ BREAK = "break"+ CONTINUE = "continue"+++class _Read(NamedTuple):+ """A name read: the bindings that reach it are recorded against its node."""++ node: ast.Name+ name: str+++class _Bind(NamedTuple):+ """A name bound, replacing whatever it held."""++ name: str+ binding: _Binding+++class _Kill(NamedTuple):+ """A name deleted, or an except target cleared as its handler ends."""++ name: str+++class _Enter(NamedTuple):+ """The point of the module's flow a scope written there starts to run from."""++ point: _EntryPoint+++class _Branch(NamedTuple):+ """Paths of which exactly one runs; an empty path is the way around the others."""++ paths: tuple[list[_Event], ...]+++class _Loop(NamedTuple):+ """A loop: its test runs before each pass and before it ends, its body any number of times, its ``else`` on a normal end."""++ test: list[_Event]+ body: list[_Event]+ orelse: list[_Event]+++class _Try(NamedTuple):+ """A ``try``, or a ``with`` statement, whose context manager may swallow what its body raises."""++ body: list[_Event]+ handlers: tuple[list[_Event], ...]+ orelse: list[_Event]+ final: list[_Event]+++class _Match(NamedTuple):+ """A ``match``: each case's pattern and guard, then its body, and whether its last case always matches."""++ cases: tuple[tuple[list[_Event], list[_Event]], ...]+ is_exhaustive: bool+++class _Jump(NamedTuple):+ """A ``return``, ``raise``, ``break`` or ``continue``: nothing after it in its block runs."""++ kind: _JumpKind+++_Event: TypeAlias = _Read | _Bind | _Kill | _Enter | _Branch | _Loop | _Try | _Match | _Jump++#: The bindings that can reach a point for one name, ``None`` standing for a path on which the name holds nothing.+_Reaching: TypeAlias = frozenset[_Binding | None]++_NOTHING: _Reaching = frozenset({None})+++def _union(*, sets: Iterable[_Reaching]) -> _Reaching:+ merged: set[_Binding | None] = set()+ for reaching in sets:+ merged.update(reaching)+ return frozenset(merged)+++class _FlowState:+ """What reaches one point of a scope's flow: each name's bindings, and the entry points already passed."""++ def __init__(self, *, names: dict[str, _Reaching], active: frozenset[_EntryPoint]) -> None:+ self.names = names+ self.active = active++ def reaching(self, *, name: str) -> _Reaching:+ return self.names.get(name, _NOTHING)++ def copy(self) -> _FlowState:+ return _FlowState(names=dict(self.names), active=self.active)++ def is_same_as(self, *, other: _FlowState) -> bool:+ return self.names == other.names and self.active == other.active+++def _joined(*, states: Iterable[_FlowState | None]) -> _FlowState | None:+ """The state where paths meet: each name holding what it holds on any of them; ``None`` when no path gets there."""+ live = [state for state in states if state is not None]+ if not live:+ return None+ if len(live) == 1:+ return live[0].copy()+ every_name: set[str] = set()+ for state in live:+ every_name.update(state.names)+ names = {name: _union(sets=(state.reaching(name=name) for state in live)) for name in every_name}+ active: set[_EntryPoint] = set()+ for state in live:+ active.update(state.active)+ return _FlowState(names=names, active=frozenset(active))+++class _LoopFrame:+ """A loop being run: the states its ``break`` and ``continue`` statements leave with."""++ def __init__(self) -> None:+ self.jumps: dict[_JumpKind, list[_FlowState]] = {}+++class _RaiseFrame:+ """A region whose exceptions a handler or a ``finally`` takes over: every state reached in it, joined.++ A ``finally`` region also keeps the jumps that leave through it, which resume once the ``finally`` has run.+ """++ def __init__(self, *, state: _FlowState, has_finally: bool) -> None:+ self.state = state.copy()+ self.has_finally = has_finally+ self.jumps: dict[_JumpKind, list[_FlowState]] = {}++ def note(self, *, name: str, reaching: _Reaching) -> None:+ self.state.names[name] = self.state.reaching(name=name) | reaching+++class _FlowRunner:+ """Runs one scope's flow, recording at each name read every binding that can reach it.++ A loop runs until the state at its head stops growing, so a binding later in its body reaches a read earlier in it.+ """++ def __init__(self, *, recorded: dict[ast.Name, set[_Binding | None]]) -> None:+ self._recorded = recorded+ self._frames: list[_LoopFrame | _RaiseFrame] = []++ def run(self, *, events: Sequence[_Event], state: _FlowState | None) -> _FlowState | None:+ """The state after the events, ``None`` when no path gets through them. The state given is consumed."""+ for event in events:+ if state is None:+ return None+ state = self._step(event=event, state=state)+ return state++ def _step(self, *, event: _Event, state: _FlowState) -> _FlowState | None:+ match event:+ case _Read(node=node, name=name):+ self._recorded.setdefault(node, set()).update(state.reaching(name=name))+ return state+ case _Bind(name=name, binding=binding):+ state.names[name] = frozenset({binding})+ for point in state.active:+ point.after.setdefault(name, set()).add(binding)+ self._note(name=name, reaching=frozenset({binding}))+ return state+ case _Kill(name=name):+ state.names.pop(name, None)+ self._note(name=name, reaching=_NOTHING)+ return state+ case _Enter(point=point):+ for name, reaching in state.names.items():+ point.at_entry.setdefault(name, set()).update(binding for binding in reaching if binding is not None)+ state.active |= {point}+ for frame in self._raise_frames():+ frame.state.active |= {point}+ return state+ case _Branch(paths=paths):+ return _joined(states=[self.run(events=path, state=state.copy()) for path in paths])+ case _Loop():+ return self._run_loop(loop=event, state=state)+ case _Try():+ return self._run_try(statement=event, state=state)+ case _Match():+ return self._run_match(statement=event, state=state)+ case _Jump(kind=kind):+ self._jump(kind=kind, state=state)+ return None++ def _raise_frames(self) -> list[_RaiseFrame]:+ return [frame for frame in self._frames if isinstance(frame, _RaiseFrame)]++ def _note(self, *, name: str, reaching: _Reaching) -> None:+ """An exception may be raised once a name changes: every enclosing handler and ``finally`` may see it."""+ for frame in self._raise_frames():+ frame.note(name=name, reaching=reaching)++ def _jump(self, *, kind: _JumpKind, state: _FlowState) -> None:+ """Hand a jump's state to what it resumes at: the innermost ``finally`` it leaves through, else its loop."""+ match kind:+ case _JumpKind.RAISE:+ # Every state a region reaches is already noted in the frames that take its exceptions over.+ return+ case _JumpKind.RETURN:+ frames = [frame for frame in self._raise_frames() if frame.has_finally]+ if frames:+ frames[-1].jumps.setdefault(kind, []).append(state.copy())+ case _JumpKind.BREAK | _JumpKind.CONTINUE:+ for frame in reversed(self._frames):+ if isinstance(frame, _LoopFrame) or frame.has_finally:+ frame.jumps.setdefault(kind, []).append(state.copy())+ return++ def _run_loop(self, *, loop: _Loop, state: _FlowState) -> _FlowState | None:+ head = state.copy()+ while True:+ frame = _LoopFrame()+ self._frames.append(frame)+ tested = self.run(events=loop.test, state=head.copy())+ body_end = self.run(events=loop.body, state=tested.copy() if tested is not None else None)+ self._frames.pop()+ next_head = _joined(states=[state, body_end, *frame.jumps.get(_JumpKind.CONTINUE, [])])+ if next_head is None or next_head.is_same_as(other=head):+ break+ head = next_head+ finished = self.run(events=loop.orelse, state=tested)+ return _joined(states=[finished, *frame.jumps.get(_JumpKind.BREAK, [])])++ def _run_try(self, *, statement: _Try, state: _FlowState) -> _FlowState | None:+ """The handlers start from any state the body reached, and a ``finally`` runs on every way out."""+ finally_frame = _RaiseFrame(state=state, has_finally=True) if statement.final else None+ if finally_frame is not None:+ self._frames.append(finally_frame)+ body_frame = _RaiseFrame(state=state, has_finally=False)+ self._frames.append(body_frame)+ body_end = self.run(events=statement.body, state=state)+ self._frames.pop()+ handler_ends = [self.run(events=handler, state=body_frame.state.copy()) for handler in statement.handlers]+ finished = _joined(states=[self.run(events=statement.orelse, state=body_end), *handler_ends])+ if finally_frame is None:+ return finished+ self._frames.pop()+ # After an exception the `finally` runs and the exception goes on; after a jump it runs and the jump resumes.+ self.run(events=statement.final, state=finally_frame.state.copy())+ for kind, jump_states in finally_frame.jumps.items():+ resumed = self.run(events=statement.final, state=_joined(states=jump_states))+ if resumed is not None:+ self._jump(kind=kind, state=resumed)+ return self.run(events=statement.final, state=finished)++ def _run_match(self, *, statement: _Match, state: _FlowState) -> _FlowState | None:+ """Each case is tried from what the failed ones left: a pattern may bind its captures and still fail."""+ trying = state+ ends: list[_FlowState | None] = []+ for pattern, body in statement.cases:+ matched = self.run(events=pattern, state=trying.copy())+ if matched is None:+ continue+ ends.append(self.run(events=body, state=matched.copy()))+ trying = _joined(states=[trying, matched]) or trying+ if not statement.is_exhaustive:+ ends.append(trying)+ return _joined(states=ends)+++def _is_irrefutable(*, case: ast.match_case) -> bool:+ """Whether a case always matches: a bare capture or ``_``, with no guard."""+ return case.guard is None and isinstance(case.pattern, ast.MatchAs) and case.pattern.pattern is None+++# ---- the index -------------------------------------------------------------------------+++class _ScopeIndex:+ """Every scope of one module with the names it binds and the flow of its statements, built in one walk, then+ each flow run once, which records the bindings that can reach each name read.++ The flow follows Python's control flow: a binding reaches a read along straight-line code until another+ replaces it, the branches of an ``if``, a ``try`` or a ``match`` each bring theirs, a loop brings the bindings+ of its later passes, and code after a ``return``, a ``raise``, a ``break`` or a ``continue`` is reached by+ nothing.+ """++ def __init__(self, *, module: ast.Module, package: str) -> None:+ self.module_scope = _Scope(kind=_ScopeKind.MODULE, parent=None)+ self.call_scopes: dict[ast.Call, _Scope] = {}+ self._package = package+ self._scopes: list[_Scope] = [self.module_scope]+ self._serials = itertools.count()+ self._recorded: dict[ast.Name, set[_Binding | None]] = {}+ for statement in module.body:+ self._visit(node=statement, scope=self.module_scope)+ self._apply_declarations()+ for scope in self._scopes:+ if not scope.kind.is_comprehension:+ _FlowRunner(recorded=self._recorded).run(events=scope.events, state=_FlowState(names={}, active=frozenset()))++ # ---- the walk ---------------------------------------------------------------------++ def _new_binding(+ self,+ *,+ value: ast.expr | None,+ scope: _Scope,+ lineno: int,+ operator: ast.operator | None = None,+ prior: ast.Name | None = None,+ opaque: _OpaqueBinding | None = None,+ import_path: str | None = None,+ ) -> _Binding:+ return _Binding(+ serial=next(self._serials),+ value=value,+ scope=scope,+ lineno=lineno,+ operator=operator,+ prior=prior,+ opaque=opaque,+ import_path=import_path,+ )++ def _nested_scope(self, *, kind: _ScopeKind, parent: _Scope) -> _Scope:+ """A scope written in ``parent``, with the point of the module's flow it starts to run from."""+ scope = _Scope(kind=kind, parent=parent)+ self._scopes.append(scope)+ flow = parent.statement_scope+ if flow.kind.is_module and not kind.is_comprehension:+ point = _EntryPoint()+ self._emit(scope=flow, event=_Enter(point=point))+ scope.entry = point+ else:+ scope.entry = flow.entry+ scope.runs_later = flow.runs_later or kind.runs_when_called+ return scope++ @staticmethod+ def _emit(*, scope: _Scope, event: _Event) -> None:+ scope.statement_scope.sinks[-1].append(event)++ @contextmanager+ def _sink(self, *, scope: _Scope) -> Generator[list[_Event]]:+ """Collect the events the walk emits in a scope's flow, for one block of a compound statement."""+ events: list[_Event] = []+ flow = scope.statement_scope+ flow.sinks.append(events)+ try:+ yield events+ finally:+ flow.sinks.pop()++ def _collected(self, *, nodes: Iterable[ast.AST | None], scope: _Scope) -> list[_Event]:+ with self._sink(scope=scope) as events:+ self._visit_all(nodes=nodes, scope=scope)+ return events++ def _bind(self, *, name: str, owner: _Scope, binding: _Binding) -> None:+ """Bind a name in the scope that owns it and, unless that is a comprehension, in that scope's flow."""+ owner.bind(name=name, binding=binding)+ if not owner.kind.is_comprehension:+ self._emit(scope=owner, event=_Bind(name=name, binding=binding))++ def _visit_all(self, *, nodes: Iterable[ast.AST | None], scope: _Scope) -> None:+ for node in nodes:+ if node is not None:+ self._visit(node=node, scope=scope)++ def _visit(self, *, node: ast.AST, scope: _Scope) -> None:+ match node:+ case ast.FunctionDef() | ast.AsyncFunctionDef():+ self._visit_all(nodes=node.decorator_list, scope=scope)+ self._visit_signature_outside(arguments=node.args, scope=scope)+ self._visit_all(nodes=[node.returns, *getattr(node, "type_params", [])], scope=scope)+ function_scope = self._nested_scope(kind=_ScopeKind.FUNCTION, parent=scope)+ self._bind_parameters(arguments=node.args, scope=function_scope)+ self._visit_all(nodes=node.body, scope=function_scope)+ self._bind_opaque(name=node.name, kind=_OpaqueBinding.DEFINITION, scope=scope, lineno=node.lineno)+ case ast.Lambda():+ self._visit_signature_outside(arguments=node.args, scope=scope)+ lambda_scope = self._nested_scope(kind=_ScopeKind.FUNCTION, parent=scope)+ self._bind_parameters(arguments=node.args, scope=lambda_scope)+ self._visit(node=node.body, scope=lambda_scope)+ case ast.ClassDef():+ self._visit_all(nodes=[*node.decorator_list, *node.bases, *node.keywords, *getattr(node, "type_params", [])], scope=scope)+ class_scope = self._nested_scope(kind=_ScopeKind.CLASS, parent=scope)+ self._visit_all(nodes=node.body, scope=class_scope)+ self._bind_opaque(name=node.name, kind=_OpaqueBinding.DEFINITION, scope=scope, lineno=node.lineno)+ case ast.ListComp(elt=elt, generators=generators) | ast.SetComp(elt=elt, generators=generators):+ self._visit_comprehension(generators=generators, results=[elt], scope=scope)+ case ast.GeneratorExp(elt=elt, generators=generators):+ self._visit_comprehension(generators=generators, results=[elt], scope=scope)+ case ast.DictComp(key=key, value=value, generators=generators):+ self._visit_comprehension(generators=generators, results=[key, value], scope=scope)+ case ast.Assign(targets=targets, value=value):+ self._visit(node=value, scope=scope)+ for target in targets:+ if isinstance(target, ast.Name):+ self._bind(name=target.id, owner=scope, binding=self._new_binding(value=value, scope=scope, lineno=node.lineno))+ else:+ self._bind_target(target=target, kind=_OpaqueBinding.UNPACKING, scope=scope)+ case ast.AnnAssign(target=target, annotation=annotation, value=value):+ self._visit_all(nodes=[annotation, value], scope=scope)+ if isinstance(target, ast.Name):+ if value is None:+ # A bare annotation binds no value but makes the name local, by Python's rules.+ scope.bound_names.add(target.id)+ else:+ self._bind(name=target.id, owner=scope, binding=self._new_binding(value=value, scope=scope, lineno=node.lineno))+ else:+ self._visit(node=target, scope=scope)+ case ast.AugAssign(target=ast.Name(id=name) as target, op=operator, value=value):+ # The value updated is read where the update stands.+ self._emit(scope=scope, event=_Read(node=target, name=name))+ self._visit(node=value, scope=scope)+ binding = self._new_binding(value=value, scope=scope, lineno=node.lineno, operator=operator, prior=target)+ self._bind(name=name, owner=scope, binding=binding)+ case ast.NamedExpr(target=ast.Name(id=name), value=value):+ self._visit(node=value, scope=scope)+ # A `:=` in a comprehension binds in the scope the comprehension is written in, its value read where it stands.+ self._bind(name=name, owner=scope.statement_scope, binding=self._new_binding(value=value, scope=scope, lineno=node.lineno))+ case ast.If(test=test, body=body, orelse=orelse):+ self._visit(node=test, scope=scope)+ self._emit(scope=scope, event=_Branch(paths=(self._collected(nodes=body, scope=scope), self._collected(nodes=orelse, scope=scope))))+ case ast.While(test=test, body=body, orelse=orelse):+ loop = _Loop(+ test=self._collected(nodes=[test], scope=scope),+ body=self._collected(nodes=body, scope=scope),+ orelse=self._collected(nodes=orelse, scope=scope),+ )+ self._emit(scope=scope, event=loop)+ case (+ ast.For(target=target, iter=iterable, body=body, orelse=orelse) | ast.AsyncFor(target=target, iter=iterable, body=body, orelse=orelse)+ ):+ self._visit(node=iterable, scope=scope)+ with self._sink(scope=scope) as loop_body:+ self._bind_target(target=target, kind=_OpaqueBinding.FOR_TARGET, scope=scope)+ self._visit_all(nodes=body, scope=scope)+ self._emit(scope=scope, event=_Loop(test=[], body=loop_body, orelse=self._collected(nodes=orelse, scope=scope)))+ case ast.With(items=items, body=body) | ast.AsyncWith(items=items, body=body):+ for item in items:+ self._visit(node=item.context_expr, scope=scope)+ if item.optional_vars is not None:+ self._bind_target(target=item.optional_vars, kind=_OpaqueBinding.WITH_TARGET, scope=scope)+ # A context manager may swallow what its body raises, so what follows may see any state the body reached.+ self._emit(scope=scope, event=_Try(body=self._collected(nodes=body, scope=scope), handlers=([],), orelse=[], final=[]))+ case (+ ast.Try(body=body, handlers=handlers, orelse=orelse, finalbody=finalbody)+ | ast.TryStar(body=body, handlers=handlers, orelse=orelse, finalbody=finalbody)+ ):+ statement = _Try(+ body=self._collected(nodes=body, scope=scope),+ handlers=tuple(self._handler_events(handler=handler, scope=scope) for handler in handlers),+ orelse=self._collected(nodes=orelse, scope=scope),+ final=self._collected(nodes=finalbody, scope=scope),+ )+ self._emit(scope=scope, event=statement)+ case ast.Match(subject=subject, cases=cases):+ self._visit(node=subject, scope=scope)+ match_cases = tuple(+ (self._collected(nodes=[case.pattern, case.guard], scope=scope), self._collected(nodes=case.body, scope=scope)) for case in cases+ )+ self._emit(scope=scope, event=_Match(cases=match_cases, is_exhaustive=bool(cases) and _is_irrefutable(case=cases[-1])))+ case ast.Return(value=value):+ self._visit_all(nodes=[value], scope=scope)+ self._emit(scope=scope, event=_Jump(kind=_JumpKind.RETURN))+ case ast.Raise(exc=exception, cause=cause):+ self._visit_all(nodes=[exception, cause], scope=scope)+ self._emit(scope=scope, event=_Jump(kind=_JumpKind.RAISE))+ case ast.Break():+ self._emit(scope=scope, event=_Jump(kind=_JumpKind.BREAK))+ case ast.Continue():+ self._emit(scope=scope, event=_Jump(kind=_JumpKind.CONTINUE))+ case ast.Import() | ast.ImportFrom():+ self._bind_imports(statement=node, scope=scope)+ case ast.Global(names=names):+ # A module-level `global` changes nothing.+ if not scope.kind.is_module:+ scope.global_names.update(names)+ case ast.Nonlocal(names=names):+ scope.nonlocal_names.update(names)+ case ast.MatchAs(pattern=pattern, name=capture_name):+ if pattern is not None:+ self._visit(node=pattern, scope=scope)+ if capture_name is not None:+ self._bind_opaque(name=capture_name, kind=_OpaqueBinding.MATCH_CAPTURE, scope=scope, lineno=node.lineno)+ case ast.MatchStar(name=capture_name):+ if capture_name is not None:+ self._bind_opaque(name=capture_name, kind=_OpaqueBinding.MATCH_CAPTURE, scope=scope, lineno=node.lineno)+ case ast.MatchMapping(keys=keys, patterns=patterns, rest=rest):+ self._visit_all(nodes=[*keys, *patterns], scope=scope)+ if rest is not None:+ self._bind_opaque(name=rest, kind=_OpaqueBinding.MATCH_CAPTURE, scope=scope, lineno=node.lineno)+ case ast.BoolOp(values=values):+ # Each operand after the first runs only when the ones before it did not decide.+ self._visit(node=values[0], scope=scope)+ self._visit_short_circuit(values=values[1:], scope=scope)+ case ast.IfExp(test=test, body=body, orelse=orelse):+ self._visit(node=test, scope=scope)+ self._emit(+ scope=scope, event=_Branch(paths=(self._collected(nodes=[body], scope=scope), self._collected(nodes=[orelse], scope=scope)))+ )+ case ast.Name(id=name, ctx=ast.Load()):+ self._emit(scope=scope, event=_Read(node=node, name=name))+ case ast.Name(id=name, ctx=ast.Store()):+ self._bind_opaque(name=name, kind=_OpaqueBinding.ASSIGNMENT_TARGET, scope=scope, lineno=node.lineno)+ case ast.Name(id=name, ctx=ast.Del()):+ # `del` makes a name local without giving it a value, by Python's rules, and empties it.+ scope.bound_names.add(name)+ self._emit(scope=scope, event=_Kill(name=name))+ case ast.Call():+ self.call_scopes[node] = scope+ self._visit_all(nodes=ast.iter_child_nodes(node), scope=scope)+ case _:+ self._visit_all(nodes=ast.iter_child_nodes(node), scope=scope)++ def _visit_short_circuit(self, *, values: list[ast.expr], scope: _Scope) -> None:+ if not values:+ return+ with self._sink(scope=scope) as evaluated:+ self._visit(node=values[0], scope=scope)+ self._visit_short_circuit(values=values[1:], scope=scope)+ self._emit(scope=scope, event=_Branch(paths=(evaluated, [])))++ def _handler_events(self, *, handler: ast.ExceptHandler, scope: _Scope) -> list[_Event]:+ with self._sink(scope=scope) as events:+ self._visit_all(nodes=[handler.type], scope=scope)+ if handler.name is not None:+ self._bind_opaque(name=handler.name, kind=_OpaqueBinding.EXCEPT_TARGET, scope=scope, lineno=handler.lineno)+ self._visit_all(nodes=handler.body, scope=scope)+ if handler.name is not None:+ # Python deletes an except target as its handler ends.+ self._emit(scope=scope, event=_Kill(name=handler.name))+ return events++ def _visit_signature_outside(self, *, arguments: ast.arguments, scope: _Scope) -> None:+ """A signature's defaults and annotations, which are evaluated in the scope the definition is written in."""+ every_argument = [*arguments.posonlyargs, *arguments.args, *arguments.kwonlyargs, arguments.vararg, arguments.kwarg]+ annotations = [argument.annotation for argument in every_argument if argument is not None]+ self._visit_all(nodes=[*arguments.defaults, *arguments.kw_defaults, *annotations], scope=scope)++ def _bind_parameters(self, *, arguments: ast.arguments, scope: _Scope) -> None:+ for argument in (*arguments.posonlyargs, *arguments.args, *arguments.kwonlyargs, arguments.vararg, arguments.kwarg):+ if argument is not None:+ self._bind_opaque(name=argument.arg, kind=_OpaqueBinding.PARAMETER, scope=scope, lineno=argument.lineno)++ def _visit_comprehension(self, *, generators: list[ast.comprehension], results: list[ast.expr], scope: _Scope) -> None:+ """A comprehension: its first iterable is read in the enclosing scope, everything else in a scope of its own.++ Its body runs any number of times, as a loop of the flow it is written in, where its `:=` bind.+ """+ self._visit(node=generators[0].iter, scope=scope)+ comprehension_scope = self._nested_scope(kind=_ScopeKind.COMPREHENSION, parent=scope)+ with self._sink(scope=scope) as body:+ for index_generator, generator in enumerate(generators):+ if index_generator > 0:+ self._visit(node=generator.iter, scope=comprehension_scope)+ self._bind_target(target=generator.target, kind=_OpaqueBinding.COMPREHENSION_TARGET, scope=comprehension_scope)+ self._visit_all(nodes=generator.ifs, scope=comprehension_scope)+ self._visit_all(nodes=results, scope=comprehension_scope)+ self._emit(scope=scope, event=_Loop(test=[], body=body, orelse=[]))++ def _bind_target(self, *, target: ast.expr, kind: _OpaqueBinding, scope: _Scope) -> None:+ """The names an assignment target binds: a name, reached through tuples, lists and starred parts.++ An attribute or a subscript rebinds no name, ``cache[msg] = 1`` leaving ``msg`` as it was: its parts are read.+ """+ match target:+ case ast.Name(id=name):+ self._bind_opaque(name=name, kind=kind, scope=scope, lineno=target.lineno)+ case ast.Tuple(elts=elements) | ast.List(elts=elements):+ for element in elements:+ self._bind_target(target=element, kind=kind, scope=scope)+ case ast.Starred(value=value):+ self._bind_target(target=value, kind=kind, scope=scope)+ case _:+ self._visit(node=target, scope=scope)++ def _bind_opaque(self, *, name: str, kind: _OpaqueBinding, scope: _Scope, lineno: int, import_path: str | None = None) -> None:+ self._bind(name=name, owner=scope, binding=self._new_binding(value=None, scope=scope, lineno=lineno, opaque=kind, import_path=import_path))++ def _bind_imports(self, *, statement: ast.Import | ast.ImportFrom, scope: _Scope) -> None:+ """The names an import binds, each with the dotted path it binds them to.++ ``import a.b`` binds ``a`` to ``a``, ``import a.b as x`` binds ``x`` to ``a.b``, ``from a import b as c`` binds+ ``c`` to ``a.b``, a relative import resolves against the module's package, and a star import from a module that+ exports the facade binds its name.+ """+ match statement:+ case ast.Import(names=aliases):+ for alias in aliases:+ bound_name = alias.asname or alias.name.partition(".")[0]+ module_path = alias.name if alias.asname else bound_name+ self._bind_opaque(name=bound_name, kind=_OpaqueBinding.IMPORT, scope=scope, lineno=statement.lineno, import_path=module_path)+ case ast.ImportFrom(module=module, level=level, names=aliases):+ base = _absolute_module(module=module, level=level, package=self._package)+ for alias in aliases:+ if alias.name == "*":+ if base in FACADE_STAR_MODULES:+ star_path = f"{base}.{FACADE_NAME}"+ self._bind_opaque(+ name=FACADE_NAME, kind=_OpaqueBinding.IMPORT, scope=scope, lineno=statement.lineno, import_path=star_path+ )+ continue+ imported_path = f"{base}.{alias.name}" if base else None+ self._bind_opaque(+ name=alias.asname or alias.name, kind=_OpaqueBinding.IMPORT, scope=scope, lineno=statement.lineno, import_path=imported_path+ )++ def _apply_declarations(self) -> None:+ """Move the bindings of a ``global`` or ``nonlocal`` name to the scope that owns it."""+ for scope in self._scopes:+ for name in sorted(scope.global_names):+ for binding in scope.bindings.pop(name, []):+ self.module_scope.bind(name=name, binding=binding)+ self.module_scope.moved_bindings.setdefault(name, []).append(binding)+ for name in sorted(scope.nonlocal_names):+ owner = self._nonlocal_owner(scope=scope, name=name)+ moved = scope.bindings.pop(name, [])+ if owner is not None:+ for binding in moved:+ owner.bind(name=name, binding=binding)+ owner.moved_bindings.setdefault(name, []).append(binding)++ @staticmethod+ def _nonlocal_owner(*, scope: _Scope, name: str) -> _Scope | None:+ enclosing = scope.parent+ while enclosing is not None and not enclosing.kind.is_module:+ if not enclosing.kind.is_class and enclosing.owns(name=name):+ return enclosing+ enclosing = enclosing.parent+ return None++ # ---- name resolution --------------------------------------------------------------++ def locate(self, *, scope: _Scope, name: str) -> _Location:+ """Where a name read in a scope resolves, by Python's rules.++ Its own scope, a comprehension reading as part of the scope it is written in; then the enclosing functions,+ class bodies never among them, a name one of them binds being captured and not followed; then the module.+ """+ current = scope+ has_crossed_comprehension = False+ while current.kind.is_comprehension and not current.owns(name=name) and current.parent is not None:+ current = current.parent+ has_crossed_comprehension = True+ if name in current.global_names:+ return self._module_location(name=name)+ # A comprehension written in a class body does not see the class's names, as no nested scope does.+ if current.owns(name=name) and not (has_crossed_comprehension and current.kind.is_class):+ return current+ if name in current.nonlocal_names:+ return _CAPTURED_PLACEHOLDER+ enclosing = current.parent+ while enclosing is not None and not enclosing.kind.is_module:+ if not enclosing.kind.is_class:+ if name in enclosing.global_names:+ return self._module_location(name=name)+ if enclosing.owns(name=name):+ return _CAPTURED_PLACEHOLDER+ enclosing = enclosing.parent+ return self._module_location(name=name)++ def _module_location(self, *, name: str) -> _Location:+ return self.module_scope if self.module_scope.owns(name=name) else _UNBOUND_PLACEHOLDER++ def reaching(self, *, node: ast.Name, scope: _Scope) -> _Reach:+ """The bindings that can reach a name read in a scope, or the placeholder of a name the guard does not follow.++ A read of its own flow's name gets what the flow's run recorded there. A read of a module name from a scope+ written in the module gets what the module held where that scope starts to run, and, from a function, every+ module binding made once it is defined. A comprehension's target is any of its bindings. A binding another+ scope makes through ``global`` or ``nonlocal`` runs whenever that scope is called, so it reaches every read.+ """+ name = node.id+ location = self.locate(scope=scope, name=name)+ if isinstance(location, str):+ return location+ flow = scope.statement_scope+ found: set[_Binding] = set()+ if location.kind.is_comprehension:+ found.update(location.bindings.get(name, []))+ else:+ # A function that declares a module name `global` tracks its own bindings of it, in its flow.+ is_read_in_own_flow = location is flow or name in flow.global_names+ recorded: set[_Binding | None] = self._recorded.get(node, set()) if is_read_in_own_flow else {None}+ found.update(binding for binding in recorded if binding is not None)+ if None in recorded and location is not flow and flow.entry is not None:+ found.update(flow.entry.at_entry.get(name, set()))+ if flow.runs_later:+ found.update(flow.entry.after.get(name, set()))+ found.update(binding for binding in location.moved_bindings.get(name, []) if binding.scope.statement_scope is not flow)+ return sorted(found, key=lambda binding: (binding.lineno, binding.serial))++ def receiver_bindings(self, *, node: ast.Name, scope: _Scope) -> list[_Binding]:+ """The bindings a call's receiver may hold where the call is made, a captured name's every binding included."""+ reach = self.reaching(node=node, scope=scope)+ if not isinstance(reach, str):+ return reach+ if reach != _CAPTURED_PLACEHOLDER:+ return []+ enclosing = scope.statement_scope.parent+ while enclosing is not None and not enclosing.kind.is_module:+ if not enclosing.kind.is_class and enclosing.owns(name=node.id):+ return list(enclosing.bindings.get(node.id, []))+ enclosing = enclosing.parent+ return []+++# --------------------------------------------------------------------------------------+# Reading a message+# --------------------------------------------------------------------------------------++#: The form a message expression takes: ``None`` when it is fixed, otherwise the rule it breaks and what it is,+#: as a noun phrase the report completes ("the message is an f-string").+_Form: TypeAlias = RuleBreach | None++#: The text a message can reach the console as, as runs of literal text: between two consecutive runs sits a value+#: the guard cannot read, so a markup tag is looked for within a run and never across one.+_Shape: TypeAlias = tuple[str, ...]++#: The shape of a value the guard cannot read.+_UNKNOWN_SHAPE: _Shape = ("", "")++#: The most shapes a `+` folds its operands into; past it, the operands are scanned apart, as they would be unread.+_MAX_FOLDED_SHAPES = 256++#: The bindings a reading is inside of, so a binding a loop feeds back into itself is read once.+_Seen: TypeAlias = frozenset[_Binding]+++def _folded(*, left: set[_Shape], right: set[_Shape]) -> set[_Shape]:+ """The shapes of a concatenation: each left text's last run joined to each right text's first run."""+ if len(left) * len(right) > _MAX_FOLDED_SHAPES:+ return left | right+ return {(*left_shape[:-1], left_shape[-1] + right_shape[0], *right_shape[1:]) for left_shape, right_shape in itertools.product(left, right)}+++def _short_source(*, expr: ast.expr, limit: int = 60) -> str:+ text = render_source(expr=expr)+ return text if len(text) <= limit else text[: limit - 1] + "…"+++def _is_none(*, expr: ast.expr) -> bool:+ return isinstance(expr, ast.Constant) and expr.value is None+++class _MessageReader:+ """Reads a message expression in the scope it is written in, through the bindings that reach the names it holds.++ Every binding it reads is recorded in ``trace``, as a signature writes it, so the identity of a call that breaks+ a rule changes whenever what it logs does.+ """++ def __init__(self, *, index: _ScopeIndex, trace: set[str]) -> None:+ self._index = index+ self.trace = trace++ def _reach(self, *, node: ast.Name, scope: _Scope) -> _Reach:+ """The bindings that reach a name, the placeholder of one not followed recorded in the trace."""+ reach = self._index.reaching(node=node, scope=scope)+ if isinstance(reach, str):+ self.trace.add(f"{node.id} = {reach}")+ elif not reach:+ self.trace.add(f"{node.id} = {_UNBOUND_PLACEHOLDER}")+ else:+ self.trace.update(binding.render(name=node.id) for binding in reach)+ return reach++ # ---- the form, for the interpolation rule -----------------------------------------++ def form(self, *, expr: ast.expr, scope: _Scope, seen: _Seen, allows_none: bool) -> _Form:+ """Whether a message expression is fixed, and if not, the rule it breaks.++ The outermost form names the rule: ``f"{x}" + "!"`` is a concatenation. A title may be statically ``None``.+ """+ match expr:+ case ast.Constant(value=str()):+ return None+ case ast.Constant(value=None) if allows_none:+ return None+ case ast.JoinedStr(values=values):+ if any(isinstance(value, ast.FormattedValue) for value in values):+ return RuleBreach(rule=LogCallRule.F_STRING, detail="an f-string")+ return None+ case ast.BinOp(op=ast.Add(), left=left, right=right):+ left_form = self.form(expr=left, scope=scope, seen=seen, allows_none=False)+ right_form = self.form(expr=right, scope=scope, seen=seen, allows_none=False)+ if left_form is None and right_form is None:+ return None+ return RuleBreach(rule=LogCallRule.CONCATENATION, detail="a `+` concatenation")+ case ast.BinOp(op=ast.Mod()):+ return RuleBreach(rule=LogCallRule.PERCENT_FORMAT, detail="a `%` format")+ case ast.Call(func=ast.Attribute(attr="format")):+ return RuleBreach(rule=LogCallRule.FORMAT_CALL, detail="a `.format()` call")+ case ast.IfExp(body=body, orelse=orelse):+ # Both branches are read, so the trace holds what either binds.+ body_form = self.form(expr=body, scope=scope, seen=seen, allows_none=allows_none)+ orelse_form = self.form(expr=orelse, scope=scope, seen=seen, allows_none=allows_none)+ return body_form or orelse_form+ case ast.Name():+ return self._name_form(node=expr, scope=scope, seen=seen, allows_none=allows_none)+ case _:+ return RuleBreach(rule=LogCallRule.NON_LITERAL, detail=f"`{_short_source(expr=expr)}`, not a literal")++ def _name_form(self, *, node: ast.Name, scope: _Scope, seen: _Seen, allows_none: bool) -> _Form:+ name = node.id+ reach = self._reach(node=node, scope=scope)+ if isinstance(reach, str):+ if reach == _CAPTURED_PLACEHOLDER:+ return RuleBreach(rule=LogCallRule.NON_LITERAL, detail=f"`{name}`, captured from an enclosing function")+ return RuleBreach(rule=LogCallRule.NON_LITERAL, detail=f"`{name}`, bound to no literal in its scope or at module level")+ if not reach:+ return RuleBreach(rule=LogCallRule.NON_LITERAL, detail=f"`{name}`, bound to no literal in its scope or at module level")+ first_form: _Form = None+ for binding in reach:+ if binding in seen:+ # A binding a loop feeds back into itself, `msg = msg + "!"`: the bindings it started from decide.+ continue+ binding_form = self._binding_form(name=name, binding=binding, seen=seen | {binding}, allows_none=allows_none)+ first_form = first_form or binding_form+ return first_form++ def _binding_form(self, *, name: str, binding: _Binding, seen: _Seen, allows_none: bool) -> _Form:+ if binding.opaque is not None or binding.value is None:+ kind = binding.opaque or _OpaqueBinding.ASSIGNMENT_TARGET+ return RuleBreach(rule=LogCallRule.NON_LITERAL, detail=f"`{name}`, bound at line {binding.lineno} as a {kind}, not to a literal")+ match binding.operator:+ case None:+ value_form = self.form(expr=binding.value, scope=binding.scope, seen=seen, allows_none=allows_none)+ if value_form is None:+ return None+ return RuleBreach(rule=value_form.rule, detail=f"`{name}`, bound at line {binding.lineno} to {value_form.detail}")+ case ast.Add():+ # `msg += "!"` keeps a literal literal: the value it extends decides, then what extends it.+ prior_form = None if binding.prior is None else self._name_form(node=binding.prior, scope=binding.scope, seen=seen, allows_none=False)+ if prior_form is not None:+ return prior_form+ if self.form(expr=binding.value, scope=binding.scope, seen=seen, allows_none=False) is None:+ return None+ return RuleBreach(rule=LogCallRule.CONCATENATION, detail=f"`{name}`, extended with `+=` at line {binding.lineno}")+ case ast.Mod():+ return RuleBreach(rule=LogCallRule.PERCENT_FORMAT, detail=f"`{name}`, formatted with `%=` at line {binding.lineno}")+ case _:+ symbol = _operator_symbol(operator=binding.operator)+ return RuleBreach(rule=LogCallRule.NON_LITERAL, detail=f"`{name}`, updated with `{symbol}=` at line {binding.lineno}")++ # ---- the shapes, for the markup rule ----------------------------------------------++ def shapes(self, *, expr: ast.expr, scope: _Scope, seen: _Seen) -> set[_Shape]:+ """The texts a message expression can reach the console as, its statically known concatenations folded."""+ match expr:+ case ast.Constant(value=str() as text):+ return {(text,)}+ case ast.Constant(value=None):+ return {("",)}+ case ast.JoinedStr(values=values):+ runs = [""]+ for value in values:+ if isinstance(value, ast.Constant) and isinstance(value.value, str):+ runs[-1] += value.value+ else:+ runs.append("")+ return {tuple(runs)}+ case ast.BinOp(op=ast.Add(), left=left, right=right):+ return _folded(left=self.shapes(expr=left, scope=scope, seen=seen), right=self.shapes(expr=right, scope=scope, seen=seen))+ case ast.BinOp(op=ast.Mod(), left=left):+ return self.shapes(expr=left, scope=scope, seen=seen)+ case ast.Call(func=ast.Attribute(attr="format", value=receiver)):+ return self.shapes(expr=receiver, scope=scope, seen=seen)+ case ast.IfExp(body=body, orelse=orelse):+ return self.shapes(expr=body, scope=scope, seen=seen) | self.shapes(expr=orelse, scope=scope, seen=seen)+ case ast.Name():+ return self._name_shapes(node=expr, scope=scope, seen=seen)+ case _:+ return {_UNKNOWN_SHAPE}++ def _name_shapes(self, *, node: ast.Name, scope: _Scope, seen: _Seen) -> set[_Shape]:+ """The texts a name can hold where it is read: those of each binding that can reach it."""+ reach = self._reach(node=node, scope=scope)+ if isinstance(reach, str) or not reach:+ return {_UNKNOWN_SHAPE}+ result: set[_Shape] = set()+ for binding in reach:+ if binding in seen:+ result.add(_UNKNOWN_SHAPE)+ continue+ result |= self._binding_shapes(binding=binding, seen=seen | {binding})+ return result++ def _binding_shapes(self, *, binding: _Binding, seen: _Seen) -> set[_Shape]:+ """The texts a binding gives its name: an augmented one updates the text that reaches it."""+ if binding.opaque is not None or binding.value is None:+ return {_UNKNOWN_SHAPE}+ match binding.operator:+ case None:+ return self.shapes(expr=binding.value, scope=binding.scope, seen=seen)+ case ast.Add():+ return _folded(+ left=self._prior_shapes(binding=binding, seen=seen), right=self.shapes(expr=binding.value, scope=binding.scope, seen=seen)+ )+ case ast.Mod():+ return self._prior_shapes(binding=binding, seen=seen)+ case _:+ return {_UNKNOWN_SHAPE}++ def _prior_shapes(self, *, binding: _Binding, seen: _Seen) -> set[_Shape]:+ """The texts an augmented assignment updates: those reaching its target where it stands."""+ if binding.prior is None:+ return {_UNKNOWN_SHAPE}+ return self._name_shapes(node=binding.prior, scope=binding.scope, seen=seen)+++def markup_tags_of(*, shapes: Iterable[_Shape]) -> list[str]:+ """The distinct markup tags the runs of these shapes hold, in a stable order."""+ tags: list[str] = []+ for shape in sorted(shapes):+ for run in shape:+ for tag in find_markup_tags(text=run):+ if tag not in tags:+ tags.append(tag)+ return tags+++# --------------------------------------------------------------------------------------+# The facade+# --------------------------------------------------------------------------------------+++def module_package_of(*, relative_path: str) -> str:+ """The package a module's relative imports resolve against, read off its path: ``pipelex.core`` for ``pipelex/core/x.py``."""+ path = Path(relative_path)+ for import_root in IMPORT_ROOTS:+ if path.is_relative_to(import_root):+ path = path.relative_to(import_root)+ return ".".join(path.parent.parts)+++def _absolute_module(*, module: str | None, level: int, package: str) -> str | None:+ if level == 0:+ return module+ package_parts = package.split(".") if package else []+ if level - 1 > len(package_parts):+ return None+ base_parts = package_parts[: len(package_parts) - (level - 1)]+ if module:+ base_parts.append(module)+ return ".".join(base_parts) or None+++def _receiver_root(*, expr: ast.expr) -> tuple[ast.Name, list[str]] | None:+ """``a.b.c`` as the name ``a`` and the attributes ``["b", "c"]``, or ``None`` when the expression is not a dotted name."""+ attributes: list[str] = []+ while isinstance(expr, ast.Attribute):+ attributes.append(expr.attr)+ expr = expr.value+ if not isinstance(expr, ast.Name):+ return None+ return expr, list(reversed(attributes))+++def _expanded_entries(*, expr: ast.expr) -> list[tuple[str, ast.expr]] | None:+ """The keywords a ``**`` expansion passes, when it expands a dict literal whose keys are all strings, else ``None``."""+ if not isinstance(expr, ast.Dict):+ return None+ entries: list[tuple[str, ast.expr]] = []+ for key, value in zip(expr.keys, expr.values, strict=True):+ if not isinstance(key, ast.Constant) or not isinstance(key.value, str):+ return None+ entries.append((key.value, value))+ return entries+++def message_parts_of(*, call: ast.Call) -> tuple[list[tuple[str | None, ast.expr]], list[ast.expr]]:+ """The parts of a call's message, the message labelled ``None`` and a title by its keyword, and the ``**``+ expansions whose keywords cannot be read.++ A ``**`` of a dict literal with string keys passes its ``content``, ``title`` and ``inline`` entries as keywords;+ any other expansion may carry any of them, so the message cannot be read through it.+ """+ keywords: list[tuple[str, ast.expr]] = []+ unread: list[ast.expr] = []+ for keyword in call.keywords:+ if keyword.arg is not None:+ keywords.append((keyword.arg, keyword.value))+ continue+ entries = _expanded_entries(expr=keyword.value)+ if entries is None:+ unread.append(keyword.value)+ else:+ keywords.extend(entries)+ parts: list[tuple[str | None, ast.expr]] = []+ content = call.args[0] if call.args else next((value for name, value in keywords if name == CONTENT_KEYWORD), None)+ if content is not None:+ parts.append((None, content))+ # A title or inline title that is statically `None` is no text at all.+ parts.extend((name, value) for name, value in keywords if name in TITLE_KEYWORDS and not _is_none(expr=value))+ return parts, unread+++# --------------------------------------------------------------------------------------+# The walk+# --------------------------------------------------------------------------------------+++class _LogCallCollector(ast.NodeVisitor):+ """Walks one module, tracking the qualified name it is in, and records every facade call that breaks a rule."""++ def __init__(self, *, relative_path: str, module: ast.Module) -> None:+ self.relative_path = relative_path+ self.offending_calls: list[OffendingCall] = []+ self._index = _ScopeIndex(module=module, package=module_package_of(relative_path=relative_path))+ self._qualified_parts: list[str] = []++ # ---- qualified names --------------------------------------------------------------++ def _visit_named_scope(self, *, node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> None:+ # Decorators, defaults and bases run in the enclosing scope, under its name.+ for decorator in node.decorator_list:+ self.visit(decorator)+ if isinstance(node, ast.ClassDef):+ for base in (*node.bases, *node.keywords):+ self.visit(base)+ else:+ for default in (*node.args.defaults, *(default for default in node.args.kw_defaults if default is not None)):+ self.visit(default)+ self._qualified_parts.append(node.name)+ for statement in node.body:+ self.visit(statement)+ self._qualified_parts.pop()++ @override+ def visit_FunctionDef(self, node: ast.FunctionDef) -> None: # pylint: disable=invalid-name # ast.NodeVisitor dispatch name+ self._visit_named_scope(node=node)++ @override+ def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None: # pylint: disable=invalid-name # ast.NodeVisitor dispatch name+ self._visit_named_scope(node=node)++ @override+ def visit_ClassDef(self, node: ast.ClassDef) -> None: # pylint: disable=invalid-name # ast.NodeVisitor dispatch name+ self._visit_named_scope(node=node)++ @property+ def _qualified_name(self) -> str:+ return ".".join(self._qualified_parts) or MODULE_SCOPE_NAME++ # ---- the calls --------------------------------------------------------------------++ @override+ def visit_Call(self, node: ast.Call) -> None: # pylint: disable=invalid-name # ast.NodeVisitor dispatch name+ method = self._facade_method(node=node)+ if method is not None:+ self._check_call(node=node, method=method)+ self.generic_visit(node)++ def _facade_method(self, *, node: ast.Call) -> str | None:+ """The facade method a call invokes, its receiver read where the call is made.++ The receiver's name is the facade when a binding that can reach the call imports the facade, under whatever+ name or module path: a parameter or a local of that name, or an import made in another function, is not.+ """+ if not isinstance(node.func, ast.Attribute) or node.func.attr not in MARKUP_BOUND_METHODS:+ return None+ receiver = _receiver_root(expr=node.func.value)+ if receiver is None:+ return None+ root, attributes = receiver+ for binding in self._index.receiver_bindings(node=root, scope=self._index.call_scopes[node]):+ if binding.import_path is not None and ".".join([binding.import_path, *attributes]) in FACADE_PATHS:+ return node.func.attr+ return None++ def _check_call(self, *, node: ast.Call, method: str) -> None:+ scope = self._index.call_scopes[node]+ parts, unread_expansions = message_parts_of(call=node)++ trace: set[str] = set()+ reader = _MessageReader(index=self._index, trace=trace)+ # A `**` expansion the guard cannot read may carry the message or a title, so neither rule can be checked.+ breaches = [+ RuleBreach(rule=LogCallRule.NON_LITERAL, detail=f"`**{_short_source(expr=expansion)}` is an expansion whose keywords cannot be read")+ for expansion in unread_expansions+ ]+ if method in INTERPOLATION_BOUND_METHODS:+ for label, expr in parts:+ form = reader.form(expr=expr, scope=scope, seen=frozenset(), allows_none=label is not None)+ if form is not None:+ breaches.append(RuleBreach(rule=form.rule, detail=f"{_part_name(label=label)} is {form.detail}"))+ for label, expr in parts:+ for tag in markup_tags_of(shapes=reader.shapes(expr=expr, scope=scope, seen=frozenset())):+ breaches.append(RuleBreach(rule=LogCallRule.MARKUP, detail=f"{_part_name(label=label)} holds the markup tag `{tag}`"))++ if not breaches:+ return+ self.offending_calls.append(+ OffendingCall(+ relative_path=self.relative_path,+ qualified_name=self._qualified_name,+ lineno=node.lineno,+ signature=call_signature(+ method=method,+ parts=parts,+ rules={breach.rule for breach in breaches},+ bindings=trace,+ expansions=unread_expansions,+ ),+ breaches=tuple(breaches),+ )+ )+++def _part_name(*, label: str | None) -> str:+ """How the report names a part of a call's message: the message itself, or the keyword a title rides."""+ return "the message" if label is None else f"`{label}=`"+++def call_signature(+ *,+ method: str,+ parts: Sequence[tuple[str | None, ast.expr]],+ rules: Iterable[LogCallRule],+ bindings: Iterable[str] = (),+ expansions: Sequence[ast.expr] = (),+) -> str:+ """A call's identity in the baseline, never a line.++ Its method, its message's source and any title's, the ``**`` expansions it cannot read, the rules it breaks in+ their declared order, and every binding the guard read to judge it, sorted:+ ``warning: msg [f-string] where msg = f"Loaded {alias}"``.+ """+ rendered = [render_source(expr=expr) if label is None else f"{label}={render_source(expr=expr)}" for label, expr in parts]+ rendered.extend(f"**{render_source(expr=expansion)}" for expansion in expansions)+ broken = set(rules)+ rule_names = [str(rule) for rule in LogCallRule if rule in broken]+ signature = f"{method}: {', '.join(rendered) or '<no message>'} [{', '.join(rule_names)}]"+ sorted_bindings = sorted(set(bindings))+ if sorted_bindings:+ signature += " where " + "; ".join(sorted_bindings)+ return signature+++def find_offending_calls_in_source(*, source: str, relative_path: str) -> list[OffendingCall]:+ """The facade calls in one module's source that break a rule, in source order."""+ module = ast.parse(source)+ collector = _LogCallCollector(relative_path=relative_path, module=module)+ collector.visit(module)+ return sorted(collector.offending_calls, key=lambda call: (call.lineno, call.signature))+++def _is_excluded(*, relative_path: Path) -> bool:+ return any(relative_path.is_relative_to(excluded) for excluded in EXCLUDED_ROOTS)+++def iter_scanned_files(*, repo_root: Path) -> Iterator[Path]:+ """Every ``.py`` file the guard reads, as a path relative to the repo root, in a stable order.++ Raises:+ LogCallGuardError: If a scan root is missing or holds no module, which means the guard runs from somewhere+ other than the repo root and would otherwise pass having read nothing.+ """+ for scan_root in SCAN_ROOTS:+ absolute_root = repo_root / scan_root+ if not absolute_root.is_dir():+ msg = f"The log-call guard's scan root '{scan_root.as_posix()}/' does not exist under '{repo_root}'. Run it from the repo root."+ raise LogCallGuardError(msg)+ nb_files = 0+ for path in sorted(absolute_root.rglob("*.py")):+ if "__pycache__" in path.parts:+ continue+ relative_path = path.relative_to(repo_root)+ if _is_excluded(relative_path=relative_path):+ continue+ nb_files += 1+ yield relative_path+ if nb_files == 0:+ msg = f"The log-call guard's scan root '{scan_root.as_posix()}/' holds no Python module under '{repo_root}'."+ raise LogCallGuardError(msg)+++def collect_offending_calls(*, repo_root: Path) -> list[OffendingCall]:+ """Every facade call in the scanned trees that breaks a rule, sorted by file, then line."""+ offending: list[OffendingCall] = []+ for relative_path in iter_scanned_files(repo_root=repo_root):+ source = (repo_root / relative_path).read_text(encoding="utf-8")+ offending.extend(find_offending_calls_in_source(source=source, relative_path=relative_path.as_posix()))+ return sorted(offending, key=lambda call: (call.relative_path, call.lineno, call.signature))+++# --------------------------------------------------------------------------------------+# The baseline+# --------------------------------------------------------------------------------------++#: The baseline's content: each key's signatures, a signature listed once per call that carries it.+Baseline: TypeAlias = dict[str, list[str]]++_BASELINE_ENTRY_KEYS = frozenset({"calls"})++_BASELINE_HEADER = (+ "The log calls that broke the log-call conventions when the guard arrived (pipelex-dev check-log-calls).",+ "Keyed by <relative_path>::<qualified_name>, each call listed by its method, its message's source,",+ "the rules it breaks and the bindings its message was read through.",+ "It only shrinks: convert a call, then remove its signature (pipelex-dev check-log-calls --prune).",+ "Never add an entry: the check refuses a baseline that lists more than its base. See docs/contribute/log-calls.md.",+)+++def parse_baseline(*, text: str, origin: str) -> Baseline:+ """Parse and validate a baseline's text, ``origin`` naming where it was read for an error.++ Raises:+ LogCallGuardError: When the text is not a well-formed baseline at ``BASELINE_VERSION``.+ """+ try:+ raw = tomllib.loads(text)+ except tomllib.TOMLDecodeError as exc:+ msg = f"The log-call baseline {origin} is not valid TOML: {exc}"+ raise LogCallGuardError(msg) from exc+ version = raw.pop("version", None)+ if version != BASELINE_VERSION:+ msg = f"The log-call baseline {origin} must declare `version = {BASELINE_VERSION}` (found: {version!r})"+ raise LogCallGuardError(msg)+ baseline: Baseline = {}+ for key, raw_entry in raw.items():+ relative_path, separator, qualified_name = key.partition("::")+ if not separator or not qualified_name or not relative_path.endswith(".py"):+ msg = f"The log-call baseline key '{key}' is not of the form '<relative_path>::<qualified_name>'"+ raise LogCallGuardError(msg)+ if not isinstance(raw_entry, dict):+ msg = f"The log-call baseline entry '{key}' must be a table"+ raise LogCallGuardError(msg)+ entry = cast("dict[str, Any]", raw_entry)+ unknown_keys = set(entry) - _BASELINE_ENTRY_KEYS+ if unknown_keys:+ msg = f"The log-call baseline entry '{key}' has unknown key(s): {sorted(unknown_keys)}"+ raise LogCallGuardError(msg)+ calls = entry.get("calls")+ if not isinstance(calls, list) or not calls:+ msg = f"The log-call baseline entry '{key}' must list its calls as a non-empty `calls` array"+ raise LogCallGuardError(msg)+ signatures: list[str] = []+ for call in cast("list[Any]", calls):+ if not isinstance(call, str) or not call.strip():+ msg = f"The log-call baseline entry '{key}' lists a call that is not a non-empty string: {call!r}"+ raise LogCallGuardError(msg)+ signatures.append(call)+ baseline[key] = signatures+ return baseline+++def load_baseline(*, repo_root: Path) -> Baseline:+ """Load and validate the committed baseline.++ Raises:+ LogCallGuardError: When the file is missing or malformed. A missing baseline is an error, never an empty+ one, which would report every listed call as new.+ """+ path = repo_root / BASELINE_FILE+ if not path.is_file():+ msg = f"The log-call baseline was not found at '{path}'. It is committed at the repo root; run the check from there."+ raise LogCallGuardError(msg)+ return parse_baseline(text=path.read_text(encoding="utf-8"), origin=f"'{path}'")+++def _signatures_by_key(*, offending: Sequence[OffendingCall]) -> dict[str, list[OffendingCall]]:+ by_key: dict[str, list[OffendingCall]] = {}+ for call in offending:+ by_key.setdefault(call.key, []).append(call)+ return by_key+++def compare_with_baseline(*, offending: Sequence[OffendingCall], baseline: Mapping[str, Sequence[str]]) -> BaselineComparison:+ """Match the offending calls against the baseline, exactly, both ways.++ A call is covered when its key lists its signature, once per call carrying it; a call beyond what is listed is+ unlisted, and a listed signature beyond the calls carrying it is stale.+ """+ unlisted: list[OffendingCall] = []+ stale: list[StaleEntry] = []+ by_key = _signatures_by_key(offending=offending)+ for key in sorted(set(by_key) | set(baseline)):+ listed = Counter(baseline.get(key, ()))+ calls_by_signature: dict[str, list[OffendingCall]] = {}+ for call in by_key.get(key, []):+ calls_by_signature.setdefault(call.signature, []).append(call)+ for signature, calls in calls_by_signature.items():+ unlisted.extend(calls[listed[signature] :])+ for signature, count in sorted(listed.items()):+ found = len(calls_by_signature.get(signature, []))+ # A signature listed more times than calls carry it is stale once per extra listing, the entry being immutable.+ stale.extend([StaleEntry(key=key, signature=signature)] * (count - found))+ return BaselineComparison(+ unlisted=sorted(unlisted, key=lambda call: (call.relative_path, call.lineno, call.signature)),+ stale=stale,+ )+++def compare_with_trusted_baseline(*, baseline: Mapping[str, Sequence[str]], trusted: Mapping[str, Sequence[str]]) -> list[BaselineGrowth]:+ """Every signature the working baseline lists more times than the trusted one: the entries added since, sorted.++ The baseline only shrinks, so a pass is an empty list: every signature listed as often as at the trusted+ revision, or less.+ """+ growth: list[BaselineGrowth] = []+ for key in sorted(baseline):+ trusted_counts = Counter(trusted.get(key, ()))+ for signature, working_count in sorted(Counter(baseline[key]).items()):+ if working_count > trusted_counts[signature]:+ growth.append(BaselineGrowth(key=key, signature=signature, trusted_count=trusted_counts[signature], working_count=working_count))+ return growth+++def build_baseline(*, offending: Sequence[OffendingCall]) -> Baseline:+ """The baseline that lists exactly the given calls, which is how the committed one was generated."""+ return {key: sorted(call.signature for call in calls) for key, calls in sorted(_signatures_by_key(offending=offending).items())}+++def prune_baseline(*, baseline: Mapping[str, Sequence[str]], offending: Sequence[OffendingCall]) -> Baseline:+ """The baseline without its stale signatures. It never adds one: an unlisted call stays unlisted."""+ calls_by_key = _signatures_by_key(offending=offending)+ pruned: Baseline = {}+ for key in sorted(baseline):+ found = Counter(call.signature for call in calls_by_key.get(key, []))+ kept: list[str] = []+ for signature, count in sorted(Counter(baseline[key]).items()):+ kept.extend([signature] * min(count, found[signature]))+ if kept:+ pruned[key] = kept+ return pruned+++def baseline_document(*, baseline: Mapping[str, Sequence[str]]) -> tomlkit.TOMLDocument:+ """The baseline as a TOML document: the header, the version, then every key in sorted order with its sorted calls.++ Each ``calls`` array is laid out one signature per line, indented the way ``plxt fmt`` indents an array, so a+ prune followed by ``make format`` moves nothing else.+ """+ document = tomlkit.document()+ for line in _BASELINE_HEADER:+ document.add(tomlkit.comment(line))+ document.add(tomlkit.nl())+ document.add("version", tomlkit.integer(BASELINE_VERSION))+ for key in sorted(baseline):+ calls = tomlkit.array()+ for signature in sorted(baseline[key]):+ calls.add_line(signature, indent=" ")+ calls.add_line(indent="")+ table = tomlkit.table()+ table.add("calls", calls)+ document.add(key, table)+ return document+++def render_baseline(*, baseline: Mapping[str, Sequence[str]]) -> str:+ """The baseline file's text, as ``write_baseline`` writes it."""+ return baseline_document(baseline=baseline).as_string()+++def write_baseline(*, baseline: Mapping[str, Sequence[str]], repo_root: Path) -> None:+ """Write the baseline file at the repo root, through the repo's TOML writer."""+ save_toml_to_path(baseline_document(baseline=baseline), path=repo_root / BASELINE_FILE)+++def package_area_of(*, key: str) -> str:+ """The package area a baseline key belongs to, for the report: ``pipelex/<area>``, ``pipelex`` for a root module, or the API server."""+ parts = key.partition("::")[0].split("/")+ if parts[0] == "api":+ return "api/pipelex_api"+ if len(parts) > 2:+ return f"{parts[0]}/{parts[1]}"+ return parts[0]+++# --------------------------------------------------------------------------------------+# The trusted baseline, read through git+# --------------------------------------------------------------------------------------+++class _GitResult(NamedTuple):+ returncode: int+ stdout: str+ stderr: str+++def _run_git(*, args: list[str], repo_root: Path) -> _GitResult:+ try:+ result = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true]+ ["git", *args], # ruff: ignore[start-process-with-partial-path]+ cwd=repo_root,+ capture_output=True,+ text=True,+ timeout=GIT_TIMEOUT_SECONDS,+ check=False,+ )+ except FileNotFoundError as exc:+ msg = "git was not found on PATH: the comparison with a trusted baseline reads it through git"+ raise LogCallGuardError(msg) from exc+ except subprocess.TimeoutExpired as exc:+ msg = f"git {' '.join(args)} timed out after {GIT_TIMEOUT_SECONDS}s"+ raise LogCallGuardError(msg) from exc+ return _GitResult(returncode=result.returncode, stdout=result.stdout, stderr=result.stderr.strip())+++def resolve_merge_base(*, repo_root: Path, ref: str) -> str | None:+ """The merge base of ``HEAD`` and ``ref``, or ``None`` when it does not resolve: an unknown ref, or a shallow history."""+ result = _run_git(args=["merge-base", "HEAD", ref], repo_root=repo_root)+ merge_base = result.stdout.strip()+ if result.returncode != 0 or not merge_base:+ return None+ return merge_base+++def _path_exists_at(*, repo_root: Path, commit: str, path: Path) -> bool:+ return _run_git(args=["cat-file", "-e", f"{commit}:{path.as_posix()}"], repo_root=repo_root).returncode == 0+++def load_trusted_baseline(*, repo_root: Path, ref: str) -> Baseline | None:+ """The baseline committed at a trusted revision, read through ``git show``.++ A revision that runs the guard but holds no baseline file has an empty one. A revision the guard does not exist+ at yet holds nothing to compare with: ``None``, for the caller to say so.++ Raises:+ LogCallGuardError: When the revision does not resolve to a commit, or its baseline is malformed or of another+ version: the comparison cannot be made, and a gate that cannot compare fails.+ """+ resolved = _run_git(args=["rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}"], repo_root=repo_root)+ commit = resolved.stdout.strip()+ if resolved.returncode != 0 or not commit:+ msg = f"The revision '{ref}' the log-call baseline is compared with does not resolve to a commit. Fetch it first."+ raise LogCallGuardError(msg)+ if not _path_exists_at(repo_root=repo_root, commit=commit, path=BASELINE_FILE):+ if _path_exists_at(repo_root=repo_root, commit=commit, path=GUARD_MODULE_FILE):+ return {}+ return None+ shown = _run_git(args=["show", f"{commit}:{BASELINE_FILE.as_posix()}"], repo_root=repo_root)+ if shown.returncode != 0:+ msg = f"git could not read {BASELINE_FILE.as_posix()} at '{ref}': {shown.stderr}"+ raise LogCallGuardError(msg)+ return parse_baseline(text=shown.stdout, origin=f"at '{ref}'")diff --git a/pipelex/kit/agent_rules/codex_commands.md b/pipelex/kit/agent_rules/codex_commands.mdindex c9afa27e9..5345dcc8e 100644--- a/pipelex/kit/agent_rules/codex_commands.md+++ b/pipelex/kit/agent_rules/codex_commands.md@@ -7,7 +7,7 @@```bashmake agent-check# If the current system doesn't have the `make` command,- # lookup the "agent-check" target in the Makefile and run the commands one by one (targets fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist drift-check api-agent-check)+ # lookup the "agent-check" target in the Makefile and run the commands one by one (targets fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check)```This runs multiple code quality tools:diff --git a/pipelex/kit/agent_rules/commands.md b/pipelex/kit/agent_rules/commands.mdindex 832a24a4d..42d34bb22 100644--- a/pipelex/kit/agent_rules/commands.md+++ b/pipelex/kit/agent_rules/commands.md@@ -2,7 +2,7 @@`make` targets activate the virtual environment themselves; anything else (`pytest`, `pipelex`, `pipelex-dev`) runs from `.venv/bin/` (`.venv\Scripts\` on Windows), never bare. The Makefile is the reference for every target and alias; without `make`, read the target there and run its prerequisites one by one.-- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist drift-check api-agent-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check, the Rich import check (`cri`: Rich is the `cli` extra, so no module outside `pipelex/cli/` imports it at module level or reaches it through a CLI module), the Actions allowlist check (`caa`: every workflow action must be one `.github/actions-allowlist.toml` allows), the drift contracts, and the server's own gate. The drift digest reads the git index, so stage your changes before the check.+- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check, the Rich import check (`cri`: Rich is the `cli` extra, so no module outside `pipelex/cli/` imports it at module level or reaches it through a CLI module), the Actions allowlist check (`caa`: every workflow action must be one `.github/actions-allowlist.toml` allows), the log-call check (`clc`: a log message at INFO and above is a literal with its values in `fields=`, and no log message holds Rich markup, against `log_call_baseline.toml`, which only shrinks: the check refuses an entry the baseline at the merge base with `origin/dev` does not list; see `docs/contribute/log-calls.md`), the drift contracts, and the server's own gate. The drift digest reads the git index, so stage your changes before the check.- **The Pipelex API server is the `api/` workspace member** (the `pipelex-api` distribution, package `pipelex_api`; its guide is `api/CLAUDE.md`). It runs the pipelex of the same commit from its own environment, `api/.venv`, which its targets provision themselves. `make agent-check` ends with `api-agent-check` (`make -C api agent-check`: its install, ruff, pyright, mypy, and the drift checks of its OpenAPI artifact and of its vendored inference tree) and `make agent-test` with `api-agent-test`, so a library change that breaks the server, moves its wire or leaves its inference tree behind fails in the same change. A kit change reaches the server's tree through `make up-kit-configs` (`ukc`); a change to the server's wire is committed with `make -C api openapi-export`.- **Keyword-only arguments** (the convention is in the standards and in `docs/contribute/keyword-only-arguments.md`): `make check-keyword-only` (`cko`) is the gate, `make fix-keyword-only` (`fko`) inserts the bare `*` where it can — on ungranted subjects too — and reports the shapes it cannot fix, and `make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"` (`sgr`) grants a positional subject. Grant before `make agent-check`, which runs the fixer.- **Drift contracts.** When `make drift-check` reports an open contract: `make drift-plan`, review and fix the stale targets, `git add` the trigger files, then `make drift-ack CONTRACT=<id> RATIONALE="<verdict>: …"`, the rationale opening with its verdict, `real-catch`, `clean-pass` or `friction`. No bypass flag; "clean-pass: reviewed, no doc change needed" is a legitimate rationale. See `docs/contribute/drift-contracts.md` and the `/drift-review` skill.diff --git a/pipelex/kit/agent_rules/python_standards.md b/pipelex/kit/agent_rules/python_standards.mdindex a034bb57c..8e7edf79f 100644--- a/pipelex/kit/agent_rules/python_standards.md+++ b/pipelex/kit/agent_rules/python_standards.md@@ -75,6 +75,7 @@pretty_print(output_object, title="Your first Pipelex output")```- Both handle formatting json using Rich, pretty_print makes it prettier.+- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.### StrEnum and Self typediff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.pyindex 3d0c2daab..7a2d9b83d 100644--- a/pipelex/libraries/library_manager.py+++ b/pipelex/libraries/library_manager.py@@ -3,7 +3,7 @@ from collections.abc import Generatorfrom contextlib import ExitStack, contextmanagerfrom graphlib import CycleError, TopologicalSorterfrom pathlib import Path-from typing import TYPE_CHECKING, ForwardRef, Literal, get_args, get_origin+from typing import TYPE_CHECKING, Any, ForwardRef, Literal, get_args, get_originfrom kajson.class_registry import ClassRegistryfrom kajson.kajson_manager import KajsonManager@@ -66,6 +66,7 @@ from pipelex.pipe_machinery.pipe_factory import PipeFactoryfrom pipelex.runtime_hub import get_class_registryfrom pipelex.system.registries.class_registry_utils import ClassRegistryUtilsfrom pipelex.system.registries.func_registry_utils import FuncRegistryUtils+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.semver import SemVerError, parse_constraint, parse_version, version_satisfiesfrom pipelex.validation_error_types import PipeValidationErrorType@@ -462,15 +463,12 @@ class LibraryManager(LibraryManagerAbstract):# (worker-local leak state deciding setup success would be the M1 class again).# _pop_and_teardown_library forgets the entry pop-first, so the id is free either way.log.warning(- f"open_fresh_library: stale teardown of pre-existing library '{library_id}' raised; "- f"continuing with a fresh library: {stale_teardown_exc}"+ "The teardown of a stale library raised; continuing with a fresh library",+ fields={"library_id": library_id, **error_fields(exc=stale_teardown_exc)},)else:if removed_existing:- log.warning(- f"open_fresh_library: tore down pre-existing library '{library_id}' — "- f"leftover of an interrupted execution whose cleanup never ran"- )+ log.warning("Tore down a library left over by an interrupted execution whose cleanup never ran", fields={"library_id": library_id})_library_id, the_library = self.open_library(library_id=library_id)return the_library@@ -641,10 +639,13 @@ class LibraryManager(LibraryManagerAbstract):num_registered = ClassRegistryUtils.auto_register_all_subclasses(base_class=StructuredContent,)- log.verbose(f"Auto-registered {num_registered} StructuredContent classes from loaded modules")+ log.verbose("Auto-registered the StructuredContent classes of the loaded modules", fields={"class_count": num_registered})# Load MTHDS files into the specific library- log.verbose(f"Loading MTHDS files from: {[str(p) for p in valid_mthds_paths]}")+ log.verbose(+ "Loading the MTHDS files into the library",+ fields={"library_id": library_id, "mthds_paths": [str(mthds_path) for mthds_path in valid_mthds_paths]},+ )return self._load_mthds_files_into_library(library_id=library_id, valid_mthds_paths=valid_mthds_paths)@override@@ -725,7 +726,7 @@ class LibraryManager(LibraryManagerAbstract):fingerprint = crate.fingerprintloaded_set = self._loaded_fingerprints.setdefault(library_id, set())if fingerprint in loaded_set:- log.verbose(f"Crate with fingerprint {fingerprint[:12]}... already loaded into '{library_id}', skipping")+ log.verbose("Skipped a crate already loaded into the library", fields={"library_id": library_id, "crate_fingerprint": fingerprint})return []library = self.get_library(library_id=library_id)@@ -1133,14 +1134,20 @@ class LibraryManager(LibraryManagerAbstract):constraint = parse_constraint(mthds_version_constraint)current_version = parse_version(MTHDS_STANDARD_VERSION)except SemVerError as exc:- log.warning(f"Could not parse mthds_version constraint '{mthds_version_constraint}' for package '{package_address}': {exc}")+ log.warning(+ "The mthds_version constraint of a package could not be parsed",+ fields={"package_address": package_address, "mthds_version_constraint": mthds_version_constraint, **error_fields(exc=exc)},+ )returnif not version_satisfies(current_version, constraint=constraint):log.warning(- f"Package '{package_address}' requires MTHDS standard version "- f"'{mthds_version_constraint}', but the current version is "- f"'{MTHDS_STANDARD_VERSION}'. Some features may not work correctly."+ "A package requires another MTHDS standard version than this runtime's; some features may not work correctly",+ fields={+ "package_address": package_address,+ "mthds_version_constraint": mthds_version_constraint,+ "mthds_standard_version": MTHDS_STANDARD_VERSION,+ },)def _check_package_visibility(@@ -1168,7 +1175,7 @@ class LibraryManager(LibraryManagerAbstract):try:manifest = find_package_manifest(mthds_paths[0])except ManifestError as exc:- log.warning(f"Could not parse METHODS.toml: {exc.message}")+ log.warning("The package's METHODS.toml could not be parsed", fields=error_fields(exc=exc))# Still enforce reserved domains even when manifest is unparseablechecker = make_visibility_checker(manifest=None, blueprints=blueprints)reserved_errors = checker.validate_reserved_domains()@@ -1307,7 +1314,7 @@ class LibraryManager(LibraryManagerAbstract):dep_blueprints.append(blueprint)if not dep_blueprints:- log.warning(f"No valid blueprints found for dependency '{alias}'")+ log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias, "package_address": package_address})return# Warn if the dependency requires a newer MTHDS standard version@@ -1428,7 +1435,10 @@ class LibraryManager(LibraryManagerAbstract):)child_library.pipe_library.add_new_pipe(pipe=pipe)except ValidationError as exc:- log.warning(f"Could not load dependency '{alias}' pipe '{pipe_code}': {exc}")+ log.warning(+ "A pipe of a dependency could not be loaded",+ fields={"dependency_alias": alias, "pipe_code": pipe_code, **error_fields(exc=exc)},+ )unbuilt_pipe_reasons[pipe_ref] = "; ".join(str(error["msg"]) for error in exc.errors()) or str(exc)finally:# Remove temporary concept entries from main library@@ -1448,7 +1458,10 @@ class LibraryManager(LibraryManagerAbstract):for pipe_ref, reason in unbuilt_pipe_reasons.items():library.pipe_library.add_unbuilt_dependency_pipe(alias=alias, pipe_ref=pipe_ref, reason=reason)- log.verbose(f"Loaded dependency '{alias}': {len(dep_concepts)} concepts, pipes from {len(dep_blueprints)} bundles")+ log.verbose(+ "Loaded a dependency",+ fields={"dependency_alias": alias, "concept_count": len(dep_concepts), "bundle_count": len(dep_blueprints)},+ )def _load_address_based_dependencies(self,@@ -1516,7 +1529,7 @@ class LibraryManager(LibraryManagerAbstract):# The item carries the caller-facing text; the host's log keeps the whole cause chain, git's raw output# included, since a cause on the host (git missing, an unwritable clone directory) becomes an item too.causes = " <- ".join(f"{type(cause).__name__}: {cause}" for cause in iter_cause_chain(exc))- log.warning(f"Method package '{full_address}' could not be resolved: {causes}")+ log.warning("A method package could not be resolved", fields={"package_address": full_address, **error_fields(exc=exc, text=causes)})unresolved_items.append(PipesAndConceptValidationErrorData(error_type=PipeValidationErrorType.UNRESOLVED_PACKAGE_DEPENDENCY,@@ -1712,7 +1725,10 @@ class LibraryManager(LibraryManagerAbstract):})if not (is_generated and refuses_unresolved_structures and missing_names):- log.debug(f"The structure class of {concept.concept_ref} stays incomplete, and will fail at first use: {rebuild_error}")+ incomplete_fields: dict[str, Any] = {"concept_ref": concept.concept_ref}+ if rebuild_error is not None:+ incomplete_fields.update(error_fields(exc=rebuild_error))+ log.debug("The structure class of a concept stays incomplete, and will fail at first use", fields=incomplete_fields)continuesource = concept_sources.get(concept.concept_ref)where = f" (declared in '{source}')" if source else ""diff --git a/pipelex/tools/log/console_fields.py b/pipelex/tools/log/console_fields.pyindex f4be2c8c6..4cea282cb 100644--- a/pipelex/tools/log/console_fields.py+++ b/pipelex/tools/log/console_fields.py@@ -11,8 +11,9 @@ content the message already renders, which is why the dispatch never stamps a laA value renders on one line: a string bare unless it is empty or holds a space, an equals sign, a quote, abackslash or a character a terminal would act on, in which case it is quoted, with a backslash and a quoteescaped by a backslash and that character written as its escape; anything else as compact JSON; and the-whole cut short past ``FIELD_VALUE_MAX_LENGTH``. A key is written the same way, so a field name holding a-line break, a space, an equals sign or an escape sequence can forge neither a line nor a pair. Redaction has+whole cut short past ``FIELD_VALUE_MAX_LENGTH``, or past the generous length ``FIELD_MAX_LENGTHS`` gives a field of+its own, a handled exception's text. A key is written the same way, so a field name holding a line break, a space, an+equals sign or an escape sequence can forge neither a line nor a pair. Redaction hasalready run when the console renders a record, so what is rendered is what the scrub left.Colour follows the name the field was given, from ``FIELD_STYLES``, wherever the field appears, and whatever@@ -31,6 +32,7 @@ from typing import TYPE_CHECKING, Anyfrom pydantic import BaseModel+from pipelex.tools.log.error_fields import ERROR_MESSAGE_FIELDfrom pipelex.tools.log.log_context import PIPE_RUN_ID_FIELD, PIPELINE_RUN_ID_FIELD, REQUEST_ID_FIELDfrom pipelex.tools.log.log_fields import DATA_FIELD, attached_field_names, given_field_namefrom pipelex.tools.log.log_sink import json_fallback, spell_non_finite@@ -64,6 +66,14 @@ CONSOLE_HIDDEN_FIELDS = frozenset({REQUEST_ID_FIELD, PIPELINE_RUN_ID_FIELD, PIPEFIELD_VALUE_MAX_LENGTH = 80TRUNCATION_MARK = "…"+# The longest a handled exception's text gets, the truncation mark included. Its diagnosis, a cause chain or a parse+# error's location, is lost to a fragment cut at the length above, yet a dependency's raw output, a validation+# error's every line or git's stderr, would flood the console uncut.+ERROR_MESSAGE_MAX_LENGTH = 2000++# The fields the console cuts at a length of their own, by the name the caller gave them.+FIELD_MAX_LENGTHS: dict[str, int] = {ERROR_MESSAGE_FIELD: ERROR_MESSAGE_MAX_LENGTH}+FIELD_SEPARATOR = " "KEY_VALUE_SEPARATOR = "="QUOTE = '"'@@ -112,18 +122,26 @@ def field_suffix_segments(*, fields: Mapping[str, Any], presented_fields: frozen# The key is written like a value: a name a caller chose can hold a line break that would forge a# line, a space that would read as two pairs or an escape sequence the terminal would act on.segments.append((f"{format_field_value(value=name)}{KEY_VALUE_SEPARATOR}", FIELD_KEY_STYLE))- segments.append((format_field_value(value=value), field_style(name=name)))+ segments.append((format_field_value(value=value, max_length=field_max_length(name=name)), field_style(name=name)))return segments-def format_field_value(*, value: Any) -> str:- """A field's value as the suffix prints it: one line, a string quoted when it could forge a pair, cut short when long."""- return _truncated(text=_one_line(value=value, is_quoting_strings=True))+def field_max_length(*, name: str) -> int:+ """The longest the console writes a field's value: its entry in ``FIELD_MAX_LENGTHS``, else ``FIELD_VALUE_MAX_LENGTH``.++ Read off the name the caller gave rather than the one it landed on, as the style is.+ """+ return FIELD_MAX_LENGTHS.get(given_field_name(name=name), FIELD_VALUE_MAX_LENGTH)+++def format_field_value(*, value: Any, max_length: int = FIELD_VALUE_MAX_LENGTH) -> str:+ """A field's value as the suffix prints it: one line, a string quoted when it could forge a pair, cut short past ``max_length``."""+ return _truncated(text=_one_line(value=value, is_quoting_strings=True), max_length=max_length)def format_layout_value(*, value: Any) -> str:"""A field's value as a layout substitutes it: one line, a string as itself, cut short when long."""- return _truncated(text=_one_line(value=value, is_quoting_strings=False))+ return _truncated(text=_one_line(value=value, is_quoting_strings=False), max_length=FIELD_VALUE_MAX_LENGTH)def one_line_text(*, text: str) -> str:@@ -173,7 +191,7 @@ def _escaped_character(*, character: str) -> str:return character.encode("unicode_escape").decode("ascii")-def _truncated(*, text: str) -> str:- if len(text) <= FIELD_VALUE_MAX_LENGTH:+def _truncated(*, text: str, max_length: int) -> str:+ if len(text) <= max_length:return text- return f"{text[: FIELD_VALUE_MAX_LENGTH - len(TRUNCATION_MARK)]}{TRUNCATION_MARK}"+ return f"{text[: max_length - len(TRUNCATION_MARK)]}{TRUNCATION_MARK}"diff --git a/pipelex/tools/log/error_fields.py b/pipelex/tools/log/error_fields.pynew file mode 100644index 000000000..f486d2603--- /dev/null+++ b/pipelex/tools/log/error_fields.py@@ -0,0 +1,33 @@+"""The fields a handled exception rides a log line as, when the line carries no traceback.++A line at WARNING or below about an exception the code expected and recovered from names the exception's class and+its text in two fields, and never splices the exception into its message: the message stays the same on every+emission, so a log store groups and counts it, while the fields say what went wrong this time and get the redaction's+field treatment, control characters escaped included. No traceback rides along: a handled, expected failure is not a+bug in Pipelex's frames, and only ``error`` and ``critical`` take ``include_exception``.++``error.type`` is the OpenTelemetry semantic-convention key for the class of error an operation ended with.+``error.message`` is the key the conventions gave an error's text before deprecating the general attribute in favour+of domain-specific ones; it is kept here as ``error.type``'s companion because the ``exception.*`` keys belong to the+sinks, which write them for a record that carries the exception itself and prefix a field spelling one.+"""++#: The class of the handled exception, by its name.+ERROR_TYPE_FIELD = "error.type"++#: The handled exception's text.+ERROR_MESSAGE_FIELD = "error.message"+++def error_fields(*, exc: BaseException, text: str | None = None) -> dict[str, str]:+ """The ``error.type`` and ``error.message`` fields of a handled exception, to spread into a call's ``fields``.++ Args:+ exc: The exception the line is about.+ text: The text to carry instead of ``str(exc)``, for a line whose diagnosis is the exception's cause chain+ rather than its own text.++ Returns:+ ``{"error.type": <the exception's class name>, "error.message": <its text>}``.+ """+ return {ERROR_TYPE_FIELD: type(exc).__name__, ERROR_MESSAGE_FIELD: str(exc) if text is None else text}diff --git a/tests/helpers/rich_markup.py b/tests/helpers/rich_markup.pydeleted file mode 100644index 8251ad65e..000000000--- a/tests/helpers/rich_markup.py+++ /dev/null@@ -1,49 +0,0 @@-"""What Rich would read as console markup in a piece of text: the tags it applies as styling rather than prints.--A tag-shaped span is not markup by its shape alone. Rich's tag pattern also matches the ``[int]`` of ``list[int]``,-a ``[cycle]`` marker and a backend's table, ``[openai]``, yet none of them names a style, and a log message holding-one is plain text that prints as written. So a tag counts as markup only when Rich would style with it: a closing-tag, ``[/]`` or ``[/red]``; an ``@`` handler, ``[@click=app.bell]``; or an opening tag whose text Rich parses as a-style, ``[bold]``, ``[on blue]``, ``[link=https://pipelex.com]``, or that names a style of Rich's default theme,-``[repr.number]``. A tag escaped with a backslash is text, since Rich prints it as written.-"""--from __future__ import annotations--from rich.default_styles import DEFAULT_STYLES-from rich.errors import StyleSyntaxError-from rich.markup import RE_TAGS-from rich.style import Style---def _reads_as_style(*, tag_text: str) -> bool:- """Whether Rich applies a tag's text as styling, rather than leaving the reader a bracketed word.-- A closing tag and an ``@`` handler are markup whatever they name. An opening tag is markup when it names a style- of the default theme, or when Rich parses its text as a style, ``name=parameters`` read the way Rich's own- ``Tag`` reads it.- """- if tag_text.startswith(("/", "@")):- return True- if tag_text in DEFAULT_STYLES:- return True- name, separator, parameters = tag_text.partition("=")- style_text = f"{name} {parameters}" if separator else name- try:- Style.parse(style_text)- except StyleSyntaxError:- return False- return True---def find_markup_tags(*, text: str) -> list[str]:- """The unescaped tags in the text that Rich would apply as markup, in order, each as written."""- tags: list[str] = []- for match in RE_TAGS.finditer(text):- full_text, escapes, tag_text = match.groups()- # An odd run of backslashes escapes the tag, which then prints as written.- if len(escapes) % 2 == 1:- continue- if _reads_as_style(tag_text=tag_text):- tags.append(full_text[len(escapes) :])- return tagsdiff --git a/tests/helpers/test_rich_markup.py b/tests/helpers/test_rich_markup.pyindex cc2bd9883..b1e8bb500 100644--- a/tests/helpers/test_rich_markup.py+++ b/tests/helpers/test_rich_markup.py@@ -2,7 +2,7 @@ from __future__ import annotationsimport pytest-from tests.helpers.rich_markup import find_markup_tags+from pipelex.cli.dev_cli.commands.log_call_guard import find_markup_tagsclass TestFindMarkupTags:diff --git a/tests/integration/pipelex/libraries/test_unresolved_package_dependency.py b/tests/integration/pipelex/libraries/test_unresolved_package_dependency.pyindex 97a779862..229af1f31 100644--- a/tests/integration/pipelex/libraries/test_unresolved_package_dependency.py+++ b/tests/integration/pipelex/libraries/test_unresolved_package_dependency.py@@ -27,6 +27,7 @@ from pipelex.mthds_parsing.parser import MthdsParserfrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pipelex.pipeline.execution_seams import acquire_libraryfrom pipelex.pipeline.validate_bundle import validate_bundle+from pipelex.tools.log.error_fields import ERROR_MESSAGE_FIELD, ERROR_TYPE_FIELDfrom pipelex.validation_error_types import PipeValidationErrorTypefrom tests.integration.pipelex.libraries.installed_packages import isolate_installed_methods, write_consumerfrom tests.integration.pipelex.libraries.test_data import ProbePackageTestData@@ -160,12 +161,16 @@ class TestUnresolvedPackageDependency:await _verdict_for(mthds_content=ProbePackageTestData.CONSUMER_BUNDLE)warnings = [- record.message for record in caplog.records if record.levelno == logging.WARNING and ProbePackageTestData.DEP_ALIAS in record.message+ record+ for record in caplog.records+ if record.levelno == logging.WARNING and getattr(record, "package_address", None) == ProbePackageTestData.DEP_ALIAS]- assert len(warnings) == 1, warnings- assert "MethodDependencyFetchError" in warnings[0]- assert "VCSFetchError" in warnings[0]- assert "Cloning into '/host/clones/x'" in warnings[0]+ assert [record.getMessage() for record in warnings] == ["A method package could not be resolved"]+ assert getattr(warnings[0], ERROR_TYPE_FIELD) == "MethodDependencyFetchError"+ cause_chain = getattr(warnings[0], ERROR_MESSAGE_FIELD)+ assert "MethodDependencyFetchError" in cause_chain+ assert "VCSFetchError" in cause_chain+ assert "Cloning into '/host/clones/x'" in cause_chainasync def test_a_repository_without_the_package_is_one_item(self, tmp_path: Path, mocker: MockerFixture) -> None:isolate_installed_methods(mocker=mocker, root=tmp_path)diff --git a/tests/integration/pipelex/pipeline/test_log_messages_carry_no_markup.py b/tests/integration/pipelex/pipeline/test_log_messages_carry_no_markup.pyindex f65c5e53d..820598373 100644--- a/tests/integration/pipelex/pipeline/test_log_messages_carry_no_markup.py+++ b/tests/integration/pipelex/pipeline/test_log_messages_carry_no_markup.py@@ -22,6 +22,7 @@ from typing import TYPE_CHECKING, Anyimport pytestfrom typing_extensions import override+from pipelex.cli.dev_cli.commands.log_call_guard import find_markup_tagsfrom pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstractfrom pipelex.cogt.llm.thinking_mode import ThinkingModefrom pipelex.cogt.model_backends.model_spec import InferenceModelSpec@@ -31,7 +32,6 @@ from pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.tools.log.json_log_sink import LOGGER_KEY, MESSAGE_KEY, SEVERITY_KEY, JsonLogSinkfrom pipelex.tools.log.log_levels import LOGGING_LEVEL_VERBOSE, LOGGING_LEVEL_VERBOSE_NAME-from tests.helpers.rich_markup import find_markup_tagsfrom tests.integration.pipelex.pipeline.test_data import LogMarkupTestDataif TYPE_CHECKING:diff --git a/tests/unit/pipelex/cli/dev/test_check_log_calls_cmd.py b/tests/unit/pipelex/cli/dev/test_check_log_calls_cmd.pynew file mode 100644index 000000000..226617aaa--- /dev/null+++ b/tests/unit/pipelex/cli/dev/test_check_log_calls_cmd.py@@ -0,0 +1,164 @@+from __future__ import annotations++import io+from typing import TYPE_CHECKING++import pytest+from rich.console import Console++from pipelex.cli.dev_cli.commands import check_log_calls_cmd as cmd_mod+from pipelex.cli.dev_cli.commands.check_log_calls_cmd import check_log_calls_cmd+from pipelex.cli.dev_cli.commands.log_call_guard import LogCallGuardError, LogCallRule, OffendingCall, RuleBreach++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++#: Wide enough that no assertion below depends on where Rich decides to wrap.+CONSOLE_WIDTH = 400++LISTED_KEY = "pipelex/core/sample_module.py::Loader.load"+LISTED_SIGNATURE = 'warning: f"Loaded {alias}"'+STALE_SIGNATURE = 'info: f"Fetched {address}"'++OFFENDING_CALL = OffendingCall(+ relative_path="pipelex/core/sample_module.py",+ qualified_name="Loader.load",+ lineno=12,+ signature=LISTED_SIGNATURE,+ breaches=(RuleBreach(rule=LogCallRule.F_STRING, detail="the message is an f-string"),),+)+++class TestCheckLogCallsCmd:+ @pytest.fixture+ def console_buffer(self, mocker: MockerFixture) -> io.StringIO:+ """Route every `get_console()` call in the command module to one StringIO-backed console."""+ buffer = io.StringIO()+ mocker.patch.object(cmd_mod, "get_console", return_value=Console(file=buffer, force_terminal=False, width=CONSOLE_WIDTH))+ return buffer++ @pytest.mark.parametrize(+ ("quiet", "expected_verdict"),+ [+ (True, "✓ Log-call check: PASSED (1 baselined call(s) left)"),+ (False, "Log-call Check: PASSED"),+ ],+ )+ def test_a_tree_matching_its_baseline_passes(+ self, mocker: MockerFixture, console_buffer: io.StringIO, quiet: bool, expected_verdict: str+ ) -> None:+ """A tree whose every offending call is listed returns normally, which is exit 0, and a quiet run says so in one line."""+ mocker.patch.object(cmd_mod, "collect_offending_calls", return_value=[OFFENDING_CALL])+ mocker.patch.object(cmd_mod, "load_baseline", return_value={LISTED_KEY: [LISTED_SIGNATURE]})+ check_log_calls_cmd(quiet=quiet)+ output = console_buffer.getvalue()+ assert expected_verdict in output+ if quiet:+ assert output.strip().splitlines() == [expected_verdict]++ @pytest.mark.parametrize("quiet", [True, False])+ def test_an_unlisted_call_exits_1_with_its_site_its_rule_and_the_remedy(+ self, mocker: MockerFixture, console_buffer: io.StringIO, quiet: bool+ ) -> None:+ """The gate: a quiet CI run still carries the site, the rule, its detail and the rule's remedy."""+ mocker.patch.object(cmd_mod, "collect_offending_calls", return_value=[OFFENDING_CALL])+ mocker.patch.object(cmd_mod, "load_baseline", return_value={})++ with pytest.raises(SystemExit) as exit_info:+ check_log_calls_cmd(quiet=quiet)++ assert exit_info.value.code == 1+ output = console_buffer.getvalue()+ assert "pipelex/core/sample_module.py:12" in output+ assert "Loader.load" in output+ assert "f-string: the message is an f-string" in output+ assert LogCallRule.F_STRING.remedy in output++ def test_a_stale_signature_exits_1_naming_it_and_how_to_remove_it(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:+ mocker.patch.object(cmd_mod, "collect_offending_calls", return_value=[OFFENDING_CALL])+ mocker.patch.object(cmd_mod, "load_baseline", return_value={LISTED_KEY: [LISTED_SIGNATURE, STALE_SIGNATURE]})+ write_baseline = mocker.patch.object(cmd_mod, "write_baseline")++ with pytest.raises(SystemExit) as exit_info:+ check_log_calls_cmd(quiet=True)++ assert exit_info.value.code == 1+ output = console_buffer.getvalue()+ assert "1 baseline signature(s) are stale" in output+ assert STALE_SIGNATURE in output+ assert "pipelex-dev check-log-calls --prune" in output+ write_baseline.assert_not_called()++ def test_prune_removes_the_stale_signature_and_then_passes(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:+ mocker.patch.object(cmd_mod, "collect_offending_calls", return_value=[OFFENDING_CALL])+ mocker.patch.object(cmd_mod, "load_baseline", return_value={LISTED_KEY: [LISTED_SIGNATURE, STALE_SIGNATURE]})+ write_baseline = mocker.patch.object(cmd_mod, "write_baseline")++ check_log_calls_cmd(prune=True, quiet=True)++ assert write_baseline.call_args.kwargs["baseline"] == {LISTED_KEY: [LISTED_SIGNATURE]}+ output = console_buffer.getvalue()+ assert "Removed 1 stale signature(s) from log_call_baseline.toml" in output+ assert "✓ Log-call check: PASSED (1 baselined call(s) left)" in output++ def test_prune_never_lists_an_unlisted_call(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:+ mocker.patch.object(cmd_mod, "collect_offending_calls", return_value=[OFFENDING_CALL])+ mocker.patch.object(cmd_mod, "load_baseline", return_value={})+ write_baseline = mocker.patch.object(cmd_mod, "write_baseline")++ with pytest.raises(SystemExit) as exit_info:+ check_log_calls_cmd(prune=True, quiet=True)++ assert exit_info.value.code == 1+ write_baseline.assert_not_called()+ assert "1 call(s) break the conventions" in console_buffer.getvalue()++ def test_report_prints_the_baseline_by_package_area_and_gates_nothing(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:+ mocker.patch.object(cmd_mod, "collect_offending_calls", return_value=[])+ mocker.patch.object(+ cmd_mod,+ "load_baseline",+ return_value={+ LISTED_KEY: [LISTED_SIGNATURE, STALE_SIGNATURE],+ "pipelex/core/other_module.py::<module>": [LISTED_SIGNATURE],+ "api/pipelex_api/routes.py::start": [LISTED_SIGNATURE],+ },+ )+ check_log_calls_cmd(report=True)+ lines = [line.strip() for line in console_buffer.getvalue().splitlines() if line.strip()]+ assert lines[1:4] == ["pipelex/core 3 call(s)", "api/pipelex_api 1 call(s)", "Total baselined calls: 4"]++ def test_the_two_trusted_revisions_are_exclusive(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:+ mocker.patch.object(cmd_mod, "collect_offending_calls", return_value=[OFFENDING_CALL])+ mocker.patch.object(cmd_mod, "load_baseline", return_value={LISTED_KEY: [LISTED_SIGNATURE]})++ with pytest.raises(SystemExit) as exit_info:+ check_log_calls_cmd(quiet=True, against="origin/dev", against_merge_base="origin/dev")++ assert exit_info.value.code == 1+ assert "Give `--against` or `--against-merge-base`, not both" in console_buffer.getvalue()++ def test_a_signature_added_since_the_trusted_revision_exits_1_naming_it(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:+ """The tree and the working baseline agree, so only the trusted revision's baseline says the entry is new."""+ mocker.patch.object(cmd_mod, "collect_offending_calls", return_value=[OFFENDING_CALL])+ mocker.patch.object(cmd_mod, "load_baseline", return_value={LISTED_KEY: [LISTED_SIGNATURE]})+ mocker.patch.object(cmd_mod, "load_trusted_baseline", return_value={})++ with pytest.raises(SystemExit) as exit_info:+ check_log_calls_cmd(quiet=True, against="abc123")++ assert exit_info.value.code == 1+ output = console_buffer.getvalue()+ assert "0 call(s) break the conventions, 0 baseline signature(s) are stale, 1 baseline signature(s) were added since 'abc123'" in output+ assert f"{LISTED_KEY} listed 1 time(s), 0 at the base" in output+ assert LISTED_SIGNATURE in output++ def test_a_guard_error_exits_1_even_when_quiet(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:+ mocker.patch.object(cmd_mod, "collect_offending_calls", return_value=[])+ mocker.patch.object(cmd_mod, "load_baseline", side_effect=LogCallGuardError("The baseline log_call_baseline.toml was not found"))++ with pytest.raises(SystemExit) as exit_info:+ check_log_calls_cmd(quiet=True)++ assert exit_info.value.code == 1+ assert "✗ Log-call check: FAILED - The baseline log_call_baseline.toml was not found" in console_buffer.getvalue()diff --git a/tests/unit/pipelex/cli/dev/test_log_call_baseline.py b/tests/unit/pipelex/cli/dev/test_log_call_baseline.pynew file mode 100644index 000000000..ecc2c2d72--- /dev/null+++ b/tests/unit/pipelex/cli/dev/test_log_call_baseline.py@@ -0,0 +1,200 @@+from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++import pytest++from pipelex.cli.dev_cli.commands import log_call_guard as guard_mod+from pipelex.cli.dev_cli.commands.log_call_guard import (+ BASELINE_FILE,+ BaselineGrowth,+ LogCallGuardError,+ OffendingCall,+ StaleEntry,+ build_baseline,+ collect_offending_calls,+ compare_with_baseline,+ compare_with_trusted_baseline,+ find_offending_calls_in_source,+ load_baseline,+ prune_baseline,+ render_baseline,+ write_baseline,+)++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++#: Anchored on `tests/` by name rather than by a parent count, for the reason `test_hub_layering_guard.py` gives.+_REPO_ROOT = next(parent for parent in Path(__file__).resolve().parents if parent.name == "tests").parent++PILOT_MODULE = "pipelex/libraries/library_manager.py"+SAMPLE_PATH = "pipelex/core/sample_module.py"++INTERPOLATED = 'from pipelex import log\n\ndef load(alias):\n log.warning(f"Loaded {alias}")\n'+CONVERTED = 'from pipelex import log\n\ndef load(alias):\n log.warning("Loaded a dependency", fields={"dependency_alias": alias})\n'+MOVED = 'from pipelex import log\n\ndef fetch(alias):\n log.warning(f"Loaded {alias}")\n'+REWORDED = 'from pipelex import log\n\ndef load(alias):\n log.warning(f"Loaded the dependency {alias}")\n'+TWICE = 'from pipelex import log\n\ndef load(alias):\n log.warning(f"Loaded {alias}")\n log.warning(f"Loaded {alias}")\n'++LISTED_SIGNATURE = 'warning: f"Loaded {alias}" [f-string]'+LISTED_KEY = f"{SAMPLE_PATH}::load"+++def _offending(source: str) -> list[OffendingCall]:+ return find_offending_calls_in_source(source=source, relative_path=SAMPLE_PATH)+++def _write_tree(*, root: Path, files: dict[str, str]) -> None:+ for relative_path, content in files.items():+ target = root / relative_path+ target.parent.mkdir(parents=True, exist_ok=True)+ target.write_text(content, encoding="utf-8")+++class TestLogCallBaseline:+ def test_a_baselined_call_passes(self) -> None:+ comparison = compare_with_baseline(offending=_offending(INTERPOLATED), baseline={LISTED_KEY: [LISTED_SIGNATURE]})+ assert comparison.is_clean++ def test_a_call_the_baseline_does_not_list_fails(self) -> None:+ comparison = compare_with_baseline(offending=_offending(INTERPOLATED), baseline={})+ assert [(call.key, call.signature) for call in comparison.unlisted] == [(LISTED_KEY, LISTED_SIGNATURE)]+ assert comparison.stale == []++ @pytest.mark.parametrize(+ ("topic", "source", "expected_unlisted"),+ [+ ("the call now complies", CONVERTED, []),+ ("the call moved to another function", MOVED, [(f"{SAMPLE_PATH}::fetch", LISTED_SIGNATURE)]),+ ("the call's message changed", REWORDED, [(LISTED_KEY, 'warning: f"Loaded the dependency {alias}" [f-string]')]),+ ],+ )+ def test_a_listed_call_no_call_matches_any_more_is_stale_until_its_entry_is_removed(+ self, topic: str, source: str, expected_unlisted: list[tuple[str, str]]+ ) -> None:+ """The symmetric staleness: the listed signature fails the check, and whatever replaced the call is held as new code."""+ comparison = compare_with_baseline(offending=_offending(source), baseline={LISTED_KEY: [LISTED_SIGNATURE]})+ assert comparison.stale == [StaleEntry(key=LISTED_KEY, signature=LISTED_SIGNATURE)], topic+ assert [(call.key, call.signature) for call in comparison.unlisted] == expected_unlisted, topic++ def test_a_signature_is_listed_once_per_call_that_carries_it(self) -> None:+ """A second identical call beside a listed one is new, and a signature listed twice for one call is stale once."""+ assert len(compare_with_baseline(offending=_offending(TWICE), baseline={LISTED_KEY: [LISTED_SIGNATURE]}).unlisted) == 1+ doubled = compare_with_baseline(offending=_offending(INTERPOLATED), baseline={LISTED_KEY: [LISTED_SIGNATURE, LISTED_SIGNATURE]})+ assert doubled.stale == [StaleEntry(key=LISTED_KEY, signature=LISTED_SIGNATURE)]+ assert doubled.unlisted == []++ def test_pruning_removes_stale_signatures_and_never_adds_one(self) -> None:+ offending = _offending(MOVED)+ pruned = prune_baseline(baseline={LISTED_KEY: [LISTED_SIGNATURE]}, offending=offending)+ assert pruned == {}+ assert [call.key for call in compare_with_baseline(offending=offending, baseline=pruned).unlisted] == [f"{SAMPLE_PATH}::fetch"]++ def test_pruning_keeps_what_still_matches(self) -> None:+ baseline = {LISTED_KEY: [LISTED_SIGNATURE, LISTED_SIGNATURE]}+ assert prune_baseline(baseline=baseline, offending=_offending(INTERPOLATED)) == {LISTED_KEY: [LISTED_SIGNATURE]}++ def test_adding_a_violation_together_with_its_entry_fails_against_the_trusted_baseline(self) -> None:+ """The tree and its own baseline agree, so only the comparison with the base refuses the exemption the change gave itself."""+ offending = _offending(INTERPOLATED)+ working = build_baseline(offending=offending)+ assert compare_with_baseline(offending=offending, baseline=working).is_clean+ assert compare_with_trusted_baseline(baseline=working, trusted={}) == [+ BaselineGrowth(key=LISTED_KEY, signature=LISTED_SIGNATURE, trusted_count=0, working_count=1)+ ]++ def test_a_signature_listed_more_often_than_at_the_base_fails(self) -> None:+ working = build_baseline(offending=_offending(TWICE))+ assert compare_with_trusted_baseline(baseline=working, trusted={LISTED_KEY: [LISTED_SIGNATURE]}) == [+ BaselineGrowth(key=LISTED_KEY, signature=LISTED_SIGNATURE, trusted_count=1, working_count=2)+ ]++ @pytest.mark.parametrize(+ ("topic", "trusted", "working"),+ [+ ("the entry was removed", {LISTED_KEY: [LISTED_SIGNATURE]}, {}),+ ("the baseline is unchanged", {LISTED_KEY: [LISTED_SIGNATURE]}, {LISTED_KEY: [LISTED_SIGNATURE]}),+ ("one of two identical entries was removed", {LISTED_KEY: [LISTED_SIGNATURE, LISTED_SIGNATURE]}, {LISTED_KEY: [LISTED_SIGNATURE]}),+ ],+ )+ def test_a_baseline_that_shrank_or_stayed_passes_against_the_trusted_one(+ self, topic: str, trusted: dict[str, list[str]], working: dict[str, list[str]]+ ) -> None:+ assert compare_with_trusted_baseline(baseline=working, trusted=trusted) == [], topic++ def test_the_baseline_is_written_through_the_repo_s_toml_writer(self, mocker: MockerFixture, tmp_path: Path) -> None:+ save_toml = mocker.spy(guard_mod, "save_toml_to_path")+ write_baseline(baseline={LISTED_KEY: [LISTED_SIGNATURE]}, repo_root=tmp_path)+ save_toml.assert_called_once()+ assert save_toml.call_args.kwargs["path"] == tmp_path / BASELINE_FILE+ assert (tmp_path / BASELINE_FILE).read_text(encoding="utf-8") == render_baseline(baseline={LISTED_KEY: [LISTED_SIGNATURE]})++ def test_the_committed_baseline_is_exactly_what_the_writer_writes(self) -> None:+ """With `make format`'s plxt check in CI, this pins the writer to what `plxt fmt` leaves, so a prune moves nothing else."""+ committed = (_REPO_ROOT / BASELINE_FILE).read_text(encoding="utf-8")+ assert render_baseline(baseline=load_baseline(repo_root=_REPO_ROOT)) == committed++ def test_the_rendered_baseline_loads_back_as_written(self, tmp_path: Path) -> None:+ baseline = {+ LISTED_KEY: [LISTED_SIGNATURE, 'error: "a \\\\ backslash", title="tab\\there"'],+ "api/pipelex_api/sample.py::<module>": ['info: f"Quoted \\"{value}\\" and é"'],+ }+ write_baseline(baseline=baseline, repo_root=tmp_path)+ assert load_baseline(repo_root=tmp_path) == {key: sorted(calls) for key, calls in baseline.items()}+ rendered = render_baseline(baseline=baseline)+ assert rendered.index("api/pipelex_api/sample.py") < rendered.index(SAMPLE_PATH), "keys are written sorted"++ @pytest.mark.parametrize(+ ("topic", "content", "expected_message"),+ [+ ("a wrong version", 'version = 2\n["pipelex/a.py::f"]\ncalls = ["info: x"]\n', "must declare `version = 1`"),+ ("a key without a qualified name", 'version = 1\n["pipelex/a.py"]\ncalls = ["info: x"]\n', "is not of the form"),+ ("an entry with no calls", 'version = 1\n["pipelex/a.py::f"]\ncalls = []\n', "non-empty `calls` array"),+ ("an unknown key", 'version = 1\n["pipelex/a.py::f"]\ncalls = ["info: x"]\nreason = "later"\n', "unknown key(s)"),+ ("a blank call", 'version = 1\n["pipelex/a.py::f"]\ncalls = [" "]\n', "not a non-empty string"),+ ("invalid TOML", "version = \n", "is not valid TOML"),+ ],+ )+ def test_a_malformed_baseline_is_an_error_never_an_empty_one(self, tmp_path: Path, topic: str, content: str, expected_message: str) -> None:+ (tmp_path / BASELINE_FILE).write_text(content, encoding="utf-8")+ with pytest.raises(LogCallGuardError) as error_info:+ load_baseline(repo_root=tmp_path)+ assert expected_message in str(error_info.value), topic++ def test_a_missing_baseline_is_an_error(self, tmp_path: Path) -> None:+ with pytest.raises(LogCallGuardError, match="was not found"):+ load_baseline(repo_root=tmp_path)++ def test_the_scan_reads_both_trees_and_leaves_the_facade_package_out(self, tmp_path: Path) -> None:+ _write_tree(+ root=tmp_path,+ files={+ "pipelex/core/sample_module.py": INTERPOLATED,+ "pipelex/tools/log/log_dispatch.py": INTERPOLATED,+ "api/pipelex_api/routes.py": INTERPOLATED,+ },+ )+ offending = collect_offending_calls(repo_root=tmp_path)+ assert [call.key for call in offending] == ["api/pipelex_api/routes.py::load", "pipelex/core/sample_module.py::load"]+ assert build_baseline(offending=offending) == {+ "api/pipelex_api/routes.py::load": [LISTED_SIGNATURE],+ "pipelex/core/sample_module.py::load": [LISTED_SIGNATURE],+ }++ def test_a_missing_scan_root_is_an_error_rather_than_a_pass(self, tmp_path: Path) -> None:+ _write_tree(root=tmp_path, files={"pipelex/core/sample_module.py": CONVERTED})+ with pytest.raises(LogCallGuardError, match="does not exist"):+ collect_offending_calls(repo_root=tmp_path)++ def test_the_committed_baseline_matches_the_tree(self) -> None:+ """What `make check-log-calls` gates, read here too so `make agent-test` catches a drift between the two."""+ comparison = compare_with_baseline(offending=collect_offending_calls(repo_root=_REPO_ROOT), baseline=load_baseline(repo_root=_REPO_ROOT))+ assert comparison.unlisted == []+ assert comparison.stale == []++ def test_the_pilot_module_has_no_baseline_entry(self) -> None:+ """The pilot follows the conventions throughout, so the baseline holds nothing for it."""+ baseline = load_baseline(repo_root=_REPO_ROOT)+ assert [key for key in baseline if key.startswith(f"{PILOT_MODULE}::")] == []diff --git a/tests/unit/pipelex/cli/dev/test_log_call_guard.py b/tests/unit/pipelex/cli/dev/test_log_call_guard.pynew file mode 100644index 000000000..75d7b56dc--- /dev/null+++ b/tests/unit/pipelex/cli/dev/test_log_call_guard.py@@ -0,0 +1,423 @@+from __future__ import annotations++import textwrap++import pytest++from pipelex.cli.dev_cli.commands.log_call_guard import (+ MODULE_SCOPE_NAME,+ LogCallRule,+ OffendingCall,+ find_markup_tags,+ find_offending_calls_in_source,+)++SAMPLE_PATH = "pipelex/core/sample_module.py"+FACADE_IMPORT = "from pipelex import log\n"+++def _offending(body: str, *, header: str = FACADE_IMPORT) -> list[OffendingCall]:+ """The offending calls of a snippet, the facade imported at its top unless the header says otherwise."""+ return find_offending_calls_in_source(source=header + textwrap.dedent(body), relative_path=SAMPLE_PATH)+++def _rules(body: str, *, header: str = FACADE_IMPORT) -> list[list[LogCallRule]]:+ """The rules each offending call of a snippet breaks, in source order."""+ return [[breach.rule for breach in call.breaches] for call in _offending(body, header=header)]+++class TestLogCallGuard:+ @pytest.mark.parametrize("method", ["info", "warning", "error", "critical"])+ @pytest.mark.parametrize(+ ("topic", "message", "expected_rule"),+ [+ ("an f-string with a placeholder", 'f"Loaded {alias}"', LogCallRule.F_STRING),+ ("a percent format", '"Loaded %s" % alias', LogCallRule.PERCENT_FORMAT),+ ("a concatenation with a value", '"Loaded " + alias', LogCallRule.CONCATENATION),+ ("a .format() call", '"Loaded {}".format(alias)', LogCallRule.FORMAT_CALL),+ ("an attribute", "self.message", LogCallRule.NON_LITERAL),+ ("a call's result", "describe(alias)", LogCallRule.NON_LITERAL),+ ("a mapping", '{"alias": alias}', LogCallRule.NON_LITERAL),+ ],+ )+ def test_an_interpolated_or_non_literal_message_is_refused_at_info_and_above(+ self, method: str, topic: str, message: str, expected_rule: LogCallRule+ ) -> None:+ """Each form a message can be built in is refused under its own name, on every method at INFO and above."""+ assert _rules(f"def load(alias, self, describe):\n log.{method}({message})\n") == [[expected_rule]], topic++ @pytest.mark.parametrize(+ ("topic", "body"),+ [+ ("a string constant", 'log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})\n'),+ ("an implicit concatenation", 'log.info("A long message " "split in two")\n'),+ ("an f-string without a placeholder", 'log.error(f"A run failed", include_exception=True)\n'),+ ("a + between literals", 'log.info("A long message " + "split in two")\n'),+ ("a conditional between literals", 'log.info("Hosted" if alias else "Local")\n'),+ ("a literal passed as content=", 'log.info(content="Loaded the library")\n'),+ ("a literal title", 'log.info("Loaded", title="Library")\n'),+ ],+ )+ def test_a_literal_message_passes(self, topic: str, body: str) -> None:+ assert _offending(f"def load(alias):\n {body}") == [], topic++ @pytest.mark.parametrize("method", ["debug", "verbose"])+ def test_debug_and_verbose_may_keep_an_f_string(self, method: str) -> None:+ assert _offending(f'def load(alias):\n log.{method}(f"Loaded {{alias}}", title=f"Load of {{alias}}")\n') == []++ def test_a_name_bound_to_an_f_string_is_refused_as_one_naming_the_binding_line(self) -> None:+ offending = _offending(+ """+ def load(alias):+ msg = f"Loaded {alias}"+ log.warning(msg)+ """+ )+ assert [[breach.rule for breach in call.breaches] for call in offending] == [[LogCallRule.F_STRING]]+ assert offending[0].breaches[0].detail == "the message is `msg`, bound at line 4 to an f-string"++ @pytest.mark.parametrize(+ ("topic", "body", "expected"),+ [+ ("a local literal", 'def load():\n msg = "Loaded"\n log.info(msg)\n', []),+ ("a module-level constant", 'LOADED_MESSAGE = "Loaded"\n\ndef load():\n log.info(LOADED_MESSAGE)\n', []),+ ("a literal built from a module constant", 'PREFIX = "Loaded"\n\ndef load():\n log.info(PREFIX + " the library")\n', []),+ ("a parameter", "def load(msg):\n log.info(msg)\n", [[LogCallRule.NON_LITERAL]]),+ ("an unbound name", "def load():\n log.info(msg)\n", [[LogCallRule.NON_LITERAL]]),+ ("a loop variable", 'def load():\n for msg in ["a", "b"]:\n log.info(msg)\n', [[LogCallRule.NON_LITERAL]]),+ (+ "a name extended with +=",+ 'def load(alias):\n msg = "Loaded "\n msg += alias\n log.info(msg)\n',+ [[LogCallRule.CONCATENATION]],+ ),+ ("a name bound to a call", "def load(alias):\n msg = describe(alias)\n log.info(msg)\n", [[LogCallRule.NON_LITERAL]]),+ (+ "a name bound in another function is not this one's",+ 'def other():\n msg = "Loaded"\n\ndef load():\n log.info(msg)\n',+ [[LogCallRule.NON_LITERAL]],+ ),+ ],+ )+ def test_a_named_message_is_read_through_its_bindings(self, topic: str, body: str, expected: list[list[LogCallRule]]) -> None:+ assert _rules(body) == expected, topic++ @pytest.mark.parametrize("keyword", ["title", "inline"])+ def test_an_interpolated_title_is_refused_at_info_and_above(self, keyword: str) -> None:+ offending = _offending(f'def load(alias):\n log.warning("Loaded", {keyword}=f"Load of {{alias}}")\n')+ assert [[breach.rule for breach in call.breaches] for call in offending] == [[LogCallRule.F_STRING]]+ assert offending[0].breaches[0].detail == f"`{keyword}=` is an f-string"++ @pytest.mark.parametrize("method", ["verbose", "debug", "info", "warning", "error", "critical"])+ @pytest.mark.parametrize(+ ("topic", "message", "expected_tag"),+ [+ ("an opening and a closing tag", '"[red]compose_company[/red] runs"', "[red]"),+ ("a compound style", '"[bold green]Company[/bold green]"', "[bold green]"),+ ("a bare closing tag", '"Done[/]"', "[/]"),+ ("a link", '"See [link=https://pipelex.com]the docs[/link]"', "[link=https://pipelex.com]"),+ ("an @ handler", '"Click [@click=app.bell]here[/]"', "[@click=app.bell]"),+ ("a theme style name", '"[repr.number]7[/repr.number]"', "[repr.number]"),+ ],+ )+ def test_a_markup_tag_in_a_literal_message_is_refused_at_every_level(self, method: str, topic: str, message: str, expected_tag: str) -> None:+ offending = _offending(f"def load():\n log.{method}({message})\n")+ assert len(offending) == 1, topic+ markup_details = [breach.detail for breach in offending[0].breaches if breach.rule == LogCallRule.MARKUP]+ assert markup_details[0] == f"the message holds the markup tag `{expected_tag}`"++ def test_markup_in_the_literal_parts_of_a_debug_f_string_is_refused(self) -> None:+ """An f-string is allowed below INFO, its markup is not."""+ assert _rules('def load(alias):\n log.debug(f"[red]{alias}[/red]")\n') == [[LogCallRule.MARKUP, LogCallRule.MARKUP]]++ def test_markup_in_a_title_is_refused_below_info(self) -> None:+ offending = _offending('def load():\n log.verbose("Loaded", title="[bold]Library[/bold]")\n')+ assert offending[0].breaches[0].detail == "`title=` holds the markup tag `[bold]`"++ def test_markup_a_name_is_bound_to_is_refused(self) -> None:+ assert _rules('def load():\n msg = "[red]Loaded[/red]"\n log.verbose(msg)\n') == [[LogCallRule.MARKUP, LogCallRule.MARKUP]]++ @pytest.mark.parametrize(+ ("topic", "text"),+ [+ ("a type subscript", "expected list[int], got dict[str, Any]"),+ ("an errno", "[Errno 2] No such file or directory"),+ ("an index that is no style", "items[index] is missing"),+ ("an escaped tag", "\\[red] stays literal"),+ ("no bracket", "Loaded the library"),+ ],+ )+ def test_brackets_that_are_no_markup_pass(self, topic: str, text: str) -> None:+ assert find_markup_tags(text=text) == [], topic++ def test_a_call_breaking_both_rules_is_one_offending_call(self) -> None:+ assert _rules('def load(alias):\n log.info(f"[red]{alias}[/red]")\n') == [[LogCallRule.F_STRING, LogCallRule.MARKUP, LogCallRule.MARKUP]]++ @pytest.mark.parametrize(+ ("topic", "header", "call"),+ [+ ("the facade from its own module", "from pipelex.tools.log.log import log\n", 'log.info(f"{alias}")'),+ ("the facade under an alias", "from pipelex import log as pipelex_log\n", 'pipelex_log.info(f"{alias}")'),+ ("the facade from its own module under an alias", "from pipelex.tools.log.log import log as plog\n", 'plog.info(f"{alias}")'),+ ("the package imported", "import pipelex\n", 'pipelex.log.warning(f"{alias}")'),+ ("the package imported under an alias", "import pipelex as px\n", 'px.log.info(f"{alias}")'),+ ("the facade's module imported from its package", "from pipelex.tools.log import log as m\n", 'm.log.info(f"{alias}")'),+ ("the facade's module imported under an alias", "import pipelex.tools.log.log as x\n", 'x.log.info(f"{alias}")'),+ ("the facade's module imported by its full path", "import pipelex.tools.log.log\n", 'pipelex.tools.log.log.log.info(f"{alias}")'),+ ("a parent package imported", "from pipelex.tools import log as log_package\n", 'log_package.log.log.info(f"{alias}")'),+ ("a relative import of the facade", "from ..tools.log.log import log\n", 'log.info(f"{alias}")'),+ ("a relative import of the package's re-export", "from .. import log\n", 'log.info(f"{alias}")'),+ ("a star import from the package", "from pipelex import *\n", 'log.info(f"{alias}")'),+ ("an import inside the function", "", 'from pipelex import log as local_log\n local_log.info(f"{alias}")'),+ ],+ )+ def test_the_facade_is_found_under_the_name_it_is_imported_as(self, topic: str, header: str, call: str) -> None:+ assert _rules(f"def load(alias):\n {call}\n", header=header) == [[LogCallRule.F_STRING]], topic++ @pytest.mark.parametrize(+ ("topic", "header", "call"),+ [+ ("a stdlib logger", "import logging\n", 'logging.getLogger(__name__).info(f"{alias}")'),+ ("a logger attribute", "", 'self._logger.warning(f"{alias}")'),+ ("a log the module never imported from pipelex", "", 'log.info(f"{alias}")'),+ ("a facade method that does not log", FACADE_IMPORT, 'log.context(request_id=f"{alias}")'),+ ("the facade's module, not the facade", "from pipelex.tools.log import log\n", 'log.info(f"{alias}")'),+ ("another package's log", "from somewhere import log\n", 'log.info(f"{alias}")'),+ ],+ )+ def test_a_call_that_is_not_the_facade_s_is_not_read(self, topic: str, header: str, call: str) -> None:+ assert _offending(f"def load(self, alias):\n {call}\n", header=header) == [], topic++ @pytest.mark.parametrize(+ ("topic", "header", "body", "expected"),+ [+ ("a parameter named like the facade", FACADE_IMPORT, 'def load(log, alias):\n log.info(f"{alias}")\n', []),+ (+ "a local named like the facade",+ FACADE_IMPORT,+ 'def load(alias):\n log = logging.getLogger(__name__)\n log.info(f"{alias}")\n',+ [],+ ),+ (+ "the facade imported in another function",+ "",+ 'def setup():\n from pipelex import log\n\ndef load(alias):\n log.info(f"{alias}")\n',+ [],+ ),+ (+ "the facade imported in the same function",+ "",+ 'def setup():\n from pipelex import log\n log.info(f"{__name__}")\n\ndef load(alias):\n log.info(f"{alias}")\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "the facade imported in an enclosing function",+ "",+ 'def load(alias):\n from pipelex import log\n def inner():\n log.info(f"{alias}")\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "the facade imported after a function that calls it",+ "",+ 'def load(alias):\n log.info(f"{alias}")\n\nfrom pipelex import log\n',+ [[LogCallRule.F_STRING]],+ ),+ ],+ )+ def test_a_receiver_is_the_facade_where_a_facade_import_reaches_the_call(+ self, topic: str, header: str, body: str, expected: list[list[LogCallRule]]+ ) -> None:+ """The receiver's name is read in the call's own scope, by the same bindings a message is read through."""+ assert _rules(body, header=header) == expected, topic++ @pytest.mark.parametrize(+ ("topic", "call", "expected_details"),+ [+ ("an expanded message", 'log.warning(**{"content": f"Value {alias}"})', ["the message is an f-string"]),+ ("an expanded title", 'log.warning("Loaded", **{"title": f"Load of {alias}"})', ["`title=` is an f-string"]),+ ("an expanded inline title", 'log.warning("Loaded", **{"inline": f"Load of {alias}"})', ["`inline=` is an f-string"]),+ (+ "expanded markup below INFO",+ 'log.debug(**{"content": "[red]Loaded[/red]"})',+ ["the message holds the markup tag `[red]`", "the message holds the markup tag `[/red]`"],+ ),+ ("an expanded literal with fields", 'log.info(**{"content": "Loaded", "fields": {"alias": alias}})', []),+ ],+ )+ def test_a_dict_literal_expanded_into_a_call_is_read_as_its_keywords(self, topic: str, call: str, expected_details: list[str]) -> None:+ offending = _offending(f"def load(alias):\n {call}\n")+ assert [breach.detail for call_found in offending for breach in call_found.breaches] == expected_details, topic++ @pytest.mark.parametrize(+ ("topic", "call", "expected_detail"),+ [+ ("a mapping", "log.warning(**params)", "`**params` is an expansion whose keywords cannot be read"),+ ("a mapping below INFO", 'log.debug("Loaded", **params)', "`**params` is an expansion whose keywords cannot be read"),+ (+ "a dict literal with a computed key",+ 'log.info(**{key: "Loaded"})',+ "`**{key: 'Loaded'}` is an expansion whose keywords cannot be read",+ ),+ (+ "a dict literal expanding another",+ 'log.info(**{**params, "content": "Loaded"})',+ "`**{**params, 'content': 'Loaded'}` is an expansion whose keywords cannot be read",+ ),+ ],+ )+ def test_an_expansion_that_cannot_be_read_is_refused_at_every_level(self, topic: str, call: str, expected_detail: str) -> None:+ """A `**` the guard cannot read may carry the message or a title, so neither rule could be checked through it."""+ offending = _offending(f"def load(params, key):\n {call}\n")+ assert [[(breach.rule, breach.detail) for breach in call_found.breaches] for call_found in offending] == [+ [(LogCallRule.NON_LITERAL, expected_detail)]+ ], topic++ def test_an_expansion_that_cannot_be_read_is_named_in_the_signature(self) -> None:+ offending = _offending("def load(params):\n log.warning(**params)\n")+ assert [call.signature for call in offending] == ["warning: **params [non-literal]"]++ @pytest.mark.parametrize(+ ("topic", "body", "expected_qualified_name"),+ [+ ("a module-level call", 'log.info(f"{ALIAS}")\n', MODULE_SCOPE_NAME),+ ("a function", 'def load(alias):\n log.info(f"{alias}")\n', "load"),+ ("a method", 'class Loader:\n def load(self, alias):\n log.info(f"{alias}")\n', "Loader.load"),+ ("a nested function", 'def load():\n def inner(alias):\n log.info(f"{alias}")\n', "load.inner"),+ (+ "a class inside a function",+ 'def load():\n class Local:\n def run(self, alias):\n log.info(f"{alias}")\n',+ "load.Local.run",+ ),+ ],+ )+ def test_a_call_is_keyed_by_its_file_and_enclosing_qualified_name(self, topic: str, body: str, expected_qualified_name: str) -> None:+ offending = _offending(body)+ assert [call.key for call in offending] == [f"{SAMPLE_PATH}::{expected_qualified_name}"], topic++ def test_the_signature_is_the_method_and_the_message_source_never_a_line(self) -> None:+ offending = _offending(+ """+ def load(alias, exc):+ log.warning(+ f"Could not load '{alias}': {exc!r:>10}",+ title=f"Load of {alias}",+ )+ """+ )+ assert offending[0].signature == 'warning: f"Could not load \'{alias}\': {exc!r:>10}", title=f"Load of {alias}" [f-string]'++ @pytest.mark.parametrize(+ ("topic", "body", "expected_signature"),+ [+ (+ "a name bound to an f-string",+ 'def load(alias):\n msg = f"Loaded {alias}"\n log.warning(msg)\n',+ 'warning: msg [f-string] where msg = f"Loaded {alias}"',+ ),+ (+ "a name bound twice",+ 'def load(alias, cached):\n msg = f"Loaded {alias}"\n if cached:\n msg = f"Reused {alias}"\n log.warning(msg)\n',+ 'warning: msg [f-string] where msg = f"Loaded {alias}"; msg = f"Reused {alias}"',+ ),+ ("a parameter", "def load(msg):\n log.info(msg)\n", "info: msg [non-literal] where msg = <parameter>"),+ (+ "a module constant read through a concatenation",+ 'PREFIX = "Loaded "\n\ndef load(alias):\n log.info(PREFIX + alias)\n',+ "info: PREFIX + alias [concatenation] where PREFIX = 'Loaded '; alias = <parameter>",+ ),+ (+ "a name captured from an enclosing function",+ 'def load(alias):\n msg = "Loaded"\n def inner():\n log.info(msg)\n',+ "info: msg [non-literal] where msg = <enclosing function>",+ ),+ (+ "a binding that cannot reach the call stays out",+ (+ 'def load(alias):\n msg = f"Loaded {alias}"\n log.warning(msg)\n'+ ' msg = f"Could not load {alias}"\n raise ValueError(msg)\n'+ ),+ 'warning: msg [f-string] where msg = f"Loaded {alias}"',+ ),+ (+ "a name rebuilt from itself",+ 'def load():\n msg = "["\n msg = msg + "red]Loaded"\n log.debug(msg)\n',+ "debug: msg [markup] where msg = '['; msg = msg + 'red]Loaded'",+ ),+ ],+ )+ def test_a_named_message_s_signature_carries_its_bindings_and_its_rules(self, topic: str, body: str, expected_signature: str) -> None:+ """The bindings are source text, sorted, never a line: what the call logs is its identity."""+ assert [call.signature for call in _offending(body)] == [expected_signature], topic++ @pytest.mark.parametrize(+ ("topic", "before", "after"),+ [+ (+ "the bound f-string is reworded",+ 'def load(alias):\n msg = f"Loaded {alias}"\n log.warning(msg)\n',+ 'def load(alias):\n msg = f"Loaded the dependency {alias}"\n log.warning(msg)\n',+ ),+ (+ "the bound f-string gains markup",+ 'def load(alias):\n msg = f"Loaded {alias}"\n log.warning(msg)\n',+ 'def load(alias):\n msg = f"[red]Loaded[/red] {alias}"\n log.warning(msg)\n',+ ),+ (+ "a module constant the message concatenates gains markup",+ 'PREFIX = "Loaded "\n\ndef load(alias):\n log.info(PREFIX + alias)\n',+ 'PREFIX = "[red]Loaded[/red] "\n\ndef load(alias):\n log.info(PREFIX + alias)\n',+ ),+ ],+ )+ def test_editing_what_a_grandfathered_call_logs_changes_its_signature(self, topic: str, before: str, after: str) -> None:+ """The call's own source is unchanged, so only the bindings and the rules in its signature tell the exemption is spent."""+ before_calls = _offending(before)+ after_calls = _offending(after)+ assert len(before_calls) == len(after_calls) == 1, topic+ assert before_calls[0].signature != after_calls[0].signature, topic++ def test_new_markup_is_named_in_the_signature_s_rules(self) -> None:+ offending = _offending('PREFIX = "[red]Loaded[/red] "\n\ndef load(alias):\n log.info(PREFIX + alias)\n')+ assert offending[0].signature == "info: PREFIX + alias [concatenation, markup] where PREFIX = '[red]Loaded[/red] '; alias = <parameter>"++ @pytest.mark.parametrize(+ ("topic", "body", "expected_tag"),+ [+ ("two literals", 'log.info("[" + "red]Loaded")', "[red]"),+ ("a named literal operand", 'log.info(OPENING + "red]Loaded")', "[red]"),+ ("a literal extended with +=", 'msg = "["\n msg += "red]Loaded"\n log.verbose(msg)', "[red]"),+ ("a conditional between literals", 'log.debug(("[" if flag else "(") + "red]Loaded")', "[red]"),+ ("an f-string's literal edge", 'log.debug("[" + f"red]Loaded {flag}")', "[red]"),+ ("a name rebuilt from itself", 'msg = "["\n msg = msg + "red]Loaded"\n log.debug(msg)', "[red]"),+ ],+ )+ def test_markup_split_across_a_concatenation_is_refused(self, topic: str, body: str, expected_tag: str) -> None:+ offending = _offending(f'OPENING = "["\n\ndef load(flag):\n {body}\n')+ markup_details = [breach.detail for call in offending for breach in call.breaches if breach.rule == LogCallRule.MARKUP]+ assert markup_details == [f"the message holds the markup tag `{expected_tag}`"], topic++ def test_a_value_between_two_literals_keeps_their_brackets_apart(self) -> None:+ """The guard cannot read the value, so it never joins the texts around it into a tag."""+ assert _offending('def load(alias):\n log.debug("[" + alias + "red]")\n') == []++ @pytest.mark.parametrize(+ ("topic", "body"),+ [+ ("a None title", 'log.info("Loaded", title=None)'),+ ("a None inline title", 'log.warning("Loaded", inline=None)'),+ ("a title that is None or a literal", 'log.info("Loaded", title=None if alias else "Library")'),+ ("a title bound to None or a literal", 'title = None\n if alias:\n title = "Library"\n log.info("Loaded", title=title)'),+ ],+ )+ def test_a_title_that_is_statically_none_is_no_message(self, topic: str, body: str) -> None:+ assert _offending(f"def load(alias):\n {body}\n") == [], topic++ def test_a_none_title_stays_out_of_the_signature(self) -> None:+ offending = _offending('def load(alias):\n log.info(f"Loaded {alias}", title=None)\n')+ assert [call.signature for call in offending] == ['info: f"Loaded {alias}" [f-string]']++ def test_moving_a_call_down_its_function_keeps_its_signature_and_key(self) -> None:+ """Lines never enter the identity, so an edit above a call moves nothing in the baseline."""+ before = _offending('def load(alias):\n log.info(f"Loaded {alias}")\n')+ after = _offending('def load(alias):\n prepared = True\n del prepared\n log.info(f"Loaded {alias}")\n')+ assert [(call.key, call.signature) for call in before] == [(call.key, call.signature) for call in after]+ assert before[0].lineno != after[0].linenodiff --git a/tests/unit/pipelex/cli/dev/test_log_call_guard_scopes.py b/tests/unit/pipelex/cli/dev/test_log_call_guard_scopes.pynew file mode 100644index 000000000..fccde27ae--- /dev/null+++ b/tests/unit/pipelex/cli/dev/test_log_call_guard_scopes.py@@ -0,0 +1,258 @@+from __future__ import annotations++import ast+import textwrap+from typing import TYPE_CHECKING++import pytest++from pipelex.cli.dev_cli.commands.log_call_guard import LogCallRule, OffendingCall, find_offending_calls_in_source++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++SAMPLE_PATH = "pipelex/core/sample_module.py"++#: The facade, and a module-level literal that a name resolving to the wrong scope would wrongly pass as.+HEADER = 'from pipelex import log\n\nMSG = "A fixed message"\n\n'+++def _offending(body: str) -> list[OffendingCall]:+ return find_offending_calls_in_source(source=HEADER + textwrap.dedent(body), relative_path=SAMPLE_PATH)+++def _rules(body: str) -> list[list[LogCallRule]]:+ return [[breach.rule for breach in call.breaches] for call in _offending(body)]+++class TestLogCallGuardScopes:+ def test_a_name_bound_in_an_enclosing_function_is_captured_never_the_module_s_literal(self) -> None:+ offending = _offending(+ """+ def outer(alias):+ MSG = f"Loaded {alias}"+ def inner():+ log.info(MSG)+ """+ )+ assert [[breach.rule for breach in call.breaches] for call in offending] == [[LogCallRule.NON_LITERAL]]+ assert offending[0].breaches[0].detail == "the message is `MSG`, captured from an enclosing function"++ @pytest.mark.parametrize(+ ("topic", "body", "expected"),+ [+ ("a module literal read from a method", "class Loader:\n def load(self):\n log.info(MSG)\n", []),+ (+ "a class attribute is no enclosing scope of a method",+ 'class Loader:\n MSG = f"{__name__}"\n def load(self):\n log.info(MSG)\n',+ [],+ ),+ (+ "a call in a class body reads the class's names",+ 'class Loader:\n MSG = f"{__name__}"\n log.info(MSG)\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "a lambda's free name is captured from its enclosing function",+ 'def load(alias):\n MSG = "Loaded"\n return lambda: log.info(MSG)\n',+ [[LogCallRule.NON_LITERAL]],+ ),+ (+ "a comprehension reads as part of the function it is written in",+ 'def load(items):\n message = "Loaded"\n return [log.info(message) for _item in items]\n',+ [],+ ),+ (+ "a global assignment in a function rebinds the module's name",+ 'def reset(alias):\n global MSG\n MSG = f"Loaded {alias}"\n\ndef load():\n log.info(MSG)\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "a nonlocal assignment rebinds the enclosing function's name",+ (+ 'def load(alias):\n message = "Loaded"\n def reset():\n nonlocal message\n'+ ' message = f"Loaded {alias}"\n log.info(message)\n'+ ),+ [[LogCallRule.F_STRING]],+ ),+ ],+ )+ def test_a_name_resolves_by_python_s_scoping(self, topic: str, body: str, expected: list[list[LogCallRule]]) -> None:+ assert _rules(body) == expected, topic++ @pytest.mark.parametrize(+ ("topic", "body", "expected_rule"),+ [+ ("a list comprehension target", "def load(items):\n return [log.info(MSG) for MSG in items]\n", LogCallRule.NON_LITERAL),+ ("a set comprehension target", "def load(items):\n return {log.info(MSG) for MSG in items}\n", LogCallRule.NON_LITERAL),+ ("a generator target", "def load(items):\n return list(log.info(MSG) for MSG in items)\n", LogCallRule.NON_LITERAL),+ ("a dict comprehension target", "def load(items):\n return {MSG: log.info(MSG) for MSG in items}\n", LogCallRule.NON_LITERAL),+ ("a match capture", "def load(subject):\n match subject:\n case MSG:\n log.info(MSG)\n", LogCallRule.NON_LITERAL),+ ("a match star", "def load(subject):\n match subject:\n case [*MSG]:\n log.info(MSG)\n", LogCallRule.NON_LITERAL),+ (+ "a match mapping rest",+ "def load(subject):\n match subject:\n case {**MSG}:\n log.info(MSG)\n",+ LogCallRule.NON_LITERAL,+ ),+ ("a lambda parameter", "handler = lambda MSG: log.info(MSG)\n", LogCallRule.NON_LITERAL),+ ("a function parameter", "def load(MSG):\n log.info(MSG)\n", LogCallRule.NON_LITERAL),+ ("a walrus", 'def load(alias):\n if (MSG := f"Loaded {alias}"):\n log.info(MSG)\n', LogCallRule.F_STRING),+ (+ "a walrus in a comprehension binds in its function",+ 'def load(items):\n _ = [(MSG := f"Loaded {item}") for item in items]\n log.info(MSG)\n',+ LogCallRule.F_STRING,+ ),+ ("a for target", "def load(items):\n for MSG in items:\n log.info(MSG)\n", LogCallRule.NON_LITERAL),+ ("a with target", "def load(path):\n with open(path) as MSG:\n log.info(MSG)\n", LogCallRule.NON_LITERAL),+ (+ "an except target",+ "def load(path):\n try:\n open(path)\n except OSError as MSG:\n log.info(MSG)\n",+ LogCallRule.NON_LITERAL,+ ),+ ("an import alias", "def load():\n from somewhere import thing as MSG\n log.info(MSG)\n", LogCallRule.NON_LITERAL),+ ("an unpacking", "def load(pair):\n MSG, _other = pair\n log.info(MSG)\n", LogCallRule.NON_LITERAL),+ ],+ )+ def test_every_binding_form_shadows_the_module_s_literal(self, topic: str, body: str, expected_rule: LogCallRule) -> None:+ assert _rules(body) == [[expected_rule]], topic++ @pytest.mark.parametrize(+ ("topic", "body"),+ [+ ("a subscript store", 'def load(cache):\n msg = "Loaded"\n cache[msg] = 1\n log.info(msg)\n'),+ ("an attribute store", 'def load(alias):\n msg = "Loaded"\n msg.attr = alias\n log.info(msg)\n'),+ ("an augmented subscript store", 'def load(counts):\n msg = "Loaded"\n counts[msg] += 1\n log.info(msg)\n'),+ ],+ )+ def test_an_assignment_that_only_mentions_a_name_does_not_rebind_it(self, topic: str, body: str) -> None:+ assert _offending(body) == [], topic++ @pytest.mark.parametrize(+ ("topic", "body", "expected"),+ [+ ("a literal += a literal", 'def load():\n msg = "Loaded"\n msg += " the library"\n log.info(msg)\n', []),+ ("a literal += a module literal", 'def load():\n msg = "Loaded: "\n msg += MSG\n log.info(msg)\n', []),+ ("a literal built from itself", 'def load():\n msg = "Loaded"\n msg = msg + " the library"\n log.info(msg)\n', []),+ ("a literal += a value", 'def load(alias):\n msg = "Loaded "\n msg += alias\n log.info(msg)\n', [[LogCallRule.CONCATENATION]]),+ (+ "a literal %= a value",+ 'def load(alias):\n msg = "Loaded %s"\n msg %= alias\n log.info(msg)\n',+ [[LogCallRule.PERCENT_FORMAT]],+ ),+ ("a literal *= a count", 'def load(count):\n msg = "Loaded"\n msg *= count\n log.info(msg)\n', [[LogCallRule.NON_LITERAL]]),+ ],+ )+ def test_an_augmented_assignment_is_read_by_its_operator_and_value(self, topic: str, body: str, expected: list[list[LogCallRule]]) -> None:+ assert _rules(body) == expected, topic++ @pytest.mark.parametrize(+ ("topic", "body", "expected"),+ [+ (+ "a binding after the call, before a raise",+ 'def load(alias):\n msg = "Loaded"\n log.info(msg)\n msg = f"Could not load {alias}"\n raise ValueError(msg)\n',+ [],+ ),+ ("a binding replaced on straight-line code", 'def load(alias):\n msg = f"{alias}"\n msg = "Loaded"\n log.info(msg)\n', []),+ (+ "a branch that raises brings nothing",+ (+ 'def load(alias):\n msg = "Loaded"\n if alias:\n'+ ' msg = f"Bad {alias}"\n raise ValueError(msg)\n log.info(msg)\n'+ ),+ [],+ ),+ (+ "a branch that returns brings nothing",+ 'def load(alias):\n msg = "Loaded"\n if alias:\n msg = f"Bad {alias}"\n return\n log.info(msg)\n',+ [],+ ),+ (+ "either branch of an if",+ 'def load(alias):\n if alias:\n msg = f"{alias}"\n else:\n msg = "Loaded"\n log.info(msg)\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "an if without an else keeps what came before",+ 'def load(alias):\n msg = f"{alias}"\n if alias:\n msg = "Loaded"\n log.info(msg)\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "a handler sees what the try body bound",+ (+ 'def load(alias):\n msg = "Loaded"\n try:\n msg = f"{alias}"\n'+ " open(alias)\n except OSError:\n log.info(msg)\n"+ ),+ [[LogCallRule.F_STRING]],+ ),+ (+ "a try body or its handler",+ 'def load(alias):\n try:\n msg = f"{alias}"\n except OSError:\n msg = "Failed"\n log.info(msg)\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "a match case",+ (+ 'def load(alias):\n match alias:\n case "x":\n msg = f"{alias}"\n'+ ' case _:\n msg = "Loaded"\n log.info(msg)\n'+ ),+ [[LogCallRule.F_STRING]],+ ),+ (+ "a binding later in a loop reaches an earlier read",+ 'def load(items):\n msg = "Loaded"\n for item in items:\n log.info(msg)\n msg = f"{item}"\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "a binding after a loop does not reach a read in it",+ (+ 'def load(items, alias):\n msg = "Loaded"\n for item in items:\n'+ ' log.info(msg)\n msg = f"{alias}"\n raise ValueError(msg)\n'+ ),+ [],+ ),+ (+ "a break leaves the loop with what it bound",+ 'def load(alias):\n msg = "Loaded"\n while alias:\n msg = f"{alias}"\n break\n log.info(msg)\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "a module name rebound once a function exists reaches its calls",+ 'TEXT = "Loaded"\n\ndef load():\n log.info(TEXT)\n\nTEXT = f"Loaded {__name__}"\n',+ [[LogCallRule.F_STRING]],+ ),+ (+ "a module name replaced before a function exists does not",+ 'TEXT = f"Loaded {__name__}"\nTEXT = "Loaded"\n\ndef load():\n log.info(TEXT)\n',+ [],+ ),+ (+ "a module-level call reads the module's flow",+ 'TEXT = "Loaded"\nlog.info(TEXT)\nTEXT = f"Loaded {__name__}"\n',+ [],+ ),+ ],+ )+ def test_only_the_bindings_that_can_reach_a_read_are_read(self, topic: str, body: str, expected: list[list[LogCallRule]]) -> None:+ """A binding counts when some path of the control flow carries it to the read, and never otherwise."""+ assert _rules(body) == expected, topic++ def test_each_scope_is_indexed_once_however_many_calls_read_it(self, mocker: MockerFixture) -> None:+ """The walk grows with the module, not with the module times its calls: a lookup reads an index, never the scope again."""++ def nodes_walked(*, nb_functions: int) -> int:+ # A module-level statement beside each function, so a walk of the module per lookup costs what the module holds.+ functions = "".join(+ f"VALUE_{index_function} = {index_function}\n\ndef load_{index_function}():\n log.info(MSG)\n\n"+ for index_function in range(nb_functions)+ )+ spy = mocker.spy(ast, "iter_child_nodes")+ find_offending_calls_in_source(source=HEADER + functions, relative_path=SAMPLE_PATH)+ count = spy.call_count+ mocker.stop(spy)+ return count++ small = nodes_walked(nb_functions=10)+ large = nodes_walked(nb_functions=80)+ # Eight times the functions: a linear walk is about eight times longer, a walk per lookup about sixty-four.+ assert large <= 10 * smalldiff --git a/tests/unit/pipelex/cli/dev/test_log_call_trusted_baseline.py b/tests/unit/pipelex/cli/dev/test_log_call_trusted_baseline.pynew file mode 100644index 000000000..7790f28bb--- /dev/null+++ b/tests/unit/pipelex/cli/dev/test_log_call_trusted_baseline.py@@ -0,0 +1,195 @@+from __future__ import annotations++import io+from pathlib import Path+from typing import TYPE_CHECKING++import pytest+from rich.console import Console++from pipelex.cli.dev_cli.commands import check_log_calls_cmd as cmd_mod+from pipelex.cli.dev_cli.commands.check_log_calls_cmd import check_log_calls_cmd+from pipelex.cli.dev_cli.commands.log_call_guard import (+ BASELINE_FILE,+ GUARD_MODULE_FILE,+ LogCallGuardError,+ build_baseline,+ collect_offending_calls,+ load_trusted_baseline,+ render_baseline,+ resolve_merge_base,+)++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++ from tests.unit.pipelex.cli.dev.conftest import GitRepo++#: Wide enough that no assertion below depends on where Rich decides to wrap.+CONSOLE_WIDTH = 400++SAMPLE_MODULE = "pipelex/core/sample_module.py"+API_MODULE = "api/pipelex_api/routes.py"++CONVERTED = 'from pipelex import log\n\ndef load(alias):\n log.warning("Loaded a dependency", fields={"dependency_alias": alias})\n'+INTERPOLATED = 'from pipelex import log\n\ndef load(alias):\n log.warning(f"Loaded {alias}")\n'+LISTED_SIGNATURE = 'warning: f"Loaded {alias}" [f-string]'+++class TestLogCallTrustedBaseline:+ @pytest.fixture+ def console_buffer(self, mocker: MockerFixture) -> io.StringIO:+ buffer = io.StringIO()+ mocker.patch.object(cmd_mod, "get_console", return_value=Console(file=buffer, force_terminal=False, width=CONSOLE_WIDTH))+ return buffer++ @staticmethod+ def _write_tree(*, repo: GitRepo, sample_source: str, with_guard: bool = True, with_baseline: bool = True) -> None:+ """A tree the guard can scan: both scan roots, the guard's own module, and the baseline that matches the sample."""+ repo.write(SAMPLE_MODULE, content=sample_source)+ repo.write(API_MODULE, content=CONVERTED)+ if with_guard:+ repo.write(GUARD_MODULE_FILE.as_posix(), content="# the guard\n")+ if with_baseline:+ offending = collect_offending_calls(repo_root=repo.root)+ repo.write(BASELINE_FILE.as_posix(), content=render_baseline(baseline=build_baseline(offending=offending)))++ def test_the_trusted_baseline_is_read_at_the_revision(self, git_repo: GitRepo) -> None:+ self._write_tree(repo=git_repo, sample_source=INTERPOLATED)+ git_repo.add_all()+ git_repo.commit("guard with a baseline")+ assert load_trusted_baseline(repo_root=git_repo.root, ref="HEAD") == {f"{SAMPLE_MODULE}::load": [LISTED_SIGNATURE]}++ @pytest.mark.parametrize(+ ("topic", "with_guard", "expected"),+ [+ ("a revision that runs the guard has an empty baseline", True, {}),+ ("a revision before the guard has none to compare with", False, None),+ ],+ )+ def test_a_revision_without_the_baseline_file(+ self, git_repo: GitRepo, topic: str, with_guard: bool, expected: dict[str, list[str]] | None+ ) -> None:+ self._write_tree(repo=git_repo, sample_source=CONVERTED, with_guard=with_guard, with_baseline=False)+ git_repo.add_all()+ git_repo.commit("no baseline")+ assert load_trusted_baseline(repo_root=git_repo.root, ref="HEAD") == expected, topic++ def test_a_revision_that_does_not_resolve_is_an_error(self, git_repo: GitRepo) -> None:+ self._write_tree(repo=git_repo, sample_source=CONVERTED)+ git_repo.add_all()+ git_repo.commit("guard")+ with pytest.raises(LogCallGuardError, match="does not resolve to a commit"):+ load_trusted_baseline(repo_root=git_repo.root, ref="no-such-branch")++ def test_the_merge_base_resolves_or_is_none(self, git_repo: GitRepo) -> None:+ self._write_tree(repo=git_repo, sample_source=CONVERTED)+ git_repo.add_all()+ git_repo.commit("base")+ base_commit = git_repo.git("rev-parse", "HEAD").strip()+ git_repo.git("branch", "base")+ git_repo.write("pipelex/core/other_module.py", content=CONVERTED)+ git_repo.add_all()+ git_repo.commit("topic")+ assert resolve_merge_base(repo_root=git_repo.root, ref="base") == base_commit+ assert resolve_merge_base(repo_root=git_repo.root, ref="no-such-branch") is None++ def test_adding_a_violation_with_its_exemption_fails_against_the_base(+ self, git_repo: GitRepo, console_buffer: io.StringIO, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """The tree and its baseline agree, so the tree check alone passes; the comparison with the base refuses the new entry."""+ self._write_tree(repo=git_repo, sample_source=CONVERTED)+ git_repo.add_all()+ git_repo.commit("base, clean")+ self._write_tree(repo=git_repo, sample_source=INTERPOLATED)+ monkeypatch.chdir(git_repo.root)++ check_log_calls_cmd(quiet=True)+ assert "✓ Log-call check: PASSED (1 baselined call(s) left)" in console_buffer.getvalue()++ with pytest.raises(SystemExit) as exit_info:+ check_log_calls_cmd(quiet=True, against="HEAD")++ assert exit_info.value.code == 1+ output = console_buffer.getvalue()+ assert "1 baseline signature(s) were added since 'HEAD'" in output+ assert f"{SAMPLE_MODULE}::load listed 1 time(s), 0 at the base" in output+ assert LISTED_SIGNATURE in output++ def test_removing_an_entry_passes_against_the_base(self, git_repo: GitRepo, console_buffer: io.StringIO, monkeypatch: pytest.MonkeyPatch) -> None:+ self._write_tree(repo=git_repo, sample_source=INTERPOLATED)+ git_repo.add_all()+ git_repo.commit("base, one baselined call")+ self._write_tree(repo=git_repo, sample_source=CONVERTED)+ monkeypatch.chdir(git_repo.root)++ check_log_calls_cmd(quiet=True, against="HEAD")++ assert "✓ Log-call check: PASSED (0 baselined call(s) left, none added since 'HEAD')" in console_buffer.getvalue()++ def test_the_merge_base_comparison_runs_when_it_resolves(+ self, git_repo: GitRepo, console_buffer: io.StringIO, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ self._write_tree(repo=git_repo, sample_source=CONVERTED)+ git_repo.add_all()+ git_repo.commit("base, clean")+ git_repo.git("branch", "base")+ self._write_tree(repo=git_repo, sample_source=INTERPOLATED)+ git_repo.add_all()+ git_repo.commit("topic, with an exemption it gave itself")+ monkeypatch.chdir(git_repo.root)++ with pytest.raises(SystemExit) as exit_info:+ check_log_calls_cmd(quiet=True, against_merge_base="base")++ assert exit_info.value.code == 1+ assert "were added since the merge base with base" in console_buffer.getvalue()++ @pytest.mark.parametrize(+ ("topic", "against_merge_base", "with_guard", "expected_notice"),+ [+ ("no merge base resolves", "no-such-branch", True, "no merge base of HEAD and 'no-such-branch' resolves"),+ ("the guard does not exist at the base", "base", False, "the log-call guard does not exist at the merge base with base"),+ ],+ )+ def test_a_comparison_that_cannot_run_says_so_and_checks_the_tree(+ self,+ git_repo: GitRepo,+ console_buffer: io.StringIO,+ monkeypatch: pytest.MonkeyPatch,+ topic: str,+ against_merge_base: str,+ with_guard: bool,+ expected_notice: str,+ ) -> None:+ self._write_tree(repo=git_repo, sample_source=CONVERTED, with_guard=with_guard, with_baseline=with_guard)+ git_repo.add_all()+ git_repo.commit("base")+ git_repo.git("branch", "base")+ self._write_tree(repo=git_repo, sample_source=INTERPOLATED)+ monkeypatch.chdir(git_repo.root)++ check_log_calls_cmd(quiet=True, against_merge_base=against_merge_base)++ output = console_buffer.getvalue()+ assert expected_notice in output, topic+ assert "✓ Log-call check: PASSED (1 baselined call(s) left)" in output, topic++ def test_an_unresolvable_trusted_revision_fails_the_check(+ self, git_repo: GitRepo, console_buffer: io.StringIO, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ self._write_tree(repo=git_repo, sample_source=CONVERTED)+ git_repo.add_all()+ git_repo.commit("base")+ monkeypatch.chdir(git_repo.root)++ with pytest.raises(SystemExit) as exit_info:+ check_log_calls_cmd(quiet=True, against="no-such-branch")++ assert exit_info.value.code == 1+ assert "The revision 'no-such-branch' the log-call baseline is compared with does not resolve to a commit" in console_buffer.getvalue()++ def test_the_guard_module_path_names_this_guard(self) -> None:+ """A revision is read as running the guard when it holds this file, so a move of the module must move the constant."""+ repo_root = next(parent for parent in Path(__file__).resolve().parents if parent.name == "tests").parent+ assert (repo_root / GUARD_MODULE_FILE).resolve() == Path(cmd_mod.__file__).resolve().parent / "log_call_guard.py"diff --git a/tests/unit/pipelex/libraries/test_mthds_version_warning.py b/tests/unit/pipelex/libraries/test_mthds_version_warning.pyindex 3ca294edc..c347b19cc 100644--- a/tests/unit/pipelex/libraries/test_mthds_version_warning.py+++ b/tests/unit/pipelex/libraries/test_mthds_version_warning.py@@ -6,6 +6,7 @@ from pytest_mock import MockerFixturefrom pipelex.libraries.library_factory import LibraryFactoryfrom pipelex.libraries.library_manager import LibraryManager+from pipelex.tools.log.error_fields import ERROR_MESSAGE_FIELD, ERROR_TYPE_FIELDclass TestMthdsVersionWarning:@@ -23,10 +24,14 @@ class TestMthdsVersionWarning:)mock_log.warning.assert_called_once()- warning_msg = mock_log.warning.call_args[0][0]- assert "github.com/org/pkg" in warning_msg- assert "^2.0.0" in warning_msg- assert "1.0.0" in warning_msg+ assert mock_log.warning.call_args.args == (+ "A package requires another MTHDS standard version than this runtime's; some features may not work correctly",+ )+ assert mock_log.warning.call_args.kwargs["fields"] == {+ "package_address": "github.com/org/pkg",+ "mthds_version_constraint": "^2.0.0",+ "mthds_standard_version": "1.0.0",+ }def test_no_warning_when_version_satisfied(self, mocker: MockerFixture) -> None:"""No warning emitted when current MTHDS standard version satisfies the constraint."""@@ -52,8 +57,12 @@ class TestMthdsVersionWarning:)mock_log.warning.assert_called_once()- warning_msg = mock_log.warning.call_args[0][0]- assert "Could not parse" in warning_msg+ assert mock_log.warning.call_args.args == ("The mthds_version constraint of a package could not be parsed",)+ fields = mock_log.warning.call_args.kwargs["fields"]+ assert fields["package_address"] == "github.com/org/pkg"+ assert fields["mthds_version_constraint"] == ">>>garbage"+ assert fields[ERROR_TYPE_FIELD]+ assert fields[ERROR_MESSAGE_FIELD]def test_warning_emitted_for_dependency_mthds_version(self, mocker: MockerFixture, tmp_path: Path) -> None:"""Warning emitted when a dependency manifest has unsatisfied mthds_version."""@@ -89,6 +98,10 @@ class TestMthdsVersionWarning:)# Verify a version warning was emitted for the dependency address- warning_calls = [call_args[0][0] for call_args in mock_log.warning.call_args_list]- dep_version_warnings = [msg for msg in warning_calls if "github.com/org/dep-pkg" in msg and "^2.0.0" in msg]+ warning_fields = [call_args.kwargs.get("fields", {}) for call_args in mock_log.warning.call_args_list]+ dep_version_warnings = [+ fields+ for fields in warning_fields+ if fields.get("package_address") == "github.com/org/dep-pkg" and fields.get("mthds_version_constraint") == "^2.0.0"+ ]assert len(dep_version_warnings) >= 1diff --git a/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_announcement.py b/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_announcement.pyindex f107ff97b..e9835ef01 100644--- a/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_announcement.py+++ b/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_announcement.py@@ -22,6 +22,7 @@ from rich.logging import RichHandlerfrom rich.text import Textfrom typing_extensions import override+from pipelex.cli.dev_cli.commands.log_call_guard import find_markup_tagsfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCodefrom pipelex.core.memory.working_memory_factory import WorkingMemoryFactory@@ -39,7 +40,6 @@ from pipelex.tools.log.log_config import HighlighterName, RichLogConfigfrom pipelex.tools.log.log_fields import LAYOUT_MARKfrom pipelex.tools.log.log_formatter import EmojiLogFormatterfrom tests.helpers.console_log_rendering import package_log_config-from tests.helpers.rich_markup import find_markup_tagsif TYPE_CHECKING:from pipelex.core.memory.working_memory import WorkingMemorydiff --git a/tests/unit/pipelex/tools/test_log_console_fields.py b/tests/unit/pipelex/tools/test_log_console_fields.pyindex 10a97d1ff..aba6d3ba6 100644--- a/tests/unit/pipelex/tools/test_log_console_fields.py+++ b/tests/unit/pipelex/tools/test_log_console_fields.py@@ -6,7 +6,15 @@ from typing import TYPE_CHECKING, Anyimport pytest-from pipelex.tools.log.console_fields import FIELD_KEY_STYLE, FIELD_STYLES, FIELD_VALUE_MAX_LENGTH, TRUNCATION_MARK, UNMAPPED_FIELD_STYLE+from pipelex.tools.log.console_fields import (+ ERROR_MESSAGE_MAX_LENGTH,+ FIELD_KEY_STYLE,+ FIELD_STYLES,+ FIELD_VALUE_MAX_LENGTH,+ TRUNCATION_MARK,+ UNMAPPED_FIELD_STYLE,+)+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.log.log_fields import (COLLIDING_FIELD_PREFIX,FIELD_NAMES_MARK,@@ -135,6 +143,29 @@ class TestConsoleFields:assert f"excerpt={'x' * (FIELD_VALUE_MAX_LENGTH - len(TRUNCATION_MARK))}{TRUNCATION_MARK}" in renderedassert "x" * FIELD_VALUE_MAX_LENGTH not in rendered+ def test_an_error_message_gets_a_generous_cut_while_other_fields_stay_cut_short(self) -> None:+ """The cause chain of an unresolved package outgrows the common cut, and a fragment ending in an ellipsis loses the diagnosis."""+ causes = "PackageFetchError: could not clone 'github.com/acme/methods' <- GitError: " + "fatal: repository not found; " * 6+ text = rendered_text(+ record=record_with_fields(+ message="A method package could not be resolved",+ extra={"package_address": "github.com/acme/methods", **error_fields(exc=RuntimeError("boom"), text=causes), "excerpt": "x" * 500},+ ),+ )++ quoted_causes = '"' + causes.replace('"', '\\"') + '"'+ assert f"error.message={quoted_causes}" in text.plain+ assert TRUNCATION_MARK + " excerpt=" not in text.plain+ assert f"excerpt={'x' * (FIELD_VALUE_MAX_LENGTH - len(TRUNCATION_MARK))}{TRUNCATION_MARK}" in text.plain++ def test_an_error_message_past_its_own_cut_is_cut_short(self) -> None:+ """A dependency's raw output, a validation error's every line, never floods the console."""+ flood = "y" * (2 * ERROR_MESSAGE_MAX_LENGTH)+ text = rendered_text(record=record_with_fields(message="A method package could not be resolved", extra=error_fields(exc=RuntimeError(flood))))++ assert text.plain.endswith(f"error.message={'y' * (ERROR_MESSAGE_MAX_LENGTH - len(TRUNCATION_MARK))}{TRUNCATION_MARK}")+ assert "y" * ERROR_MESSAGE_MAX_LENGTH not in text.plain+def test_a_field_is_styled_by_its_name_and_a_field_outside_the_map_is_dimmed(self) -> None:text = rendered_text(record=record_with_fields(diff --git a/tests/unit/pipelex/tools/test_log_error_fields.py b/tests/unit/pipelex/tools/test_log_error_fields.pynew file mode 100644index 000000000..6def58a0e--- /dev/null+++ b/tests/unit/pipelex/tools/test_log_error_fields.py@@ -0,0 +1,70 @@+from __future__ import annotations++import io+import json+import logging+from typing import TYPE_CHECKING++import pytest++from pipelex.system.configuration.config_loader import ConfigLoader+from pipelex.tools.log.error_fields import ERROR_MESSAGE_FIELD, ERROR_TYPE_FIELD, error_fields+from pipelex.tools.log.json_log_sink import EXCEPTION_KEY, LOGGER_KEY, MESSAGE_KEY, JsonLogSink+from pipelex.tools.log.log import Log+from pipelex.tools.log.log_config import LogConfig+from pipelex.tools.misc.toml_utils import load_toml_from_path++if TYPE_CHECKING:+ from collections.abc import Iterator+++class _ManifestParseError(ValueError):+ pass+++class TestLogErrorFields:+ @pytest.mark.parametrize(+ ("topic", "exc", "text", "expected"),+ [+ ("the exception's own text", _ManifestParseError("line 3: expected a table"), None, ("_ManifestParseError", "line 3: expected a table")),+ (+ "the cause chain instead",+ KeyError("dep"),+ "dep: not found; git: repository not found",+ ("KeyError", "dep: not found; git: repository not found"),+ ),+ ("an exception with no text", RuntimeError(), None, ("RuntimeError", "")),+ ],+ )+ def test_the_fields_name_the_class_and_carry_the_text(self, topic: str, exc: BaseException, text: str | None, expected: tuple[str, str]) -> None:+ assert error_fields(exc=exc, text=text) == {ERROR_TYPE_FIELD: expected[0], ERROR_MESSAGE_FIELD: expected[1]}, topic++ @pytest.fixture+ def json_buffer(self, caplog: pytest.LogCaptureFixture) -> Iterator[tuple[Log, io.StringIO]]:+ """A fresh ``Log`` with the json sink installed on a buffer, torn down so the root logger is left as found."""+ caplog.set_level(logging.INFO, logger=__name__)+ config_dict = load_toml_from_path(ConfigLoader().pipelex_root_dir / "pipelex.toml")+ buffer = io.StringIO()+ fresh = Log()+ fresh.configure(log_config=LogConfig.model_validate(config_dict["runtime"]["log"]))+ fresh.install_sink(JsonLogSink(stream=buffer))+ try:+ yield fresh, buffer+ finally:+ fresh.reset()++ def test_a_handled_exception_reaches_a_structured_sink_as_two_keys_and_no_traceback(self, json_buffer: tuple[Log, io.StringIO]) -> None:+ """The dotted names are nobody's attribute, so they land unprefixed, and a warning carries no exception."""+ fresh, buffer = json_buffer+ error_text = "line 3: expected a table"+ try:+ raise _ManifestParseError(error_text)+ except _ManifestParseError as exc:+ fresh.warning("The package's METHODS.toml could not be parsed", fields=error_fields(exc=exc))+ lines = [json.loads(line) for line in buffer.getvalue().splitlines() if line]+ own_lines = [line for line in lines if line[LOGGER_KEY] == __name__]+ assert len(own_lines) == 1+ assert own_lines[0][MESSAGE_KEY] == "The package's METHODS.toml could not be parsed"+ assert own_lines[0][ERROR_TYPE_FIELD] == "_ManifestParseError"+ assert own_lines[0][ERROR_MESSAGE_FIELD] == "line 3: expected a table"+ assert EXCEPTION_KEY not in own_lines[0]