Skip to content

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.

Decouple pipelex-tools, add plxt tests, rule sync (#791)

Louis Choquelae86f057b828
diff --git a/CLAUDE.md b/CLAUDE.md
index d96e829a3..16df444c9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -30,7 +30,9 @@
### Running Tests
- After you're finished making code changes, you must always run tests using `make agent-test`.
+ After making code changes, run **targeted tests** based on what you changed. See `tests/CLAUDE.md` for the source-to-test mapping and the pytest command template.
+
+ Fall back to the full suite when changes are broad (3+ areas), touch shared infrastructure, or when preparing a release/push/commit to remote:
```bash
make agent-test
@@ -144,7 +146,7 @@ This document outlines the core coding standards, best practices, and quality co
#### **Imports at the top of the file**
- - Import all necessary libraries at the top of the file
+ - Avoid as much as possible import statements outside of a module's top-level scope.
- Do not import libraries in functions or classes unless in very specific cases, to be discussed with the user, as they would required a `# noqa: ...` comment to pass linting
- Do not bother with ordering the imports or removing unused imports, our Ruff linter will handle it for us.
- `if TYPE_CHECKING:` blocks must always be the **last** block in the imports section, placed after all regular imports.
diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.py
index bc54648c0..0696b1faf 100644
--- a/pipelex/cli/agent_cli/commands/agent_output.py
+++ b/pipelex/cli/agent_cli/commands/agent_output.py
@@ -46,7 +46,7 @@ AGENT_ERROR_HINTS: dict[str, str] = {
"GatewayTermsNotAcceptedError": "Run 'pipelex init config' to accept gateway terms, or disable pipelex_gateway in backends.toml",
"GatewayApiKeyMissingError": "Set the PIPELEX_GATEWAY_API_KEY environment variable, or disable pipelex_gateway in backends.toml",
"GatewayDoNotTrackConflictError": "Unset the DO_NOT_TRACK environment variable, or disable pipelex_gateway in backends.toml",
- "BinaryNotFoundError": "Install pipelex-tools: pip install pipelex-tools",
+ "BinaryNotFoundError": "Install pipelex-tools: uv tool install pipelex-tools",
"RemoteConfigFetchError": "Check internet connection and firewall settings, or disable pipelex_gateway in backends.toml",
"RemoteConfigValidationError": (
"This is a server-side issue; report it on Discord/GitHub. Disable pipelex_gateway in backends.toml as a workaround"
diff --git a/pipelex/cli/agent_cli/commands/plxt_passthrough.py b/pipelex/cli/agent_cli/commands/plxt_passthrough.py
index 9bd2ca0a0..dc8474e1f 100644
--- a/pipelex/cli/agent_cli/commands/plxt_passthrough.py
+++ b/pipelex/cli/agent_cli/commands/plxt_passthrough.py
@@ -11,8 +11,8 @@ from pipelex.cli.agent_cli.commands.agent_output import agent_error
def run_plxt(subcommand: str, file_path: str) -> None:
"""Execute a plxt subcommand with full stdin/stdout/stderr passthrough.
- Locates the plxt binary (guaranteed co-installed via pipelex-tools dependency),
- runs ``plxt <subcommand> <file_path>``, and exits with the same return code.
+ Locates the plxt binary, runs ``plxt <subcommand> <file_path>``,
+ and exits with the same return code.
Args:
subcommand: The plxt subcommand to run (e.g., "fmt", "lint").
@@ -21,7 +21,7 @@ def run_plxt(subcommand: str, file_path: str) -> None:
plxt_path = shutil.which("plxt")
if plxt_path is None:
agent_error(
- message="plxt binary not found. It should be installed as part of pipelex-tools. Try: pip install pipelex-tools",
+ message="plxt binary not found. Install via: uv tool install pipelex-tools",
error_type="BinaryNotFoundError",
)
diff --git a/pyproject.toml b/pyproject.toml
index efa44ac3a..b50291b77 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,7 +36,6 @@ dependencies = [
"opentelemetry-semantic-conventions",
"opentelemetry-sdk",
"pillow>=11.2.1",
- "pipelex-tools>=0.3.2", # plxt CLI for MTHDS/TOML/PLX formatting & linting, needed by client projects too
"polyfactory>=2.21.0",
"portkey-ai>=2.1.0",
"posthog>=6.7.0",
@@ -87,6 +86,7 @@ dev = [
"boto3-stubs>=1.35.24",
"moto[s3]>=5.0.0",
"mypy==1.19.1",
+ "pipelex-tools>=0.3.2",
"pyright==1.1.408",
"pylint==4.0.4",
"pytest>=9.0.2",
diff --git a/tests/CLAUDE.md b/tests/CLAUDE.md
new file mode 100644
index 000000000..71b215cd7
--- /dev/null
+++ b/tests/CLAUDE.md
@@ -0,0 +1,64 @@
+# Targeted Test Guide
+
+Instead of running the full suite (`make agent-test`) every time, run only the tests relevant to what you changed.
+
+## Command template
+
+```bash
+.venv/bin/pytest -n auto \
+ -m "(dry_runnable or not (inference or llm or img_gen or extract or search)) and not pipelex_api" \
+ -o log_level=WARNING --tb=short -q \
+ <paths>
+```
+
+Replace `<paths>` with the test directories from the mapping below. Concatenate paths when multiple source areas are touched.
+
+## Source-to-test mapping
+
+| Changed source | Test paths to run |
+|---|---|
+| `pipelex/builder/` | `tests/unit/pipelex/builder/ tests/integration/pipelex/builder/` |
+| `pipelex/cli/` | `tests/unit/pipelex/cli/ tests/integration/pipelex/cli/ tests/e2e/pipelex/cli/` |
+| `pipelex/cogt/` | `tests/unit/pipelex/cogt/ tests/integration/pipelex/cogt/` |
+| `pipelex/core/` | `tests/unit/pipelex/core/ tests/integration/pipelex/core/ tests/integration/pipelex/pipes/` |
+| `pipelex/graph/` | `tests/unit/pipelex/graph/ tests/e2e/pipelex/graph/` |
+| `pipelex/kit/` | `tests/unit/pipelex/kit/ tests/integration/pipelex/kit/` |
+| `pipelex/language/` | `tests/unit/pipelex/language/ tests/integration/pipelex/language/` |
+| `pipelex/libraries/` | `tests/unit/pipelex/libraries/ tests/integration/pipelex/libraries/` |
+| `pipelex/pipe_controllers/` | `tests/unit/pipelex/pipe_controllers/ tests/integration/pipelex/pipes/` |
+| `pipelex/pipe_operators/` | `tests/unit/pipelex/pipe_operators/ tests/integration/pipelex/pipes/` |
+| `pipelex/pipe_run/` | `tests/unit/pipelex/pipe_run/ tests/integration/pipelex/pipes/` |
+| `pipelex/pipeline/` | `tests/integration/pipelex/pipeline/` |
+| `pipelex/plugins/` | `tests/unit/pipelex/plugins/ tests/integration/pipelex/plugins/` |
+| `pipelex/system/` | `tests/unit/pipelex/system/ tests/integration/pipelex/system/` |
+| `pipelex/temporal/` | `tests/unit/pipelex/temporal/ tests/integration/pipelex/temporal/` |
+| `pipelex/tools/` | `tests/unit/pipelex/tools/ tests/integration/pipelex/tools/` |
+
+Note: `pipe_controllers/`, `pipe_operators/`, and `pipe_run/` share integration tests at `tests/integration/pipelex/pipes/` -- deduplicate the path when multiple of these areas are touched.
+
+## Cross-cutting triggers
+
+Add these to any targeted run when applicable:
+
+- **Config TOML changes** (`pipelex/pipelex.toml`, `pipelex/kit/configs/`): also run `make tb` (boot test)
+- **`.mthds` file changes**: also add `tests/unit/pipelex/builder/ tests/integration/pipelex/builder/ tests/integration/pipelex/pipes/`
+- **Test fixtures changed** (`tests/data/`, `tests/cases/`): also run tests that import from those fixtures
+
+## When to run full `make agent-test`
+
+Fall back to the full suite when:
+
+- Changes span 3+ source areas from the mapping above
+- Changes touch `pyproject.toml`, `tests/conftest.py`, or `tests/helpers/`
+- Changes touch root-level modules: `pipelex/__init__.py`, `pipelex/hub.py`, `pipelex/types.py`
+- Changes touch `pipelex/system/configuration/` (config loading affects everything)
+- Refactors touching base exceptions or shared base classes
+- Preparing a release, a push, or a commit intended for remote (e.g. `/release`, `/commit-push`, `/ship`, or when the context makes it obvious the work is about to land)
+
+## Quick reference
+
+| Command | When to use |
+|---|---|
+| `make tb` | Config/TOML-only changes (boot sanity check) |
+| `make agent-check` | Always run after code changes (linting, formatting, type checking) |
+| `make agent-test` | Full suite fallback for broad changes |
diff --git a/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py b/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py
new file mode 100644
index 000000000..2afe24c18
--- /dev/null
+++ b/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py
@@ -0,0 +1,121 @@
+"""Unit tests for plxt passthrough, fmt_cmd, and lint_cmd."""
+
+from __future__ import annotations
+
+import json
+import subprocess # noqa: S404
+from typing import TYPE_CHECKING
+
+import pytest
+import typer
+
+from pipelex.cli.agent_cli.commands.fmt_cmd import fmt_cmd
+from pipelex.cli.agent_cli.commands.lint_cmd import lint_cmd
+from pipelex.cli.agent_cli.commands.plxt_passthrough import run_plxt
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+
+class TestPlxtPassthrough:
+ """Tests for run_plxt(), fmt_cmd(), and lint_cmd() delegation to the plxt binary."""
+
+ def test_run_plxt_raises_binary_not_found_error_when_plxt_missing(
+ self,
+ mocker: MockerFixture,
+ capsys: pytest.CaptureFixture[str],
+ ) -> None:
+ """run_plxt exits with code 1 and BinaryNotFoundError when plxt is not on PATH."""
+ mocker.patch("shutil.which", return_value=None)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ run_plxt("fmt", "file.mthds")
+
+ assert exc_info.value.exit_code == 1
+ parsed = json.loads(capsys.readouterr().err)
+ assert parsed["error_type"] == "BinaryNotFoundError"
+
+ def test_error_message_references_uv_tool_install(
+ self,
+ mocker: MockerFixture,
+ capsys: pytest.CaptureFixture[str],
+ ) -> None:
+ """Error message tells the user how to install pipelex-tools."""
+ mocker.patch("shutil.which", return_value=None)
+
+ with pytest.raises(typer.Exit):
+ run_plxt("lint", "file.mthds")
+
+ parsed = json.loads(capsys.readouterr().err)
+ assert "uv tool install pipelex-tools" in parsed["message"]
+
+ @pytest.mark.parametrize(
+ ("topic", "exit_code"),
+ [
+ ("success", 0),
+ ("general failure", 1),
+ ("custom exit code", 42),
+ ],
+ )
+ def test_run_plxt_propagates_exit_code(
+ self,
+ mocker: MockerFixture,
+ topic: str, # noqa: ARG002
+ exit_code: int,
+ ) -> None:
+ """run_plxt propagates the subprocess exit code via typer.Exit."""
+ mocker.patch("shutil.which", return_value="/usr/bin/plxt")
+ mocker.patch(
+ "subprocess.run",
+ return_value=subprocess.CompletedProcess(args=[], returncode=exit_code),
+ )
+
+ with pytest.raises(typer.Exit) as exc_info:
+ run_plxt("fmt", "file.mthds")
+
+ assert exc_info.value.exit_code == exit_code
+
+ def test_subprocess_args_passed_correctly(
+ self,
+ mocker: MockerFixture,
+ ) -> None:
+ """run_plxt passes [plxt_path, subcommand, file_path] to subprocess.run."""
+ mocker.patch("shutil.which", return_value="/usr/bin/plxt")
+ mock_run = mocker.patch(
+ "subprocess.run",
+ return_value=subprocess.CompletedProcess(args=[], returncode=0),
+ )
+
+ with pytest.raises(typer.Exit):
+ run_plxt("fmt", "/path/to/file.mthds")
+
+ mock_run.assert_called_once_with(
+ ["/usr/bin/plxt", "fmt", "/path/to/file.mthds"],
+ check=False,
+ )
+
+ def test_fmt_cmd_delegates_to_plxt_with_fmt_subcommand(
+ self,
+ mocker: MockerFixture,
+ ) -> None:
+ """fmt_cmd calls run_plxt with 'fmt' subcommand."""
+ mock_run_plxt = mocker.patch(
+ "pipelex.cli.agent_cli.commands.fmt_cmd.run_plxt",
+ )
+
+ fmt_cmd("some/file.mthds")
+
+ mock_run_plxt.assert_called_once_with("fmt", "some/file.mthds")
+
+ def test_lint_cmd_delegates_to_plxt_with_lint_subcommand(
+ self,
+ mocker: MockerFixture,
+ ) -> None:
+ """lint_cmd calls run_plxt with 'lint' subcommand."""
+ mock_run_plxt = mocker.patch(
+ "pipelex.cli.agent_cli.commands.lint_cmd.run_plxt",
+ )
+
+ lint_cmd("some/file.mthds")
+
+ mock_run_plxt.assert_called_once_with("lint", "some/file.mthds")
diff --git a/uv.lock b/uv.lock
index aef707837..65260c78d 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3470,7 +3470,6 @@ dependencies = [
{ name = "opentelemetry-sdk" },
{ name = "opentelemetry-semantic-conventions" },
{ name = "pillow" },
- { name = "pipelex-tools" },
{ name = "polyfactory" },
{ name = "portkey-ai" },
{ name = "posthog" },
@@ -3500,6 +3499,7 @@ dev = [
{ name = "boto3-stubs" },
{ name = "moto", extra = ["s3"] },
{ name = "mypy" },
+ { name = "pipelex-tools" },
{ name = "pylint" },
{ name = "pyright" },
{ name = "pytest" },
@@ -3597,7 +3597,7 @@ requires-dist = [
{ name = "opentelemetry-sdk" },
{ name = "opentelemetry-semantic-conventions" },
{ name = "pillow", specifier = ">=11.2.1" },
- { name = "pipelex-tools", specifier = ">=0.3.2" },
+ { name = "pipelex-tools", marker = "extra == 'dev'", specifier = ">=0.3.2" },
{ name = "polyfactory", specifier = ">=2.21.0" },
{ name = "portkey-ai", specifier = ">=2.1.0" },
{ name = "posthog", specifier = ">=6.7.0" },