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.
Run a method by address: MethodRef grammar, fetch-at-tag, manifest-identity location, bounds, structures refusal (Phase 1) (#1160)
Louis Choquele84ab2c30a13
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex d010e2e6d..49e69244a 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:c3043b7ae643783145bc6b481ead8e5c866c80017fff0d339e6aaa052f148b8b"+digest = "sha256:ff4d5a366ab260fa3f93c01df71d949514a8b56549201ba84f8f1b827f9c4395"reviewed_by = "Louis Choquel"-reviewed_at = "2026-08-25T09:27:54Z"-rationale = "The bare CLI's validate bundle now echoes its advisory warnings before the strict pending-signature gate rather than after it, matching validate --all. Reviewed both targets: docs/tools/cli/validate.md said the warnings print beside the success message, which is no longer where they appear and hid the case that motivated the change, so its Advisory Warnings section now states the ordering and that a bundle with an unimplemented placeholder still shows them while exiting non-zero. The agent-CLI contract doc needed no ordering change (its envelope is JSON) but its composition-point sentence was overstating the channel scope and now says advisory-bearing, naming the surfaces that carry none. No command, option, argument or exit code moved."+reviewed_at = "2026-08-29T00:19:01Z"+rationale = "Docstring/help-text only: the run method command's help now names the address form and adds an address example; the docs pages were already updated in this same change and stay accurate."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -30,7 +30,7 @@ rationale = "The bare CLI's validate bundle now echoes its advisory warnings bef"pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:d37826d96099028a1ad5dbc5cbf8ce0cfdb01e30""pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:7e19284687b334c684fb03381a8d9d20af1aa152""pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:43ac0fe0887f5f31144df4e4973a1ab1d0dec166"-"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:b0839083b096b5f5a07844ca35cc8e44c68f74fa"+"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:80b08588fcde09e3a903b5bb7c774fc03d164d86""pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:a5cf89c89d5e2e84cc7b817ec184e8dc9e92b781""pipelex/cli/agent_cli/commands/lint_cmd.py" = "blob:91ad9cb4d618ba4c0b7da366cde2f74f38d350df""pipelex/cli/agent_cli/commands/migrate_cmd.py" = "blob:ce733b78df03e65c3c8a10d46b27b57c05ec054c"@@ -43,14 +43,14 @@ rationale = "The bare CLI's validate bundle now echoes its advisory warnings bef"pipelex/cli/agent_cli/commands/run/_run_core_api.py" = "blob:78a27e0ba91e6bbf99c11caedb29ad4cf20ac78b""pipelex/cli/agent_cli/commands/run/app.py" = "blob:64b2ecc02007cda11b526d8d3fc139593875dd9d""pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:daf6207146c0ea41fe34bb272ed51350208af790"-"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:1115f848865ecd217f0f3e3ae9776840d5842894"+"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:577f5b301de7de5cec263ac0af04d82c317992a2""pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:df5e7f80a328932ffde901eda8d0585d009678ad""pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:4bc7f4e91ddb3900a75356f8f8e6ba5a586a3690""pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:6e9e8488573fe17d7769608e299879a092ceaf6c""pipelex/cli/agent_cli/commands/validate/app.py" = "blob:d2d0ed19288c2d1c25be1650dd962189fcdb3b86""pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:3207973c194b096ed5c6ec2d3a955c417789e019"-"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:985226bdaf005a41f8c9fa7559485b67cb1b3d19"+"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:27d0e4b3f3550bd6352356abe06bc863a0255260""pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:7c15cf5a7341b774baad2f14540acbef8daebf76""pipelex/cli/bundle_target_resolution.py" = "blob:8dccc50b700b877968ed1b2c1c3652ab1c32e956""pipelex/cli/cli_factory.py" = "blob:1f859ab3b995e1a67e5fdc812a168d56c338e970"@@ -61,19 +61,19 @@ rationale = "The bare CLI's validate bundle now echoes its advisory warnings bef"pipelex/cli/commands/build/inputs/_inputs_core.py" = "blob:50317e058df75070722d2e29edab4537e6b7b438""pipelex/cli/commands/build/inputs/app.py" = "blob:2a7770c8294b8c2c1b4420ac00d6ffdfa50609bf""pipelex/cli/commands/build/inputs/bundle_cmd.py" = "blob:0cd99e9d307f46b8e8899bf7d5f3813563fcdf10"-"pipelex/cli/commands/build/inputs/method_cmd.py" = "blob:668e0b66e1c4df0451eeae7e57c2afac8706ad5b"+"pipelex/cli/commands/build/inputs/method_cmd.py" = "blob:4ab9efefc01572c24f5f15bc0eeded2dd4f60804""pipelex/cli/commands/build/inputs/pipe_cmd.py" = "blob:00625740fd29837e3165d31be692e40e96065fc8""pipelex/cli/commands/build/output/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/build/output/_output_core.py" = "blob:9ba47b88a3c0b6cbf3f8de5f9a4939373f64ceb8""pipelex/cli/commands/build/output/app.py" = "blob:67996650b99551fbd58be30e692688204d16935a""pipelex/cli/commands/build/output/bundle_cmd.py" = "blob:54c07aedb123eaaf2049965859e82b6d4800560d"-"pipelex/cli/commands/build/output/method_cmd.py" = "blob:2625da8d562ba4f66cf17890772c7a1a674c3bb9"+"pipelex/cli/commands/build/output/method_cmd.py" = "blob:89bb60c732b1ecb1a0b1bad756c846bc56e64cdb""pipelex/cli/commands/build/output/pipe_cmd.py" = "blob:eb0db8279c93fcff9d5fe4546f593d753282acb5""pipelex/cli/commands/build/runner/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/build/runner/_runner_core.py" = "blob:e4745231cb46547de93d83d1ac7a6db28ae81494""pipelex/cli/commands/build/runner/app.py" = "blob:b5aa321ed93dc2cb9b138e4a26bae9eb75c732b7""pipelex/cli/commands/build/runner/bundle_cmd.py" = "blob:5b5ca0628f0595a0c3aae9b539ae4e7e0c92a853"-"pipelex/cli/commands/build/runner/method_cmd.py" = "blob:0f497ffcae50d89483d8cf953c6dc03599bc2a5f"+"pipelex/cli/commands/build/runner/method_cmd.py" = "blob:63ecd2c06b1455e300b4f0090af188c527298299""pipelex/cli/commands/build/structures_cmd.py" = "blob:d13ba3b6fc1433f787e1aa97c6c04a67483ec7ed""pipelex/cli/commands/bundle_path_resolver.py" = "blob:60c6a2994c9b7c6e0ec212702467d668eecb6d50""pipelex/cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"@@ -115,7 +115,7 @@ rationale = "The bare CLI's validate bundle now echoes its advisory warnings bef"pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148""pipelex/cli/commands/run/bundle_cmd.py" = "blob:cb420bf4879c863d64c5e20ed535c42732b720a2""pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"-"pipelex/cli/commands/run/method_cmd.py" = "blob:828bd9b9c72a0e1132e54241817e388c97d9adad"+"pipelex/cli/commands/run/method_cmd.py" = "blob:6be6e163eb3c1ca768332a47916f8fe479e20e7c""pipelex/cli/commands/run/pipe_cmd.py" = "blob:f92fcb94e3ad55cf5aeec366a59fa7a74bcc9667""pipelex/cli/commands/show_cmd.py" = "blob:7974d91404ea93f05b16b05b9aef3c1a540b965d""pipelex/cli/commands/update_cmd.py" = "blob:06100ec3b9d6c66ca89a8c1536aa27983ae409ca"@@ -123,12 +123,12 @@ rationale = "The bare CLI's validate bundle now echoes its advisory warnings bef"pipelex/cli/commands/validate/_validate_core.py" = "blob:3294c9c716ac616a89213c7356d38a8eff62da40""pipelex/cli/commands/validate/app.py" = "blob:309061423af13f2f6c496a024306ad696af567ab""pipelex/cli/commands/validate/bundle_cmd.py" = "blob:1fbf3e0cf695db39101c83160a724df6468988e9"-"pipelex/cli/commands/validate/method_cmd.py" = "blob:2cb68d5c371a5b45841fce9c26da5e4622e6b042"+"pipelex/cli/commands/validate/method_cmd.py" = "blob:db630f0a3ce633b54721656ef0758d9bda0f7839""pipelex/cli/commands/validate/pipe_cmd.py" = "blob:d67267571559006459628180f2c8b216ba7fee31""pipelex/cli/commands/which_cmd.py" = "blob:68661d4bab22e2c4dab183d59bd9f2c6dd573472""pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c""pipelex/cli/error_handlers.py" = "blob:7a925ef0517bf9b01c3ca4b91ae54a70f57123a6""pipelex/cli/exceptions.py" = "blob:1d51c3a53ddd3f6cf8de566fa2ade3fa75ab7a3a"-"pipelex/cli/installed_methods.py" = "blob:2a1adeda25082bd2bef44887b9af60c29dab8d7b"-"pipelex/cli/method_resolver.py" = "blob:850ad43ee2c6fb0ffc3f449f62ceea1ab6f17297"+"pipelex/cli/installed_methods.py" = "blob:565b08fdd10efa0682d17619cfd7df252dbf61b5"+"pipelex/cli/method_resolver.py" = "blob:83511db5f6010982aa6c4d3569c475acbfe3af61""pipelex/cli/readiness.py" = "blob:6d185324ed0784663e1dc78d1194a28312c54798"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6986ee052..1c888ba22 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,14 @@## [Unreleased]+### Added++- **Run a method by address**: every command that resolves a method target (`pipelex run method`, `pipelex validate method`, the `pipelex build` method commands, and their agent-CLI twins) now accepts a method reference `<address>[@<tag>]` — `github.com/<owner>/<repo>[/<selector>]`, optionally pinned at a git tag (a `@<name>` that names a branch rather than a tag is refused, so only tags pin a revision) — alongside installed names, local paths, and full GitHub URLs. The new `pipelex/methods/` package is the single implementation the CLI, the API, and tests all share: the `MethodRef` grammar parser, fetch-at-tag (wiring the `mthds` `clone_at_version` machinery beside `clone_default_branch`, with the fetched commit SHA always resolved and reported as provenance), package location inside the clone by **manifest identity** (scan for `METHODS.toml`, match the full address, case-insensitively; a miss or ambiguity is a loud error listing the packages the clone contains), env-tunable fetched-package ceilings (file count and total bytes, plus a bounded manifest scan — a size cap per `METHODS.toml` read and a cap on manifests considered per repository), and the reusable structures-refusal check — an AST scan for `StructuredContent` subclasses producing the rule-naming error (*hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python*), which the CLI surfaces as a hosted-parity warning and a hosted runner can apply as a hard refusal. See [Run a Method by Address](tools/cli/run-by-address.md). (Breaking: bare `github.com/...` targets no longer resolve as local paths, and packages inside a fetched repository are located by manifest identity rather than directory path — `/tree/<branch>/<dir>` deep links now resolve through the manifest's `address`/`name`.)++### Changed++- **Structure-class-not-found diagnostics teach the missing-module case**: when a concept's declared structure class does not resolve (`ConceptStructureClassNotFoundError`, and the corresponding PipeFunc output validation error), the message now states that the class may live in a Python module that was not part of the request, and suggests including the module or expressing the type as MTHDS concepts.+### Fixed- **Blueprint serialization schemas**: `ConceptBlueprint`, `ConceptStructureBlueprint`, `InputSlotBlueprint` and `ConstructBlueprint` publish their real shape again in serialization mode. Each carries a `@model_serializer(mode="wrap")` annotated `-> dict[str, Any]`, and pydantic turns a serializer's return annotation into the model's serialization JSON Schema in preference to the one it would generate — so all four came back as an opaque `{"type": "object", "additionalProperties": true}` with no properties, no `required` and no closed shape. This is the same annotation `mthds` 0.11.1 dropped for the input-form field descriptors. Nothing here noticed, because validation-mode schemas and `model_dump()` were both correct throughout; the damage landed in consumers that generate response-model schemas, which FastAPI always does, so a downstream OpenAPI artifact regains its field-level detail on its next `pipelex` bump. A new sweep test holds every Pipelex model to the rule, and the agent rules now scope "every function return must be typed" so a serializer's return stays unannotated.diff --git a/docs/errors/index.md b/docs/errors/index.mdindex 3651f91ac..c374a7807 100644--- a/docs/errors/index.md+++ b/docs/errors/index.md@@ -18,7 +18,7 @@ the error came from:- [Authoring & language](authoring-and-language.md) — MTHDS parsing, Core language, Pipe operators, Pipe controllers, Pipe signatures, Builder, Libraries.- [Execution & runtime](execution-and-runtime.md) — Pipe execution, Pipeline execution, Runtime bridge, Graph, Tracing.- [Inference & providers](inference-and-providers.md) — Inference (Cogt), Provider adapters, Plugin system.-- [Platform & tooling](platform-and-tooling.md) — Base & root errors, Tools, Kit, System & configuration, CLI, Codegen, Migration.+- [Platform & tooling](platform-and-tooling.md) — Base & root errors, Tools, Kit, System & configuration, CLI, Codegen, Methods, Migration.See [Error Model](../under-the-hood/error-model.md) for the underlying contractand classification rules.diff --git a/docs/errors/method-fetch-error.md b/docs/errors/method-fetch-error.mdnew file mode 100644index 000000000..d5697506a--- /dev/null+++ b/docs/errors/method-fetch-error.md@@ -0,0 +1,21 @@+---+title: "Method fetch"+description: "Reference for the `MethodFetchError` Pipelex error class."+---++<!-- pipelex:generated -->++# Method fetch++Fetching the repository behind a method reference failed (clone or commit resolution).++| Field | Value |+|---|---|+| `error_type` | `MethodFetchError` |+| `title` | Method fetch |+| `type_uri` | `https://docs.pipelex.com/latest/errors/method-fetch-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.methods.exceptions` |+| Parent class | [`MethodRefError`](method-ref-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/method-package-ambiguity-error.md b/docs/errors/method-package-ambiguity-error.mdnew file mode 100644index 000000000..c76666201--- /dev/null+++ b/docs/errors/method-package-ambiguity-error.md@@ -0,0 +1,21 @@+---+title: "Method package ambiguity"+description: "Reference for the `MethodPackageAmbiguityError` Pipelex error class."+---++<!-- pipelex:generated -->++# Method package ambiguity++More than one package inside the fetched repository matches the requested address.++| Field | Value |+|---|---|+| `error_type` | `MethodPackageAmbiguityError` |+| `title` | Method package ambiguity |+| `type_uri` | `https://docs.pipelex.com/latest/errors/method-package-ambiguity-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.methods.exceptions` |+| Parent class | [`MethodRefError`](method-ref-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/method-package-not-found-error.md b/docs/errors/method-package-not-found-error.mdnew file mode 100644index 000000000..771e62e5b--- /dev/null+++ b/docs/errors/method-package-not-found-error.md@@ -0,0 +1,21 @@+---+title: "Method package not found"+description: "Reference for the `MethodPackageNotFoundError` Pipelex error class."+---++<!-- pipelex:generated -->++# Method package not found++No package inside the fetched repository matches the requested address by manifest identity.++| Field | Value |+|---|---|+| `error_type` | `MethodPackageNotFoundError` |+| `title` | Method package not found |+| `type_uri` | `https://docs.pipelex.com/latest/errors/method-package-not-found-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.methods.exceptions` |+| Parent class | [`MethodRefError`](method-ref-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/method-package-too-large-error.md b/docs/errors/method-package-too-large-error.mdnew file mode 100644index 000000000..7044b1a21--- /dev/null+++ b/docs/errors/method-package-too-large-error.md@@ -0,0 +1,21 @@+---+title: "Method package too large"+description: "Reference for the `MethodPackageTooLargeError` Pipelex error class."+---++<!-- pipelex:generated -->++# Method package too large++The selected package exceeds the fetched-package ceilings (file count or total bytes).++| Field | Value |+|---|---|+| `error_type` | `MethodPackageTooLargeError` |+| `title` | Method package too large |+| `type_uri` | `https://docs.pipelex.com/latest/errors/method-package-too-large-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.methods.exceptions` |+| Parent class | [`MethodRefError`](method-ref-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/method-ref-error.md b/docs/errors/method-ref-error.mdnew file mode 100644index 000000000..6c1987855--- /dev/null+++ b/docs/errors/method-ref-error.md@@ -0,0 +1,21 @@+---+title: "Method reference error"+description: "Reference for the `MethodRefError` Pipelex error class."+---++<!-- pipelex:generated -->++# Method reference error++Base class for errors while resolving a method reference (`<address>[@<tag>]`).++| Field | Value |+|---|---|+| `error_type` | `MethodRefError` |+| `title` | Method reference error |+| `type_uri` | `https://docs.pipelex.com/latest/errors/method-ref-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.methods.exceptions` |+| Parent class | [`PipelexError`](pipelex-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/method-ref-parse-error.md b/docs/errors/method-ref-parse-error.mdnew file mode 100644index 000000000..14b6cef00--- /dev/null+++ b/docs/errors/method-ref-parse-error.md@@ -0,0 +1,21 @@+---+title: "Method ref parse"+description: "Reference for the `MethodRefParseError` Pipelex error class."+---++<!-- pipelex:generated -->++# Method ref parse++The method reference does not match the `<address>[@<tag>]` grammar.++| Field | Value |+|---|---|+| `error_type` | `MethodRefParseError` |+| `title` | Method ref parse |+| `type_uri` | `https://docs.pipelex.com/latest/errors/method-ref-parse-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.methods.exceptions` |+| Parent class | [`MethodRefError`](method-ref-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/method-structures-refused-error.md b/docs/errors/method-structures-refused-error.mdnew file mode 100644index 000000000..4612ae6bc--- /dev/null+++ b/docs/errors/method-structures-refused-error.md@@ -0,0 +1,21 @@+---+title: "Method structures refused"+description: "Reference for the `MethodStructuresRefusedError` Pipelex error class."+---++<!-- pipelex:generated -->++# Method structures refused++The fetched package declares in-process Python structure classes, which hosted execution refuses.++| Field | Value |+|---|---|+| `error_type` | `MethodStructuresRefusedError` |+| `title` | Method structures refused |+| `type_uri` | `https://docs.pipelex.com/latest/errors/method-structures-refused-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.methods.exceptions` |+| Parent class | [`MethodRefError`](method-ref-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.mdindex 1d24326e4..3ee83506a 100644--- a/docs/errors/platform-and-tooling.md+++ b/docs/errors/platform-and-tooling.md@@ -102,6 +102,16 @@ own page. Classes are grouped by subsystem.- [`CodegenLockError`](codegen-lock-error.md) — Codegen lock error- [`CodegenStampError`](codegen-stamp-error.md) — Codegen stamp error+## Methods++- [`MethodFetchError`](method-fetch-error.md) — Method fetch+- [`MethodPackageAmbiguityError`](method-package-ambiguity-error.md) — Method package ambiguity+- [`MethodPackageNotFoundError`](method-package-not-found-error.md) — Method package not found+- [`MethodPackageTooLargeError`](method-package-too-large-error.md) — Method package too large+- [`MethodRefError`](method-ref-error.md) — Method reference error+- [`MethodRefParseError`](method-ref-parse-error.md) — Method ref parse+- [`MethodStructuresRefusedError`](method-structures-refused-error.md) — Method structures refused+## Migration- [`MigrationError`](migration-error.md) — Migration errordiff --git a/docs/tools/cli/build/inputs.md b/docs/tools/cli/build/inputs.mdindex f78827ded..c0770accb 100644--- a/docs/tools/cli/build/inputs.md+++ b/docs/tools/cli/build/inputs.md@@ -53,7 +53,7 @@ pipelex build inputs method <NAME> [OPTIONS]**Arguments:**-- `NAME` - Name of the installed method+- `NAME` - Name of the installed method, a method address (`github.com/owner/repo[/name][@tag]`), or a GitHub URL — see [Run a Method by Address](../run-by-address.md)**Options:**diff --git a/docs/tools/cli/build/output.md b/docs/tools/cli/build/output.mdindex ecca6c044..732ec7ead 100644--- a/docs/tools/cli/build/output.md+++ b/docs/tools/cli/build/output.md@@ -52,7 +52,7 @@ pipelex build output method <NAME> [OPTIONS]**Arguments:**-- `NAME` - Name of the installed method+- `NAME` - Name of the installed method, a method address (`github.com/owner/repo[/name][@tag]`), or a GitHub URL — see [Run a Method by Address](../run-by-address.md)**Options:**diff --git a/docs/tools/cli/build/runner.md b/docs/tools/cli/build/runner.mdindex 69652759a..d850b5b16 100644--- a/docs/tools/cli/build/runner.md+++ b/docs/tools/cli/build/runner.md@@ -32,7 +32,7 @@ pipelex build runner method <NAME> [OPTIONS]**Arguments:**-- `NAME` - Name of the installed method+- `NAME` - Name of the installed method, a method address (`github.com/owner/repo[/name][@tag]`), or a GitHub URL — see [Run a Method by Address](../run-by-address.md)**Options:**diff --git a/docs/tools/cli/index.md b/docs/tools/cli/index.mdindex 8d98a579a..9d3a109ed 100644--- a/docs/tools/cli/index.md+++ b/docs/tools/cli/index.md@@ -20,6 +20,7 @@ The Pipelex CLI is organized into several command groups:| [**fix**](fix.md) | Apply deterministic safe fixes to a bundle and re-validate || [**show**](show.md) | Inspect configuration, pipes, and AI models || [**run**](run.md) | Execute pipelines |+| [**run method by address**](run-by-address.md) | Fetch and run a method straight from a public GitHub repository || [**build**](build/index.md) | Generate pipelines, runners, and structures |## Global flagsdiff --git a/docs/tools/cli/run-by-address.md b/docs/tools/cli/run-by-address.mdnew file mode 100644index 000000000..81f873cb2--- /dev/null+++ b/docs/tools/cli/run-by-address.md@@ -0,0 +1,63 @@+---+description: "Run, validate, and build against a method fetched straight from a public GitHub repository, addressed as github.com/owner/repo[/name][@tag]."+---++# Run a Method by Address++Every command that takes an installed method name — `pipelex run method`, `pipelex validate method`, the `pipelex build` method commands, and their agent-CLI twins — also accepts a **method reference**: a globally resolvable address pointing at a package in a public GitHub repository. Pipelex fetches the repository, locates the package inside it, and runs it, with no install step.++```bash+# Run a method from the public library at a pinned tag+pipelex run method github.com/Pipelex/methods/[email protected] --inputs inputs.json++# Same method, default branch at HEAD (no tag)+pipelex run method github.com/Pipelex/methods/documents --pipe extract_document_text++# Validate a method by address+pipelex validate method github.com/Pipelex/methods/documents --pipe extract_document_text+```++## The reference grammar++A method reference is `<address>[@<tag>]`:++- **The address** is `github.com/<owner>/<repo>[/<selector>]` (GitHub only for now). The first two path segments name the repository — the clone URL is derived as `https://github.com/<owner>/<repo>.git` — and anything after them selects a package *within* the repository.+- **A bare address** (no `@<tag>`) means the repository's default branch at HEAD.+- **`@<tag>`** pins the repository at that git tag. The recommended form is `vX.Y.Z` (e.g. `@v0.2.0`). The name must be a tag — a branch name after `@` is refused, so only tags pin a revision.++Full browser URLs keep working: `https://github.com/owner/repo` (with or without `.git`) is normalized into the address form, and a `/tree/<branch>/...` deep link is accepted with the branch segment discarded — only tags pin a revision.++Every fetch prints its provenance — the resolved package address, the tag when one was named, and the **commit SHA of what was actually cloned**. Tags can move; the SHA is what makes a run reproducible and explainable.++## How the package is located: manifest identity++The package inside the clone is located by **manifest identity, not directory path**. Pipelex scans the clone for `METHODS.toml` files and selects the one whose identity matches the requested address:++- A **repo-root package** matches when its manifest `address` equals the requested address.+- A **package in a library repo** matches when its manifest `address + "/" + name` equals the requested address. For example, in [`Pipelex/methods`](https://github.com/Pipelex/methods) the documents package's manifest carries `address = "github.com/Pipelex/methods"` and `name = "documents"`, so its full address is `github.com/Pipelex/methods/documents` — wherever it sits in the repository tree.++Address comparison is case-insensitive, matching GitHub's own behavior for owner and repository names.++No match, or more than one, is a loud error listing the packages the clone does contain — so requesting a library repo's bare address tells you which packages it offers.++## The entry pipe++The pipe to run defaults to the manifest's `main_pipe`; `--pipe <code>` overrides it. A method with no `main_pipe` requires `--pipe`.++## Python in fetched methods: the hosted rule++What decides whether Python in a method is acceptable is **where it would execute**:++- `.mthds` content is data — always fine.+- **PipeFunc `.py`** is supported: on hosted deployments it executes in a network-blocked sandbox, never in the runner's process.+- **Python structure classes** (`StructuredContent` subclasses) are imported into the runner's own process, so *hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python*. A fetched method declaring structure classes runs locally, but the CLI prints a hosted-parity warning: express the types as MTHDS concepts (inline structures) to keep the method hosted-runnable.++## Bounds++Fetched packages are bounded: the clone has a fixed timeout, and the selected package is capped in file count and total bytes (tunable via the `PIPELEX_MAX_FETCHED_PACKAGE_FILES` and `PIPELEX_MAX_FETCHED_PACKAGE_TOTAL_KIB` environment variables). The manifest scan that locates the package is bounded too: at most `PIPELEX_MAX_SCANNED_MANIFESTS` manifests are considered per repository, and a `METHODS.toml` larger than `PIPELEX_MAX_MANIFEST_FILE_KIB` is skipped and reported rather than read. Content exceeding the caps is rejected with a clear error.++## Related Documentation++- [CLI Run](run.md)+- [CLI Validate](validate.md)+- [Methods & Packages](../../building-methods/packages.md)diff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.mdindex f8c82709e..8ebfbfb38 100644--- a/docs/tools/cli/run.md+++ b/docs/tools/cli/run.md@@ -123,7 +123,7 @@ Runs a pipeline from an installed method package.**Arguments:**-- `NAME` - The name of the installed method to run+- `NAME` - The name of the installed method to run, a method address (`github.com/owner/repo[/name][@tag]`), or a GitHub URL — see [Run a Method by Address](run-by-address.md)**Options:**@@ -152,6 +152,9 @@ pipelex run method invoice_extractor --pipe extract_amounts# Run with inputspipelex run method invoice_extractor --inputs invoice_data.json++# Run a method fetched by address from a public GitHub repository, pinned at a tag+pipelex run method github.com/Pipelex/methods/[email protected] --pipe extract_document_text```## Input File Formatsdiff --git a/docs/tools/cli/validate.md b/docs/tools/cli/validate.mdindex 66770fc8c..ab68a21e7 100644--- a/docs/tools/cli/validate.md+++ b/docs/tools/cli/validate.md@@ -105,7 +105,7 @@ Validates all pipes in an installed method package.**Arguments:**-- `NAME` - The name of the installed method to validate+- `NAME` - The name of the installed method to validate, a method address (`github.com/owner/repo[/name][@tag]`), or a GitHub URL — see [Run a Method by Address](run-by-address.md)**Options:**diff --git a/mkdocs.yml b/mkdocs.ymlindex 6fc0b2ac5..570d2622c 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -281,6 +281,7 @@ plugins:- tools/cli/validate.md: "CLI Validate"- tools/cli/fix.md: "CLI Fix"- tools/cli/run.md: "CLI Run"+ - tools/cli/run-by-address.md: "CLI Run by Address"- tools/cli/show.md: "CLI Show"- tools/cli/pkg.md: "CLI Pkg"- tools/cli/build/index.md: "CLI Build Overview"@@ -518,6 +519,7 @@ nav:- Validate: tools/cli/validate.md- Fix: tools/cli/fix.md- Run: tools/cli/run.md+ - Run by Address: tools/cli/run-by-address.md- Show: tools/cli/show.md- Pkg: tools/cli/pkg.md- Build:diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.mdindex 8e8c71f68..c20dd4cc6 100644--- a/pipelex/cli/agent_cli/CLAUDE.md+++ b/pipelex/cli/agent_cli/CLAUDE.md@@ -45,7 +45,7 @@ commands/app.py # run_app Typer, subcommand registrationpipe_cmd.py # run pipe — execute by pipe codebundle_cmd.py # run bundle — execute from bundle file/directory- method_cmd.py # run method — execute installed method+ method_cmd.py # run method — execute method (installed name, address/URL, or path)_run_core.py # Shared async run logic (local runner)_run_core_api.py # Shared async run logic (API runner)_output_helpers.py # Output formatting helpers@@ -54,7 +54,7 @@ commands/app.py # validate_app Typer, subcommand registrationpipe_cmd.py # validate pipe — validate by code, or --allbundle_cmd.py # validate bundle — validate bundle file/directory (+ --graph)- method_cmd.py # validate method — validate installed method+ method_cmd.py # validate method — validate method (installed name, address/URL, or path)_validate_core.py # Shared validation logicfix/ # fix — deterministic in-place bundle fixesapp.py # fix_app Typer, subcommand registration@@ -63,7 +63,7 @@ commands/app.py # inputs_app Typer, subcommand registrationpipe_cmd.py # inputs pipe — inputs for a pipe by codebundle_cmd.py # inputs bundle — inputs from bundle file/directory- method_cmd.py # inputs method — inputs for installed method+ method_cmd.py # inputs method — inputs for method (installed name, address/URL, or path)_inputs_core.py # Shared inputs logiccodegen/ # codegen — crate projections + offline drift checkapp.py # codegen_app Typer, subcommand registrationdiff --git a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py b/pipelex/cli/agent_cli/commands/inputs/method_cmd.pyindex b0839083b..80b08588f 100644--- a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py@@ -23,7 +23,7 @@ from pipelex.pipeline.exceptions import ValidateBundleErrordef inputs_method_cmd(name: Annotated[str,- typer.Argument(help="Name of the installed method"),+ typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),],pipe: Annotated[str | None,diff --git a/pipelex/cli/agent_cli/commands/run/method_cmd.py b/pipelex/cli/agent_cli/commands/run/method_cmd.pyindex 1115f8488..577f5b301 100644--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py@@ -29,7 +29,7 @@ def run_method_cmd(ctx: typer.Context,name: Annotated[str,- typer.Argument(help="Name of the installed method"),+ typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),],pipe: Annotated[str | None,diff --git a/pipelex/cli/agent_cli/commands/validate/method_cmd.py b/pipelex/cli/agent_cli/commands/validate/method_cmd.pyindex 985226bda..27d0e4b3f 100644--- a/pipelex/cli/agent_cli/commands/validate/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/validate/method_cmd.py@@ -31,7 +31,7 @@ from pipelex.pipeline.validation_render import format_validate_markdowndef validate_method_cmd(name: Annotated[str,- typer.Argument(help="Name of the installed method"),+ typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),],pipe: Annotated[str | None,diff --git a/pipelex/cli/commands/build/inputs/method_cmd.py b/pipelex/cli/commands/build/inputs/method_cmd.pyindex 668e0b66e..4ab9efefc 100644--- a/pipelex/cli/commands/build/inputs/method_cmd.py+++ b/pipelex/cli/commands/build/inputs/method_cmd.py@@ -14,7 +14,7 @@ from pipelex.pipe_machinery.rendering.input_renderer import InputsTemplateFormatdef build_inputs_method_cmd(name: Annotated[str,- typer.Argument(help="Name of the installed method"),+ typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),],pipe: Annotated[str | None,diff --git a/pipelex/cli/commands/build/output/method_cmd.py b/pipelex/cli/commands/build/output/method_cmd.pyindex 2625da8d5..89bb60c73 100644--- a/pipelex/cli/commands/build/output/method_cmd.py+++ b/pipelex/cli/commands/build/output/method_cmd.py@@ -13,7 +13,7 @@ from pipelex.core.concepts.concept_representation_generator import ConceptRepresdef build_output_method_cmd(name: Annotated[str,- typer.Argument(help="Name of the installed method"),+ typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),],pipe: Annotated[str | None,diff --git a/pipelex/cli/commands/build/runner/method_cmd.py b/pipelex/cli/commands/build/runner/method_cmd.pyindex 0f497ffca..63ecd2c06 100644--- a/pipelex/cli/commands/build/runner/method_cmd.py+++ b/pipelex/cli/commands/build/runner/method_cmd.py@@ -12,7 +12,7 @@ from pipelex.cli.method_resolver import resolve_method_targetdef build_runner_method_cmd(name: Annotated[str,- typer.Argument(help="Name of the installed method"),+ typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL"),],pipe: Annotated[str | None,diff --git a/pipelex/cli/commands/run/method_cmd.py b/pipelex/cli/commands/run/method_cmd.pyindex 828bd9b9c..6be6e163e 100644--- a/pipelex/cli/commands/run/method_cmd.py+++ b/pipelex/cli/commands/run/method_cmd.py@@ -13,7 +13,7 @@ from pipelex.cli.method_resolver import resolve_method_targetdef run_method_cmd(name: Annotated[str,- typer.Argument(help="Name of the installed method to run"),+ typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL to run"),],pipe: Annotated[str | None,@@ -104,17 +104,18 @@ def run_method_cmd(),] = None,) -> None:- """Run an installed method by name.+ """Run a method by name, address, or URL.- Resolves the method from ~/.mthds/methods/ or .mthds/methods/,- determines the pipe to execute (using --pipe or the method's main_pipe),- and runs it.+ Resolves the method from ~/.mthds/methods/ or .mthds/methods/ (or fetches it+ by address / GitHub URL, optionally pinned at a git tag), determines the pipe+ to execute (using --pipe or the method's main_pipe), and runs it.Examples:pipelex run method my-methodpipelex run method my-method --pipe custom_pipepipelex run method my-method --inputs data.jsonpipelex run method my-method --dry-run+ pipelex run method github.com/Pipelex/methods/[email protected] --pipe extract_document_text"""validate_run_flag_combination(dry_run=dry_run, mock_usage=mock_usage, mock_inputs=mock_inputs)diff --git a/pipelex/cli/commands/validate/method_cmd.py b/pipelex/cli/commands/validate/method_cmd.pyindex 2cb68d5c3..db630f0a3 100644--- a/pipelex/cli/commands/validate/method_cmd.py+++ b/pipelex/cli/commands/validate/method_cmd.py@@ -12,7 +12,7 @@ from pipelex.cli.method_resolver import resolve_method_targetdef validate_method_cmd(name: Annotated[str,- typer.Argument(help="Name of the installed method to validate"),+ typer.Argument(help="Installed method name, method address (github.com/owner/repo[/name][@tag]), or GitHub URL to validate"),],pipe: Annotated[str | None,diff --git a/pipelex/cli/installed_methods.py b/pipelex/cli/installed_methods.pyindex 2a1adeda2..565b08fdd 100644--- a/pipelex/cli/installed_methods.py+++ b/pipelex/cli/installed_methods.py@@ -11,6 +11,8 @@ from mthds.package.manifest.parser import parse_methods_tomlfrom mthds.package.manifest.schema import MethodsManifestfrom pydantic import BaseModel+from pipelex.methods.fetching import MethodProvenance+GLOBAL_METHODS_DIR = Path.home() / ".mthds" / "methods"PROJECT_METHODS_DIR = Path(".mthds") / "methods"@@ -32,12 +34,17 @@ class DuplicateMethodNameError(Exception):class InstalledMethod(BaseModel):- """An installed method discovered from the filesystem."""+ """An installed method discovered from the filesystem.++ ``provenance`` is set only for methods fetched by reference: the address, the tag when+ one was named, and the commit SHA of what was actually cloned.+ """name: strpath: Pathmanifest: MethodsManifestmthds_files: list[Path]+ provenance: MethodProvenance | None = Nonedef discover_installed_methods(diff --git a/pipelex/cli/method_resolver.py b/pipelex/cli/method_resolver.pyindex 850ad43ee..83511db5f 100644--- a/pipelex/cli/method_resolver.py+++ b/pipelex/cli/method_resolver.py@@ -6,8 +6,6 @@ import tempfilefrom pathlib import Pathimport typer-from mthds.package.exceptions import VCSFetchError-from mthds.package.vcs_resolver import clone_default_branchfrom pipelex.cli.installed_methods import (DuplicateMethodNameError,@@ -17,6 +15,14 @@ from pipelex.cli.installed_methods import (discover_method_at,find_method_by_name,)+from pipelex.methods.exceptions import MethodRefError, MethodRefParseError+from pipelex.methods.fetching import fetch_method_package+from pipelex.methods.method_ref import looks_like_method_ref, parse_method_ref+from pipelex.methods.structures_check import (+ STRUCTURES_REFUSAL_RULE,+ describe_structured_content_violations,+ scan_structured_content_classes,+)def _get_all_exported_pipes(method: InstalledMethod) -> set[str]:@@ -60,70 +66,6 @@ def _find_method_by_exported_pipe(pipe_code: str) -> InstalledMethod:return matches[0]-def is_github_url(target: str) -> bool:- """Return True if *target* looks like a GitHub URL."""- return target.startswith(("https://github.com/", "http://github.com/"))---def parse_github_url(url: str) -> tuple[str, str | None]:- """Extract an HTTPS clone URL and optional sub-path from a GitHub URL.-- Handles plain repo URLs (``https://github.com/org/repo``), repo URLs- with a trailing ``.git``, and subdirectory URLs such as- ``https://github.com/org/repo/tree/branch/path/to/dir`` or the shorthand- ``https://github.com/org/repo/path/to/dir`` that GitHub auto-resolves.-- Args:- url: A GitHub URL pointing to a repository or a subdirectory within it.-- Returns:- A tuple of (clone_url, sub_path). *sub_path* is ``None`` when the URL- points to the repository root.- """- clean = url.rstrip("/")-- # Strip .git suffix before parsing- if clean.endswith(".git"):- return (clean, None)-- # Split off the scheme + github.com prefix- # URL looks like https://github.com/owner/repo[/rest...]- for prefix in ("https://github.com/", "http://github.com/"):- if clean.startswith(prefix):- remainder = clean[len(prefix) :]- break- else:- # Should not happen since callers check is_github_url first- clone_url = f"{clean}.git"- return (clone_url, None)-- parts = remainder.split("/")- if len(parts) < 2:- clone_url = f"{clean}.git"- return (clone_url, None)-- owner = parts[0]- repo = parts[1]- scheme = "https" if clean.startswith("https") else "http"- clone_url = f"{scheme}://github.com/{owner}/{repo}.git"-- # No extra path segments → repo root- if len(parts) <= 2:- return (clone_url, None)-- # Handle /tree/<branch>/path/... or /blob/<branch>/path/...- rest = parts[2:]- if rest[0] in {"tree", "blob"} and len(rest) >= 2:- # Skip the segment type and branch name- sub_parts = rest[2:]- sub_path = "/".join(sub_parts) if sub_parts else None- else:- # Shorthand: https://github.com/owner/repo/path/to/dir- sub_path = "/".join(rest)-- return (clone_url, sub_path or None)--def is_local_path(target: str) -> bool:"""Return True if *target* looks like a filesystem path (absolute or relative with separators)."""if target.startswith(("https://", "http://")):@@ -165,63 +107,65 @@ def resolve_method_from_path(method_path: str) -> InstalledMethod:return method-def resolve_method_from_url(url: str) -> InstalledMethod:- """Clone a remote repository and discover the method package inside it.+def resolve_method_from_ref(ref_str: str) -> InstalledMethod:+ """Fetch a method by reference (`<address>[@<tag>]` or a GitHub URL) and discover it.- Supports both repo-root URLs (``https://github.com/org/repo``) and- subdirectory URLs (``https://github.com/org/repo/tree/main/path/to/method``- or the shorthand ``https://github.com/org/repo/path/to/method``).+ Clones the repository (at the tag when one is named), locates the package inside the+ clone by manifest identity, prints the fetch provenance (address, tag, commit SHA),+ and warns — hosted parity — when the package declares in-process Python structure+ classes that hosted execution would refuse.- Uses a temporary directory that persists for the duration of the CLI- process, so the cloned files remain available for subsequent steps.+ Uses a temporary directory that persists for the duration of the CLI process, so the+ fetched files remain available for subsequent steps.Args:- url: A GitHub URL pointing to a repository or subdirectory- containing a method package.+ ref_str: The method reference string.Returns:- The discovered ``InstalledMethod``.+ The discovered ``InstalledMethod``, carrying the fetch provenance.Raises:- typer.Exit: On clone failure or if no method package is found.+ typer.Exit: On a parse, fetch, location, or bounds failure."""- clone_url, sub_path = parse_github_url(url)+ try:+ method_ref = parse_method_ref(ref_str)+ except MethodRefParseError as exc:+ typer.secho(str(exc), fg=typer.colors.RED, err=True)+ raise typer.Exit(1) from exc+dest = Path(tempfile.mkdtemp(prefix="mthds_remote_"))atexit.register(shutil.rmtree, dest, True)try:- clone_default_branch(clone_url, dest)- except VCSFetchError as exc:- typer.secho(- f"Failed to clone repository from '{url}': {exc.message}",- fg=typer.colors.RED,- err=True,- )+ fetched = fetch_method_package(ref=method_ref, dest_dir=dest)+ except MethodRefError as exc:+ typer.secho(str(exc), fg=typer.colors.RED, err=True)raise typer.Exit(1) from exc- # Determine the method directory (repo root or a sub-path within it)- method_dir = dest / sub_path if sub_path else dest+ typer.secho(+ f"Fetched {fetched.full_address}{f'@{method_ref.tag}' if method_ref.tag else ''} at commit {fetched.commit_sha}",+ fg=typer.colors.GREEN,+ err=True,+ )- if not method_dir.is_dir():+ violations = scan_structured_content_classes(package_dir=fetched.package_dir)+ if violations:+ details = describe_structured_content_violations(violations=violations)typer.secho(- f"Path '{sub_path}' not found in the cloned repository from '{url}'.",- fg=typer.colors.RED,+ f"Warning: this method declares Python structure classes ({details}). It runs locally, but {STRUCTURES_REFUSAL_RULE} — "+ f"hosted execution would refuse it. Express the types as MTHDS concepts to keep the method hosted-runnable.",+ fg=typer.colors.YELLOW,err=True,)- raise typer.Exit(1)- # Discover the method package- seen_dirs: set[Path] = set()- method = discover_method_at(method_dir, seen_dirs=seen_dirs)- if method is None:- typer.secho(- f"No method package (METHODS.toml) found at '{url}'.",- fg=typer.colors.RED,- err=True,- )- raise typer.Exit(1)-- return method+ name = fetched.manifest.name or fetched.package_dir.name+ return InstalledMethod(+ name=name,+ path=fetched.package_dir,+ manifest=fetched.manifest,+ mthds_files=sorted(fetched.package_dir.rglob("*.mthds")),+ provenance=fetched.provenance,+ )def resolve_method_target(@@ -230,15 +174,16 @@ def resolve_method_target(pipe_override: str | None = None,library_dirs: list[str] | None = None,) -> tuple[str, list[str], InstalledMethod]:- """Resolve a method name or GitHub URL to (pipe_code, library_dirs, method).+ """Resolve a method name, address, URL, or local path to (pipe_code, library_dirs, method).- Finds the installed method by name (or clones from a GitHub URL),- determines the pipe to run (using pipe_override or main_pipe), and- returns the library directories needed to load the method's bundles+ Finds the installed method by name (or fetches it by method reference — a bare+ `github.com/...` address, optionally `@<tag>`-pinned, or a full GitHub URL — or+ discovers it at a local path), determines the pipe to run (using pipe_override or+ main_pipe), and returns the library directories needed to load the method's bundlesalong with the method itself.Args:- method_name: The installed method name or GitHub URL to resolve.+ method_name: The installed method name, method reference, or local path to resolve.pipe_override: Optional pipe code override (takes precedence over main_pipe).library_dirs: Additional directories to search for methods.@@ -249,8 +194,8 @@ def resolve_method_target(typer.Exit: On resolution errors with user-friendly messages."""method: InstalledMethod- if is_github_url(method_name):- method = resolve_method_from_url(method_name)+ if looks_like_method_ref(method_name):+ method = resolve_method_from_ref(method_name)elif is_local_path(method_name):method = resolve_method_from_path(method_name)else:diff --git a/pipelex/libraries/concept/concept_library.py b/pipelex/libraries/concept/concept_library.pyindex 7389616b4..fde06db3a 100644--- a/pipelex/libraries/concept/concept_library.py+++ b/pipelex/libraries/concept/concept_library.py@@ -133,7 +133,9 @@ class ConceptLibrary(RootModel[ConceptLibraryRoot], ConceptLibraryAbstract):except (ClassRegistryNotFoundError, ClassRegistryInheritanceError) as exc:msg = (f"Concept '{concept.concept_ref}' declares structure class '{concept.structure_class_name}', "- f"which is not a registered subclass of StuffContent: {exc}"+ f"which is not a registered subclass of StuffContent: {exc}. "+ f"The class may live in a Python module that was not part of the request — include that module, "+ f"or express the type as MTHDS concepts.")raise ConceptStructureClassNotFoundError(msg) from excreturn cast("type[StuffContent]", structure_class)diff --git a/pipelex/methods/__init__.py b/pipelex/methods/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/pipelex/methods/exceptions.py b/pipelex/methods/exceptions.pynew file mode 100644index 000000000..3ca7d6e3d--- /dev/null+++ b/pipelex/methods/exceptions.py@@ -0,0 +1,38 @@+from typing import ClassVar++from pipelex.base_exceptions import PipelexError+++class MethodRefError(PipelexError):+ """Base class for errors while resolving a method reference (`<address>[@<tag>]`).++ Every subclass describes the caller's own reference or the package it points at,+ so the messages are caller-facing by design.+ """++ _declared_title = "Method reference error"+ _authors_caller_facing_message: ClassVar[bool] = True+++class MethodRefParseError(MethodRefError):+ """The method reference does not match the `<address>[@<tag>]` grammar."""+++class MethodFetchError(MethodRefError):+ """Fetching the repository behind a method reference failed (clone, tag verification, or commit resolution)."""+++class MethodPackageNotFoundError(MethodRefError):+ """No package inside the fetched repository matches the requested address by manifest identity."""+++class MethodPackageAmbiguityError(MethodRefError):+ """More than one package inside the fetched repository matches the requested address."""+++class MethodPackageTooLargeError(MethodRefError):+ """Fetched content exceeds a ceiling: the selected package's file count or total bytes, or the repository's manifest scan."""+++class MethodStructuresRefusedError(MethodRefError):+ """The fetched package declares in-process Python structure classes, which hosted execution refuses."""diff --git a/pipelex/methods/fetch_limits.py b/pipelex/methods/fetch_limits.pynew file mode 100644index 000000000..8e30bb03d--- /dev/null+++ b/pipelex/methods/fetch_limits.py@@ -0,0 +1,37 @@+"""Centralized, env-tunable ceilings for fetched method packages.++A fetched package is content this process pulled from a remote repository, so its size is+bounded here rather than trusted. Values are read once at import time — a change requires+a process restart. The pattern mirrors the request-size ceilings of `pipelex-api`.+"""++from pipelex import log+from pipelex.system.environment import get_optional_env++DEFAULT_MAX_FETCHED_PACKAGE_FILES = 256+DEFAULT_MAX_FETCHED_PACKAGE_TOTAL_KIB = 8 * 1024 # 8 MiB across the selected package+DEFAULT_MAX_MANIFEST_FILE_KIB = 256 # per METHODS.toml read during package location+DEFAULT_MAX_SCANNED_MANIFESTS = 100 # METHODS.toml files considered per fetched repository+++def _read_positive_int(*, env_var: str, default: int) -> int:+ raw = get_optional_env(env_var)+ if not raw:+ return default+ try:+ parsed = int(raw)+ except ValueError:+ log.warning(f"Invalid {env_var}={raw!r}, falling back to {default}")+ return default+ if parsed <= 0:+ log.warning(f"{env_var} must be positive (got {parsed}), falling back to {default}")+ return default+ return parsed+++MAX_FETCHED_PACKAGE_FILES = _read_positive_int(env_var="PIPELEX_MAX_FETCHED_PACKAGE_FILES", default=DEFAULT_MAX_FETCHED_PACKAGE_FILES)+MAX_FETCHED_PACKAGE_TOTAL_BYTES = (+ _read_positive_int(env_var="PIPELEX_MAX_FETCHED_PACKAGE_TOTAL_KIB", default=DEFAULT_MAX_FETCHED_PACKAGE_TOTAL_KIB) * 1024+)+MAX_MANIFEST_FILE_BYTES = _read_positive_int(env_var="PIPELEX_MAX_MANIFEST_FILE_KIB", default=DEFAULT_MAX_MANIFEST_FILE_KIB) * 1024+MAX_SCANNED_MANIFESTS = _read_positive_int(env_var="PIPELEX_MAX_SCANNED_MANIFESTS", default=DEFAULT_MAX_SCANNED_MANIFESTS)diff --git a/pipelex/methods/fetching.py b/pipelex/methods/fetching.pynew file mode 100644index 000000000..54f9b971e--- /dev/null+++ b/pipelex/methods/fetching.py@@ -0,0 +1,209 @@+"""Fetch a method package by reference: clone, resolve the commit, locate, bound, refuse.++The clone rides the `mthds` fetch machinery as released (`clone_default_branch` for a bare+address, `clone_at_version` for `@<tag>`, both depth-1 with a bounded timeout). The commit+SHA of what was cloned is always resolved and recorded — tags can move, so the SHA is the+honest cache key and what keeps runs explainable.+"""++import subprocess # ruff: ignore[suspicious-subprocess-import]+from pathlib import Path++from mthds.package.exceptions import VCSFetchError+from mthds.package.manifest.schema import MethodsManifest+from mthds.package.vcs_resolver import clone_at_version, clone_default_branch+from pydantic import BaseModel, ConfigDict++from pipelex.methods.exceptions import MethodFetchError, MethodPackageTooLargeError+from pipelex.methods.fetch_limits import MAX_FETCHED_PACKAGE_FILES, MAX_FETCHED_PACKAGE_TOTAL_BYTES+from pipelex.methods.method_ref import MethodRef+from pipelex.methods.package_locator import locate_package_in_clone+from pipelex.methods.structures_check import ensure_no_structured_content_python++GIT_REV_PARSE_TIMEOUT_SECONDS = 30++_SKIPPED_DIR_NAMES = {".git"}+++class MethodProvenance(BaseModel):+ """What a fetched-method run must record: address, tag, and the resolved commit SHA."""++ model_config = ConfigDict(frozen=True)++ address: str+ tag: str | None = None+ commit_sha: str+++class FetchedMethodPackage(BaseModel):+ """The result of fetching a method package by reference."""++ model_config = ConfigDict(frozen=True)++ ref: MethodRef+ full_address: str+ commit_sha: str+ clone_dir: Path+ package_dir: Path+ manifest: MethodsManifest++ @property+ def provenance(self) -> MethodProvenance:+ return MethodProvenance(address=self.full_address, tag=self.ref.tag, commit_sha=self.commit_sha)+++def resolve_head_commit_sha(*, clone_dir: Path) -> str:+ """Resolve the commit SHA a clone's HEAD points at.++ Args:+ clone_dir: The clone's root directory.++ Returns:+ The full commit SHA.++ Raises:+ MethodFetchError: If git is unavailable or the resolution fails.+ """+ try:+ result = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true]+ ["git", "-C", str(clone_dir), "rev-parse", "HEAD"], # ruff: ignore[start-process-with-partial-path]+ capture_output=True,+ text=True,+ check=True,+ timeout=GIT_REV_PARSE_TIMEOUT_SECONDS,+ )+ except FileNotFoundError as exc:+ msg = "git is not installed or not found on PATH"+ raise MethodFetchError(msg) from exc+ except subprocess.CalledProcessError as exc:+ msg = f"Failed to resolve the fetched commit in '{clone_dir}': {exc.stderr.strip()}"+ raise MethodFetchError(msg) from exc+ except subprocess.TimeoutExpired as exc:+ msg = f"Timed out resolving the fetched commit in '{clone_dir}'"+ raise MethodFetchError(msg) from exc+ return result.stdout.strip()+++def ensure_cloned_at_tag(*, clone_dir: Path, ref: MethodRef) -> None:+ """Verify that a `@<tag>` clone actually checked out a tag, not a branch.++ `git clone --branch` accepts branch names too, so `@main` would otherwise silently pin+ a moving branch. A depth-1 clone at a tag carries `refs/tags/<tag>`; a clone at a+ branch does not — so the ref's presence in the clone is the discriminator.++ Args:+ clone_dir: The clone's root directory.+ ref: The method reference whose tag was cloned.++ Raises:+ MethodFetchError: If the cloned name is not a tag (or git fails).+ """+ try:+ result = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true]+ ["git", "-C", str(clone_dir), "rev-parse", "--verify", "--quiet", f"refs/tags/{ref.tag}"], # ruff: ignore[start-process-with-partial-path]+ capture_output=True,+ text=True,+ check=False,+ timeout=GIT_REV_PARSE_TIMEOUT_SECONDS,+ )+ except FileNotFoundError as exc:+ msg = "git is not installed or not found on PATH"+ raise MethodFetchError(msg) from exc+ except subprocess.TimeoutExpired as exc:+ msg = f"Timed out verifying tag '{ref.tag}' in '{clone_dir}'"+ raise MethodFetchError(msg) from exc+ if result.returncode != 0:+ msg = (+ f"'{ref.tag}' in method reference '{ref.ref_str}' does not name a git tag on the repository — "+ f"`@<tag>` pins a git tag (recommended form vX.Y.Z); branch names are not accepted."+ )+ raise MethodFetchError(msg)+++def ensure_package_within_bounds(*, package_dir: Path, package_address: str) -> None:+ """Reject a selected package that exceeds the fetched-package ceilings.++ Args:+ package_dir: The selected package directory.+ package_address: The package's full address, named in the error.++ Raises:+ MethodPackageTooLargeError: If the package exceeds the file-count or total-bytes cap.+ """+ file_count = 0+ total_bytes = 0+ for file_path in package_dir.rglob("*"):+ relative_parts = file_path.relative_to(package_dir).parts+ if any(part in _SKIPPED_DIR_NAMES for part in relative_parts):+ continue+ if not file_path.is_file():+ continue+ file_count += 1+ total_bytes += file_path.stat().st_size+ if file_count > MAX_FETCHED_PACKAGE_FILES:+ msg = f"Method package '{package_address}' exceeds the fetched-package ceiling of {MAX_FETCHED_PACKAGE_FILES} files."+ raise MethodPackageTooLargeError(msg)+ if total_bytes > MAX_FETCHED_PACKAGE_TOTAL_BYTES:+ msg = f"Method package '{package_address}' exceeds the fetched-package ceiling of {MAX_FETCHED_PACKAGE_TOTAL_BYTES} bytes in total."+ raise MethodPackageTooLargeError(msg)+++def fetch_method_package(+ *,+ ref: MethodRef,+ dest_dir: Path,+ clone_url: str | None = None,+ refuse_structures: bool = False,+) -> FetchedMethodPackage:+ """Fetch the method package a reference points at.++ Clones the repository (at the tag when the reference names one, at the default branch+ otherwise), resolves the fetched commit SHA, locates the package by manifest identity,+ enforces the fetched-package ceilings, and — when *refuse_structures* is set — refuses+ a package that declares in-process Python structure classes before anything can load it.++ Args:+ ref: The parsed method reference.+ dest_dir: The directory to clone into (must not already contain a clone).+ clone_url: Override for the derived clone URL (tests, non-default remotes).+ refuse_structures: Refuse `StructuredContent`-declaring packages (the runner's+ hard-refusal mode; the CLI scans separately and warns instead).++ Returns:+ The fetched package with its provenance.++ Raises:+ MethodFetchError: If the clone fails, `@<tag>` does not name a tag, or commit resolution fails.+ MethodPackageNotFoundError: If no package matches the requested address.+ MethodPackageAmbiguityError: If more than one package matches.+ MethodPackageTooLargeError: If the selected package exceeds the ceilings.+ MethodStructuresRefusedError: If *refuse_structures* is set and the package+ declares structure classes.+ """+ effective_clone_url = clone_url or ref.clone_url+ try:+ if ref.tag:+ clone_at_version(clone_url=effective_clone_url, version_tag=ref.tag, destination=dest_dir)+ else:+ clone_default_branch(clone_url=effective_clone_url, destination=dest_dir)+ except VCSFetchError as exc:+ msg = f"Failed to fetch method '{ref.ref_str}': {exc.message}"+ raise MethodFetchError(msg) from exc++ if ref.tag:+ ensure_cloned_at_tag(clone_dir=dest_dir, ref=ref)++ commit_sha = resolve_head_commit_sha(clone_dir=dest_dir)+ located = locate_package_in_clone(clone_root=dest_dir, requested_address=ref.address)+ ensure_package_within_bounds(package_dir=located.package_dir, package_address=located.full_address)+ if refuse_structures:+ ensure_no_structured_content_python(package_dir=located.package_dir, package_address=located.full_address)++ return FetchedMethodPackage(+ ref=ref,+ full_address=located.full_address,+ commit_sha=commit_sha,+ clone_dir=dest_dir,+ package_dir=located.package_dir,+ manifest=located.manifest,+ )diff --git a/pipelex/methods/method_ref.py b/pipelex/methods/method_ref.pynew file mode 100644index 000000000..7bfa1dd36--- /dev/null+++ b/pipelex/methods/method_ref.py@@ -0,0 +1,138 @@+"""The method reference grammar: `<address>[@<tag>]`.++A method reference names a package hosted on a public git forge. The address is+`github.com/<owner>/<repo>[/<selector>]` (MVP scope: `github.com` only). A bare address+means the repository's default branch at HEAD; `@<tag>` pins the repository at that git+tag (recommended form `vX.Y.Z`). Full browser URLs (`https://github.com/...`) are accepted+and normalized into the address form, including `/tree/<branch>/...` deep links whose+branch segment is discarded.++This module is the single place the CLI, the API, and the tests parse that grammar.+"""++import re++from mthds.package.vcs_resolver import address_to_clone_url+from pydantic import BaseModel, ConfigDict++from pipelex.methods.exceptions import MethodRefParseError++GITHUB_HOST = "github.com"++_URL_PREFIXES = (f"https://{GITHUB_HOST}/", f"http://{GITHUB_HOST}/")+_ADDRESS_SEGMENT_PATTERN = re.compile(r"^[A-Za-z0-9._-]+$")+_TAG_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]*$")+++class MethodRef(BaseModel):+ """A parsed method reference.++ `address` is the normalized address (no scheme, no `.git` suffix, no tag):+ `github.com/<owner>/<repo>[/<selector>]`. `tag` is the optional git tag from `@<tag>`.+ """++ model_config = ConfigDict(frozen=True)++ address: str+ tag: str | None = None++ @property+ def owner(self) -> str:+ return self.address.split("/")[1]++ @property+ def repo(self) -> str:+ return self.address.split("/")[2]++ @property+ def selector(self) -> str | None:+ """The package selector within the repository (everything after owner/repo), if any."""+ parts = self.address.split("/")+ return "/".join(parts[3:]) or None++ @property+ def repo_address(self) -> str:+ """The repository address alone: `github.com/<owner>/<repo>`."""+ return "/".join(self.address.split("/")[:3])++ @property+ def clone_url(self) -> str:+ """The HTTPS clone URL derived from the repository address."""+ return address_to_clone_url(self.repo_address)++ @property+ def ref_str(self) -> str:+ """The canonical string form of this reference: `<address>[@<tag>]`."""+ if self.tag:+ return f"{self.address}@{self.tag}"+ return self.address+++def looks_like_method_ref(target: str) -> bool:+ """Return True if *target* looks like a method reference (bare address or GitHub URL).++ This is the dispatch test only — a True result still needs :func:`parse_method_ref`+ to validate the structure. Bare `github.com/...` addresses count, so they no longer+ fall through to local-path resolution.+ """+ return target.startswith((f"{GITHUB_HOST}/", *_URL_PREFIXES))+++def parse_method_ref(ref: str) -> MethodRef:+ """Parse a method reference string into a :class:`MethodRef`.++ Accepts the bare address form (`github.com/owner/repo[/selector][@tag]`) and full+ GitHub URLs (`https://github.com/owner/repo[...]`, with an optional trailing `.git`+ or a `/tree/<branch>/...` deep link whose branch segment is discarded).++ Args:+ ref: The reference string to parse.++ Returns:+ The parsed, normalized method reference.++ Raises:+ MethodRefParseError: If the reference does not match the grammar.+ """+ raw = ref.strip()+ if not raw:+ msg = "Empty method reference. Expected '<address>[@<tag>]', e.g. 'github.com/Pipelex/methods/[email protected]'."+ raise MethodRefParseError(msg)++ body = raw+ tag: str | None = None+ if "@" in raw:+ body, tag_part = raw.rsplit("@", 1)+ if not tag_part or not _TAG_PATTERN.match(tag_part):+ msg = f"Invalid tag '{tag_part}' in method reference '{raw}'. A tag must be a git tag name, e.g. 'v0.1.0'."+ raise MethodRefParseError(msg)+ tag = tag_part++ for prefix in _URL_PREFIXES:+ if body.startswith(prefix):+ body = f"{GITHUB_HOST}/{body[len(prefix) :]}"+ break++ body = body.rstrip("/").removesuffix(".git")++ if not body.startswith(f"{GITHUB_HOST}/"):+ msg = f"Unsupported method address '{raw}': only '{GITHUB_HOST}/...' addresses are supported."+ raise MethodRefParseError(msg)++ parts = body.split("/")++ # Browser deep links: github.com/<owner>/<repo>/tree/<branch>/<path> — drop the+ # `tree/<branch>` (or `blob/<branch>`) segments and keep the path as the selector.+ if len(parts) >= 5 and parts[3] in {"tree", "blob"}:+ parts = parts[:3] + parts[5:]++ if len(parts) < 3:+ msg = f"Invalid method address '{raw}': expected '{GITHUB_HOST}/<owner>/<repo>[/<selector>]'."+ raise MethodRefParseError(msg)++ for segment in parts[1:]:+ if not _ADDRESS_SEGMENT_PATTERN.match(segment):+ msg = f"Invalid segment '{segment}' in method address '{raw}': allowed characters are letters, digits, '.', '_' and '-'."+ raise MethodRefParseError(msg)++ return MethodRef(address="/".join(parts), tag=tag)diff --git a/pipelex/methods/package_locator.py b/pipelex/methods/package_locator.pynew file mode 100644index 000000000..328dbbb70--- /dev/null+++ b/pipelex/methods/package_locator.py@@ -0,0 +1,139 @@+"""Locate a package inside a fetched clone by manifest identity.++Package location is by manifest identity, not directory path: the clone is scanned for+`METHODS.toml` files, and the requested package is the one whose manifest `address` equals+the requested address (a repo-root package) or whose `address + "/" + name` equals it (a+package in a library repo). No match, or more than one, is a loud error listing the+packages the clone does contain.++Address comparison is case-insensitive: GitHub owner and repository names are+case-insensitive, and manifests in the wild mix their casing.+"""++from pathlib import Path++from mthds.package.discovery import MANIFEST_FILENAME+from mthds.package.exceptions import ManifestError+from mthds.package.manifest.parser import parse_methods_toml+from mthds.package.manifest.schema import MethodsManifest+from pydantic import BaseModel, ConfigDict, Field++from pipelex.methods.exceptions import MethodPackageAmbiguityError, MethodPackageNotFoundError, MethodPackageTooLargeError+from pipelex.methods.fetch_limits import MAX_MANIFEST_FILE_BYTES, MAX_SCANNED_MANIFESTS+from pipelex.tools.typing.pydantic_utils import empty_list_factory_of++_SKIPPED_DIR_NAMES = {".git"}+++class PackageCandidate(BaseModel):+ """One package found inside a clone: its directory and parsed manifest."""++ model_config = ConfigDict(frozen=True)++ package_dir: Path+ manifest: MethodsManifest++ @property+ def full_address(self) -> str:+ """The package's full address: `address + "/" + name` when named, else `address`."""+ if self.manifest.name:+ return f"{self.manifest.address}/{self.manifest.name}"+ return self.manifest.address+++class PackageScan(BaseModel):+ """The result of scanning a clone for `METHODS.toml` manifests."""++ model_config = ConfigDict(frozen=True)++ candidates: list[PackageCandidate] = Field(default_factory=empty_list_factory_of(PackageCandidate))+ invalid_manifests: list[str] = Field(default_factory=list)+++def scan_packages_in_clone(*, clone_root: Path) -> PackageScan:+ """Scan a clone for packages, tolerating unparseable manifests.++ The scan is bounded — the repository is fetched content: at most+ ``MAX_SCANNED_MANIFESTS`` manifests are considered, and a manifest larger than+ ``MAX_MANIFEST_FILE_BYTES`` is skipped (and reported) rather than read.++ Args:+ clone_root: The root directory of the fetched clone.++ Returns:+ The scan result: valid candidates and a note for each manifest that failed to parse.++ Raises:+ MethodPackageTooLargeError: If the repository contains more manifests than the scan ceiling.+ """+ candidates: list[PackageCandidate] = []+ invalid_manifests: list[str] = []+ manifest_count = 0+ for manifest_path in sorted(clone_root.rglob(MANIFEST_FILENAME)):+ relative_parts = manifest_path.relative_to(clone_root).parts+ if any(part in _SKIPPED_DIR_NAMES for part in relative_parts):+ continue+ manifest_count += 1+ if manifest_count > MAX_SCANNED_MANIFESTS:+ msg = f"The fetched repository contains more than {MAX_SCANNED_MANIFESTS} {MANIFEST_FILENAME} manifests; refusing to scan further."+ raise MethodPackageTooLargeError(msg)+ if manifest_path.stat().st_size > MAX_MANIFEST_FILE_BYTES:+ invalid_manifests.append(f"{'/'.join(relative_parts)}: exceeds the manifest size ceiling of {MAX_MANIFEST_FILE_BYTES} bytes, skipped")+ continue+ try:+ manifest = parse_methods_toml(manifest_path.read_text(encoding="utf-8"))+ except ManifestError as exc:+ invalid_manifests.append(f"{'/'.join(relative_parts)}: {exc.message}")+ continue+ candidates.append(PackageCandidate(package_dir=manifest_path.parent, manifest=manifest))+ return PackageScan(candidates=candidates, invalid_manifests=invalid_manifests)+++def _matches(*, candidate: PackageCandidate, requested: str, clone_root: Path) -> bool:+ folded = requested.casefold()+ if candidate.manifest.name and candidate.full_address.casefold() == folded:+ # Library-repo identity: address + "/" + name, wherever the package sits in the tree.+ return True+ # Address-only identity belongs to a repo-root package: a nested package's identity is+ # address + "/" + name, so a bare repository address must not silently select it.+ return candidate.manifest.address.casefold() == folded and candidate.package_dir.resolve() == clone_root.resolve()+++def locate_package_in_clone(*, clone_root: Path, requested_address: str) -> PackageCandidate:+ """Locate the requested package inside a clone by manifest identity.++ Args:+ clone_root: The root directory of the fetched clone.+ requested_address: The full requested address, e.g. `github.com/Pipelex/methods/documents`.++ Returns:+ The single matching package candidate.++ Raises:+ MethodPackageNotFoundError: If no package matches; the message lists the packages+ the clone does contain (and any manifests that failed to parse).+ MethodPackageAmbiguityError: If more than one package matches; the message lists them.+ """+ scan = scan_packages_in_clone(clone_root=clone_root)+ matches = [candidate for candidate in scan.candidates if _matches(candidate=candidate, requested=requested_address, clone_root=clone_root)]++ if len(matches) == 1:+ return matches[0]++ if not matches:+ if scan.candidates:+ available = ", ".join(sorted(candidate.full_address for candidate in scan.candidates))+ msg = f"No package at address '{requested_address}' in the fetched repository. Packages it contains: {available}."+ else:+ msg = f"No package (no {MANIFEST_FILENAME}) found in the repository fetched for '{requested_address}'."+ if scan.invalid_manifests:+ details = "; ".join(scan.invalid_manifests)+ msg = f"{msg} Manifests that failed to parse: {details}"+ raise MethodPackageNotFoundError(msg)++ matched = ", ".join(sorted(f"{candidate.full_address} ({candidate.package_dir.name}/)" for candidate in matches))+ msg = (+ f"Ambiguous method address '{requested_address}': it matches more than one package in the fetched repository: {matched}. "+ f"Use the package's full address (address + '/' + name) to disambiguate."+ )+ raise MethodPackageAmbiguityError(msg)diff --git a/pipelex/methods/structures_check.py b/pipelex/methods/structures_check.pynew file mode 100644index 000000000..66b5a2539--- /dev/null+++ b/pipelex/methods/structures_check.py@@ -0,0 +1,88 @@+"""The structures-refusal check, reusable by the CLI, the runner, and the loader.++The rule (execution locus decides): `.mthds` content is data — always acceptable. PipeFunc+`.py` executes in the network-blocked sandbox — acceptable on sandbox-hosted deployments.+`structures/*.py` is imported into the runner's own process, so a fetched package that+declares `StructuredContent` subclasses is refused, loudly, with an error that names the+rule. The discrimination is what the AST declares — the same AST pre-check the library+loader's import gate performs — never mere `.py` presence: PipeFunc-only Python is+supported.+"""++from pathlib import Path++from pydantic import BaseModel, ConfigDict++from pipelex.methods.exceptions import MethodStructuresRefusedError+from pipelex.tools.typing.exceptions import ModuleFileError+from pipelex.tools.typing.module_inspector import find_class_names_in_file++STRUCTURE_BASE_CLASS_NAME = "StructuredContent"++STRUCTURES_REFUSAL_RULE = "hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python"++_SKIPPED_DIR_NAMES = {".git", "__pycache__"}+++class StructuredContentViolation(BaseModel):+ """One `.py` file inside a package that declares `StructuredContent` subclasses."""++ model_config = ConfigDict(frozen=True)++ relative_path: str+ class_names: list[str]+++def scan_structured_content_classes(*, package_dir: Path) -> list[StructuredContentViolation]:+ """AST-scan a package directory for `.py` files declaring `StructuredContent` subclasses.++ Files that cannot be parsed are skipped: the loader's own AST import gate skips them+ the same way, so they cannot smuggle a structure class into the process.++ Args:+ package_dir: The package directory to scan.++ Returns:+ One violation per offending file, with the subclass names it declares.+ """+ violations: list[StructuredContentViolation] = []+ for py_file in sorted(package_dir.rglob("*.py")):+ relative = py_file.relative_to(package_dir)+ if any(part in _SKIPPED_DIR_NAMES for part in relative.parts):+ continue+ try:+ class_names = find_class_names_in_file(py_file, base_class_names=[STRUCTURE_BASE_CLASS_NAME])+ except ModuleFileError:+ # Unparseable or otherwise unloadable file: the loader's AST gate would skip it too.+ continue+ if class_names:+ violations.append(StructuredContentViolation(relative_path=relative.as_posix(), class_names=class_names))+ return violations+++def describe_structured_content_violations(*, violations: list[StructuredContentViolation]) -> str:+ """Render violations as a compact, human-readable listing."""+ return "; ".join(f"{violation.relative_path} defines {', '.join(violation.class_names)}" for violation in violations)+++def ensure_no_structured_content_python(*, package_dir: Path, package_address: str) -> None:+ """Refuse a package that declares in-process Python structure classes.++ Args:+ package_dir: The package directory to check.+ package_address: The package's full address, named in the error.++ Raises:+ MethodStructuresRefusedError: If the package declares `StructuredContent` subclasses.+ The message names the rule and teaches the fix.+ """+ violations = scan_structured_content_classes(package_dir=package_dir)+ if not violations:+ return+ details = describe_structured_content_violations(violations=violations)+ msg = (+ f"Method package '{package_address}' declares Python structure classes ({details}), which are imported "+ f"into the runner's own process. Refused: {STRUCTURES_REFUSAL_RULE}. Express the types as MTHDS concepts "+ f"with inline structures instead of Python classes."+ )+ raise MethodStructuresRefusedError(msg)diff --git a/pipelex/pipe_operators/func/pipe_func.py b/pipelex/pipe_operators/func/pipe_func.pyindex 2ee9917ee..50469254c 100644--- a/pipelex/pipe_operators/func/pipe_func.py+++ b/pipelex/pipe_operators/func/pipe_func.py@@ -117,7 +117,9 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):if concept_structure_class is None:msg = (f"PipeFunc '{self.code}' failed to validate output with library: "- f"Concept structure class '{self.output.concept.structure_class_name}' not found in registry."+ f"Concept structure class '{self.output.concept.structure_class_name}' not found in registry. "+ f"The class may live in a Python module that was not part of the request — include that module, "+ f"or express the type as MTHDS concepts.")raise TypeError(msg)diff --git a/subject_grants.toml b/subject_grants.tomlindex 8ab39e0d3..006f6f1ac 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -872,25 +872,17 @@ rationale = "Looks up from the pipe_code; single operand."param = "method"rationale = "Looks up from the method; single operand."-["pipelex/cli/method_resolver.py::is_github_url"]-param = "target"-rationale = "Operates on the target; single operand."-["pipelex/cli/method_resolver.py::is_local_path"]param = "target"rationale = "Operates on the target; single operand."-["pipelex/cli/method_resolver.py::parse_github_url"]-param = "url"-rationale = "Parses the url; single operand."-["pipelex/cli/method_resolver.py::resolve_method_from_path"]param = "method_path"rationale = "Operates on the method_path; single operand."-["pipelex/cli/method_resolver.py::resolve_method_from_url"]-param = "url"-rationale = "Operates on the url; single operand."+["pipelex/cli/method_resolver.py::resolve_method_from_ref"]+param = "ref_str"+rationale = "Operates on the ref string; single operand."["pipelex/cli/method_resolver.py::resolve_method_target"]param = "method_name"@@ -3900,6 +3892,14 @@ rationale = "Verb-object: the refs naming the removed pipes; single operand."param = "blueprint"rationale = "Conversion: derives metadata from the blueprint; single operand."+["pipelex/methods/method_ref.py::looks_like_method_ref"]+param = "target"+rationale = "Tests the target string; single operand."++["pipelex/methods/method_ref.py::parse_method_ref"]+param = "ref"+rationale = "Parses the ref; single operand."+["pipelex/mthds_parsing/bundle_elaborator.py::BundleElaborator.elaborate"]param = "bundle"rationale = "Verb-object: elaborates the bundle; single operand."diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex b099df0b4..b9cd4ca6d 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -153,6 +153,13 @@ LinkupError | Linkup | https://docs.pipelex.com/latest/errors/linkup-error/LinkupSearchEmptyResultError | Linkup search empty result | https://docs.pipelex.com/latest/errors/linkup-search-empty-result-error/LinkupSearchResponseError | Linkup search response | https://docs.pipelex.com/latest/errors/linkup-search-response-error/ListWhereSingularError | List where singular | https://docs.pipelex.com/latest/errors/list-where-singular-error/+MethodFetchError | Method fetch | https://docs.pipelex.com/latest/errors/method-fetch-error/+MethodPackageAmbiguityError | Method package ambiguity | https://docs.pipelex.com/latest/errors/method-package-ambiguity-error/+MethodPackageNotFoundError | Method package not found | https://docs.pipelex.com/latest/errors/method-package-not-found-error/+MethodPackageTooLargeError | Method package too large | https://docs.pipelex.com/latest/errors/method-package-too-large-error/+MethodRefError | Method reference error | https://docs.pipelex.com/latest/errors/method-ref-error/+MethodRefParseError | Method ref parse | https://docs.pipelex.com/latest/errors/method-ref-parse-error/+MethodStructuresRefusedError | Method structures refused | https://docs.pipelex.com/latest/errors/method-structures-refused-error/MigrationError | Migration error | https://docs.pipelex.com/latest/errors/migration-error/MigrationGoldenError | Migration golden error | https://docs.pipelex.com/latest/errors/migration-golden-error/MigrationLedgerError | Migration ledger error | https://docs.pipelex.com/latest/errors/migration-ledger-error/diff --git a/tests/integration/pipelex/methods/test_fetch_at_tag.py b/tests/integration/pipelex/methods/test_fetch_at_tag.pynew file mode 100644index 000000000..7bd7f74e5--- /dev/null+++ b/tests/integration/pipelex/methods/test_fetch_at_tag.py@@ -0,0 +1,117 @@+"""Integration tests for fetch-at-tag against a real local git repository.++Builds a git repository in tmp_path with a library-repo layout, tags it, moves the default+branch past the tag, and fetches through `fetch_method_package` with a `file://` clone URL —+exercising the real `clone_default_branch` / `clone_at_version` machinery and the commit-SHA+resolution, without any network.+"""++from __future__ import annotations++import subprocess # ruff: ignore[suspicious-subprocess-import]+from typing import TYPE_CHECKING++import pytest++from pipelex.methods.exceptions import MethodFetchError+from pipelex.methods.fetching import fetch_method_package+from pipelex.methods.method_ref import parse_method_ref++if TYPE_CHECKING:+ from pathlib import Path++MANIFEST_V1 = """\+[package]+name = "documents"+address = "github.com/Pipelex/methods"+version = "0.1.0"+description = "A test package."+main_pipe = "extract"++[exports.documents]+pipes = ["extract"]+"""+++def _git(repo_dir: Path, *args: str) -> str:+ result = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true]+ ["git", "-C", str(repo_dir), *args], # ruff: ignore[start-process-with-partial-path]+ capture_output=True,+ text=True,+ check=True,+ timeout=30,+ )+ return result.stdout.strip()++[email protected](name="seed_repo")+def seed_repo_fixture(tmp_path: Path) -> tuple[Path, str, str]:+ """A local git repo with one package, a v0.1.0 tag, and a later commit on the default branch.++ Returns (repo_dir, tagged_commit_sha, head_commit_sha).+ """+ repo_dir = tmp_path / "seed-repo"+ package_dir = repo_dir / "methods" / "documents"+ package_dir.mkdir(parents=True)+ (package_dir / "METHODS.toml").write_text(MANIFEST_V1, encoding="utf-8")+ (package_dir / "documents.mthds").write_text("# v1 placeholder", encoding="utf-8")++ _git(repo_dir, "init", "--initial-branch=main")+ _git(repo_dir, "config", "user.email", "[email protected]")+ _git(repo_dir, "config", "user.name", "Test")+ _git(repo_dir, "add", "-A")+ _git(repo_dir, "commit", "-m", "v1")+ _git(repo_dir, "tag", "-a", "v0.1.0", "-m", "release v0.1.0")+ tagged_sha = _git(repo_dir, "rev-parse", "HEAD")++ (package_dir / "documents.mthds").write_text("# v2 placeholder", encoding="utf-8")+ _git(repo_dir, "add", "-A")+ _git(repo_dir, "commit", "-m", "v2")+ head_sha = _git(repo_dir, "rev-parse", "HEAD")++ return repo_dir, tagged_sha, head_sha+++class TestFetchAtTag:+ """Real-git integration: tag clone vs default-branch clone, with the SHA recorded."""++ def test_fetch_at_tag_records_the_tagged_commit(self, seed_repo: tuple[Path, str, str], tmp_path: Path) -> None:+ """Fetching `@v0.1.0` clones the tagged state and records the tagged commit SHA."""+ repo_dir, tagged_sha, head_sha = seed_repo++ fetched = fetch_method_package(+ ref=parse_method_ref("github.com/Pipelex/methods/[email protected]"),+ dest_dir=tmp_path / "clone-at-tag",+ clone_url=f"file://{repo_dir}",+ )++ assert fetched.commit_sha == tagged_sha+ assert fetched.commit_sha != head_sha+ assert fetched.provenance.tag == "v0.1.0"+ assert (fetched.package_dir / "documents.mthds").read_text(encoding="utf-8") == "# v1 placeholder"++ def test_fetch_bare_address_records_the_head_commit(self, seed_repo: tuple[Path, str, str], tmp_path: Path) -> None:+ """Fetching the bare address clones the default branch at HEAD and records that SHA."""+ repo_dir, tagged_sha, head_sha = seed_repo++ fetched = fetch_method_package(+ ref=parse_method_ref("github.com/Pipelex/methods/documents"),+ dest_dir=tmp_path / "clone-default",+ clone_url=f"file://{repo_dir}",+ )++ assert fetched.commit_sha == head_sha+ assert fetched.commit_sha != tagged_sha+ assert fetched.provenance.tag is None+ assert (fetched.package_dir / "documents.mthds").read_text(encoding="utf-8") == "# v2 placeholder"++ def test_branch_name_is_refused_as_a_tag(self, seed_repo: tuple[Path, str, str], tmp_path: Path) -> None:+ """`@<name>` naming a branch, not a tag, is refused — only tags pin a revision."""+ repo_dir, _, _ = seed_repo++ with pytest.raises(MethodFetchError, match="does not name a git tag"):+ fetch_method_package(+ ref=parse_method_ref("github.com/Pipelex/methods/documents@main"),+ dest_dir=tmp_path / "clone-at-branch",+ clone_url=f"file://{repo_dir}",+ )diff --git a/tests/unit/pipelex/cli/test_method_resolver.py b/tests/unit/pipelex/cli/test_method_resolver.pyindex 202a50cc6..27327673e 100644--- a/tests/unit/pipelex/cli/test_method_resolver.py+++ b/tests/unit/pipelex/cli/test_method_resolver.py@@ -1,4 +1,4 @@-"""Unit tests for GitHub URL and local path support in resolve_method_target."""+"""Unit tests for method-reference, local-path, and name dispatch in resolve_method_target."""from __future__ import annotations@@ -10,11 +10,9 @@ from mthds.package.discovery import MANIFEST_FILENAMEfrom mthds.package.exceptions import VCSFetchErrorfrom pipelex.cli.method_resolver import (- is_github_url,is_local_path,- parse_github_url,resolve_method_from_path,- resolve_method_from_url,+ resolve_method_from_ref,resolve_method_target,)@@ -23,6 +21,8 @@ if TYPE_CHECKING:from pytest_mock import MockerFixture+FAKE_SHA = "0123456789abcdef0123456789abcdef01234567"+MINIMAL_MANIFEST = """\[package]address = "github.com/test/remote-method"@@ -35,6 +35,14 @@ main_pipe = "test_pipe"pipes = ["test_pipe"]"""+STRUCTURES_MODULE = """\+from pipelex.core.stuffs.structured_content import StructuredContent+++class Invoice(StructuredContent):+ total: float+"""+def _write_method_package(dest: Path) -> None:"""Write a minimal method package (METHODS.toml + .mthds file) into *dest*."""@@ -44,133 +52,111 @@ def _write_method_package(dest: Path) -> None:class TestResolveMethodTarget:- """Tests for GitHub URL detection, parsing, and resolution in the method resolver."""-- @pytest.mark.parametrize(- "url",- [- "https://github.com/org/repo",- "https://github.com/org/repo.git",- "https://github.com/org/repo/",- "http://github.com/org/repo",- "https://github.com/org/repo/tree/main/methods/my-method",- ],- )- def test_is_github_url_positive(self, url: str) -> None:- """Various valid GitHub URLs are correctly detected."""- assert is_github_url(url) is True-- @pytest.mark.parametrize(- "target",- [- "my-method",- "some-random-string",- "github.com/org/repo",- "https://gitlab.com/org/repo",- "",- ],- )- def test_is_github_url_negative(self, target: str) -> None:- """Method names and non-GitHub strings are not detected as GitHub URLs."""- assert is_github_url(target) is False-- @pytest.mark.parametrize(- ("url", "expected_clone_url", "expected_sub_path"),- [- ("https://github.com/org/repo", "https://github.com/org/repo.git", None),- ("https://github.com/org/repo/", "https://github.com/org/repo.git", None),- ("https://github.com/org/repo.git", "https://github.com/org/repo.git", None),- ("http://github.com/org/repo", "http://github.com/org/repo.git", None),- (- "https://github.com/org/repo/tree/main/methods/my-method",- "https://github.com/org/repo.git",- "methods/my-method",- ),- (- "https://github.com/org/repo/methods/my-method",- "https://github.com/org/repo.git",- "methods/my-method",- ),- ],- )- def test_parse_github_url(self, url: str, expected_clone_url: str, expected_sub_path: str | None) -> None:- """Clone URL and sub-path are correctly extracted from various GitHub URL formats."""- clone_url, sub_path = parse_github_url(url)- assert clone_url == expected_clone_url- assert sub_path == expected_sub_path-- def test_resolve_method_from_url_success(self, mocker: MockerFixture, tmp_path: Path) -> None:- """A successful clone containing a valid package returns an InstalledMethod."""- dest_dir = tmp_path / "cloned"+ """Tests for reference detection, fetch-backed resolution, and local-path resolution."""- def fake_clone(_clone_url: str, destination: Path) -> None:+ def _mock_clone(self, mocker: MockerFixture, dest_dir: Path) -> None:+ def fake_clone(*, clone_url: str, destination: Path) -> None:+ assert clone_url.endswith(".git")_write_method_package(destination)- mocker.patch("pipelex.cli.method_resolver.clone_default_branch", side_effect=fake_clone)+ mocker.patch("pipelex.methods.fetching.clone_default_branch", side_effect=fake_clone)+ mocker.patch("pipelex.methods.fetching.resolve_head_commit_sha", return_value=FAKE_SHA)mocker.patch("pipelex.cli.method_resolver.tempfile.mkdtemp", return_value=str(dest_dir))- method = resolve_method_from_url("https://github.com/test/remote-method")+ def test_resolve_method_from_ref_success(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A successful fetch containing a matching package returns an InstalledMethod with provenance."""+ self._mock_clone(mocker, tmp_path / "cloned")++ method = resolve_method_from_ref("github.com/test/remote-method")assert method.name == "remote_method"assert method.manifest.main_pipe == "test_pipe"assert len(method.mthds_files) == 1+ assert method.provenance is not None+ assert method.provenance.address == "github.com/test/remote-method/remote_method"+ assert method.provenance.commit_sha == FAKE_SHA- def test_resolve_method_from_url_with_sub_path(self, mocker: MockerFixture, tmp_path: Path) -> None:- """A subdirectory URL correctly discovers the method in the sub-path."""- dest_dir = tmp_path / "cloned"-- def fake_clone(_clone_url: str, destination: Path) -> None:- destination.mkdir(parents=True, exist_ok=True)- _write_method_package(destination / "methods" / "my-method")+ def test_resolve_method_from_ref_accepts_full_url(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """Full https GitHub URLs keep working, normalized into the address form."""+ self._mock_clone(mocker, tmp_path / "cloned")- mocker.patch("pipelex.cli.method_resolver.clone_default_branch", side_effect=fake_clone)- mocker.patch("pipelex.cli.method_resolver.tempfile.mkdtemp", return_value=str(dest_dir))-- method = resolve_method_from_url("https://github.com/test/repo/methods/my-method")+ method = resolve_method_from_ref("https://github.com/test/remote-method")assert method.name == "remote_method"- assert method.manifest.main_pipe == "test_pipe"- def test_resolve_method_from_url_clone_failure(self, mocker: MockerFixture, tmp_path: Path) -> None:+ def test_resolve_method_from_ref_clone_failure(self, mocker: MockerFixture, tmp_path: Path) -> None:"""A VCSFetchError during clone raises typer.Exit."""- mocker.patch(- "pipelex.cli.method_resolver.clone_default_branch",- side_effect=VCSFetchError("connection refused"),- )+ mocker.patch("pipelex.methods.fetching.clone_default_branch", side_effect=VCSFetchError("connection refused"))mocker.patch("pipelex.cli.method_resolver.tempfile.mkdtemp", return_value=str(tmp_path / "dest"))with pytest.raises(typer.Exit):- resolve_method_from_url("https://github.com/test/broken-repo")+ resolve_method_from_ref("github.com/test/broken-repo")- def test_resolve_method_from_url_no_manifest(self, mocker: MockerFixture, tmp_path: Path) -> None:- """A clone that contains no METHODS.toml raises typer.Exit."""- dest_dir = tmp_path / "empty"+ def test_resolve_method_from_ref_no_matching_package(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A clone whose packages match no requested address raises typer.Exit."""+ self._mock_clone(mocker, tmp_path / "cloned")- def fake_clone(_clone_url: str, destination: Path) -> None:- destination.mkdir(parents=True, exist_ok=True)+ with pytest.raises(typer.Exit):+ resolve_method_from_ref("github.com/test/other-address")- mocker.patch("pipelex.cli.method_resolver.clone_default_branch", side_effect=fake_clone)- mocker.patch("pipelex.cli.method_resolver.tempfile.mkdtemp", return_value=str(dest_dir))+ def test_resolve_method_from_ref_parse_error(self, mocker: MockerFixture) -> None:+ """An invalid reference raises typer.Exit without attempting a clone."""+ clone_spy = mocker.patch("pipelex.methods.fetching.clone_default_branch")with pytest.raises(typer.Exit):- resolve_method_from_url("https://github.com/test/no-manifest")+ resolve_method_from_ref("github.com/only-owner")- def test_resolve_method_target_dispatches_to_url(self, mocker: MockerFixture, tmp_path: Path) -> None:- """resolve_method_target dispatches to resolve_method_from_url for GitHub URLs."""- dest_dir = tmp_path / "dispatched"+ assert clone_spy.call_count == 0- def fake_clone(_clone_url: str, destination: Path) -> None:+ def test_resolve_method_from_ref_warns_on_structures(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """Hosted-parity: a fetched package declaring StructuredContent subclasses resolves locally with a warning."""+ dest_dir = tmp_path / "cloned"++ def fake_clone(*, clone_url: str, destination: Path) -> None:+ assert clone_url.endswith(".git")_write_method_package(destination)+ (destination / "structures.py").write_text(STRUCTURES_MODULE, encoding="utf-8")- mocker.patch("pipelex.cli.method_resolver.clone_default_branch", side_effect=fake_clone)+ mocker.patch("pipelex.methods.fetching.clone_default_branch", side_effect=fake_clone)+ mocker.patch("pipelex.methods.fetching.resolve_head_commit_sha", return_value=FAKE_SHA)mocker.patch("pipelex.cli.method_resolver.tempfile.mkdtemp", return_value=str(dest_dir))+ secho_spy = mocker.patch("pipelex.cli.method_resolver.typer.secho")- pipe_code, lib_dirs, method = resolve_method_target("https://github.com/test/remote-method")+ method = resolve_method_from_ref("github.com/test/remote-method")++ assert method.name == "remote_method"+ warning_calls = [call for call in secho_spy.call_args_list if "hosted execution would refuse" in str(call)]+ assert len(warning_calls) == 1++ def test_resolve_method_target_dispatches_bare_address(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A bare github.com address dispatches to the fetch arm, not the local-path arm."""+ self._mock_clone(mocker, tmp_path / "dispatched")++ pipe_code, lib_dirs, method = resolve_method_target("github.com/test/remote-method")assert pipe_code == "test_pipe"assert method.name == "remote_method"assert len(lib_dirs) == 1+ def test_resolve_method_target_dispatches_tagged_address(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A `@<tag>` address dispatches to the tag-clone arm."""++ def fake_clone(*, clone_url: str, version_tag: str, destination: Path) -> None:+ assert clone_url == "https://github.com/test/remote-method.git"+ assert version_tag == "v0.1.0"+ _write_method_package(destination)++ mocker.patch("pipelex.methods.fetching.clone_at_version", side_effect=fake_clone)+ mocker.patch("pipelex.methods.fetching.ensure_cloned_at_tag")+ mocker.patch("pipelex.methods.fetching.resolve_head_commit_sha", return_value=FAKE_SHA)+ mocker.patch("pipelex.cli.method_resolver.tempfile.mkdtemp", return_value=str(tmp_path / "tagged"))++ pipe_code, _, method = resolve_method_target("github.com/test/[email protected]")++ assert pipe_code == "test_pipe"+ assert method.provenance is not None+ assert method.provenance.tag == "v0.1.0"+@pytest.mark.parametrize(("target", "expected"),[@@ -199,6 +185,7 @@ class TestResolveMethodTarget:assert method.name == "remote_method"assert method.manifest.main_pipe == "test_pipe"assert len(method.mthds_files) == 1+ assert method.provenance is Nonedef test_resolve_method_from_path_not_a_directory(self, tmp_path: Path) -> None:"""A non-existent path raises typer.Exit."""diff --git a/tests/unit/pipelex/methods/test_fetching.py b/tests/unit/pipelex/methods/test_fetching.pynew file mode 100644index 000000000..29d5861cd--- /dev/null+++ b/tests/unit/pipelex/methods/test_fetching.py@@ -0,0 +1,172 @@+"""Unit tests for fetch_method_package: clone dispatch, SHA recording, bounds, refusal guardrail."""++from __future__ import annotations++import re+from typing import TYPE_CHECKING++import pytest+from mthds.package.exceptions import VCSFetchError++from pipelex.methods.exceptions import MethodFetchError, MethodPackageTooLargeError, MethodStructuresRefusedError+from pipelex.methods.fetching import ensure_package_within_bounds, fetch_method_package+from pipelex.methods.method_ref import parse_method_ref++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture++FAKE_SHA = "0123456789abcdef0123456789abcdef01234567"++MANIFEST = """\+[package]+name = "documents"+address = "github.com/Pipelex/methods"+version = "0.1.0"+description = "A test package."+main_pipe = "extract"++[exports.documents]+pipes = ["extract"]+"""++STRUCTURES_MODULE = """\+from pipelex.core.stuffs.structured_content import StructuredContent+++class Invoice(StructuredContent):+ total: float+"""+++def _write_package(destination: Path) -> None:+ package_dir = destination / "methods" / "documents"+ package_dir.mkdir(parents=True, exist_ok=True)+ (package_dir / "METHODS.toml").write_text(MANIFEST, encoding="utf-8")+ (package_dir / "documents.mthds").write_text("# placeholder", encoding="utf-8")+++class TestFetchMethodPackage:+ """Tests for the fetch orchestration with the clone machinery mocked."""++ def test_bare_address_clones_default_branch(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A tag-less reference clones the default branch and records the resolved SHA."""++ def fake_clone(*, clone_url: str, destination: Path) -> None:+ assert clone_url == "https://github.com/Pipelex/methods.git"+ _write_package(destination)++ clone_default = mocker.patch("pipelex.methods.fetching.clone_default_branch", side_effect=fake_clone)+ clone_at_tag = mocker.patch("pipelex.methods.fetching.clone_at_version")+ mocker.patch("pipelex.methods.fetching.resolve_head_commit_sha", return_value=FAKE_SHA)++ fetched = fetch_method_package(ref=parse_method_ref("github.com/Pipelex/methods/documents"), dest_dir=tmp_path)++ assert clone_default.call_count == 1+ assert clone_at_tag.call_count == 0+ assert fetched.commit_sha == FAKE_SHA+ assert fetched.full_address == "github.com/Pipelex/methods/documents"+ assert fetched.package_dir == tmp_path / "methods" / "documents"+ assert fetched.manifest.main_pipe == "extract"+ assert fetched.provenance.address == "github.com/Pipelex/methods/documents"+ assert fetched.provenance.tag is None+ assert fetched.provenance.commit_sha == FAKE_SHA++ def test_tagged_ref_clones_at_version(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A `@<tag>` reference clones at that tag."""++ def fake_clone(*, clone_url: str, version_tag: str, destination: Path) -> None:+ assert clone_url == "https://github.com/Pipelex/methods.git"+ assert version_tag == "v0.2.0"+ _write_package(destination)++ clone_at_tag = mocker.patch("pipelex.methods.fetching.clone_at_version", side_effect=fake_clone)+ clone_default = mocker.patch("pipelex.methods.fetching.clone_default_branch")+ tag_check = mocker.patch("pipelex.methods.fetching.ensure_cloned_at_tag")+ mocker.patch("pipelex.methods.fetching.resolve_head_commit_sha", return_value=FAKE_SHA)++ fetched = fetch_method_package(ref=parse_method_ref("github.com/Pipelex/methods/[email protected]"), dest_dir=tmp_path)++ assert clone_at_tag.call_count == 1+ assert clone_default.call_count == 0+ assert tag_check.call_count == 1+ assert fetched.provenance.tag == "v0.2.0"++ def test_clone_failure_is_a_method_fetch_error(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A VCS failure surfaces as MethodFetchError naming the reference."""+ mocker.patch("pipelex.methods.fetching.clone_default_branch", side_effect=VCSFetchError("connection refused"))++ with pytest.raises(MethodFetchError, match=re.escape("github.com/Pipelex/methods/documents")):+ fetch_method_package(ref=parse_method_ref("github.com/Pipelex/methods/documents"), dest_dir=tmp_path)++ def test_refusal_fires_before_any_module_import(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """Guardrail: a fetched package carrying a StructuredContent subclass is refused with the+ rule-naming error before anything reaches the module-import machinery.+ """++ def fake_clone(*, clone_url: str, destination: Path) -> None:+ assert clone_url == "https://github.com/Pipelex/methods.git"+ _write_package(destination)+ (destination / "methods" / "documents" / "structures.py").write_text(STRUCTURES_MODULE, encoding="utf-8")++ mocker.patch("pipelex.methods.fetching.clone_default_branch", side_effect=fake_clone)+ mocker.patch("pipelex.methods.fetching.resolve_head_commit_sha", return_value=FAKE_SHA)+ import_module_spy = mocker.patch("pipelex.tools.typing.module_inspector.import_module_from_file")+ import_folder_spy = mocker.patch("pipelex.system.registries.class_registry_utils.ClassRegistryUtils.import_modules_in_folder")++ with pytest.raises(MethodStructuresRefusedError, match="not in-process Python"):+ fetch_method_package(+ ref=parse_method_ref("github.com/Pipelex/methods/documents"),+ dest_dir=tmp_path,+ refuse_structures=True,+ )++ assert import_module_spy.call_count == 0+ assert import_folder_spy.call_count == 0++ def test_without_refusal_flag_structures_package_is_returned(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """The refusal is opt-in: without the flag (local CLI parity-warning mode) the package is returned."""++ def fake_clone(*, clone_url: str, destination: Path) -> None:+ assert clone_url == "https://github.com/Pipelex/methods.git"+ _write_package(destination)+ (destination / "methods" / "documents" / "structures.py").write_text(STRUCTURES_MODULE, encoding="utf-8")++ mocker.patch("pipelex.methods.fetching.clone_default_branch", side_effect=fake_clone)+ mocker.patch("pipelex.methods.fetching.resolve_head_commit_sha", return_value=FAKE_SHA)++ fetched = fetch_method_package(ref=parse_method_ref("github.com/Pipelex/methods/documents"), dest_dir=tmp_path)++ assert fetched.full_address == "github.com/Pipelex/methods/documents"++ def test_file_count_bound_is_enforced(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A selected package with more files than the cap is rejected."""+ package_dir = tmp_path / "pkg"+ package_dir.mkdir()+ for index_file in range(5):+ (package_dir / f"file_{index_file}.mthds").write_text("# x", encoding="utf-8")+ mocker.patch("pipelex.methods.fetching.MAX_FETCHED_PACKAGE_FILES", 3)++ with pytest.raises(MethodPackageTooLargeError, match="files"):+ ensure_package_within_bounds(package_dir=package_dir, package_address="github.com/acme/big")++ def test_total_bytes_bound_is_enforced(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A selected package larger than the byte cap is rejected."""+ package_dir = tmp_path / "pkg"+ package_dir.mkdir()+ (package_dir / "big.mthds").write_text("x" * 1024, encoding="utf-8")+ mocker.patch("pipelex.methods.fetching.MAX_FETCHED_PACKAGE_TOTAL_BYTES", 512)++ with pytest.raises(MethodPackageTooLargeError, match="bytes"):+ ensure_package_within_bounds(package_dir=package_dir, package_address="github.com/acme/heavy")++ def test_bounds_ignore_git_directory(self, tmp_path: Path) -> None:+ """Files under .git/ do not count toward the ceilings."""+ package_dir = tmp_path / "pkg"+ git_dir = package_dir / ".git" / "objects"+ git_dir.mkdir(parents=True)+ (git_dir / "blob").write_bytes(b"x" * 4096)+ (package_dir / "core.mthds").write_text("# placeholder", encoding="utf-8")++ ensure_package_within_bounds(package_dir=package_dir, package_address="github.com/acme/small")diff --git a/tests/unit/pipelex/methods/test_method_ref.py b/tests/unit/pipelex/methods/test_method_ref.pynew file mode 100644index 000000000..41977fc06--- /dev/null+++ b/tests/unit/pipelex/methods/test_method_ref.py@@ -0,0 +1,99 @@+"""Unit tests for the method reference grammar: `<address>[@<tag>]`."""++from __future__ import annotations++import pytest+from pydantic import ValidationError++from pipelex.methods.exceptions import MethodRefParseError+from pipelex.methods.method_ref import MethodRef, looks_like_method_ref, parse_method_ref+++class TestMethodRefGrammar:+ """Tests for parsing and detection of method references."""++ @pytest.mark.parametrize(+ ("ref", "expected_address", "expected_tag"),+ [+ ("github.com/Pipelex/methods/documents", "github.com/Pipelex/methods/documents", None),+ ("github.com/Pipelex/methods/[email protected]", "github.com/Pipelex/methods/documents", "v0.2.0"),+ ("github.com/acme/legal-tools", "github.com/acme/legal-tools", None),+ ("github.com/acme/[email protected]", "github.com/acme/legal-tools", "1.0.0-rc.1"),+ ("github.com/org/repo@release/v1", "github.com/org/repo", "release/v1"),+ ("https://github.com/org/repo", "github.com/org/repo", None),+ ("https://github.com/org/repo/", "github.com/org/repo", None),+ ("https://github.com/org/repo.git", "github.com/org/repo", None),+ ("http://github.com/org/repo", "github.com/org/repo", None),+ ("https://github.com/org/[email protected]", "github.com/org/repo", "v1.2.3"),+ ("https://github.com/org/repo/tree/main/methods/documents", "github.com/org/repo/methods/documents", None),+ ("https://github.com/org/repo/blob/dev/pkg", "github.com/org/repo/pkg", None),+ ("github.com/org/repo/deep/nested/selector", "github.com/org/repo/deep/nested/selector", None),+ ],+ )+ def test_parse_valid(self, ref: str, expected_address: str, expected_tag: str | None) -> None:+ """Valid references parse into the normalized address and optional tag."""+ parsed = parse_method_ref(ref)+ assert parsed.address == expected_address+ assert parsed.tag == expected_tag++ @pytest.mark.parametrize(+ "ref",+ [+ "",+ " ",+ "github.com",+ "github.com/only-owner",+ "gitlab.com/org/repo",+ "https://gitlab.com/org/repo",+ "example.io/pkg",+ "github.com/org/repo@",+ "github.com/org/re po",+ "github.com/org/repo@v1@v2",+ ],+ )+ def test_parse_invalid(self, ref: str) -> None:+ """Invalid references raise MethodRefParseError."""+ with pytest.raises(MethodRefParseError):+ parse_method_ref(ref)++ def test_parsed_ref_properties(self) -> None:+ """Owner, repo, selector, repo address, clone URL, and canonical string are derived."""+ parsed = parse_method_ref("github.com/Pipelex/methods/[email protected]")+ assert parsed.owner == "Pipelex"+ assert parsed.repo == "methods"+ assert parsed.selector == "documents"+ assert parsed.repo_address == "github.com/Pipelex/methods"+ assert parsed.clone_url == "https://github.com/Pipelex/methods.git"+ assert parsed.ref_str == "github.com/Pipelex/methods/[email protected]"++ def test_repo_root_ref_has_no_selector(self) -> None:+ """A repo-root reference has no selector and round-trips its address."""+ parsed = parse_method_ref("github.com/acme/legal-tools")+ assert parsed.selector is None+ assert parsed.repo_address == "github.com/acme/legal-tools"+ assert parsed.ref_str == "github.com/acme/legal-tools"++ @pytest.mark.parametrize(+ ("target", "expected"),+ [+ ("github.com/Pipelex/methods/documents", True),+ ("github.com/Pipelex/methods/[email protected]", True),+ ("https://github.com/org/repo", True),+ ("http://github.com/org/repo", True),+ ("my-method", False),+ ("./local/path", False),+ ("/absolute/path", False),+ ("methods/documents", False),+ ("https://gitlab.com/org/repo", False),+ ("", False),+ ],+ )+ def test_looks_like_method_ref(self, target: str, expected: bool) -> None:+ """Bare github.com addresses and GitHub URLs are detected; names and paths are not."""+ assert looks_like_method_ref(target) is expected++ def test_method_ref_is_frozen(self) -> None:+ """MethodRef is immutable."""+ parsed = MethodRef(address="github.com/org/repo", tag="v1.0.0")+ with pytest.raises(ValidationError, match="frozen"):+ parsed.tag = "v2.0.0" # type: ignore[misc] # pyright: ignore[reportAttributeAccessIssue]diff --git a/tests/unit/pipelex/methods/test_package_locator.py b/tests/unit/pipelex/methods/test_package_locator.pynew file mode 100644index 000000000..b3b17a727--- /dev/null+++ b/tests/unit/pipelex/methods/test_package_locator.py@@ -0,0 +1,149 @@+"""Unit tests for manifest-identity package location inside a fetched clone."""++from __future__ import annotations++import re+from typing import TYPE_CHECKING++import pytest++from pipelex.methods.exceptions import MethodPackageAmbiguityError, MethodPackageNotFoundError, MethodPackageTooLargeError+from pipelex.methods.package_locator import locate_package_in_clone, scan_packages_in_clone++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture+++def _write_manifest(package_dir: Path, *, address: str, name: str | None = None, main_pipe: str | None = None) -> None:+ package_dir.mkdir(parents=True, exist_ok=True)+ lines = ["[package]", f'address = "{address}"', 'version = "0.1.0"', 'description = "A test package."']+ if name is not None:+ lines.insert(1, f'name = "{name}"')+ if main_pipe is not None:+ lines.append(f'main_pipe = "{main_pipe}"')+ (package_dir / "METHODS.toml").write_text("\n".join(lines) + "\n", encoding="utf-8")+ (package_dir / "core.mthds").write_text("# placeholder", encoding="utf-8")+++class TestPackageLocator:+ """Tests for locating a package by manifest identity (repo-root and library-repo layouts)."""++ def test_repo_root_package_matches_by_address(self, tmp_path: Path) -> None:+ """A repo-root package whose manifest address equals the requested address is located."""+ _write_manifest(tmp_path, address="github.com/acme/legal-tools", name="legal_tools")++ located = locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/acme/legal-tools")++ assert located.package_dir == tmp_path+ assert located.manifest.name == "legal_tools"+ assert located.full_address == "github.com/acme/legal-tools/legal_tools"++ def test_library_repo_package_matches_by_address_plus_name(self, tmp_path: Path) -> None:+ """In a library repo, address + '/' + name identifies the package regardless of directory path."""+ _write_manifest(tmp_path / "methods" / "documents", address="github.com/Pipelex/methods", name="documents")+ _write_manifest(tmp_path / "methods" / "imaging", address="github.com/Pipelex/methods", name="image_generation")++ located = locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/Pipelex/methods/documents")++ assert located.package_dir == tmp_path / "methods" / "documents"+ assert located.full_address == "github.com/Pipelex/methods/documents"++ # Directory path is not the identity: the imaging/ directory holds image_generation+ located_by_name = locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/Pipelex/methods/image_generation")+ assert located_by_name.package_dir == tmp_path / "methods" / "imaging"++ def test_address_match_is_case_insensitive(self, tmp_path: Path) -> None:+ """GitHub owner/repo names are case-insensitive, so the manifest-identity match is too."""+ _write_manifest(tmp_path / "pkg", address="github.com/pipelex/methods", name="documents")++ located = locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/Pipelex/Methods/documents")++ assert located.full_address == "github.com/pipelex/methods/documents"++ def test_no_match_lists_candidates(self, tmp_path: Path) -> None:+ """A miss is a loud error naming the packages the clone does contain."""+ _write_manifest(tmp_path / "methods" / "documents", address="github.com/Pipelex/methods", name="documents")+ _write_manifest(tmp_path / "methods" / "imaging", address="github.com/Pipelex/methods", name="image_generation")++ with pytest.raises(MethodPackageNotFoundError) as exc_info:+ locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/Pipelex/methods/nonexistent")++ message = str(exc_info.value)+ assert "github.com/Pipelex/methods/documents" in message+ assert "github.com/Pipelex/methods/image_generation" in message++ def test_empty_clone_is_a_loud_miss(self, tmp_path: Path) -> None:+ """A clone with no METHODS.toml at all raises with a clear message."""+ with pytest.raises(MethodPackageNotFoundError, match=re.escape("METHODS.toml")):+ locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/acme/empty")++ def test_ambiguity_is_a_loud_error(self, tmp_path: Path) -> None:+ """Two packages matching the same requested address raise an ambiguity error listing both."""+ _write_manifest(tmp_path / "one", address="github.com/Pipelex/methods", name="documents")+ _write_manifest(tmp_path / "two", address="github.com/Pipelex/methods", name="documents")++ with pytest.raises(MethodPackageAmbiguityError, match="documents"):+ locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/Pipelex/methods/documents")++ def test_bare_library_repo_address_lists_its_packages(self, tmp_path: Path) -> None:+ """Requesting a library repo's bare address matches no nested package — a loud miss listing them."""+ _write_manifest(tmp_path / "methods" / "documents", address="github.com/Pipelex/methods", name="documents")+ _write_manifest(tmp_path / "methods" / "imaging", address="github.com/Pipelex/methods", name="image_generation")++ with pytest.raises(MethodPackageNotFoundError) as exc_info:+ locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/Pipelex/methods")++ message = str(exc_info.value)+ assert "github.com/Pipelex/methods/documents" in message+ assert "github.com/Pipelex/methods/image_generation" in message++ def test_single_nested_package_does_not_match_bare_repo_address(self, tmp_path: Path) -> None:+ """Address-only identity belongs to repo-root packages: one nested library package is not+ silently selected by the bare repository address — the miss lists its full address.+ """+ _write_manifest(tmp_path / "methods" / "documents", address="github.com/Pipelex/methods", name="documents")++ with pytest.raises(MethodPackageNotFoundError, match=re.escape("github.com/Pipelex/methods/documents")):+ locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/Pipelex/methods")++ def test_oversized_manifest_is_skipped_and_reported(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A manifest larger than the size ceiling is never read; the miss names it."""+ big_dir = tmp_path / "big"+ big_dir.mkdir()+ (big_dir / "METHODS.toml").write_text("# " + "x" * 2048, encoding="utf-8")+ mocker.patch("pipelex.methods.package_locator.MAX_MANIFEST_FILE_BYTES", 1024)+ parse_spy = mocker.patch("pipelex.methods.package_locator.parse_methods_toml")++ with pytest.raises(MethodPackageNotFoundError, match="size ceiling"):+ locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/acme/big")++ assert parse_spy.call_count == 0++ def test_manifest_scan_count_is_bounded(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A repository with more manifests than the scan ceiling is rejected."""+ for index_pkg in range(4):+ _write_manifest(tmp_path / f"pkg_{index_pkg}", address="github.com/acme/many", name=f"pkg_{index_pkg}")+ mocker.patch("pipelex.methods.package_locator.MAX_SCANNED_MANIFESTS", 3)++ with pytest.raises(MethodPackageTooLargeError, match="refusing to scan"):+ locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/acme/many/pkg_0")++ def test_invalid_manifest_is_reported_on_miss(self, tmp_path: Path) -> None:+ """A manifest that fails to parse is skipped but named when the location misses."""+ broken_dir = tmp_path / "broken"+ broken_dir.mkdir(parents=True)+ (broken_dir / "METHODS.toml").write_text("not [valid toml", encoding="utf-8")++ with pytest.raises(MethodPackageNotFoundError, match=re.escape("broken/METHODS.toml")):+ locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/acme/broken")++ def test_scan_skips_git_directory(self, tmp_path: Path) -> None:+ """Manifests under .git/ are not candidates."""+ _write_manifest(tmp_path / ".git" / "junk", address="github.com/acme/junk", name="junk")+ _write_manifest(tmp_path / "pkg", address="github.com/acme/real", name="real")++ scan = scan_packages_in_clone(clone_root=tmp_path)++ assert [candidate.full_address for candidate in scan.candidates] == ["github.com/acme/real/real"]diff --git a/tests/unit/pipelex/methods/test_structures_check.py b/tests/unit/pipelex/methods/test_structures_check.pynew file mode 100644index 000000000..ee2b12580--- /dev/null+++ b/tests/unit/pipelex/methods/test_structures_check.py@@ -0,0 +1,106 @@+"""Unit tests for the reusable structures-refusal check."""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest++from pipelex.methods.exceptions import MethodStructuresRefusedError+from pipelex.methods.structures_check import (+ STRUCTURES_REFUSAL_RULE,+ ensure_no_structured_content_python,+ scan_structured_content_classes,+)++if TYPE_CHECKING:+ from pathlib import Path++STRUCTURES_MODULE = """\+from pipelex.core.stuffs.structured_content import StructuredContent+++class Invoice(StructuredContent):+ total: float+++class LineItem(StructuredContent):+ label: str+"""++PIPE_FUNC_MODULE = """\+from pipelex.pipe_operators.func.func_registry import pipe_func+++@pipe_func()+def compute_total(value: float) -> float:+ return value * 2+"""++PLAIN_MODULE = """\+class Helper:+ pass+"""+++class TestStructuresCheck:+ """Tests for the AST-based StructuredContent refusal — never gating on mere .py presence."""++ def test_structures_module_is_detected(self, tmp_path: Path) -> None:+ """A .py file declaring StructuredContent subclasses is a violation naming the classes."""+ (tmp_path / "structures.py").write_text(STRUCTURES_MODULE, encoding="utf-8")++ violations = scan_structured_content_classes(package_dir=tmp_path)++ assert len(violations) == 1+ assert violations[0].relative_path == "structures.py"+ assert violations[0].class_names == ["Invoice", "LineItem"]++ def test_pipe_func_only_python_is_allowed(self, tmp_path: Path) -> None:+ """PipeFunc-only Python is supported: no violation, no refusal."""+ (tmp_path / "funcs.py").write_text(PIPE_FUNC_MODULE, encoding="utf-8")+ (tmp_path / "helper.py").write_text(PLAIN_MODULE, encoding="utf-8")++ assert scan_structured_content_classes(package_dir=tmp_path) == []+ ensure_no_structured_content_python(package_dir=tmp_path, package_address="github.com/acme/funcs-only")++ def test_refusal_names_the_rule(self, tmp_path: Path) -> None:+ """The refusal error names the rule and the offending classes."""+ (tmp_path / "structures.py").write_text(STRUCTURES_MODULE, encoding="utf-8")++ with pytest.raises(MethodStructuresRefusedError) as exc_info:+ ensure_no_structured_content_python(package_dir=tmp_path, package_address="github.com/acme/bad-package")++ message = str(exc_info.value)+ assert STRUCTURES_REFUSAL_RULE in message+ assert "github.com/acme/bad-package" in message+ assert "Invoice" in message+ assert "MTHDS concepts" in message++ def test_unparseable_python_is_skipped(self, tmp_path: Path) -> None:+ """A syntactically invalid .py cannot smuggle a structure class: skipped, like the loader's gate."""+ (tmp_path / "broken.py").write_text("def broken(:\n", encoding="utf-8")++ assert scan_structured_content_classes(package_dir=tmp_path) == []++ def test_pycache_and_git_are_skipped(self, tmp_path: Path) -> None:+ """Files under .git/ and __pycache__/ are not scanned."""+ cache_dir = tmp_path / "__pycache__"+ cache_dir.mkdir()+ (cache_dir / "cached.py").write_text(STRUCTURES_MODULE, encoding="utf-8")+ git_dir = tmp_path / ".git" / "hooks"+ git_dir.mkdir(parents=True)+ (git_dir / "hook.py").write_text(STRUCTURES_MODULE, encoding="utf-8")++ assert scan_structured_content_classes(package_dir=tmp_path) == []++ def test_nested_structures_are_detected(self, tmp_path: Path) -> None:+ """Violations are found recursively, reported with their relative path."""+ nested = tmp_path / "structures"+ nested.mkdir()+ (nested / "models.py").write_text(STRUCTURES_MODULE, encoding="utf-8")++ violations = scan_structured_content_classes(package_dir=tmp_path)++ assert len(violations) == 1+ assert violations[0].relative_path == "structures/models.py"