diff --git a/CHANGELOG.md b/CHANGELOG.md index f5292f24a3..79f605864b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,23 @@ loading. A port that reports `1.2` does not know that vocabulary; upgrade every ### Added +- **A shared model can carry its requirements, and a consumer can inherit them (FR-023).** The + publisher's `shared-model` generator takes `requirements: true` (TypeScript `sharedModelFile`, + the Java/Kotlin generator arg `requirements`, C# `SharedModelGenerator.Requirements`; default + off) and then publishes the selected `requirement.*` nodes beside the model they describe; a + requirement claiming a node outside the selection is refused at publish. `template.*` is never + published. On the consumer side, `requirements.inherit` in `.metaobjects/config.json` names the + dependency packages whose requirements join the project's ledger, by the same explicit-include + rule as `scope.include` (`**` names nothing). A dependency's requirement that is not inherited + still loads, so an overlay of it resolves, but the requirement gate, its summary and lint, the + `requirement-tests` generators and the requirements pages leave it out; `requirementTestIdentities` + (TypeScript) and `requirement_test_identities` (Python) take the collection's ledger predicate + as `inLedger` / `in_ledger`, as the generator does. An imported requirement never switches object + coverage on, inherited or not, as a library's never does. Every port reads the key (TypeScript, + Python, Java, Kotlin through Java, C#). A consumer on an older toolchain treats a published + requirement as its own, so upgrade consumers before publishing with `requirements: true`. See + `docs/features/metadata-dependencies.md`, "Inheriting a dependency's requirements". + - **`maven` and `nuget` dependency transports (FR-023).** `meta deps sync` and `meta deps check` can now read a shared model out of a published package that is already in the local cache, so a JVM or .NET consumer no longer needs the publisher's directory on disk. `{ "name": "x", "maven": @@ -317,6 +334,10 @@ loading. A port that reports `1.2` does not know that vocabulary; upgrade every ### Changed +- **A new top-level requirement declared into a dependency's package is refused** with + `ERR_DEPENDENCY_PACKAGE_NOT_OWNED`, as a new object there already was. An overlay of the + dependency's own requirement is still accepted. + - **`docsSiteFile()` builds the model explorer by default.** A project that lists `docsSiteFile()` gets a different site under `site/` on its next `meta gen`, with new page paths (object pages move under `model/`); `meta gen` removes the old pages it wrote, as it diff --git a/docs/CONFORMANCE.md b/docs/CONFORMANCE.md index 28981161fc..1c8ef3632d 100644 --- a/docs/CONFORMANCE.md +++ b/docs/CONFORMANCE.md @@ -49,8 +49,8 @@ regenerate with `ls -d fixtures//*/ | wc -l` for directory-shaped corpor | [`fixtures/provider-composition-conformance/`](../fixtures/provider-composition-conformance/) | 18 (11 error-shape + 4 compose-load + 3 attr-ownership) | ✓ | ✓ | — (JVM registry via Java) | ✓ | ✓ | | [`fixtures/source-resolution-conformance/`](../fixtures/source-resolution-conformance/) | 25 cases | ✓ (reference implementation) | ✓ | inherits via Java | ✓ | ✓ | | [`fixtures/scope-conformance/`](../fixtures/scope-conformance/) | 10 cases | ✓ (reference implementation) | ✓ | inherits via Java | ✓ | ✓ | -| [`fixtures/dependency-conformance/`](../fixtures/dependency-conformance/) | 39 cases (28 resolution + 11 check) + 32 transport cases | ✓ (reference implementation; all three arms) | ✓ (resolution arm, all 28; check arm, all 11) | inherits via Java | ✓ (resolution arm, all 28; check arm, all 11, as `verify --deps`) | ✓ (resolution arm, all 28 identically; check arm, all 11, as `deps check` and `verify --deps`; the transport arm is Node-only) | -| [`fixtures/shared-model-conformance/`](../fixtures/shared-model-conformance/) | 11 cases (7 publish + 4 refusal) | ✓ (reference implementation) | ✓ (all 11; `SharedModelConformanceTest`) | inherits via Java (`KotlinSharedModelGeneratorTest` pins the generator) | ✓ (all 11; `SharedModelConformanceTests`) | ✓ (serializer arm: the 7 publish cases' document bytes; no publisher) | +| [`fixtures/dependency-conformance/`](../fixtures/dependency-conformance/) | 47 cases (36 resolution, 7 of them with a ledger arm, + 11 check) + 32 transport cases | ✓ (reference implementation; all four arms) | ✓ (resolution arm, all 36, ledger included; check arm, all 11) | inherits via Java | ✓ (resolution arm, all 36, ledger included; check arm, all 11, as `verify --deps`) | ✓ (resolution arm, all 36 identically, ledger included; check arm, all 11, as `deps check` and `verify --deps`; the transport arm is Node-only) | +| [`fixtures/shared-model-conformance/`](../fixtures/shared-model-conformance/) | 15 cases (9 publish + 6 refusal) | ✓ (reference implementation) | ✓ (all 15; `SharedModelConformanceTest`) | inherits via Java (`KotlinSharedModelGeneratorTest` pins the generator) | ✓ (all 15; `SharedModelConformanceTests`) | ✓ (serializer arm: the 9 publish cases' document bytes; no publisher) | | [`fixtures/agent-context-conformance/`](../fixtures/agent-context-conformance/) | 4 | ✓ (the emitter is TS-owned) | — | — | — | — | | [`fixtures/metamodel-docs/`](../fixtures/metamodel-docs/) | 1 | ✓ (docs emit is TS-owned) | — | — | — | — | | [`fixtures/fmt-conformance/`](../fixtures/fmt-conformance/) (#304 — `meta fmt`) | 12 | ✓ (reference) | ✓ | inherits via Java | ✓ | ✓ | @@ -463,21 +463,30 @@ also matches before a trailing newline. Kotlin has no runner of its own: it inhe the Java loader. Each of those two guards is pinned by a test beside the corpus, since the corpus asserts matches only and carries no invalid-pattern case. -### `fixtures/dependency-conformance/` (39 cases + 32 transport cases) +### `fixtures/dependency-conformance/` (47 cases + 32 transport cases) -All 39 cases → [features/metadata-dependencies.md](features/metadata-dependencies.md) +All 47 cases → [features/metadata-dependencies.md](features/metadata-dependencies.md) (declaring a dependency, `meta deps sync`, the committed snapshot + lock, default exclusion of imported metadata, overlay/extends across the boundary, every load- -and resolution-time failure, and the upstream check). File-shaped like `scope-conformance/` -above: one committed `cases.json`, no per-port fixture, no ledger. The corpus has three arms: +and resolution-time failure, the upstream check, and which imported requirements are the +project's own ledger). File-shaped like `scope-conformance/` above: one committed `cases.json`, +no per-port fixture. The corpus has four arms: -- **Resolution (28 cases).** Every case's `expectFiles`/`expectImported`/`expectSelected`/ +- **Resolution (36 cases).** Every case's `expectFiles`/`expectImported`/`expectSelected`/ `expectMigrateGoverned`/`expectLoadError` assertions. **TypeScript (the reference - implementation), Python, Java and C# all run all 28, identically**, with no exemption. The two + implementation), Python, Java and C# all run all 36, identically**, with no exemption. The two overlay cases that need a view child as incidental content use `view.currency` (the one concrete `view.*` subtype registered cross-port), not `view.text` — a prior revision used `view.text`, which Python did not register then, and carried a since-discharged allowlist for it. Kotlin inherits the Java run through the same loader and Maven plugin. +- **Ledger (7 of the resolution cases, `expectLedger` / `expectCoverageMeasured`).** Which loaded + requirements are this project's ledger (its own, plus a dependency's only when + `requirements.inherit` names the dependency's package) with each one's effective `@status`, and + whether object coverage is measured (never by an imported requirement). Each port asserts it + through its requirement gate's scan and again through its requirement-tests walk: TypeScript in + `cli/test/dependency-ledger-conformance.test.ts`, the other ports in their resolution runner. + An eighth case refuses a new requirement declared into a dependency's package + (`ERR_DEPENDENCY_PACKAGE_NOT_OWNED`) on the load-time path. - **Check (11 cases, `expectCheck`).** For each declared dependency, `current`, `drifted` or `unresolved` (a missing path, a bad manifest, a hash mismatch, or not yet in the lock). Run by TypeScript, in `cli/test/dependency-check-conformance.test.ts`, by Java in @@ -500,24 +509,25 @@ neutral one (`Resolve(null, dir)`), and the explicit metadata directory a `DependencyConformanceTests`; it runs the 11 check cases through `DependencyResolver.CheckDependencies` (S7) and skips the transport cases (C# never syncs). -### `fixtures/shared-model-conformance/` (11 cases) +### `fixtures/shared-model-conformance/` (15 cases) → [features/metadata-dependencies.md](features/metadata-dependencies.md) (the publisher's `sharedModelFile()`). A source tree under `source/`, plus `files` / `include` / `exclude` / -`version`, must produce **exactly** the pinned artifact and manifest bytes (seven cases), or be -refused for the pinned reason (four: an empty selection, a reference or `extends` outside the -selection with the `referrer → target` pairs named, and vocabulary only a consumer provider -registers). `requirement.*` and `template.*` nodes are always dropped, and the order of `files` -does not change the bytes. The manifest goldens carry the token `@@METAMODEL_VERSION@@` where +`version` / `requirements`, must produce **exactly** the pinned artifact and manifest bytes (nine +cases), or be refused for the pinned reason (six: an empty selection, a requirement alone +without `requirements`, a requirement claiming a node outside the selection, a reference or +`extends` outside the selection with the `referrer → target` pairs named, and vocabulary only a +consumer provider registers). `template.*` nodes are always dropped and `requirement.*` nodes +unless `requirements` is set, and the order of `files` does not change the bytes. The manifest goldens carry the token `@@METAMODEL_VERSION@@` where the manifest records the toolchain's `metamodelVersion`, so they do not move with it. -**TypeScript runs all 11**, in `codegen-ts/test/shared-model-conformance.test.ts`. **Python runs +**TypeScript runs all 15**, in `codegen-ts/test/shared-model-conformance.test.ts`. **Python runs the serializer arm**: for each publish case it loads `files`, takes the nodes the pinned manifest lists, and `serialize_shared_document` must reproduce the artifact byte for byte (and the sha256 the manifest records). Python has no publisher, so selection and the refusals are TypeScript's. -**Java runs all 11**, in `metadata`'s `SharedModelConformanceTest` against the `SharedModel` engine +**Java runs all 15**, in `metadata`'s `SharedModelConformanceTest` against the `SharedModel` engine the `shared-model` generator calls; **Kotlin** runs through that same engine and Maven goals and adds -only `KotlinSharedModelGeneratorTest`. **C# runs all 11**, in `SharedModelConformanceTests`. +only `KotlinSharedModelGeneratorTest`. **C# runs all 15**, in `SharedModelConformanceTests`. > **ADR-0055 (deferred overlay application) — SHIPPED in every port.** The nine cases added > for it (`overlay-mixed-file-base-in-later-file`, `overlay-mixed-file-base-in-earlier-file`, @@ -641,7 +651,7 @@ JSON and verify payload feeds it unchanged. The fixtures in the nine corpora mapped above (metamodel 449 + yaml 16 + verify 45 + render 18 + persistence 59 + api-contract 121 + source-resolution 25 + scope 10 + -dependency 39) each map to a feature doc, and so do the two requirement corpora, `shared-model-conformance`, the +dependency 47) each map to a feature doc, and so do the two requirement corpora, `shared-model-conformance`, the `cube-model` corpus and `explorer-conformance`, whose case lists live in their own READMEs. None are orphaned today. The remaining corpora in the totals table gate tooling contracts (registry manifests, provider composition, agent context, docs emit) rather than user-facing metamodel behaviour, diff --git a/docs/features/metadata-dependencies.md b/docs/features/metadata-dependencies.md index d188c5bf08..f3694b0672 100644 --- a/docs/features/metadata-dependencies.md +++ b/docs/features/metadata-dependencies.md @@ -401,6 +401,53 @@ scope too, whether or not it has any dependencies at all. `field.enum` reaches the generated `enums.ts` iff a *selected* entity's field resolves to it — decided by the using entity, never by the enum's own package. +## Inheriting a dependency's requirements + +A dependency published with `requirements: true` carries its requirements, and they load +with its model: an overlay of one resolves, and `meta verify` can see it. By default they +stay the **publisher's** ledger, not yours. The requirement gate does not check, count, +summarise or lint them, the `requirement-tests` generator writes no test for them, and the +requirements pages (`requirementsFile()`, the agent docs' `requirements.md`, an entity page's +"Required by") do not list them. +That is the same default as an imported entity's code generation, for the same reason: +you did not declare them. + +To take them on, name the dependency's package in `requirements.inherit`: + +```jsonc +// .metaobjects/config.json (consumer) +{ + "dependencies": [{ "name": "acme-common", "npm": "@acme/common-model" }], + "requirements": { "inherit": ["acme::common::**"] } +} +``` + +The inherited requirements then join your ledger: `meta verify` resolves their +`@implementedBy` against the loaded model and reports each by its status, and +`requirement-tests` scaffolds a test per claim. Change one's verdict for your project with +an overlay (same package, same name, `overlay: true`, a new `@status`); a NEW requirement +declared into the dependency's package is refused with `ERR_DEPENDENCY_PACKAGE_NOT_OWNED`, +as a new object there is. + +Three rules keep it predictable: + +- **A pattern must NAME the package.** `acme::common::**` (or a node pattern such as + `acme::common::Customers`) inherits `acme::common`; a bare `acme::common` names the + package `acme`, and `**` alone names nothing, so neither inherits it. The final segment + names a node, which is the explicit-include rule `scope.include` follows. +- **It is a separate key from `scope.include`.** Naming a package in `scope.include` + also generates code for it, which is not what taking on its requirements means. + `scope.include` alone inherits nothing. +- **An imported requirement never switches object coverage on**, inherited or not. Only a + requirement you wrote yourself does, as for a [library](libraries.md)'s requirements: + depending on a model must not enrol you in a gate you did not ask for. + +`requirements` refuses any key but `inherit`, so a misspelling fails the load instead of +quietly leaving the ledger out. A consumer on a toolchain older than this key treats a +published requirement as its own, so pin the toolchain before you publish with +`requirements: true` to a consumer you do not control. The manifest's `schema_version` does +not change. + ## What fails at load, when upstream moves The loader's own validation already fails your build the moment a target you built on @@ -473,6 +520,7 @@ export default defineConfig({ name: "acme-common", include: ["acme::common::**"], // exclude: ["acme::common::InternalOnly"], + // requirements: true, // also publish the selected requirement.* nodes (default false) // files: [...], // default: the run's own source files // version: "1.2.0", // default: the nearest package.json version target: "shared", @@ -490,13 +538,19 @@ it: 1. Loads `files` standalone with your project's own registry, strict. 2. Selects top-level nodes matching `include`/`exclude` — always excluding - `requirement.*` and `template.*` (a publisher's ledger and prompts are not a - consumer's shapes). + `template.*` (a publisher's prompts are not a consumer's shapes), and excluding + `requirement.*` unless `requirements: true`. With it, the publisher's ledger ships + with the model it describes, so a consumer can inherit it (see + [Inheriting a dependency's requirements](#inheriting-a-dependencys-requirements)). + Java and Kotlin take the same switch as the generator arg `requirements`, and C# as + `SharedModelGenerator.Requirements`. 3. **Checks the selection is closed** — every `extends` target and every ref-bearing attribute of a selected node (and its descendants) must resolve to another *selected* node, or the build fails naming the `(referrer → target)` pairs. This is what stops an internal shape from silently leaking through a dangling - reference. + reference. A published requirement's `@implementedBy` targets count as references + too: a requirement claiming a node you did not select is refused, so a consumer + never inherits a claim that cannot resolve. 4. **Re-loads the emitted artifact standalone with core providers only** — your provider vocabulary is not carried into the export; a Phase 1a export that needs it fails here, at publish time, not on a consumer's `meta deps sync`. @@ -785,8 +839,8 @@ but **not** built yet — do not assume any of the following exists: ## Verified by -- [`fixtures/dependency-conformance/`](../../fixtures/dependency-conformance/) — 39 - cases. 28 pin resolution (including `npm`, `python`, `maven` and `nuget` dependencies loading from their +- [`fixtures/dependency-conformance/`](../../fixtures/dependency-conformance/) — 47 + cases. 36 pin resolution (including `npm`, `python`, `maven` and `nuget` dependencies loading from their committed snapshot with nothing installed), the exhaustive `imported`/`inScope`/`inMigrateScope` sets, overlay/extends/reference behavior against a synced snapshot, and every load- and resolution-time error above, run by TypeScript (the reference implementation), @@ -795,22 +849,27 @@ but **not** built yet — do not assume any of the following exists: check (`current`, `drifted`, `unresolved`), run by TypeScript, Java (Kotlin through the same `metaobjects:verify` goal), Python (`metaobjects deps check`, `verify --deps`) and C# (`dotnet meta verify --deps`). - Three artifacts under `fixtures/dependency-conformance/artifacts/` are + Four artifacts under `fixtures/dependency-conformance/artifacts/` are pinned by sha256 in the README so the corpus itself can never silently drift. - Python's runner asserts all 28 resolution cases identically to TypeScript's, with no + Python's runner asserts all 36 resolution cases identically to TypeScript's, with no exemptions — the two overlay cases that need a view child as incidental content use `view.currency` (the one concrete `view.*` subtype registered cross-port, per `fixtures/registry-conformance/expected-registry.json`), not `view.text`, so they exercise the full imported/selected/governed assertions like every - other case. `transport-cases.json` beside it pins the `npm`, `python`, `maven` and `nuget` transports + other case. Seven resolution cases also pin the ledger (`expectLedger`, `expectCoverageMeasured`): + which requirements are the project's own and whether coverage is measured, asserted in + TypeScript, Python, Java and C# through each port's requirement gate and through its + `requirement-tests` identities walk, and in TypeScript through the rows the requirements + pages list (the documentation generators that list requirements are TypeScript-only). `transport-cases.json` beside it pins the `npm`, `python`, `maven` and `nuget` transports themselves (32 cases: packages laid out under a temp `node_modules`, on a temp Python import path, as a jar in a temp local Maven repository and as a package in a temp NuGet cache, the directory each resolves to, the exact lock `sync` writes, and each refusal), run by Node `meta deps sync`, the only writer. -- [`fixtures/shared-model-conformance/`](../../fixtures/shared-model-conformance/) — 11 cases +- [`fixtures/shared-model-conformance/`](../../fixtures/shared-model-conformance/) — 15 cases pinning what a publisher writes: the exact artifact and manifest bytes for a source tree and - `include` / `exclude` / `files`, and the refusals (an empty selection, a closure failure naming - every `referrer → target` pair, vocabulary a consumer's toolchain does not ship). TypeScript, Java + `include` / `exclude` / `files` / `requirements`, and the refusals (an empty selection, a + requirement claiming a node outside the selection, a closure failure naming every + `referrer → target` pair, vocabulary a consumer's toolchain does not ship). TypeScript, Java (Kotlin through the same engine) and C# run all of it; Python runs the serializer arm. ## See also diff --git a/docs/features/requirements.md b/docs/features/requirements.md index 8f072f87f4..86094d6ddb 100644 --- a/docs/features/requirements.md +++ b/docs/features/requirements.md @@ -380,9 +380,16 @@ reaches that base; a functional claim does not spread. What is counted is concre `object.entity` nodes: abstract entities, `object.value` and `object.projection` are not. **When coverage is measured.** Only when the project authored at least one requirement of -its own. A project whose only requirements came from a shipped library, with or without an -overlay on one of them, is not measured, and the summary says so instead of printing a -ratio. +its own. A project whose only requirements came from a shipped library or a metadata +dependency, with or without an overlay on one of them, is not measured, and the summary says +so instead of printing a ratio. + +**A dependency's requirements are not yours by default.** A shared model published with +`requirements: true` carries its requirements; they load, but the gate, the summary and the +`requirement-tests` generator leave them out unless `requirements.inherit` in +`.metaobjects/config.json` names the dependency's package. Inherited, they are checked and +counted like your own, and still never switch coverage on. See +[metadata-dependencies.md](metadata-dependencies.md#inheriting-a-dependencys-requirements). **The summary**, one line whenever the model declares a requirement: diff --git a/docs/ports/csharp.md b/docs/ports/csharp.md index ec80639894..a4a72b357c 100644 --- a/docs/ports/csharp.md +++ b/docs/ports/csharp.md @@ -114,7 +114,8 @@ A model published from another repository is declared under `dependencies` in reads both, at every rung of the source ladder, and never writes them: a snapshot that no longer matches the lock fails with `ERR_DEPENDENCY_SNAPSHOT_STALE`. The snapshot loads first, so your own metadata can `extends`, overlay or reference its nodes, but an imported node is not generated -(and is not counted by the requirement gate) unless `scope.include` names its package. What C# +unless `scope.include` names its package, and an imported requirement is not counted by the +requirement gate unless `requirements.inherit` names it. What C# does and does not do is in [Metadata dependencies](../features/metadata-dependencies.md). @@ -305,7 +306,8 @@ new SharedModelGenerator `` (from the project file, else the nearest `Directory.Build.props`). It writes nothing and names the option to change when the selection is empty, is not closed over `extends` and reference attributes, or needs vocabulary outside the library's. Give `OutDir` a directory that holds nothing -else. `requirement.*` and `template.*` nodes are never published. `dotnet meta eject shared-model` +else. `requirement.*` nodes are published only when `Requirements` is set (`requirements: true`, default +off); `template.*` nodes are never published. `dotnet meta eject shared-model` copies the generator into your project; the artifact bytes stay in the package, because a copy that changed them would publish a model a consumer's sync refuses. The consumer runs the Node `meta deps sync`, which stays the only writer of the lock and the snapshot. diff --git a/docs/ports/java.md b/docs/ports/java.md index d01f747798..3cd9e1343d 100644 --- a/docs/ports/java.md +++ b/docs/ports/java.md @@ -202,7 +202,8 @@ directory). `meta deps sync` (Node) is the only writer of the snapshot and `deps the Maven build reads them offline and refuses a stale or hand-edited snapshot with `ERR_DEPENDENCY_SNAPSHOT_STALE`. Your own entities can `extends` and reference the imported ones; the generators emit nothing for an imported object unless `scope.include` names its -package, and a new top-level node declared into a package a dependency owns fails with +package, an imported requirement counts toward the gate only when `requirements.inherit` names +its package, and a new top-level node declared into a package a dependency owns fails with `ERR_DEPENDENCY_PACKAGE_NOT_OWNED`. Kotlin builds inherit all of this. See [`metadata-dependencies.md`](../features/metadata-dependencies.md). @@ -802,7 +803,8 @@ Wire it like any generator: It writes the artifact and the manifest with the same bytes as the TypeScript `sharedModelFile()`: the shared corpus (`fixtures/shared-model-conformance/`) is the gate. The version comes from the -module's `` unless you pass `version`. Requirement and template nodes are never published. +module's `` unless you pass `version`. `requirement.*` nodes are published only when you pass +`true` (default off); `template.*` nodes are never published. Moving the artifact into a registry, and recording a consumer's snapshot and lock, is the Node `meta deps sync`'s job; this generator only produces the files. diff --git a/fixtures/dependency-conformance/README.md b/fixtures/dependency-conformance/README.md index 98dd19ed1a..5ec191b967 100644 --- a/fixtures/dependency-conformance/README.md +++ b/fixtures/dependency-conformance/README.md @@ -13,11 +13,13 @@ cases.json # { cases: [ { name, tree, treeFiles?, config, lock?, # resolveFrom?, expectFiles?, expectImported?, # expectSelected?, expectMigrateGoverned?, # expectLoadError?, expectErrorFiles?, expectError?, + # expectLedger?, expectCoverageMeasured?, # expectCheck? } ] } transport-cases.json # the npm / python / maven / nuget transport arm (Node `meta deps sync` only — see below) README.md artifacts/ # pinned dependency artifacts, referenced by cases via `treeFiles` acme-common-v1.json + acme-common-v1-requirements.json acme-common-v1-widened.json acme-common-v2-email-removed.json ``` @@ -42,6 +44,8 @@ artifacts/ # pinned dependency artifacts, referenced by cases via `tre // (undefined inMigrateScope admits everything) "expectLoadError": "ERR_*", // OPTIONAL: the collection resolves, then LOADING it fails with this code "expectErrorFiles": ["dep:…"], // OPTIONAL with expectLoadError: source.files[0] of the first error + "expectLedger": { "::": "" }, // OPTIONAL: the LEDGER arm, EXHAUSTIVE (see below) + "expectCoverageMeasured": true, // OPTIONAL with expectLedger: default false "expectError": "ERR_*", // resolution itself fails with this code "expectCheck": { "": "current" | "drifted" | "unresolved" } // the CHECK arm } ] } @@ -95,6 +99,18 @@ belong to the other. (`dep:/`) rather than a local one. - **`expectError`** — the resolution-failure arm: `resolveCollection` itself must reject with this exact code. +- **`expectLedger`** — OPTIONAL, alongside `expectFiles`: the LEDGER arm. The EXHAUSTIVE map, + over every loaded requirement, of the ones that are this project's own ledger, keyed + `::` (the bare path when the package is empty), each to its + effective `@status` (after overlays). A requirement belongs to the ledger unless its package + is a dependency's and `requirements.inherit` does not NAME that package (the same + explicit-include rule as `scope.include`; `**` names nothing). A port asserts the map through + its requirement gate's scan, and the same set of addresses through its requirement-tests + identities walk; TypeScript also asserts the paths its requirements pages list (the only port + with a generator that lists requirements). +- **`expectCoverageMeasured`** — OPTIONAL, alongside `expectLedger`, default `false`: whether + the gate measures object coverage. Only a requirement the project wrote itself switches it on; + an imported requirement never does, inherited or not, as a library's never does. - **`expectCheck`** — the check arm (`meta deps check` / `verify --deps`): for each declared dependency, resolve its `path` against the config's directory, read and validate the @@ -122,6 +138,10 @@ belong to the other. `field.string @maxLength: 120`). `acme-common-v1-widened.json` is identical except `@maxLength: 200` (a compatible widening). `acme-common-v2-email-removed.json` is identical except the whole `email` field child is absent (a breaking removal). +`acme-common-v1-requirements.json` is the base artifact plus the publisher's ledger, published +with `requirements: true`: `requirement.functional Customers` (live, claiming `Customer`, with a +`ReachableByEmail` child claiming `Customer.email`) and `requirement.architectural AuditedRows` +(live, claiming `Audited`). The shared-model corpus produces it byte for byte. Verify the bytes from the repo root: @@ -133,6 +153,7 @@ Expected, exactly: ``` sha256-10fbf886e22faceca32c56e5e647c3ff1c82f503e638cba3bd3aa9390f7c409d fixtures/dependency-conformance/artifacts/acme-common-v1.json +sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57 fixtures/dependency-conformance/artifacts/acme-common-v1-requirements.json sha256-fa00b9f3c54a2c302cf269af051589afc0a3217999ac82c54c77e33494638c36 fixtures/dependency-conformance/artifacts/acme-common-v1-widened.json sha256-c4ba364bff0071b164b127326c095d6d32915b57781271e0be64a7003c27ce7a fixtures/dependency-conformance/artifacts/acme-common-v2-email-removed.json ``` @@ -265,6 +286,9 @@ package are `ERR_DEPENDENCY_UNRESOLVED`; a `dir` that exists but holds no `metao - **Kotlin** — inherits via Java: it loads through the same loader and Maven plugin, and checks through the same `metaobjects:verify` goal. The Kotlin generators are covered by a codegen test that an imported entity emits nothing. +- **The ledger arm** (`expectLedger`) runs in every port but Kotlin, which shares Java's gate: + TypeScript `cli/test/dependency-ledger-conformance.test.ts` (the gate lives in the CLI + package), Python, Java and C# in the same runners named below. - **C#** — the resolution arm: resolution, load-time failure, lock/snapshot integrity, on the neutral source ladder and again through the explicit metadata directory (C# has no native config surface, so `.metaobjects/config.json` is where a dependency is declared at every diff --git a/fixtures/dependency-conformance/artifacts/acme-common-v1-requirements.json b/fixtures/dependency-conformance/artifacts/acme-common-v1-requirements.json new file mode 100644 index 0000000000..ee61ade5c2 --- /dev/null +++ b/fixtures/dependency-conformance/artifacts/acme-common-v1-requirements.json @@ -0,0 +1,109 @@ +{ + "metadata.root": { + "children": [ + { + "object.value": { + "name": "Address", + "package": "acme::common", + "children": [ + { + "field.string": { + "name": "city" + } + }, + { + "field.string": { + "name": "street" + } + } + ] + } + }, + { + "object.entity": { + "name": "Audited", + "package": "acme::common", + "abstract": true, + "children": [ + { + "field.timestamp": { + "name": "createdAt" + } + } + ] + } + }, + { + "requirement.architectural": { + "name": "AuditedRows", + "package": "acme::common", + "@counterexample": "An audited row with no creation time.", + "@implementedBy": [ + "Audited" + ], + "@statement": "Every audited row records when it was created.", + "@status": "live" + } + }, + { + "object.entity": { + "name": "Customer", + "package": "acme::common", + "children": [ + { + "source.rdb": { + "@table": "customers" + } + }, + { + "field.long": { + "name": "id" + } + }, + { + "field.string": { + "name": "email", + "@maxLength": 120 + } + }, + { + "identity.primary": { + "name": "pk", + "@fields": [ + "id" + ] + } + } + ] + } + }, + { + "requirement.functional": { + "name": "Customers", + "package": "acme::common", + "@counterexample": "Two rows for one customer.", + "@implementedBy": [ + "Customer" + ], + "@level": 4, + "@statement": "A customer is recorded once.", + "@status": "live", + "children": [ + { + "requirement.functional": { + "name": "ReachableByEmail", + "@counterexample": "A customer with no way to reach them.", + "@implementedBy": [ + "Customer.email" + ], + "@level": 5, + "@statement": "A customer carries an email address we can write to.", + "@status": "live" + } + } + ] + } + } + ] + } +} diff --git a/fixtures/dependency-conformance/cases.json b/fixtures/dependency-conformance/cases.json index 33b77b3083..a1ffe77359 100644 --- a/fixtures/dependency-conformance/cases.json +++ b/fixtures/dependency-conformance/cases.json @@ -425,6 +425,445 @@ ], "expectSelected": [] }, + { + "name": "an-imported-requirement-is-not-the-ledger-by-default", + "tree": { + "metaobjects/meta.app.json": "{\"metadata.root\":{\"package\":\"app\",\"children\":[{\"object.entity\":{\"name\":\"Order\",\"children\":[{\"source.rdb\":{\"@table\":\"orders\"}},{\"field.long\":{\"name\":\"id\"}},{\"identity.primary\":{\"name\":\"pk\",\"@fields\":[\"id\"]}}]}}]}}" + }, + "treeFiles": { + ".metaobjects/deps/acme-common/acme-common.metaobjects.json": "artifacts/acme-common-v1-requirements.json" + }, + "config": { + "schema_version": 1, + "sources": [], + "dependencies": [ + { + "name": "acme-common", + "path": "../acme-common/metaobjects" + } + ] + }, + "lock": { + "schema_version": 1, + "dependencies": { + "acme-common": { + "version": "1.1.0", + "metamodelVersion": "1.0", + "resolvedFrom": { + "path": "../acme-common/metaobjects" + }, + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::Audited", + "acme::common::AuditedRows", + "acme::common::Customer", + "acme::common::Customers" + ] + } + } + }, + "expectFiles": [ + ".metaobjects/deps/acme-common/acme-common.metaobjects.json", + "metaobjects/meta.app.json" + ], + "expectLedger": {}, + "expectCoverageMeasured": false + }, + { + "name": "an-own-requirement-beside-an-uninherited-dependency-ledger-is-the-whole-ledger", + "tree": { + "metaobjects/meta.app.json": "{\"metadata.root\":{\"package\":\"app\",\"children\":[{\"object.entity\":{\"name\":\"Order\",\"children\":[{\"source.rdb\":{\"@table\":\"orders\"}},{\"field.long\":{\"name\":\"id\"}},{\"identity.primary\":{\"name\":\"pk\",\"@fields\":[\"id\"]}}]}},{\"requirement.functional\":{\"name\":\"OrdersTaken\",\"@level\":4,\"@status\":\"live\",\"@statement\":\"An order is recorded when it is placed.\",\"@counterexample\":\"A placed order with no row.\",\"@implementedBy\":[\"Order\"]}}]}}" + }, + "treeFiles": { + ".metaobjects/deps/acme-common/acme-common.metaobjects.json": "artifacts/acme-common-v1-requirements.json" + }, + "config": { + "schema_version": 1, + "sources": [], + "dependencies": [ + { + "name": "acme-common", + "path": "../acme-common/metaobjects" + } + ] + }, + "lock": { + "schema_version": 1, + "dependencies": { + "acme-common": { + "version": "1.1.0", + "metamodelVersion": "1.0", + "resolvedFrom": { + "path": "../acme-common/metaobjects" + }, + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::Audited", + "acme::common::AuditedRows", + "acme::common::Customer", + "acme::common::Customers" + ] + } + } + }, + "expectFiles": [ + ".metaobjects/deps/acme-common/acme-common.metaobjects.json", + "metaobjects/meta.app.json" + ], + "expectLedger": { + "app::OrdersTaken": "live" + }, + "expectCoverageMeasured": true + }, + { + "name": "requirements-inherit-naming-the-package-takes-on-its-ledger", + "tree": { + "metaobjects/meta.app.json": "{\"metadata.root\":{\"package\":\"app\",\"children\":[{\"object.entity\":{\"name\":\"Order\",\"children\":[{\"source.rdb\":{\"@table\":\"orders\"}},{\"field.long\":{\"name\":\"id\"}},{\"identity.primary\":{\"name\":\"pk\",\"@fields\":[\"id\"]}}]}}]}}" + }, + "treeFiles": { + ".metaobjects/deps/acme-common/acme-common.metaobjects.json": "artifacts/acme-common-v1-requirements.json" + }, + "config": { + "schema_version": 1, + "sources": [], + "dependencies": [ + { + "name": "acme-common", + "path": "../acme-common/metaobjects" + } + ], + "requirements": { + "inherit": [ + "acme::common::**" + ] + } + }, + "lock": { + "schema_version": 1, + "dependencies": { + "acme-common": { + "version": "1.1.0", + "metamodelVersion": "1.0", + "resolvedFrom": { + "path": "../acme-common/metaobjects" + }, + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::Audited", + "acme::common::AuditedRows", + "acme::common::Customer", + "acme::common::Customers" + ] + } + } + }, + "expectFiles": [ + ".metaobjects/deps/acme-common/acme-common.metaobjects.json", + "metaobjects/meta.app.json" + ], + "expectLedger": { + "acme::common::AuditedRows": "live", + "acme::common::Customers": "live", + "acme::common::Customers.ReachableByEmail": "live" + }, + "expectCoverageMeasured": false + }, + { + "name": "a-wildcard-inherit-does-not-name-a-package", + "tree": { + "metaobjects/meta.app.json": "{\"metadata.root\":{\"package\":\"app\",\"children\":[{\"object.entity\":{\"name\":\"Order\",\"children\":[{\"source.rdb\":{\"@table\":\"orders\"}},{\"field.long\":{\"name\":\"id\"}},{\"identity.primary\":{\"name\":\"pk\",\"@fields\":[\"id\"]}}]}}]}}" + }, + "treeFiles": { + ".metaobjects/deps/acme-common/acme-common.metaobjects.json": "artifacts/acme-common-v1-requirements.json" + }, + "config": { + "schema_version": 1, + "sources": [], + "dependencies": [ + { + "name": "acme-common", + "path": "../acme-common/metaobjects" + } + ], + "requirements": { + "inherit": [ + "**" + ] + } + }, + "lock": { + "schema_version": 1, + "dependencies": { + "acme-common": { + "version": "1.1.0", + "metamodelVersion": "1.0", + "resolvedFrom": { + "path": "../acme-common/metaobjects" + }, + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::Audited", + "acme::common::AuditedRows", + "acme::common::Customer", + "acme::common::Customers" + ] + } + } + }, + "expectFiles": [ + ".metaobjects/deps/acme-common/acme-common.metaobjects.json", + "metaobjects/meta.app.json" + ], + "expectLedger": {}, + "expectCoverageMeasured": false + }, + { + "name": "a-scope-include-naming-the-package-does-not-inherit-its-requirements", + "tree": { + "metaobjects/meta.app.json": "{\"metadata.root\":{\"package\":\"app\",\"children\":[{\"object.entity\":{\"name\":\"Order\",\"children\":[{\"source.rdb\":{\"@table\":\"orders\"}},{\"field.long\":{\"name\":\"id\"}},{\"identity.primary\":{\"name\":\"pk\",\"@fields\":[\"id\"]}}]}}]}}" + }, + "treeFiles": { + ".metaobjects/deps/acme-common/acme-common.metaobjects.json": "artifacts/acme-common-v1-requirements.json" + }, + "config": { + "schema_version": 1, + "sources": [], + "dependencies": [ + { + "name": "acme-common", + "path": "../acme-common/metaobjects" + } + ], + "scope": { + "include": [ + "app::**", + "acme::common::**" + ] + } + }, + "lock": { + "schema_version": 1, + "dependencies": { + "acme-common": { + "version": "1.1.0", + "metamodelVersion": "1.0", + "resolvedFrom": { + "path": "../acme-common/metaobjects" + }, + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::Audited", + "acme::common::AuditedRows", + "acme::common::Customer", + "acme::common::Customers" + ] + } + } + }, + "expectFiles": [ + ".metaobjects/deps/acme-common/acme-common.metaobjects.json", + "metaobjects/meta.app.json" + ], + "expectLedger": {}, + "expectCoverageMeasured": false + }, + { + "name": "an-inherited-ledger-beside-an-own-requirement-measures-coverage", + "tree": { + "metaobjects/meta.app.json": "{\"metadata.root\":{\"package\":\"app\",\"children\":[{\"object.entity\":{\"name\":\"Order\",\"children\":[{\"source.rdb\":{\"@table\":\"orders\"}},{\"field.long\":{\"name\":\"id\"}},{\"identity.primary\":{\"name\":\"pk\",\"@fields\":[\"id\"]}}]}},{\"requirement.functional\":{\"name\":\"OrdersTaken\",\"@level\":4,\"@status\":\"live\",\"@statement\":\"An order is recorded when it is placed.\",\"@counterexample\":\"A placed order with no row.\",\"@implementedBy\":[\"Order\"]}}]}}" + }, + "treeFiles": { + ".metaobjects/deps/acme-common/acme-common.metaobjects.json": "artifacts/acme-common-v1-requirements.json" + }, + "config": { + "schema_version": 1, + "sources": [], + "dependencies": [ + { + "name": "acme-common", + "path": "../acme-common/metaobjects" + } + ], + "requirements": { + "inherit": [ + "acme::common::**" + ] + } + }, + "lock": { + "schema_version": 1, + "dependencies": { + "acme-common": { + "version": "1.1.0", + "metamodelVersion": "1.0", + "resolvedFrom": { + "path": "../acme-common/metaobjects" + }, + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::Audited", + "acme::common::AuditedRows", + "acme::common::Customer", + "acme::common::Customers" + ] + } + } + }, + "expectFiles": [ + ".metaobjects/deps/acme-common/acme-common.metaobjects.json", + "metaobjects/meta.app.json" + ], + "expectLedger": { + "acme::common::AuditedRows": "live", + "acme::common::Customers": "live", + "acme::common::Customers.ReachableByEmail": "live", + "app::OrdersTaken": "live" + }, + "expectCoverageMeasured": true + }, + { + "name": "an-overlay-of-an-inherited-requirement-changes-its-verdict-not-coverage", + "tree": { + "metaobjects/meta.app.json": "{\"metadata.root\":{\"package\":\"app\",\"children\":[{\"object.entity\":{\"name\":\"Order\",\"children\":[{\"source.rdb\":{\"@table\":\"orders\"}},{\"field.long\":{\"name\":\"id\"}},{\"identity.primary\":{\"name\":\"pk\",\"@fields\":[\"id\"]}}]}}]}}", + "metaobjects/meta.ext.json": "{\"metadata.root\":{\"package\":\"acme::common\",\"children\":[{\"requirement.functional\":{\"name\":\"Customers\",\"overlay\":true,\"@status\":\"partial\"}}]}}" + }, + "treeFiles": { + ".metaobjects/deps/acme-common/acme-common.metaobjects.json": "artifacts/acme-common-v1-requirements.json" + }, + "config": { + "schema_version": 1, + "sources": [], + "dependencies": [ + { + "name": "acme-common", + "path": "../acme-common/metaobjects" + } + ], + "requirements": { + "inherit": [ + "acme::common::**" + ] + } + }, + "lock": { + "schema_version": 1, + "dependencies": { + "acme-common": { + "version": "1.1.0", + "metamodelVersion": "1.0", + "resolvedFrom": { + "path": "../acme-common/metaobjects" + }, + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::Audited", + "acme::common::AuditedRows", + "acme::common::Customer", + "acme::common::Customers" + ] + } + } + }, + "expectFiles": [ + ".metaobjects/deps/acme-common/acme-common.metaobjects.json", + "metaobjects/meta.app.json", + "metaobjects/meta.ext.json" + ], + "expectLedger": { + "acme::common::AuditedRows": "live", + "acme::common::Customers": "partial", + "acme::common::Customers.ReachableByEmail": "live" + }, + "expectCoverageMeasured": false + }, + { + "name": "a-local-requirement-in-a-dependency-package-is-refused", + "tree": { + "metaobjects/meta.ext.json": "{\"metadata.root\":{\"package\":\"acme::common\",\"children\":[{\"requirement.functional\":{\"name\":\"Invoicing\",\"@level\":4,\"@status\":\"planned\",\"@statement\":\"Customers are invoiced.\",\"@counterexample\":\"A customer never invoiced.\"}}]}}" + }, + "treeFiles": { + ".metaobjects/deps/acme-common/acme-common.metaobjects.json": "artifacts/acme-common-v1-requirements.json" + }, + "config": { + "schema_version": 1, + "sources": [], + "dependencies": [ + { + "name": "acme-common", + "path": "../acme-common/metaobjects" + } + ], + "requirements": { + "inherit": [ + "acme::common::**" + ] + } + }, + "lock": { + "schema_version": 1, + "dependencies": { + "acme-common": { + "version": "1.1.0", + "metamodelVersion": "1.0", + "resolvedFrom": { + "path": "../acme-common/metaobjects" + }, + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::Audited", + "acme::common::AuditedRows", + "acme::common::Customer", + "acme::common::Customers" + ] + } + } + }, + "expectFiles": [ + ".metaobjects/deps/acme-common/acme-common.metaobjects.json", + "metaobjects/meta.ext.json" + ], + "expectLoadError": "ERR_DEPENDENCY_PACKAGE_NOT_OWNED" + }, { "name": "a-missing-lock-is-stale", "tree": { diff --git a/fixtures/shared-model-conformance/README.md b/fixtures/shared-model-conformance/README.md index bace05e1cd..f81c9fa186 100644 --- a/fixtures/shared-model-conformance/README.md +++ b/fixtures/shared-model-conformance/README.md @@ -44,10 +44,11 @@ Exactly one of `expectArtifact` + `expectManifest`, `expectRefusal` is present p token `@@METAMODEL_VERSION@@` there and a runner substitutes its own constant before comparing. `packages` and `nodes` are sorted, and `integrity` is the sha256 of the artifact's bytes. - **`expectRefusal.reason`** — one of: - - `empty-selection` — `include` / `exclude` select no node (`requirement.*` and `template.*` - never count). + - `empty-selection` — `include` / `exclude` select no node (`template.*` never counts, and + `requirement.*` counts only when `input.requirements` is `true`). - `not-closed` — a selected node `extends` or references (any ref-bearing attribute) a node - outside the selection. `pairs` is the EXHAUSTIVE list of `(referrer, target)` resolution + outside the selection, or a selected requirement's `@implementedBy` claim resolves to a node + outside it (only the owner segment counts; a claim that resolves nothing is not followed). `pairs` is the EXHAUSTIVE list of `(referrer, target)` resolution keys, sorted by referrer then target, which the error must name. - `non-core-vocabulary` — the selection loads with the publisher's own providers but not with core vocabulary alone, which is how a consumer loads it. @@ -57,8 +58,15 @@ Exactly one of `expectArtifact` + `expectManifest`, `expectRefusal` is present p ## Rules the cases pin -- `requirement.*` and `template.*` top-level nodes are never published, whatever `include` says - (`requirements-and-templates-are-always-dropped`). +- `template.*` top-level nodes are never published, whatever `include` says. `requirement.*` + nodes are published only when the case sets `input.requirements: true` + (`requirements-and-templates-are-dropped-by-default`, + `requirements-are-published-when-asked`, + `templates-are-dropped-when-requirements-are-published`, + `a-requirement-alone-is-an-empty-selection-by-default`). +- An exported requirement cannot claim a node the export leaves out: `@implementedBy` is not a + loader reference, but the closure check follows it + (`a-requirement-claiming-a-node-outside-the-selection-is-refused`). - The order of `files` does not change the bytes (`the-order-of-files-does-not-change-the-bytes`). - Nodes are sorted by resolution key; each carries its own `package`; `extends` is preserved, not flattened (`a-selection-spanning-two-packages-lists-both-sorted`). diff --git a/fixtures/shared-model-conformance/cases.json b/fixtures/shared-model-conformance/cases.json index 67bf34569a..00cf0fcc7a 100644 --- a/fixtures/shared-model-conformance/cases.json +++ b/fixtures/shared-model-conformance/cases.json @@ -91,7 +91,7 @@ "expectManifest": "expected/address-audited/metaobjects.pkg.json" }, { - "name": "requirements-and-templates-are-always-dropped", + "name": "requirements-and-templates-are-dropped-by-default", "input": { "name": "acme-common", "files": [ @@ -106,6 +106,95 @@ "expectArtifact": "expected/with-payloads/acme-common.metaobjects.json", "expectManifest": "expected/with-payloads/metaobjects.pkg.json" }, + { + "name": "requirements-are-published-when-asked", + "input": { + "name": "acme-common", + "files": [ + "source/meta.base.json", + "source/meta.customer.json", + "source/meta.ledger.json" + ], + "include": [ + "acme::common::**" + ], + "exclude": [ + "acme::common::KeepSecretsSafe", + "acme::common::Secret" + ], + "version": "1.1.0", + "requirements": true + }, + "expectArtifact": "../dependency-conformance/artifacts/acme-common-v1-requirements.json", + "expectManifest": "expected/with-requirements/metaobjects.pkg.json" + }, + { + "name": "templates-are-dropped-when-requirements-are-published", + "input": { + "name": "acme-common", + "files": [ + "source/meta.base.json", + "source/meta.prompts.json" + ], + "include": [ + "acme::common::**" + ], + "version": "0.4.0", + "requirements": true + }, + "expectArtifact": "expected/with-payloads-and-requirements/acme-common.metaobjects.json", + "expectManifest": "expected/with-payloads-and-requirements/metaobjects.pkg.json" + }, + { + "name": "a-requirement-alone-is-an-empty-selection-by-default", + "input": { + "name": "acme-common", + "files": [ + "source/meta.base.json", + "source/meta.customer.json", + "source/meta.ledger.json" + ], + "include": [ + "acme::common::Customers", + "acme::common::AuditedRows" + ], + "version": "1.0.0" + }, + "expectRefusal": { + "reason": "empty-selection" + } + }, + { + "name": "a-requirement-claiming-a-node-outside-the-selection-is-refused", + "input": { + "name": "acme-common", + "files": [ + "source/meta.base.json", + "source/meta.customer.json", + "source/meta.ledger.json" + ], + "include": [ + "acme::common::Address", + "acme::common::AuditedRows", + "acme::common::Customers" + ], + "version": "1.0.0", + "requirements": true + }, + "expectRefusal": { + "reason": "not-closed", + "pairs": [ + { + "referrer": "acme::common::AuditedRows", + "target": "acme::common::Audited" + }, + { + "referrer": "acme::common::Customers", + "target": "acme::common::Customer" + } + ] + } + }, { "name": "a-selection-spanning-two-packages-lists-both-sorted", "input": { diff --git a/fixtures/shared-model-conformance/expected/with-payloads-and-requirements/acme-common.metaobjects.json b/fixtures/shared-model-conformance/expected/with-payloads-and-requirements/acme-common.metaobjects.json new file mode 100644 index 0000000000..f0e2be9105 --- /dev/null +++ b/fixtures/shared-model-conformance/expected/with-payloads-and-requirements/acme-common.metaobjects.json @@ -0,0 +1,74 @@ +{ + "metadata.root": { + "children": [ + { + "object.value": { + "name": "Address", + "package": "acme::common", + "children": [ + { + "field.string": { + "name": "city" + } + }, + { + "field.string": { + "name": "street" + } + } + ] + } + }, + { + "object.value": { + "name": "AnswerPayload", + "package": "acme::common", + "children": [ + { + "field.string": { + "name": "text" + } + } + ] + } + }, + { + "requirement.functional": { + "name": "AnswersAreShort", + "package": "acme::common", + "@counterexample": "An answer that runs to three paragraphs.", + "@level": 5, + "@statement": "Every answer fits on one line.", + "@status": "live" + } + }, + { + "object.value": { + "name": "AskPayload", + "package": "acme::common", + "children": [ + { + "field.string": { + "name": "question" + } + } + ] + } + }, + { + "object.entity": { + "name": "Audited", + "package": "acme::common", + "abstract": true, + "children": [ + { + "field.timestamp": { + "name": "createdAt" + } + } + ] + } + } + ] + } +} diff --git a/fixtures/shared-model-conformance/expected/with-payloads-and-requirements/metaobjects.pkg.json b/fixtures/shared-model-conformance/expected/with-payloads-and-requirements/metaobjects.pkg.json new file mode 100644 index 0000000000..92a07d1cce --- /dev/null +++ b/fixtures/shared-model-conformance/expected/with-payloads-and-requirements/metaobjects.pkg.json @@ -0,0 +1,18 @@ +{ + "schema_version": 1, + "name": "acme-common", + "version": "0.4.0", + "metamodelVersion": "@@METAMODEL_VERSION@@", + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-651917937ce0797bd0308e81987c10ffebe22cd17eb9e08dc25809c7391f22a0", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::AnswerPayload", + "acme::common::AnswersAreShort", + "acme::common::AskPayload", + "acme::common::Audited" + ] +} diff --git a/fixtures/shared-model-conformance/expected/with-requirements/metaobjects.pkg.json b/fixtures/shared-model-conformance/expected/with-requirements/metaobjects.pkg.json new file mode 100644 index 0000000000..e3cc87bb15 --- /dev/null +++ b/fixtures/shared-model-conformance/expected/with-requirements/metaobjects.pkg.json @@ -0,0 +1,18 @@ +{ + "schema_version": 1, + "name": "acme-common", + "version": "1.1.0", + "metamodelVersion": "@@METAMODEL_VERSION@@", + "artifact": "acme-common.metaobjects.json", + "integrity": "sha256-4a812237fec408e10eaf1dfa25550cc642c9b3c0e41dc72581db8ba93c87eb57", + "packages": [ + "acme::common" + ], + "nodes": [ + "acme::common::Address", + "acme::common::Audited", + "acme::common::AuditedRows", + "acme::common::Customer", + "acme::common::Customers" + ] +} diff --git a/fixtures/shared-model-conformance/source/meta.ledger.json b/fixtures/shared-model-conformance/source/meta.ledger.json new file mode 100644 index 0000000000..16e21ad1e3 --- /dev/null +++ b/fixtures/shared-model-conformance/source/meta.ledger.json @@ -0,0 +1,44 @@ +{ + "metadata.root": { + "package": "acme::common", + "children": [ + { + "requirement.functional": { + "name": "Customers", + "@level": 4, + "@status": "live", + "@statement": "A customer is recorded once.", + "@counterexample": "Two rows for one customer.", + "@implementedBy": [ + "Customer" + ], + "children": [ + { + "requirement.functional": { + "name": "ReachableByEmail", + "@level": 5, + "@status": "live", + "@statement": "A customer carries an email address we can write to.", + "@counterexample": "A customer with no way to reach them.", + "@implementedBy": [ + "Customer.email" + ] + } + } + ] + } + }, + { + "requirement.architectural": { + "name": "AuditedRows", + "@status": "live", + "@statement": "Every audited row records when it was created.", + "@counterexample": "An audited row with no creation time.", + "@implementedBy": [ + "Audited" + ] + } + } + ] + } +} diff --git a/server/csharp/MetaObjects.Codegen/Generators/SharedModelGenerator.cs b/server/csharp/MetaObjects.Codegen/Generators/SharedModelGenerator.cs index 02ac797dfa..319822c697 100644 --- a/server/csharp/MetaObjects.Codegen/Generators/SharedModelGenerator.cs +++ b/server/csharp/MetaObjects.Codegen/Generators/SharedModelGenerator.cs @@ -3,7 +3,8 @@ // `meta deps sync`. The consumer's `meta deps check` / `dotnet meta verify --deps` then compares the two. // // This file decides what belongs to the PUBLISHING PROJECT: which of its source files may contribute -// (Files), which nodes are published (Include / Exclude) and which version is recorded (Version, else the +// (Files), which nodes are published (Include / Exclude, plus Requirements to add the selected +// requirement.* nodes) and which version is recorded (Version, else the // project's ). Everything a consumer checks is MetaObjects.Config.SharedModel's, in the package: // what is selected, that the selection is closed, the document's bytes, the hash over them and the // manifest's shape and file names. It is a reference helper (ADR-0034 Amendment 3): `dotnet meta eject @@ -62,6 +63,10 @@ public class SharedModelGenerator : IGenerator /// project's main load. The artifact must still load WITHOUT them: a consumer does not have them. public IReadOnlyList? Providers { get; init; } + /// Publish the selected requirement.* nodes too, so a consumer can inherit them. Default + /// false: shapes only. template.* is never published. + public bool Requirements { get; init; } + public IEnumerable Generate(GenContext ctx) { var name = Required(ModelName, nameof(ModelName), "the dependency key a consumer will sync under"); @@ -72,7 +77,7 @@ public IEnumerable Generate(GenContext ctx) var model = SharedModel.Build(new SharedModelInput( name, Files.Select(f => Path.GetFullPath(f, projectRoot)).ToList(), - Include, Exclude, Providers)); + Include, Exclude, Providers, Requirements)); // Resolved after the selection has passed every check, so a model that cannot be published says // so before a missing version does. diff --git a/server/csharp/MetaObjects.Conformance.Tests/DependencyConformanceTests.cs b/server/csharp/MetaObjects.Conformance.Tests/DependencyConformanceTests.cs index 3965bcf064..95f8ae1f99 100644 --- a/server/csharp/MetaObjects.Conformance.Tests/DependencyConformanceTests.cs +++ b/server/csharp/MetaObjects.Conformance.Tests/DependencyConformanceTests.cs @@ -11,6 +11,7 @@ using System.Text.Json; using MetaObjects; using MetaObjects.Config; +using MetaObjects.Core.Requirement; using MetaObjects.Meta; using MetaObjects.Source; using Xunit; @@ -192,7 +193,8 @@ private void AssertResolvedFiles(ResolvedMetadata resolved, JsonElement expectFi private static void AssertArms(JsonElement c, ResolvedMetadata resolved, string name) { var needsLoad = c.TryGetProperty("expectImported", out _) || c.TryGetProperty("expectSelected", out _) || - c.TryGetProperty("expectMigrateGoverned", out _) || c.TryGetProperty("expectLoadError", out _); + c.TryGetProperty("expectMigrateGoverned", out _) || c.TryGetProperty("expectLoadError", out _) || + c.TryGetProperty("expectLedger", out _); if (!needsLoad) return; var result = resolved.Load(); @@ -226,5 +228,22 @@ private static void AssertArms(JsonElement c, ResolvedMetadata resolved, string Assert.Equal(Sorted(Strings(expectSelected)), Sorted(topLevel.Where(imports.InScope))); if (c.TryGetProperty("expectMigrateGoverned", out var expectGoverned)) Assert.Equal(Sorted(Strings(expectGoverned)), Sorted(topLevel.Where(imports.InMigrateScope))); + if (c.TryGetProperty("expectLedger", out var expectLedger)) + { + // The LEDGER arm: which requirements are this project's own, keyed + // `::`, and whether object coverage is measured. + Assert.Same(imports, (result.Root as MetaRoot)?.ImportScope); + var scan = RequirementCheck.Scan(result.Root); + var ledger = scan.Addressed.ToDictionary( + a => RequirementTestIdentities.AddressOf(RequirementCheck.EffectivePackage(a.Node), a.Path), + a => a.Node.Status ?? "", StringComparer.Ordinal); + var expected = expectLedger.EnumerateObject().ToDictionary(p => p.Name, p => p.Value.GetString()!, StringComparer.Ordinal); + Assert.Equal(expected.OrderBy(kv => kv.Key, StringComparer.Ordinal), ledger.OrderBy(kv => kv.Key, StringComparer.Ordinal)); + var measured = c.TryGetProperty("expectCoverageMeasured", out var m) && m.GetBoolean(); + Assert.Equal(measured, scan.MeasureCoverage); + // The requirement-tests generator walks the same ledger: no test for the rest. + Assert.Equal(Sorted(expected.Keys), + Sorted(RequirementTestIdentities.Walk(result.Root).Select(w => RequirementTestIdentities.AddressOf(w.View.Package, w.View.Path)))); + } } } diff --git a/server/csharp/MetaObjects.Conformance.Tests/SharedModelConformanceTests.cs b/server/csharp/MetaObjects.Conformance.Tests/SharedModelConformanceTests.cs index 643801b093..42d2aaf76a 100644 --- a/server/csharp/MetaObjects.Conformance.Tests/SharedModelConformanceTests.cs +++ b/server/csharp/MetaObjects.Conformance.Tests/SharedModelConformanceTests.cs @@ -67,7 +67,8 @@ public void PublishesLikeTheReference(string caseName) var req = new SharedModelInput( input.GetProperty("name").GetString()!, Strings(input, "files").Select(f => Path.Combine(CorpusDir(), f)).ToList(), - Strings(input, "include"), Strings(input, "exclude"), providers); + Strings(input, "include"), Strings(input, "exclude"), providers, + input.TryGetProperty("requirements", out var reqs) && reqs.GetBoolean()); if (c.TryGetProperty("expectRefusal", out var refusal)) { diff --git a/server/csharp/MetaObjects/Config/Dependencies.cs b/server/csharp/MetaObjects/Config/Dependencies.cs index e551482230..f1419e2369 100644 --- a/server/csharp/MetaObjects/Config/Dependencies.cs +++ b/server/csharp/MetaObjects/Config/Dependencies.cs @@ -439,6 +439,9 @@ public sealed class ImportScope /// The project's declared migrate.scope, or null when it declares none. public IReadOnlyList? MigrateScope { get; } + /// The project's declared requirements.inherit, for the explicit-include rule. + public IReadOnlyList RequirementsInherit { get; private init; } = []; + private readonly CompiledScope? _migrate; private ImportScope(IReadOnlyList dependencies, IReadOnlyList scopeInclude, IReadOnlyList? migrateScope) @@ -469,7 +472,10 @@ public static ImportScope Resolve(string configDir, NeutralConfig? config) var resolved = specs.Count == 0 && lockEntries is null ? [] : DependencyResolver.VerifySnapshot(configDir, specs, lockEntries); - return new ImportScope(resolved, scopeInclude, migrateScope); + return new ImportScope(resolved, scopeInclude, migrateScope) + { + RequirementsInherit = config?.RequirementsInherit ?? [], + }; } /// Is in a package one of this project's dependencies owns? @@ -489,6 +495,18 @@ public bool InScope(string fqn) return !ImportedPackages.Contains(pkg) || DependencyResolver.ExplicitlyIncludes(ScopeInclude, pkg); } + /// + /// FR-023 — is the requirement at (<package>::<dotted path>) part of + /// this project's ledger? Its own requirements always are; a dependency's only when + /// requirements.inherit NAMES the dependency's package. Read by the requirement gate and the + /// requirement-tests generator. + /// + public bool InLedger(string fqn) + { + var pkg = DependencyResolver.PackageOf(fqn); + return !ImportedPackages.Contains(pkg) || DependencyResolver.ExplicitlyIncludes(RequirementsInherit, pkg); + } + /// /// The schema-side twin of : matchesScope(fqn, migrate.scope) and the /// same import rule against migrate.scope. True for everything when nothing is declared and @@ -524,8 +542,12 @@ public IReadOnlyList Sources() => // ADR-0039 SANCTIONED own-accessor case: a root-level scan. `MetaRoot` has no super, so own and // effective children are the same set here, and the question asked is precisely "what did this - // tree declare at the top level", which is the own layer by definition. - foreach (var node in root.Objects()) + // tree declare at the top level", which is the own layer by definition. Requirements too: a + // publisher may export its ledger, and a new requirement in its package would read as the + // publisher's to every gate that keys the ledger by package. + var topLevel = root.Objects().Cast() + .Concat(root.Children().Where(c => c.Type == MetaObjects.Shared.BaseTypes.TYPE_REQUIREMENT)); + foreach (var node in topLevel) { var key = node.ResolutionKey(); var pkg = DependencyResolver.PackageOf(key); diff --git a/server/csharp/MetaObjects/Config/NeutralConfig.cs b/server/csharp/MetaObjects/Config/NeutralConfig.cs index 50e3bb75b3..3631a49fa8 100644 --- a/server/csharp/MetaObjects/Config/NeutralConfig.cs +++ b/server/csharp/MetaObjects/Config/NeutralConfig.cs @@ -72,6 +72,12 @@ public sealed class NeutralConfig /// FR-023 — migrate.scope, or null when the project declares none. public IReadOnlyList? MigrateScope { get; } + /// + /// FR-023 — requirements.inherit: the dependencies whose requirements this project takes on + /// as its own ledger (). Empty when absent. + /// + public IReadOnlyList RequirementsInherit { get; private init; } = []; + /// /// The directory holding the .metaobjects/ folder this config was read from — where the lock and /// the committed dependency snapshots live beside it. @@ -282,7 +288,11 @@ private NeutralConfig( // lists read above, are IGNORED by design — see the file header. return new NeutralConfig(specs, libraries, new PhysicalNaming(columns, tables), ReadWire(root, path), ReadCSharp(root, path, configDir), dependencies, scopeInclude, migrateScope, - Path.GetFullPath(configDir)) { Enums = ReadEnums(root, path) }; + Path.GetFullPath(configDir)) + { + Enums = ReadEnums(root, path), + RequirementsInherit = ReadRequirementsInherit(root, path), + }; } } @@ -300,6 +310,23 @@ private static IReadOnlyList ReadDependencies(JsonElement root, return specs; } + /// FR-023 — requirements.inherit. Refused like naming: an unknown key inside + /// requirements would otherwise be a misspelt inherit that silently leaves the ledger out. + private static IReadOnlyList ReadRequirementsInherit(JsonElement root, string path) + { + if (!root.TryGetProperty("requirements", out var block) || block.ValueKind == JsonValueKind.Null) return []; + if (block.ValueKind != JsonValueKind.Object) + throw new MetaModelException($"{path}: \"requirements\" must be an object", ErrorCode.ERR_BAD_ATTR_VALUE); + foreach (var p in block.EnumerateObject()) + { + if (p.Name != "inherit") + throw new MetaModelException( + $"{path}: \"requirements\" has an unknown key \"{p.Name}\" (expected \"inherit\")", + ErrorCode.ERR_BAD_ATTR_VALUE); + } + return ReadPatterns(root, path, "requirements", "inherit") ?? []; + } + /// One pattern list nested in a TypeScript-owned block: `scope.include` or `migrate.scope`. The /// block must be an object when present and the list an array of non-empty strings; every OTHER key /// of the block is TypeScript's and is not read. Null when the block or the list is absent. diff --git a/server/csharp/MetaObjects/Config/SharedModel.cs b/server/csharp/MetaObjects/Config/SharedModel.cs index 16d9149483..2f6a6405df 100644 --- a/server/csharp/MetaObjects/Config/SharedModel.cs +++ b/server/csharp/MetaObjects/Config/SharedModel.cs @@ -21,6 +21,7 @@ using System.Text.Encodings.Web; using System.Text.Json; using System.Text.Json.Nodes; +using MetaObjects.Core.Requirement; using MetaObjects.Loader; using MetaObjects.Meta; @@ -69,12 +70,15 @@ public sealed class SharedModelRefusal( /// Applied after . /// The publisher's own vocabulary providers, so its extra attributes load as they /// did for the project's main load; empty is the library's own vocabulary. +/// Publish the selected requirement.* nodes too. False (the default) publishes +/// shapes only. template.* is never published. public sealed record SharedModelInput( string Name, IReadOnlyList Files, IReadOnlyList? Include = null, IReadOnlyList? Exclude = null, - IReadOnlyList? Providers = null); + IReadOnlyList? Providers = null, + bool Requirements = false); /// /// A selection that passed every check, serialized. The document is exactly the bytes that were re-loaded @@ -121,14 +125,17 @@ public static SharedModelBuilt Build(SharedModelInput input) // Step 2: select. The root has no super chain (ADR-0039 sanctioned own read). var scope = Scope.CompileScope(input.Include, input.Exclude); var selected = root.OwnChildren() - .Where(n => n.Type != TYPE_REQUIREMENT && n.Type != TYPE_TEMPLATE) + .Where(n => n.Type != TYPE_TEMPLATE) + // A published ledger is the publisher's decision: off unless asked for. + .Where(n => input.Requirements || n.Type != TYPE_REQUIREMENT) .Where(n => Scope.MatchesScope(n.ResolutionKey(), scope)) .ToList(); if (selected.Count == 0) { + var dropped = input.Requirements ? "template.*" : "requirement.* and template.*"; throw new SharedModelRefusal(SharedModelRefusalReason.EmptySelection, $"shared-model \"{input.Name}\": selected no nodes (include/exclude, always excluding " + - "requirement.* and template.*) - nothing to publish. Check `include`.", []); + $"{dropped}) - nothing to publish. Check `include`.", []); } // Step 3: closure. @@ -136,10 +143,17 @@ public static SharedModelBuilt Build(SharedModelInput input) var failures = CheckClosure(root, selected, selectedKeys); if (failures.Count > 0) { - var lines = string.Concat(failures.Select(p => $"\n {p.Referrer} -> {p.Target}")); + // Same sanctioned root-level own read as step 2: a template is never exported, so a + // reference to one can only be closed by excluding the referrer. + var templateKeys = root.OwnChildren().Where(n => n.Type == TYPE_TEMPLATE) + .Select(n => n.ResolutionKey()).ToHashSet(StringComparer.Ordinal); + var lines = string.Concat(failures.Select(p => $"\n {p.Referrer} -> {p.Target}: " + + (templateKeys.Contains(p.Target) + ? "templates are never exported; exclude the referrer" + : "include it or exclude the referrer"))); throw new SharedModelRefusal(SharedModelRefusalReason.NotClosed, $"shared-model \"{input.Name}\": the selection is not closed - these references point " + - "outside it; include it or exclude the referrer:" + lines, failures); + "outside it:" + lines, failures); } // Step 4: serialize (sorted by resolution key). @@ -232,10 +246,30 @@ private static List CheckClosure( { if (node.OwnAttr(name) is string s) candidates.Add(s); } + var targets = new List(); foreach (var raw in candidates) { var target = NamingRefs.ResolveObjectRef(root, NamingRefs.SplitChildTail(raw).Owner, referrerPkg); - if (target is null) continue; // already validated at load: defensive only + if (target is not null) targets.Add(target); // else already refused at load: defensive only + } + // A selected requirement's @implementedBy claims are followed too. They are not loader + // references (a planned claim may name a node that does not exist yet), but an exported + // requirement claiming a node the export leaves out would dangle in every consumer that + // inherits it. Owner segment only, in the requirement's effective package (ADR-0042); a + // claim that resolves nothing names nothing the export could carry. ADR-0039 sanctioned + // own-only read, as for the ref-bearing attrs above. + if (node.Type == TYPE_REQUIREMENT && node.OwnAttr(REQUIREMENT_ATTR_IMPLEMENTED_BY) is IReadOnlyList claims) + { + var claimPkg = RequirementCheck.EffectivePackage(node); + foreach (var reference in claims) + { + var owner = RequirementClaims.ResolveClaimTarget( + root, RequirementClaims.SplitMemberRef(reference).Owner, claimPkg); + if (owner is not null) targets.Add(owner); + } + } + foreach (var target in targets) + { var targetKey = target.ResolutionKey(); if (selectedKeys.Contains(targetKey)) continue; var pair = new SharedModelPair(referrerKey, targetKey); diff --git a/server/csharp/MetaObjects/Core/Requirement/RequirementCheck.cs b/server/csharp/MetaObjects/Core/Requirement/RequirementCheck.cs index 812c81e60f..0858b5946a 100644 --- a/server/csharp/MetaObjects/Core/Requirement/RequirementCheck.cs +++ b/server/csharp/MetaObjects/Core/Requirement/RequirementCheck.cs @@ -21,6 +21,7 @@ // or that a claimed node implements the requirement claiming it. using System.Globalization; +using MetaObjects.Config; using MetaObjects.Library; using MetaObjects.Meta; @@ -152,11 +153,11 @@ public static string EffectivePackage(MetaData node) /// public static RequirementScan Scan(MetaData root, bool? measureCoverage = null, bool requireImplementers = false) { - var addressed = CollectAddressed(root); + var addressed = CollectLedger(root); return new RequirementScan( addressed, ClaimedObjectKeys(root, addressed.Select(a => a.Node)), - measureCoverage ?? ProjectAuthoredRequirements(addressed), + measureCoverage ?? ProjectAuthoredRequirements(addressed, (root as MetaRoot)?.ImportScope), requireImplementers); } @@ -167,10 +168,31 @@ public static RequirementScan Scan(MetaData root, bool? measureCoverage = null, /// PACKAGE, a manifest fact. An overlay on a library requirement stays in the library's /// package and does not activate coverage. /// - private static bool ProjectAuthoredRequirements(IReadOnlyList addressed) + private static bool ProjectAuthoredRequirements(IReadOnlyList addressed, ImportScope? imports) { var libraryPackages = LibrarySources.LibraryPackages(); - return addressed.Any(a => !libraryPackages.Contains(EffectivePackage(a.Node))); + // FR-023: a dependency's requirement, inherited or not, is the publisher's design for the same + // reason a library's is, and cannot switch coverage on either. + return addressed.Any(a => + { + var pkg = EffectivePackage(a.Node); + return !libraryPackages.Contains(pkg) + && !(imports?.Imported(RequirementTestIdentities.AddressOf(pkg, a.Path)) ?? false); + }); + } + + /// + /// The requirements that are this project's ledger: every loaded requirement but a dependency's + /// that requirements.inherit does not name (, read from the + /// root). One left out is still loaded, so an overlay of it resolves, and nothing here or in the + /// requirement-tests generator addresses it. + /// + public static IReadOnlyList CollectLedger(MetaData root) + { + var imports = (root as MetaRoot)?.ImportScope; + var all = CollectAddressed(root); + if (imports is null) return all; + return all.Where(a => imports.InLedger(RequirementTestIdentities.AddressOf(EffectivePackage(a.Node), a.Path))).ToList(); } /// diff --git a/server/csharp/MetaObjects/Core/Requirement/RequirementTestIdentities.cs b/server/csharp/MetaObjects/Core/Requirement/RequirementTestIdentities.cs index aa4af1fdea..ebbec262d3 100644 --- a/server/csharp/MetaObjects/Core/Requirement/RequirementTestIdentities.cs +++ b/server/csharp/MetaObjects/Core/Requirement/RequirementTestIdentities.cs @@ -155,7 +155,9 @@ public static bool DefaultFilter(RequirementView view) => public static IReadOnlyList Walk(MetaData root) { var output = new List(); - foreach (var addressed in RequirementCheck.CollectAddressed(root)) + // FR-023: only this project's ledger. A dependency's requirement it did not inherit + // (`requirements.inherit`) is loaded and gets no test. + foreach (var addressed in RequirementCheck.CollectLedger(root)) { var node = addressed.Node; // One effective package, shared with the gate. diff --git a/server/java/codegen-base/src/main/java/com/metaobjects/generator/SharedModelGenerator.java b/server/java/codegen-base/src/main/java/com/metaobjects/generator/SharedModelGenerator.java index 89de68618c..f2707071b3 100644 --- a/server/java/codegen-base/src/main/java/com/metaobjects/generator/SharedModelGenerator.java +++ b/server/java/codegen-base/src/main/java/com/metaobjects/generator/SharedModelGenerator.java @@ -26,8 +26,9 @@ *

Args: {@code outputDir}, {@code name} (the dependency key a consumer syncs under; the artifact * is {@code .metaobjects.json}), {@code include} (comma-separated scope patterns, such as * {@code acme::common::**}), {@code files} (comma-separated metadata files that may contribute), - * and optionally {@code exclude} (applied after {@code include}) and {@code version} (default: the - * project's version).

+ * and optionally {@code exclude} (applied after {@code include}), {@code version} (default: the + * project's version) and {@code requirements} ({@code true} publishes the selected + * {@code requirement.*} nodes as well; default {@code false}).

*/ public class SharedModelGenerator extends FileEmittingGenerator { @@ -36,6 +37,7 @@ public class SharedModelGenerator extends FileEmittingGenerator { public static final String ARG_EXCLUDE = "exclude"; public static final String ARG_FILES = "files"; public static final String ARG_VERSION = "version"; + public static final String ARG_REQUIREMENTS = "requirements"; @Override protected List generate(MetaDataLoader loader) { @@ -49,7 +51,11 @@ protected List generate(MetaDataLoader loader) { // The providers the project's own load used, so its extra attributes load here too. List providers = loader.getLoaderOptions().getProviders(); - SharedModel.Built model = SharedModel.build(new SharedModel.Input(name, files, include, exclude, providers)); + // Publishing the ledger is opt-in: "true" adds the selected requirement.* nodes. + boolean requirements = hasArg(ARG_REQUIREMENTS) && Boolean.parseBoolean(getArg(ARG_REQUIREMENTS).trim()); + + SharedModel.Built model = SharedModel.build( + new SharedModel.Input(name, files, include, exclude, providers, requirements)); // Resolved after the selection has passed every check, so a model that cannot be published // says so before a missing version does. diff --git a/server/java/codegen-base/src/test/java/com/metaobjects/generator/SharedModelGeneratorTest.java b/server/java/codegen-base/src/test/java/com/metaobjects/generator/SharedModelGeneratorTest.java index 8763039b66..3d24185927 100644 --- a/server/java/codegen-base/src/test/java/com/metaobjects/generator/SharedModelGeneratorTest.java +++ b/server/java/codegen-base/src/test/java/com/metaobjects/generator/SharedModelGeneratorTest.java @@ -68,6 +68,21 @@ private static Map args(Path out) { .replace("@@METAMODEL_VERSION@@", RegistryManifest.METAMODEL_VERSION), manifest); } + @Test public void theRequirementsArgPublishesTheLedgerTheCorpusPins() throws Exception { + Path out = Files.createTempDirectory("shared-model-gen-"); + SharedModelGenerator g = new SharedModelGenerator(); + Map a = with(with(with(args(out), "version", "1.1.0"), "requirements", "true"), + "exclude", "acme::common::KeepSecretsSafe,acme::common::Secret"); + g.setArgs(with(a, "files", a.get("files") + "," + corpus().resolve("source/meta.ledger.json"))); + g.execute(loader()); + + assertEquals(Files.readString(corpus().resolve("../dependency-conformance/artifacts/acme-common-v1-requirements.json").normalize(), StandardCharsets.UTF_8), + Files.readString(out.resolve("acme-common.metaobjects.json"), StandardCharsets.UTF_8)); + assertEquals(Files.readString(corpus().resolve("expected/with-requirements/metaobjects.pkg.json"), StandardCharsets.UTF_8) + .replace("@@METAMODEL_VERSION@@", RegistryManifest.METAMODEL_VERSION), + Files.readString(out.resolve("metaobjects.pkg.json"), StandardCharsets.UTF_8)); + } + @Test public void aBlankVersionArgIsRefused() throws Exception { Path out = Files.createTempDirectory("shared-model-gen-"); SharedModelGenerator g = new SharedModelGenerator(); diff --git a/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinSharedModelGenerator.kt b/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinSharedModelGenerator.kt index f8aab0223a..b3efd5782b 100644 --- a/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinSharedModelGenerator.kt +++ b/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinSharedModelGenerator.kt @@ -23,7 +23,8 @@ import java.nio.file.Path * Args: `outputDir`, `name` (the dependency key a consumer syncs under; the artifact is * `.metaobjects.json`), `include` (comma-separated scope patterns, such as * `acme::common::**`), `files` (comma-separated metadata files that may contribute), and - * optionally `exclude` (applied after `include`) and `version` (default: the project's version). + * optionally `exclude` (applied after `include`), `version` (default: the project's version) and + * `requirements` (`true` publishes the selected `requirement.*` nodes as well; default `false`). */ open class KotlinSharedModelGenerator : FileEmittingGenerator() { @@ -35,7 +36,10 @@ open class KotlinSharedModelGenerator : FileEmittingGenerator() { // The providers the project's own load used, so its extra attributes load here too. val providers = loader.loaderOptions.providers - val model = SharedModel.build(SharedModel.Input(name, files, include, exclude, providers)) + // Publishing the ledger is opt-in: "true" adds the selected requirement.* nodes. + val requirements = hasArg(ARG_REQUIREMENTS) && getArg(ARG_REQUIREMENTS).trim().toBoolean() + + val model = SharedModel.build(SharedModel.Input(name, files, include, exclude, providers, requirements)) // Resolved after the selection has passed every check, so a model that cannot be published // says so before a missing version does. @@ -68,5 +72,6 @@ open class KotlinSharedModelGenerator : FileEmittingGenerator() { const val ARG_EXCLUDE = "exclude" const val ARG_FILES = "files" const val ARG_VERSION = "version" + const val ARG_REQUIREMENTS = "requirements" } } diff --git a/server/java/metadata/src/main/java/com/metaobjects/config/Dependencies.java b/server/java/metadata/src/main/java/com/metaobjects/config/Dependencies.java index b7320cb732..6a834d6731 100644 --- a/server/java/metadata/src/main/java/com/metaobjects/config/Dependencies.java +++ b/server/java/metadata/src/main/java/com/metaobjects/config/Dependencies.java @@ -636,8 +636,12 @@ public static void refuseUnownedPackages(MetaRoot root, Set importedPack if (importedPackages == null || importedPackages.isEmpty()) return; // ADR-0039 SANCTIONED own-accessor case: a root-level scan. MetaRoot has no super, so own // and effective children are the same set, and the question is "what did this tree declare - // at the top level", which is the own layer by definition. - for (MetaObject node : root.getChildren(MetaObject.class, false)) { + // at the top level", which is the own layer by definition. Requirements too: a publisher may + // export its ledger, and a new requirement in its package would read as the publisher's to + // every gate that keys the ledger by package. + List topLevel = new ArrayList<>(root.getChildren(MetaObject.class, false)); + topLevel.addAll(root.getChildren(com.metaobjects.requirement.MetaRequirement.class, false)); + for (MetaData node : topLevel) { String key = node.getName(); String pkg = packageOf(key); if (!importedPackages.contains(pkg) || importedNodes.contains(key)) continue; diff --git a/server/java/metadata/src/main/java/com/metaobjects/config/DependencySet.java b/server/java/metadata/src/main/java/com/metaobjects/config/DependencySet.java index 93b7357477..2bf78990af 100644 --- a/server/java/metadata/src/main/java/com/metaobjects/config/DependencySet.java +++ b/server/java/metadata/src/main/java/com/metaobjects/config/DependencySet.java @@ -44,18 +44,20 @@ public final class DependencySet { /** The set of a project that declares no dependencies. */ public static final DependencySet EMPTY = - new DependencySet(List.of(), List.of(), null); + new DependencySet(List.of(), List.of(), null, List.of()); private final List dependencies; private final List scopeInclude; private final List migrateScope; + private final List requirementsInherit; private final Set importedPackages; private final Set importedNodes; private final Scope.Compiled declaredMigrateScope; private DependencySet(List dependencies, List scopeInclude, - List migrateScope) { + List migrateScope, List requirementsInherit) { this.dependencies = List.copyOf(dependencies); + this.requirementsInherit = List.copyOf(requirementsInherit); this.scopeInclude = List.copyOf(scopeInclude); this.migrateScope = migrateScope == null ? null : List.copyOf(migrateScope); Set packages = new HashSet<>(); @@ -88,7 +90,8 @@ public static DependencySet of(Path configDir, Optional config) { List resolved = specs.isEmpty() && lock.isEmpty() ? List.of() : Dependencies.verifySnapshot(configDir, specs, lock); - return new DependencySet(resolved, include, migrate); + return new DependencySet(resolved, include, migrate, + config.map(NeutralConfig::getRequirementsInherit).orElse(List.of())); } /** @@ -114,7 +117,8 @@ public static DependencySet ofSnapshot(Optional config, List resolved = declared.isEmpty() && lock.isEmpty() ? List.of() : Dependencies.verifySnapshot(declared, lock, reader); - return new DependencySet(resolved, include, migrate); + return new DependencySet(resolved, include, migrate, + config.map(NeutralConfig::getRequirementsInherit).orElse(List.of())); } /** The resolved dependencies, in dependency-NAME order. */ @@ -162,6 +166,18 @@ public boolean inScope(String fqn) { return Dependencies.explicitlyIncludes(scopeInclude, pkg); } + /** + * FR-023 — is the requirement at {@code fqn} ({@code ::}) part of this + * project's ledger? Its own requirements always are; a dependency's only when + * {@code requirements.inherit} NAMES the dependency's package. Read by the requirement gate and + * the requirement-tests generators. + */ + public boolean inLedger(String fqn) { + String pkg = Dependencies.packageOf(fqn); + if (!importedPackages.contains(pkg)) return true; + return Dependencies.explicitlyIncludes(requirementsInherit, pkg); + } + /** * The {@code migrate.scope}-governed predicate, or empty when the project declares no * {@code migrate.scope} AND imports nothing (empty means "govern everything loaded"). diff --git a/server/java/metadata/src/main/java/com/metaobjects/config/NeutralConfig.java b/server/java/metadata/src/main/java/com/metaobjects/config/NeutralConfig.java index 7dd784ab73..eca092fcd3 100644 --- a/server/java/metadata/src/main/java/com/metaobjects/config/NeutralConfig.java +++ b/server/java/metadata/src/main/java/com/metaobjects/config/NeutralConfig.java @@ -70,6 +70,7 @@ public final class NeutralConfig { private final PhysicalNaming physicalNaming; private final WireFormat wireFormat; private EnumDefaults enumDefaults = EnumDefaults.DEFAULT; + private List requirementsInherit = List.of(); private NeutralConfig(List> sources, List> dependencies, List scopeInclude, List migrateScope, @@ -120,6 +121,15 @@ public List getMigrateScope() { return migrateScope; } + /** + * FR-023 — the declared {@code requirements.inherit} patterns: the dependencies whose + * requirements this project takes on as its own ledger ({@link DependencySet#inLedger}). + * Empty when the key is absent. + */ + public List getRequirementsInherit() { + return requirementsInherit; + } + /** * ADR-0058 — the project's physical-naming rules ({@code naming} in this file), each * absent rule at its default. Never {@code null}. @@ -338,6 +348,7 @@ public static NeutralConfig parse(String content, String origin) { NeutralConfig cfg = new NeutralConfig(specs, dependencies, scopeInclude, migrateScope, physicalNaming, wireFormat); cfg.enumDefaults = parseEnums(root.get("enums"), origin); + cfg.requirementsInherit = parseRequirementsInherit(root.get("requirements"), origin); return cfg; } @@ -467,6 +478,25 @@ private static List parseScopeInclude(JsonElement scope, String origin) return stringArray(include, "scope.include", origin); } + /** + * FR-023 — {@code requirements.inherit}. Refused like {@code naming}: an unknown key inside + * {@code requirements} would otherwise be a misspelt {@code inherit} that silently leaves the + * ledger out. + */ + private static List parseRequirementsInherit(JsonElement requirements, String origin) { + if (requirements == null || requirements.isJsonNull()) return List.of(); + if (!requirements.isJsonObject()) throw bad(origin + ": \"requirements\" must be an object"); + JsonObject obj = requirements.getAsJsonObject(); + for (String key : obj.keySet()) { + if (!"inherit".equals(key)) { + throw bad(origin + ": \"requirements\" has unknown key \"" + key + "\"; expected \"inherit\""); + } + } + JsonElement inherit = obj.get("inherit"); + if (inherit == null || inherit.isJsonNull()) return List.of(); + return stringArray(inherit, "requirements.inherit", origin); + } + /** {@code migrate.scope}, or {@code null} when absent; every other {@code migrate} key is ignored. */ private static List parseMigrateScope(JsonElement migrate, String origin) { if (migrate == null || migrate.isJsonNull()) return null; diff --git a/server/java/metadata/src/main/java/com/metaobjects/config/SharedModel.java b/server/java/metadata/src/main/java/com/metaobjects/config/SharedModel.java index adfc952483..4be477c50d 100644 --- a/server/java/metadata/src/main/java/com/metaobjects/config/SharedModel.java +++ b/server/java/metadata/src/main/java/com/metaobjects/config/SharedModel.java @@ -31,7 +31,11 @@ import com.metaobjects.loader.References; import com.metaobjects.registry.MetaDataTypeProvider; import com.metaobjects.registry.RegistryManifest; +import com.metaobjects.MetaRoot; +import com.metaobjects.validation.SymbolTable; import com.metaobjects.requirement.MetaRequirement; +import com.metaobjects.requirement.RequirementCheck; +import com.metaobjects.requirement.RequirementClaims; import com.metaobjects.template.TemplateConstants; import java.nio.charset.StandardCharsets; @@ -131,9 +135,17 @@ public List pairs() { * @param exclude applied after {@code include} * @param providers the publisher's own vocabulary providers, so its extra attributes load as * they did for the project's main load; empty = core vocabulary + * @param requirements publish the selected {@code requirement.*} nodes too; false (the default) + * publishes shapes only. {@code template.*} is never published. */ public record Input(String name, List files, List include, List exclude, - List providers) { + List providers, boolean requirements) { + /** Shapes only: no requirements, as before the option existed. */ + public Input(String name, List files, List include, List exclude, + List providers) { + this(name, files, include, exclude, providers, false); + } + public Input { files = List.copyOf(files); include = include == null ? List.of() : List.copyOf(include); @@ -179,14 +191,16 @@ public static Built build(Input input) { List selected = new ArrayList<>(); for (MetaData node : root.getChildren(MetaData.class, false)) { if (node instanceof MetaAttribute) continue; - if (MetaRequirement.TYPE_REQUIREMENT.equals(node.getType()) - || TemplateConstants.TYPE_TEMPLATE.equals(node.getType())) continue; + if (TemplateConstants.TYPE_TEMPLATE.equals(node.getType())) continue; + // A published ledger is the publisher's decision: off unless asked for. + if (!input.requirements() && MetaRequirement.TYPE_REQUIREMENT.equals(node.getType())) continue; if (Scope.matchesScope(node.getName(), scope)) selected.add(node); } if (selected.isEmpty()) { + String dropped = input.requirements() ? "template.*" : "requirement.* and template.*"; throw new Refusal(Reason.EMPTY_SELECTION, "shared-model \"" + input.name() + "\": selected no nodes (include/exclude, always excluding " - + "requirement.* and template.*) - nothing to publish. Check `include`.", List.of()); + + dropped + ") - nothing to publish. Check `include`.", List.of()); } // Step 3: closure. @@ -194,11 +208,22 @@ public static Built build(Input input) { for (MetaData n : selected) selectedKeys.add(n.getName()); List failures = checkClosure(root, selected, selectedKeys); if (!failures.isEmpty()) { + // Same sanctioned root-level own read as step 2: a template is never exported, so a + // reference to one can only be closed by excluding the referrer. + Set templateKeys = new HashSet<>(); + for (MetaData n : root.getChildren(MetaData.class, false)) { + if (TemplateConstants.TYPE_TEMPLATE.equals(n.getType())) templateKeys.add(n.getName()); + } StringBuilder lines = new StringBuilder(); - for (Pair p : failures) lines.append("\n ").append(p.referrer()).append(" -> ").append(p.target()); + for (Pair p : failures) { + lines.append("\n ").append(p.referrer()).append(" -> ").append(p.target()) + .append(templateKeys.contains(p.target()) + ? ": templates are never exported; exclude the referrer" + : ": include it or exclude the referrer"); + } throw new Refusal(Reason.NOT_CLOSED, "shared-model \"" + input.name() + "\": the selection is not closed - these references point " - + "outside it; include it or exclude the referrer:" + lines, failures); + + "outside it:" + lines, failures); } // Step 4: serialize (sorted by resolution key). @@ -285,6 +310,7 @@ private static void walkOwn(MetaData node, List out) { private static List checkClosure(MetaData root, List selected, Set selectedKeys) { Set seen = new LinkedHashSet<>(); + SymbolTable symbols = root instanceof MetaRoot mr ? SymbolTable.build(mr) : null; for (MetaData top : selected) { String referrerKey = top.getName(); List walk = new ArrayList<>(); @@ -300,11 +326,28 @@ private static List checkClosure(MetaData root, List selected, S Object value = attr.getValue(); if (value instanceof String s) candidates.add(s); } - if (candidates.isEmpty()) continue; - String referrerPkg = References.effectivePackageOf(node); - for (String raw : candidates) { - MetaData resolved = References.resolveObjectRef(root, References.splitChildTail(raw).owner(), referrerPkg).node(); - if (resolved == null) continue; // already validated at load: defensive only + List targets = new ArrayList<>(); + if (!candidates.isEmpty()) { + String referrerPkg = References.effectivePackageOf(node); + for (String raw : candidates) { + MetaData resolved = References.resolveObjectRef(root, References.splitChildTail(raw).owner(), referrerPkg).node(); + if (resolved != null) targets.add(resolved); // else already refused at load: defensive only + } + } + // A selected requirement's @implementedBy claims are followed too. They are not loader + // references (a planned claim may name a node that does not exist yet), but an exported + // requirement claiming a node the export leaves out would dangle in every consumer that + // inherits it. Owner segment only, in the requirement's effective package (ADR-0042); a + // claim that resolves nothing names nothing the export could carry. + if (node instanceof MetaRequirement && symbols != null) { + String claimPkg = RequirementCheck.effectivePackage(node); + for (String ref : ownImplementedBy(node)) { + MetaData owner = RequirementClaims.resolveClaimTarget((MetaRoot) root, symbols, + RequirementClaims.splitMemberRef(ref).owner(), claimPkg); + if (owner != null) targets.add(owner); + } + } + for (MetaData resolved : targets) { String targetKey = resolved.getName(); if (selectedKeys.contains(targetKey)) continue; seen.add(new Pair(referrerKey, targetKey)); @@ -315,4 +358,20 @@ private static List checkClosure(MetaData root, List selected, S pairs.sort(Comparator.comparing(Pair::referrer).thenComparing(Pair::target)); return pairs; } + + /** The {@code @implementedBy} values declared on this node's OWN layer. ADR-0039 sanctioned own-only + * case, as for the ref-bearing attrs: the closure walks exactly what will be emitted. */ + private static List ownImplementedBy(MetaData node) { + List out = new ArrayList<>(); + for (MetaAttribute attr : node.getMetaAttrs(false)) { + if (!MetaRequirement.ATTR_IMPLEMENTED_BY.equals(attr.getName())) continue; + Object value = attr.getValue(); + if (value instanceof List list) { + for (Object v : list) if (v instanceof String s) out.add(s); + } else if (value instanceof String s && !s.isBlank()) { + out.add(s); + } + } + return out; + } } diff --git a/server/java/metadata/src/main/java/com/metaobjects/requirement/RequirementCheck.java b/server/java/metadata/src/main/java/com/metaobjects/requirement/RequirementCheck.java index ba5d532de5..4dfe49e302 100644 --- a/server/java/metadata/src/main/java/com/metaobjects/requirement/RequirementCheck.java +++ b/server/java/metadata/src/main/java/com/metaobjects/requirement/RequirementCheck.java @@ -2,6 +2,7 @@ import com.metaobjects.MetaData; import com.metaobjects.MetaRoot; +import com.metaobjects.config.DependencySet; import com.metaobjects.io.util.IOUtil; import com.metaobjects.library.LibrarySources; import com.metaobjects.loader.ValidationPhase; @@ -133,11 +134,11 @@ public static String effectivePackage(MetaData node) { // ------------------------------------------------------------------ public static Scan scan(MetaRoot root, Options options) { - List addressed = collectAddressed(root); + List addressed = collectLedger(root); SymbolTable symbols = SymbolTable.build(root); boolean measure = options.measureCoverage() != null ? options.measureCoverage() - : projectAuthoredRequirements(addressed); + : projectAuthoredRequirements(addressed, root.getDependencySet()); return new Scan(addressed, claimedObjectKeys(root, symbols, addressed), measure, options.requireImplementers(), symbols); } @@ -149,14 +150,36 @@ public static Scan scan(MetaRoot root, Options options) { * PACKAGE. An overlay on a library requirement stays in the library's package and does not * activate coverage. */ - private static boolean projectAuthoredRequirements(List addressed) { + private static boolean projectAuthoredRequirements(List addressed, DependencySet dependencies) { Set libraryPackages = LibrarySources.libraryPackages(); for (Addressed a : addressed) { - if (!libraryPackages.contains(effectivePackage(a.node()))) return true; + String pkg = effectivePackage(a.node()); + if (libraryPackages.contains(pkg)) continue; + // FR-023: a dependency's requirement, inherited or not, is the publisher's design for + // the same reason a library's is, and cannot switch coverage on either. + if (dependencies.imported(RequirementTestIdentities.addressOf(pkg, a.path()))) continue; + return true; } return false; } + /** + * The requirements that are this project's ledger: every loaded requirement but a + * dependency's that {@code requirements.inherit} does not name ({@link DependencySet#inLedger}, + * read from the dependency set the loader put on the root). One left out is still loaded, so + * an overlay of it resolves, and nothing here or in the requirement-tests generators addresses it. + */ + public static List collectLedger(MetaRoot root) { + DependencySet dependencies = root.getDependencySet(); + List out = new ArrayList<>(); + for (Addressed a : collectAddressed(root)) { + if (dependencies.inLedger(RequirementTestIdentities.addressOf(effectivePackage(a.node()), a.path()))) { + out.add(a); + } + } + return out; + } + /** * Resolution keys of every object claimed by a requirement. Shared by the gate and the * summary. A PLANNED requirement never contributes. An ARCHITECTURAL claim also covers every diff --git a/server/java/metadata/src/main/java/com/metaobjects/requirement/RequirementTestIdentities.java b/server/java/metadata/src/main/java/com/metaobjects/requirement/RequirementTestIdentities.java index da96a93255..c094117c67 100644 --- a/server/java/metadata/src/main/java/com/metaobjects/requirement/RequirementTestIdentities.java +++ b/server/java/metadata/src/main/java/com/metaobjects/requirement/RequirementTestIdentities.java @@ -114,7 +114,9 @@ public static boolean defaultFilter(View view) { public static List walk(MetaRoot root) { SymbolTable symbols = SymbolTable.build(root); List out = new ArrayList<>(); - for (RequirementCheck.Addressed a : RequirementCheck.collectAddressed(root)) { + // FR-023: only this project's ledger. A dependency's requirement it did not inherit + // (`requirements.inherit`) is loaded and gets no test. + for (RequirementCheck.Addressed a : RequirementCheck.collectLedger(root)) { MetaRequirement node = a.node(); // One effective package, shared with the gate: the node's own, else the nearest // enclosing node's, else "". diff --git a/server/java/metadata/src/test/java/com/metaobjects/config/DependencyConformanceTest.java b/server/java/metadata/src/test/java/com/metaobjects/config/DependencyConformanceTest.java index 40bf6f1ca3..aa6649d27d 100644 --- a/server/java/metadata/src/test/java/com/metaobjects/config/DependencyConformanceTest.java +++ b/server/java/metadata/src/test/java/com/metaobjects/config/DependencyConformanceTest.java @@ -22,6 +22,7 @@ import com.metaobjects.ErrorCode; import com.metaobjects.MetaDataException; import com.metaobjects.loader.FileSource; +import com.metaobjects.requirement.RequirementCheck; import com.metaobjects.loader.LoaderOptions; import com.metaobjects.loader.MetaDataLoader; import com.metaobjects.loader.MetaDataSource; @@ -78,7 +79,8 @@ private record Case(String name, Map tree, Map t JsonObject config, JsonObject lock, String resolveFrom, List expectFiles, List expectImported, List expectSelected, List expectMigrateGoverned, - String expectLoadError, List expectErrorFiles, String expectError) {} + String expectLoadError, List expectErrorFiles, String expectError, + Map expectLedger, Boolean expectCoverageMeasured) {} static Path corpusDir() { Path dir = Paths.get("").toAbsolutePath(); @@ -131,7 +133,9 @@ name, stringMap(c, "tree"), stringMap(c, "treeFiles"), stringList(c, "expectFiles"), stringList(c, "expectImported"), stringList(c, "expectSelected"), stringList(c, "expectMigrateGoverned"), optString(c, "expectLoadError"), stringList(c, "expectErrorFiles"), - optString(c, "expectError"))}); + optString(c, "expectError"), + c.has("expectLedger") ? stringMap(c, "expectLedger") : null, + c.has("expectCoverageMeasured") ? c.get("expectCoverageMeasured").getAsBoolean() : null)}); } return rows; } @@ -213,7 +217,8 @@ public void resolvesLoadsAndScopesLikeTheReference() throws IOException { assertEquals(new TreeSet<>(testCase.expectFiles()), actual); boolean needsLoad = testCase.expectImported() != null || testCase.expectSelected() != null - || testCase.expectMigrateGoverned() != null || testCase.expectLoadError() != null; + || testCase.expectMigrateGoverned() != null || testCase.expectLoadError() != null + || testCase.expectLedger() != null; if (!needsLoad) return; DependencySet deps = collection.dependencies(); @@ -223,6 +228,7 @@ public void resolvesLoadsAndScopesLikeTheReference() throws IOException { MetaDataLoader loader = new MetaDataLoader( LoaderOptions.create(false, false, true), MetaDataLoader.SUBTYPE_MANUAL, "dep-conformance"); loader.init(); + loader.getRoot().setDependencySet(deps); Throwable thrown = null; try { loader.load(sources); @@ -268,6 +274,26 @@ public void resolvesLoadsAndScopesLikeTheReference() throws IOException { Predicate governed = deps.inMigrateScope().orElse(fqn -> true); assertEquals(new TreeSet<>(testCase.expectMigrateGoverned()), filter(loaded, governed)); } + if (testCase.expectLedger() != null) { + // The LEDGER arm: which requirements are this project's own, keyed + // `::`, and whether object coverage is measured. + RequirementCheck.Scan scan = RequirementCheck.scan(loader.getRoot(), new RequirementCheck.Options(null, false)); + Map ledger = new java.util.TreeMap<>(); + for (RequirementCheck.Addressed a : scan.addressed()) { + String status = a.node().getStatus(); + ledger.put(com.metaobjects.requirement.RequirementTestIdentities.addressOf( + RequirementCheck.effectivePackage(a.node()), a.path()), status == null ? "" : status); + } + assertEquals(new java.util.TreeMap<>(testCase.expectLedger()), ledger); + assertEquals(Boolean.TRUE.equals(testCase.expectCoverageMeasured()), scan.measureCoverage()); + // The requirement-tests generators walk the same ledger: no test for the rest. + Set walked = new TreeSet<>(); + for (com.metaobjects.requirement.RequirementTestIdentities.Walked w + : com.metaobjects.requirement.RequirementTestIdentities.walk(loader.getRoot())) { + walked.add(com.metaobjects.requirement.RequirementTestIdentities.addressOf(w.view().pkg(), w.view().path())); + } + assertEquals(new TreeSet<>(testCase.expectLedger().keySet()), walked); + } } finally { delete(root); } diff --git a/server/java/metadata/src/test/java/com/metaobjects/config/SharedModelConformanceTest.java b/server/java/metadata/src/test/java/com/metaobjects/config/SharedModelConformanceTest.java index 97ef0827e5..d9fbb0ff2b 100644 --- a/server/java/metadata/src/test/java/com/metaobjects/config/SharedModelConformanceTest.java +++ b/server/java/metadata/src/test/java/com/metaobjects/config/SharedModelConformanceTest.java @@ -105,7 +105,8 @@ public void publishesLikeTheReference() throws IOException { providers.add(new SecretHandlingProvider()); } SharedModel.Input in = new SharedModel.Input(input.get("name").getAsString(), files, - strings(input, "include"), strings(input, "exclude"), providers); + strings(input, "include"), strings(input, "exclude"), providers, + input.has("requirements") && input.get("requirements").getAsBoolean()); if (testCase.has("expectRefusal")) { JsonObject refusal = testCase.getAsJsonObject("expectRefusal"); diff --git a/server/python/src/metaobjects/cli.py b/server/python/src/metaobjects/cli.py index 3bb49c808d..6c5d733469 100644 --- a/server/python/src/metaobjects/cli.py +++ b/server/python/src/metaobjects/cli.py @@ -911,6 +911,7 @@ def _run_suite( baseline: str = "default", refused_out: list[str] | None = None, select: Callable[[str], bool] | None = None, + in_ledger: Callable[[str], bool] | None = None, api_prefix: str = DEFAULT_API_PREFIX, overwrite_hand_edits: frozenset[str] = frozenset(), overwrite_paths_out: set[str] | None = None, @@ -971,7 +972,9 @@ def _run_suite( if not generators: raise NoGeneratorsSelectedError suite = generators - result = run_gen(config, root, generators=suite, entity_filter=entity_filter, select=select) + result = run_gen( + config, root, generators=suite, entity_filter=entity_filter, select=select, in_ledger=in_ledger + ) if overwrite_paths_out is not None: overwrite_paths_out.update( path for path, by in result.generated_by.items() if by in overwrite_hand_edits @@ -1518,6 +1521,7 @@ def _run_gen_targets( baseline: str = "default", refused_out: list[str] | None = None, select: Callable[[str], bool] | None = None, + in_ledger: Callable[[str], bool] | None = None, build_ctx: GeneratorBuildContext | None = None, column_naming: str = DEFAULT_COLUMN_NAMING, selection: list[str] | None = None, @@ -1646,7 +1650,8 @@ def selected(gen: Generator, token: str) -> bool: written = _run_suite( root, out_dir, gens, t.entities, gen_state_dir=gen_state_dir, column_naming=column_naming, project_root=project_root, baseline=baseline, - refused_out=refused_out, select=select, api_prefix=config.api_prefix, + refused_out=refused_out, select=select, in_ledger=in_ledger, + api_prefix=config.api_prefix, overwrite_hand_edits=overwrite, overwrite_paths_out=overwrite_paths_out, ) if spec_gens: @@ -1654,7 +1659,7 @@ def selected(gen: Generator, token: str) -> bool: root, out_dir, spec_gens, t.entities, emit_package_init=False, gen_state_dir=gen_state_dir, column_naming=column_naming, project_root=project_root, baseline=baseline, refused_out=refused_out, - select=select, api_prefix=config.api_prefix, + select=select, in_ledger=in_ledger, api_prefix=config.api_prefix, ) except ValueError as exc: # intra-target run_gen collision → clean error errors.append(f"target '{t.name}': {exc}") @@ -1767,6 +1772,7 @@ def _cmd_gen_config(args: argparse.Namespace) -> int: baseline=baseline, refused_out=refused, select=collection.in_scope, + in_ledger=collection.in_ledger, build_ctx=GeneratorBuildContext(template_root), column_naming=column_naming, selection=selection, @@ -2131,6 +2137,7 @@ def compare(naming: str) -> tuple[list[str], list[_DirReport]]: overwrite_paths: set[str] = set() regen = dict( select=collection.in_scope, + in_ledger=collection.in_ledger, build_ctx=GeneratorBuildContext(template_root), # R31: the `names` generator's constants are strategy-dependent, so the regen # must use the strategy `gen` wrote with, or every constant reads as drift. @@ -2743,6 +2750,8 @@ def _verify_requirements(args: argparse.Namespace, model: "_VerifyModel | None") scan = scan_requirements( model.root, coverable=collection.in_scope if collection is not None else None, + in_ledger=collection.in_ledger if collection is not None else None, + imported=collection.imported if collection is not None else None, require_implementers=bool(getattr(args, "require_implementers", False)) or os.environ.get(REQUIRE_IMPLEMENTERS_ENV) == "1", ) diff --git a/server/python/src/metaobjects/codegen/generator.py b/server/python/src/metaobjects/codegen/generator.py index 80aa1e0c55..90dcffa840 100644 --- a/server/python/src/metaobjects/codegen/generator.py +++ b/server/python/src/metaobjects/codegen/generator.py @@ -31,6 +31,10 @@ class GenContext: #: The stable names of every generator in this run, so one generator can tell that a #: sibling is wired (the router emits the ``?format=`` branch only beside ``report-export``). generators: tuple[str, ...] = () + #: FR-023 — is the requirement at ``::`` this project's ledger + #: (``Collection.in_ledger``)? A dependency's requirement the project did not inherit + #: gets no generated test. ``None``: every loaded requirement is the project's. + in_ledger: Callable[[str], bool] | None = None class Generator(Protocol): diff --git a/server/python/src/metaobjects/codegen/generators/requirement_tests_generator.py b/server/python/src/metaobjects/codegen/generators/requirement_tests_generator.py index 4fd703a6bd..5c10f6fc25 100644 --- a/server/python/src/metaobjects/codegen/generators/requirement_tests_generator.py +++ b/server/python/src/metaobjects/codegen/generators/requirement_tests_generator.py @@ -233,7 +233,8 @@ def generate(self, ctx: GenContext) -> list[EmittedFile]: return [] planned: list[tuple[RequirementTestIdentity, RequirementTestArgs]] = [] uncovered: list[str] = [] - for walked in walk_requirements(ctx.loaded_root): + # FR-023 — a dependency's requirement the project did not inherit is not its ledger. + for walked in walk_requirements(ctx.loaded_root, ctx.in_ledger): if not self._include(walked.view): # Named by PATH: diagnostics use the path (contract Table A). uncovered.append(walked.view.path) diff --git a/server/python/src/metaobjects/codegen/requirement_walk.py b/server/python/src/metaobjects/codegen/requirement_walk.py index 2055a61e3e..fbc6635c31 100644 --- a/server/python/src/metaobjects/codegen/requirement_walk.py +++ b/server/python/src/metaobjects/codegen/requirement_walk.py @@ -30,7 +30,11 @@ ) from metaobjects.meta.core.requirement.resolve_claim import resolve_claim from metaobjects.meta.meta_data import MetaData -from metaobjects.requirement_check import collect_addressed_requirements, effective_package +from metaobjects.requirement_check import ( + collect_addressed_requirements, + effective_package, + requirement_fqn, +) from metaobjects.shared.separators import PACKAGE_SEP #: The unit of a requirement that resolves no target. Doubles as the catch-all renderer key. @@ -105,8 +109,16 @@ def _concern_of(node: MetaData) -> str: return f"{node.type}.{node.sub_type}" -def walk_requirements(root: MetaData) -> list[WalkedRequirement]: - """Every ``requirement.*`` node, nested ones included, in declaration order. +def walk_requirements( + root: MetaData, in_ledger: Callable[[str], bool] | None = None +) -> list[WalkedRequirement]: + """Every ``requirement.*`` node in the project's ledger, nested ones included, in + declaration order. + + ``in_ledger`` is the collection's ledger predicate (``Collection.in_ledger``), read at + ``::``: a dependency's requirement the project did not inherit is + left out. ``None``: every loaded requirement is the ledger, which is right for a model + loaded with no dependencies. An unresolvable ``@implementedBy`` reference is skipped rather than raised on: its severity depends on ``@status`` and belongs to ``verify``, and codegen must not fail a @@ -117,6 +129,8 @@ def walk_requirements(root: MetaData) -> list[WalkedRequirement]: req = item.node # The referrer package a bare reference binds in (ADR-0042) is the effective package. package = effective_package(req) + if in_ledger is not None and not in_ledger(requirement_fqn(package, item.path)): + continue targets: list[ResolvedClaim] = [] for ref in req.implemented_by(): target = resolve_claim(root, ref, package) @@ -262,14 +276,17 @@ def requirement_test_identities( *, grain: str = "concern", filter: RequirementFilter | None = None, # noqa: A002 — the seam's published name + in_ledger: Callable[[str], bool] | None = None, ) -> list[RequirementTestIdentity]: - """Every test the generator would emit, sorted by ``id`` (code points, never a locale).""" + """Every test the generator would emit for the project's ledger, sorted by ``id`` (code + points, never a locale). Pass the collection's ``in_ledger``, as the generator receives + it; ``None``: every loaded requirement is the ledger (see ``walk_requirements``).""" # Checked here as well as per requirement, so a bad grain is refused even over a ledger # the filter empties: the answer must not depend on what the model holds. assert_requirement_test_grain(grain) include = filter if filter is not None else default_requirement_test_filter out: list[RequirementTestIdentity] = [] - for walked in walk_requirements(root): + for walked in walk_requirements(root, in_ledger): if not include(walked.view): continue for unit in requirement_test_units(walked, grain): diff --git a/server/python/src/metaobjects/codegen/runner.py b/server/python/src/metaobjects/codegen/runner.py index 5c41fab5c6..d8d7191f2a 100644 --- a/server/python/src/metaobjects/codegen/runner.py +++ b/server/python/src/metaobjects/codegen/runner.py @@ -69,6 +69,7 @@ def run_gen( entity_filter: list[str] | None = None, select: Callable[[str], bool] | None = None, merge_strategy: str = "overwrite", + in_ledger: Callable[[str], bool] | None = None, ) -> RunGenResult: """Mirrors ``codegen-ts``'s ``runner.ts``. @@ -148,6 +149,7 @@ def run_gen( config=config, warn=_warn_collector(gen.name, result.warnings), generators=tuple(g.name for g in generators), + in_ledger=in_ledger, ) for f in gen.generate(ctx): full = os.path.join(config.out_dir, f.path) diff --git a/server/python/src/metaobjects/config/dependencies.py b/server/python/src/metaobjects/config/dependencies.py index c48fca7563..c32dd8d761 100644 --- a/server/python/src/metaobjects/config/dependencies.py +++ b/server/python/src/metaobjects/config/dependencies.py @@ -19,7 +19,7 @@ from metaobjects.naming import NamingRules, package_of_resolution_key from metaobjects.wire import WireFormat from metaobjects.registry_manifest import METAMODEL_VERSION -from metaobjects.shared.base_types import TYPE_OBJECT +from metaobjects.shared.base_types import TYPE_OBJECT, TYPE_REQUIREMENT #: Directory (under `.metaobjects/`) holding the synced snapshot artifacts, #: one subdirectory per dependency name: `.metaobjects/deps//`. @@ -507,9 +507,11 @@ def refuse_unowned_packages( # ADR-0039 SANCTIONED own-accessor case: a root-level scan. `MetaRoot` has # no super, so own and effective children are the same set here, and the # question asked is precisely "what did this tree declare at the top - # level", which is the own layer by definition. + # level", which is the own layer by definition. Requirements too: a publisher may + # export its ledger, and a new requirement in its package would read as the + # publisher's to every gate that keys the ledger by package. for node in root.own_children(): - if node.type != TYPE_OBJECT: + if node.type not in (TYPE_OBJECT, TYPE_REQUIREMENT): continue key = node.resolution_key() pkg = package_of_resolution_key(key) @@ -675,10 +677,24 @@ class Collection: #: attached to the loaded root beside `naming`. wire: WireFormat = WireFormat() + #: FR-023 — the declared `requirements.inherit` patterns, for `in_ledger`. + requirements_inherit: tuple[str, ...] = () + def imported(self, fqn: str) -> bool: """Is `fqn` in a package one of this project's dependencies owns?""" return package_of_resolution_key(fqn) in self.imported_packages + def in_ledger(self, fqn: str) -> bool: + """Is the requirement at `fqn` (`::`) part of this project's + ledger? Its own requirements always are; a dependency's only when + `requirements.inherit` NAMES the dependency's package (`explicitly_includes`). Read + by the requirement gate and the requirement-tests generator. + """ + pkg = package_of_resolution_key(fqn) + if pkg not in self.imported_packages: + return True + return explicitly_includes(self.requirements_inherit, pkg) + def in_scope(self, fqn: str) -> bool: """Output filter for codegen (`run_gen`'s `select`) and `verify --codegen`, and the requirement gate's coverable set (`scan_requirements`' `coverable`): an entity this diff --git a/server/python/src/metaobjects/config/neutral_config.py b/server/python/src/metaobjects/config/neutral_config.py index add024e002..0368cee221 100644 --- a/server/python/src/metaobjects/config/neutral_config.py +++ b/server/python/src/metaobjects/config/neutral_config.py @@ -2,7 +2,7 @@ import json import re -from dataclasses import dataclass +from dataclasses import dataclass, field from pathlib import Path from metaobjects.errors import ErrorCode, ParseError @@ -86,6 +86,10 @@ class NeutralConfig: #: for the same reason `naming` is. wire: WireFormat = WireFormat() + #: FR-023 — `requirements.inherit`: scope patterns naming the dependencies whose + #: requirements this project takes on as its own ledger (`Collection.in_ledger`). + requirements_inherit: list[str] = field(default_factory=list) + def find_project_dir(start: Path) -> Path | None: """The nearest directory at or above *start* that holds ``.metaobjects/config.json``, @@ -180,6 +184,7 @@ def read_neutral_config(config_dir: Path) -> NeutralConfig | None: naming = _read_naming(raw, path) wire = _read_wire(raw, path) _check_enums(raw, path) + requirements_inherit = _read_requirements_inherit(raw, path) # Unknown top-level keys are IGNORED by design — see the module docstring. return NeutralConfig( @@ -190,9 +195,32 @@ def read_neutral_config(config_dir: Path) -> NeutralConfig | None: libraries=libraries, naming=naming, wire=wire, + requirements_inherit=requirements_inherit, ) +def _read_requirements_inherit(raw: dict[str, object], path: Path) -> list[str]: + """FR-023 — `requirements.inherit`, the dependencies whose requirements join this + project's ledger. Validated like `naming`: an unknown key inside `requirements` is + refused, because a misspelt `inherit` would silently leave the ledger out. + """ + block = raw.get("requirements") + if block is None: + return [] + if not isinstance(block, dict): + raise ParseError(f"{path}: 'requirements' must be an object", code=ErrorCode.ERR_COLLECTION_NOT_FOUND) + unknown = sorted(k for k in block if k != "inherit") + if unknown: + raise ParseError( + f"{path}: 'requirements' has unknown key(s) {unknown}; accepted: ['inherit']", + code=ErrorCode.ERR_COLLECTION_NOT_FOUND, + ) + inherit = block.get("inherit") + if inherit is None: + return [] + return _string_array_or_raise(inherit, "requirements.inherit", path) + + def _string_array_or_raise(value: object, field: str, path: Path) -> list[str]: if not isinstance(value, list) or not all(isinstance(v, str) and v.strip() for v in value): raise ParseError( diff --git a/server/python/src/metaobjects/config/source_resolver.py b/server/python/src/metaobjects/config/source_resolver.py index 87c4879da2..9800672f34 100644 --- a/server/python/src/metaobjects/config/source_resolver.py +++ b/server/python/src/metaobjects/config/source_resolver.py @@ -188,6 +188,7 @@ def _collection_from_own_files( libraries=tuple(libraries), naming=naming, wire=wire, + requirements_inherit=tuple(cfg.requirements_inherit if cfg is not None else []), ) diff --git a/server/python/src/metaobjects/requirement_check.py b/server/python/src/metaobjects/requirement_check.py index cdd4a60f7f..7ab8693960 100644 --- a/server/python/src/metaobjects/requirement_check.py +++ b/server/python/src/metaobjects/requirement_check.py @@ -221,14 +221,31 @@ def _subtree_claims_anything(req: MetaRequirement) -> bool: return False -def _project_authored_requirements(addressed: list[AddressedRequirement]) -> bool: +def _project_authored_requirements( + addressed: list[AddressedRequirement], imported: Callable[[str], bool] | None = None +) -> bool: """Did the ADOPTER author any of these requirements? (FR-043 §5.4.) Provenance is the library's declared PACKAGE, a manifest fact; a node's source id differs between a checkout and an installed wheel. An adopter OVERLAYING a library - requirement stays in the library's package and is deliberately not authoring one.""" + requirement stays in the library's package and is deliberately not authoring one. + FR-023: a dependency's requirement, inherited or not, is the publisher's design for + the same reason, and cannot switch coverage on either.""" lib_pkgs = library_packages() - return any(effective_package(item.node) not in lib_pkgs for item in addressed) + for item in addressed: + pkg = effective_package(item.node) + if pkg in lib_pkgs: + continue + if imported is not None and imported(requirement_fqn(pkg, item.path)): + continue + return True + return False + + +def requirement_fqn(pkg: str, path: str) -> str: + """The key a collection predicate reads for a requirement: ``::``, or + the bare path when the effective package is empty.""" + return path if pkg == "" else f"{pkg}::{path}" def _claimed_object_keys(root: MetaData, reqs: list[MetaRequirement]) -> frozenset[str]: @@ -261,18 +278,32 @@ def scan_requirements( coverable: Callable[[str], bool] | None = None, measure_coverage: bool | None = None, require_implementers: bool = False, + in_ledger: Callable[[str], bool] | None = None, + imported: Callable[[str], bool] | None = None, ) -> RequirementScan: """Compute, once, what the gate and the summary both read. ``measure_coverage`` forces coverage on or off instead of deriving it; the one caller that legitimately knows better is a gate over a shipped library loaded standalone. + + ``in_ledger`` (FR-023, ``Collection.in_ledger``) keeps a dependency's requirement the + project did not inherit out of everything here: it is loaded, so an overlay of it + resolves, and is not checked, summarised, linted or counted as a claim. ``imported`` + (``Collection.imported``) marks a dependency's requirement, which never switches + coverage on. Both read ``::``; ``None`` keeps every requirement. """ - addressed = collect_addressed_requirements(root) + addressed = [ + a + for a in collect_addressed_requirements(root) + if in_ledger is None or in_ledger(requirement_fqn(effective_package(a.node), a.path)) + ] return RequirementScan( addressed=addressed, claimed_objects=_claimed_object_keys(root, [a.node for a in addressed]), measure_coverage=( - measure_coverage if measure_coverage is not None else _project_authored_requirements(addressed) + measure_coverage + if measure_coverage is not None + else _project_authored_requirements(addressed, imported) ), require_implementers=require_implementers, coverable=coverable, diff --git a/server/python/tests/codegen/test_requirement_tests_generator.py b/server/python/tests/codegen/test_requirement_tests_generator.py index 59aa6f5ccf..9de007e618 100644 --- a/server/python/tests/codegen/test_requirement_tests_generator.py +++ b/server/python/tests/codegen/test_requirement_tests_generator.py @@ -156,6 +156,30 @@ def test_one_file_per_metamodel_package(tmp_path: Path) -> None: ] +def test_a_requirement_outside_the_ledger_gets_no_test(tmp_path: Path) -> None: + """FR-023: a dependency's requirement the project did not inherit is loaded and gets no + test. The ledger predicate reads ``::``.""" + root = _load_yaml( + _doc(_requirement("A"), "acme::one"), + _doc(_requirement("B"), "acme::two").replace("name: Order", "name: Order2"), + ) + out = tmp_path / "gen" + seen: list[str] = [] + + def in_ledger(fqn: str) -> bool: + seen.append(fqn) + return fqn.startswith("acme::one::") + + result = run_gen( + GenConfig(out_dir=str(out)), root, generators=[requirement_tests()], in_ledger=in_ledger + ) + written = sorted( + str(Path(full).relative_to(out)) for full, _ in result.files if not full.endswith("__init__.py") + ) + assert written == ["requirements/test_acme_one_requirements.py"] + assert "acme::two::B" in seen + + def test_an_unpackaged_ledger_writes_test_root_requirements(tmp_path: Path) -> None: files, _ = generate(_load_corpus_case("unpackaged"), tmp_path) assert list(files) == ["requirements/test_root_requirements.py"] diff --git a/server/python/tests/conformance/test_dependency_conformance.py b/server/python/tests/conformance/test_dependency_conformance.py index 197a06b1ad..7792bae47f 100644 --- a/server/python/tests/conformance/test_dependency_conformance.py +++ b/server/python/tests/conformance/test_dependency_conformance.py @@ -17,11 +17,13 @@ import pytest from metaobjects.cli import _load_collection_result +from metaobjects.codegen.requirement_walk import requirement_test_identities from metaobjects.config.dependencies import LOCK_FILE, read_lock from metaobjects.config.dependency_check import check_dependencies from metaobjects.config.neutral_config import read_neutral_config from metaobjects.config.source_resolver import resolve_collection_full from metaobjects.errors import ParseError +from metaobjects.requirement_check import effective_package, requirement_fqn, scan_requirements from metaobjects.shared.base_types import TYPE_OBJECT _CORPUS_DIR = ( @@ -133,6 +135,31 @@ def test_dependency_conformance_case(case: dict, tmp_path: Path) -> None: ) assert governed == sorted(case["expectMigrateGoverned"]) + if "expectLedger" in case: + # The ledger arm: which loaded requirements are this project's ledger, and whether + # object coverage is measured (an inherited requirement never switches it on). + result = _load_collection_result(collection) + assert not result.errors, [f"{e.code}: {e.message}" for e in result.errors] + scan = scan_requirements( + result.root, + coverable=collection.in_scope, + in_ledger=collection.in_ledger, + imported=collection.imported, + ) + ledger = { + requirement_fqn(effective_package(a.node), a.path): a.node.status() or "" + for a in scan.addressed + } + assert ledger == case["expectLedger"] + assert scan.measure_coverage == case.get("expectCoverageMeasured", False) + # The requirement-tests generator walks the same ledger: no test for the rest. + identities = requirement_test_identities( + result.root, filter=lambda _view: True, in_ledger=collection.in_ledger + ) + assert sorted({requirement_fqn(t.package, t.path) for t in identities}) == sorted( + case["expectLedger"] + ) + if "expectLoadError" in case: # Two arms produce a load-time failure: a loader-native `MetaError` in # `result.errors` (parse/merge/validation), or the post-load ownership diff --git a/server/python/tests/conformance/test_shared_model_conformance.py b/server/python/tests/conformance/test_shared_model_conformance.py index 2feff2fddc..0e0682ca6e 100644 --- a/server/python/tests/conformance/test_shared_model_conformance.py +++ b/server/python/tests/conformance/test_shared_model_conformance.py @@ -20,7 +20,6 @@ from metaobjects import MetaDataLoader from metaobjects.serializer_json import serialize_shared_document -from metaobjects.shared.base_types import TYPE_OBJECT _CORPUS_DIR = Path(__file__).resolve().parents[4] / "fixtures" / "shared-model-conformance" _CASES = json.loads((_CORPUS_DIR / "cases.json").read_text())["cases"] @@ -45,11 +44,8 @@ def test_shared_document_bytes(case: dict) -> None: assert not result.errors, [f"{e.code}: {e.message}" for e in result.errors] # ADR-0039 sanctioned own: the root has no super chain, so its own children are its children. - selected = [ - c - for c in result.root.own_children() - if c.type == TYPE_OBJECT and c.resolution_key() in manifest["nodes"] - ] + # Every node the manifest lists, whatever its type: an export may carry requirement.* too. + selected = [c for c in result.root.own_children() if c.resolution_key() in manifest["nodes"]] assert sorted(c.resolution_key() for c in selected) == manifest["nodes"] document = serialize_shared_document(selected).encode("utf-8") diff --git a/server/typescript/packages/cli/src/commands/gen.ts b/server/typescript/packages/cli/src/commands/gen.ts index b5c398f41b..e0199fee10 100644 --- a/server/typescript/packages/cli/src/commands/gen.ts +++ b/server/typescript/packages/cli/src/commands/gen.ts @@ -262,6 +262,8 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat // passed: an unconfigured project's predicate admits everything, so this // is a no-op for the common case, not a behavior change. scope: genCollection.inScope, + // FR-023 — a dependency's requirement this project did not inherit gets no test. + inLedger: genCollection.inLedger, // FR-023 §4.3 — the collection's own source files (never a dependency's // snapshot artifact), so sharedModelFile() defaults its `files` selection // to exactly what this project itself declares. @@ -544,6 +546,7 @@ async function listCatalogCommand( probe: { metadata, scope: genCollection.inScope, + inLedger: genCollection.inLedger, sourceFiles: genCollection.ownFiles, sourceRoots: sourceRootsOf(genCollection), agentSchema: () => schemaOptions === undefined ? undefined : buildAgentSchemaInput( diff --git a/server/typescript/packages/cli/src/commands/verify.ts b/server/typescript/packages/cli/src/commands/verify.ts index f06809878e..ef2abe6968 100644 --- a/server/typescript/packages/cli/src/commands/verify.ts +++ b/server/typescript/packages/cli/src/commands/verify.ts @@ -797,6 +797,8 @@ export async function verifyCommand( // command line it shares with local runs. const scan = scanRequirements(root, { coverable: collection.inCoverage, + inLedger: collection.inLedger, + imported: collection.imported, requireImplementers: flags.requireImplementers || process.env.META_REQUIRE_IMPLEMENTERS === "1", }); const diags = [...checkRequirements(root, scan)]; @@ -1775,6 +1777,7 @@ export async function verifyCommand( ), schemaSettings: codegenSchema, requirementLedger, + inLedger: genCollection.inLedger, }); } catch (err) { log.error(`verify --codegen: regeneration failed: ${describeError(err)}`); @@ -1799,6 +1802,7 @@ export async function verifyCommand( agentSchema: () => buildAgentSchemaInput(codegenRoot, config.dialect, () => {}, codegenSchema), schemaSettings: codegenSchema, requirementLedger, + inLedger: genCollection.inLedger, }); return probe.error === undefined && probe.clean; } finally { diff --git a/server/typescript/packages/cli/src/lib/catalog-listing.ts b/server/typescript/packages/cli/src/lib/catalog-listing.ts index 705328bf51..fdc21dd0aa 100644 --- a/server/typescript/packages/cli/src/lib/catalog-listing.ts +++ b/server/typescript/packages/cli/src/lib/catalog-listing.ts @@ -199,6 +199,8 @@ export interface CatalogListingOpts { probe?: { metadata: MetaData; scope?: (fqn: string) => boolean; + /** The project's requirement ledger (FR-023), as `meta gen` supplies it: `requirement-tests` counts only it. */ + inLedger?: (fqn: string) => boolean; /** * The collection's OWN source files — the same list `meta gen` threads onto * `ctx.sourceFiles`. `shared-model` loads them standalone to build its artifact, so @@ -228,7 +230,7 @@ async function probeOne( project: CatalogProject, probe: NonNullable, ): Promise<{ count: number; needsConfig?: string[] } | { error: string }> { - const { metadata, scope, sourceFiles, sourceRoots, agentSchema, schemaSettings } = probe; + const { metadata, scope, inLedger, sourceFiles, sourceRoots, agentSchema, schemaSettings } = probe; const count = async (config: MetaobjectsGenConfig): Promise => { const result = await runGen({ config: { ...config, generators: [entry.factory()] }, @@ -236,6 +238,7 @@ async function probeOne( projectRoot: project.projectRoot, dryRun: true, ...(scope !== undefined ? { scope } : {}), + ...(inLedger !== undefined ? { inLedger } : {}), ...(sourceFiles !== undefined ? { sourceFiles } : {}), ...(sourceRoots !== undefined ? { sourceRoots } : {}), ...(agentSchema !== undefined ? { agentSchema } : {}), diff --git a/server/typescript/packages/cli/src/lib/codegen-drift.ts b/server/typescript/packages/cli/src/lib/codegen-drift.ts index e6ea2faee7..de224c7538 100644 --- a/server/typescript/packages/cli/src/lib/codegen-drift.ts +++ b/server/typescript/packages/cli/src/lib/codegen-drift.ts @@ -187,7 +187,7 @@ export async function computeCodegenDrift( projectRoot: string, scope?: (fqn: string) => boolean, sourceFiles?: readonly string[], - run?: Pick, + run?: Pick, ): Promise { const root = isAbsolute(projectRoot) ? projectRoot : resolve(projectRoot); @@ -284,6 +284,7 @@ export async function computeCodegenDrift( ...(run?.agentSchema !== undefined ? { agentSchema: run.agentSchema } : {}), ...(run?.schemaSettings !== undefined ? { schemaSettings: run.schemaSettings } : {}), ...(run?.requirementLedger !== undefined ? { requirementLedger: run.requirementLedger } : {}), + ...(run?.inLedger !== undefined ? { inLedger: run.inLedger } : {}), }); // Where gen discards hand edits instead of keeping them (handEdits: "overwrite"). diff --git a/server/typescript/packages/cli/src/lib/requirement-check.ts b/server/typescript/packages/cli/src/lib/requirement-check.ts index afcae8c987..329faa05d1 100644 --- a/server/typescript/packages/cli/src/lib/requirement-check.ts +++ b/server/typescript/packages/cli/src/lib/requirement-check.ts @@ -317,14 +317,25 @@ export interface RequirementScan { * what the adopter's own model is for. Treating it as activation would mean correcting * one library entry silently acquired a coverage gate over the whole estate. */ -function projectAuthoredRequirements(addressed: readonly AddressedRequirement[]): boolean { +function projectAuthoredRequirements( + addressed: readonly AddressedRequirement[], + imported?: (fqn: string) => boolean, +): boolean { const libPkgs = libraryPackages(); return addressed.some((r) => { const pkg = effectiveRequirementPackage(r.node); - return !libPkgs.has(pkg); + // FR-023 — a dependency's requirement, inherited or not, is the publisher's design for + // the same reason a library's is, and cannot switch coverage on either. + return !libPkgs.has(pkg) && !(imported?.(requirementFqn(pkg, r.path)) ?? false); }); } +/** The key a collection predicate reads for a requirement: its effective package and its + * dotted path, as `::` (just the path when the package is empty). */ +function requirementFqn(pkg: string, path: string): string { + return pkg === "" ? path : `${pkg}::${path}`; +} + export function scanRequirements( root: MetaData, opts?: { @@ -337,13 +348,24 @@ export function scanRequirements( measureCoverage?: boolean; /** Raise WARN_REQUIREMENT_NOTHING_IMPLEMENTS to severity "error". Default false. */ requireImplementers?: boolean; + /** FR-023 — which requirements are this project's ledger (`Collection.inLedger`), read + * with `::`. One left out is still loaded, so an overlay of it resolves, + * but nothing here addresses it: not checked, summarised, linted or claimed. Undefined + * means every loaded requirement, as before the option existed. */ + inLedger?: (fqn: string) => boolean; + /** FR-023 — is `::` a dependency's (`Collection.imported`)? Such a + * requirement, even an inherited one, never switches object coverage on. */ + imported?: (fqn: string) => boolean; }, ): RequirementScan { - const addressed = collectAddressedRequirements(root); + const inLedger = opts?.inLedger; + const addressed = collectAddressedRequirements(root).filter( + (r) => inLedger === undefined || inLedger(requirementFqn(effectiveRequirementPackage(r.node), r.path)), + ); return { addressed, claimedObjects: claimedObjectKeys(root, addressed.map((r) => r.node)), - measureCoverage: opts?.measureCoverage ?? projectAuthoredRequirements(addressed), + measureCoverage: opts?.measureCoverage ?? projectAuthoredRequirements(addressed, opts?.imported), requireImplementers: opts?.requireImplementers ?? false, // `exactOptionalPropertyTypes` — an omitted key, never an explicit `undefined`. ...(opts?.coverable !== undefined ? { coverable: opts.coverable } : {}), diff --git a/server/typescript/packages/cli/src/lib/requirement-payload.ts b/server/typescript/packages/cli/src/lib/requirement-payload.ts index f410ff7cea..f6b23ea061 100644 --- a/server/typescript/packages/cli/src/lib/requirement-payload.ts +++ b/server/typescript/packages/cli/src/lib/requirement-payload.ts @@ -87,9 +87,19 @@ export interface RequirementPayload { */ export function requirementPayload( root: MetaData, - collection: { inCoverage: (fqn: string) => boolean; files: readonly string[] }, + collection: { + inCoverage: (fqn: string) => boolean; + inLedger?: (fqn: string) => boolean; + imported?: (fqn: string) => boolean; + files: readonly string[]; + }, ): RequirementPayload | undefined { - const scan = scanRequirements(root, { coverable: collection.inCoverage, requireImplementers: false }); + const scan = scanRequirements(root, { + coverable: collection.inCoverage, + requireImplementers: false, + ...(collection.inLedger !== undefined ? { inLedger: collection.inLedger } : {}), + ...(collection.imported !== undefined ? { imported: collection.imported } : {}), + }); const s = summariseRequirements(root, scan); if (s === undefined) return undefined; const diags = [...checkRequirements(root, scan)]; diff --git a/server/typescript/packages/cli/test/dependency-ledger-conformance.test.ts b/server/typescript/packages/cli/test/dependency-ledger-conformance.test.ts new file mode 100644 index 0000000000..e5cbbeb926 --- /dev/null +++ b/server/typescript/packages/cli/test/dependency-ledger-conformance.test.ts @@ -0,0 +1,88 @@ +// The LEDGER arm of fixtures/dependency-conformance (FR-023): which loaded requirements are +// this project's own ledger, and whether object coverage is measured. A dependency's +// requirement joins the ledger only when `requirements.inherit` names its package, and +// never switches coverage on. Run here rather than in the sdk runner because the +// requirement gate lives in this package. + +import { describe, expect, test } from "bun:test"; +import { copyFile, mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join, resolve } from "node:path"; +import { effectiveRequirementPackage } from "@metaobjectsdev/metadata"; +import { DEFAULT_METAOBJECTS_DIR, LOCK_FILE, loadMemory, resolveCollection } from "@metaobjectsdev/sdk"; +import { requirementRows, requirementTestIdentities } from "@metaobjectsdev/codegen-ts"; +import { scanRequirements } from "../src/lib/requirement-check.js"; + +interface Case { + readonly name: string; + readonly tree: Record; + readonly treeFiles?: Record; + readonly config: unknown | null; + readonly lock?: unknown; + /** `::` → effective `@status`, EXHAUSTIVE over the ledger. */ + readonly expectLedger?: Record; + readonly expectCoverageMeasured?: boolean; +} + +const CORPUS_DIR = resolve(import.meta.dir, "../../../../../fixtures/dependency-conformance"); + +async function materialize(c: Case): Promise { + const root = await mkdtemp(join(tmpdir(), "mo-dep-ledger-")); + for (const [rel, content] of Object.entries(c.tree)) { + await mkdir(dirname(join(root, rel)), { recursive: true }); + await writeFile(join(root, rel), content); + } + for (const [rel, corpusRel] of Object.entries(c.treeFiles ?? {})) { + await mkdir(dirname(join(root, rel)), { recursive: true }); + await copyFile(join(CORPUS_DIR, corpusRel), join(root, rel)); + } + const dir = join(root, DEFAULT_METAOBJECTS_DIR); + await mkdir(dir, { recursive: true }); + if (c.config !== null) await writeFile(join(dir, "config.json"), JSON.stringify(c.config, null, 2)); + if (c.lock !== undefined) await writeFile(join(dir, LOCK_FILE), JSON.stringify(c.lock, null, 2)); + return root; +} + +const ledgerCases: Case[] = (JSON.parse(await readFile(join(CORPUS_DIR, "cases.json"), "utf8")).cases as Case[]) + .filter((c) => c.expectLedger !== undefined); + +describe("dependency conformance: the ledger arm", () => { + test("corpus has ledger cases (a silent zero-case run is a failed gate)", () => { + expect(ledgerCases.length).toBeGreaterThan(0); + }); + + for (const c of ledgerCases) { + test(c.name, async () => { + const root = await materialize(c); + const collection = await resolveCollection(root, { explicitDir: root }); + const loaded = await loadMemory(root, { + files: collection.files, + fileIds: collection.fileIds, + importedPackages: collection.importedPackages, + importedNodes: collection.importedNodes, + }); + const scan = scanRequirements(loaded, { + coverable: collection.inCoverage, + inLedger: collection.inLedger, + imported: collection.imported, + }); + const ledger: Record = {}; + for (const { node, path } of scan.addressed) { + const pkg = effectiveRequirementPackage(node); + ledger[pkg === "" ? path : `${pkg}::${path}`] = node.status() ?? ""; + } + expect(ledger).toEqual(c.expectLedger ?? {}); + expect(scan.measureCoverage).toBe(c.expectCoverageMeasured ?? false); + + // The requirement-tests generator and the requirements pages read the same ledger. + const expected = Object.keys(c.expectLedger ?? {}).sort(); + const tested = requirementTestIdentities(loaded, { filter: () => true, inLedger: collection.inLedger }); + expect([...new Set(tested.map((t) => (t.package === "" ? t.path : `${t.package}::${t.path}`)))].sort()).toEqual( + expected, + ); + const listed = requirementRows(loaded, collection.inLedger).map((r) => r.path); + const pathOf = (key: string): string => key.split("::").at(-1) ?? key; + expect(listed.sort()).toEqual(expected.map(pathOf).sort()); + }); + } +}); diff --git a/server/typescript/packages/codegen-ts/src/generator.ts b/server/typescript/packages/codegen-ts/src/generator.ts index a6059e0104..a96696b277 100644 --- a/server/typescript/packages/codegen-ts/src/generator.ts +++ b/server/typescript/packages/codegen-ts/src/generator.ts @@ -43,6 +43,11 @@ export interface GenContext { * read `select` directly to honour the same exclusion. Undefined ⇒ every * node is in scope, byte-identical to a project with no `scope` declared. */ select?: (fqn: string) => boolean; + /** FR-023 — is the requirement at `::` part of this project's ledger + * (`RunGenOpts.inLedger`, the collection's `inLedger`)? A dependency's requirement the + * project did not inherit is loaded and gets no generated test. Undefined ⇒ every loaded + * requirement is the project's, as before the option existed. */ + inLedger?: (fqn: string) => boolean; config: ResolvedGenConfig; /** Pre-built by the runner: the resolved config keys that are not on `config` — * `apiPrefix`, `columnNamingStrategy`, `collectionName`, `timestampMode` — plus the diff --git a/server/typescript/packages/codegen-ts/src/generators/agent-docs-file.ts b/server/typescript/packages/codegen-ts/src/generators/agent-docs-file.ts index c92c870d27..8295b5d03a 100644 --- a/server/typescript/packages/codegen-ts/src/generators/agent-docs-file.ts +++ b/server/typescript/packages/codegen-ts/src/generators/agent-docs-file.ts @@ -333,7 +333,7 @@ export const agentDocsFile = function agentDocsFile(opts?: AgentDocsFileOpts): G } // ---- requirements.md - const requirements = renderAgentRequirementsPage(ctx.loadedRoot); + const requirements = renderAgentRequirementsPage(ctx.loadedRoot, ctx.inLedger); if (requirements !== "") files.push({ path: `${dir}/requirements.md`, content: requirements }); return files; diff --git a/server/typescript/packages/codegen-ts/src/generators/agent-requirements-page.ts b/server/typescript/packages/codegen-ts/src/generators/agent-requirements-page.ts index 3c9cecb379..4e3eee64a8 100644 --- a/server/typescript/packages/codegen-ts/src/generators/agent-requirements-page.ts +++ b/server/typescript/packages/codegen-ts/src/generators/agent-requirements-page.ts @@ -73,9 +73,12 @@ interface NodeIndexEntry { } /** Invert the walk: claimed node → the requirements that claim it. */ -export function buildNodeIndex(root: MetaData): NodeIndexEntry[] { +export function buildNodeIndex( + root: MetaData, + inLedger?: (fqn: string) => boolean, +): NodeIndexEntry[] { const byAddress = new Map(); - for (const walked of walkRequirements(root)) { + for (const walked of walkRequirements(root, inLedger)) { const statement = walked.node.attr(REQUIREMENT_ATTR_STATEMENT); for (const target of walked.targets) { const address = nodeAddress(target.node); @@ -110,11 +113,14 @@ function oneLine(text: string): string { * `requirementsFile()` keeps, and the only reason a surface that is on by default is a * no-op for a project without a ledger. */ -export function renderAgentRequirementsPage(root: MetaData): string { - const rows = requirementRows(root); +export function renderAgentRequirementsPage( + root: MetaData, + inLedger?: (fqn: string) => boolean, +): string { + const rows = requirementRows(root, inLedger); if (rows.length === 0) return ""; - const index = buildNodeIndex(root); + const index = buildNodeIndex(root, inLedger); const out: string[] = []; out.push(GENERATED_MARKER); out.push(""); diff --git a/server/typescript/packages/codegen-ts/src/generators/docs-data-builder.ts b/server/typescript/packages/codegen-ts/src/generators/docs-data-builder.ts index 76046acfbc..f9c01a6c81 100644 --- a/server/typescript/packages/codegen-ts/src/generators/docs-data-builder.ts +++ b/server/typescript/packages/codegen-ts/src/generators/docs-data-builder.ts @@ -83,6 +83,9 @@ export interface BuildDocDataOpts { * `apiSurfaceHref` so each resolves in BOTH layouts. ABSENT for model-only * runs → default output byte-identical. */ apiRefs?: Array<{ label: string; href: string }>; + /** The collection's ledger predicate (`GenContext.inLedger`): a dependency's requirement + * the project did not inherit is not listed under "Required by". */ + inLedger?: (fqn: string) => boolean; } /** Whether a field is required — `@required` true OR a `validator.required` @@ -728,7 +731,7 @@ export function buildEntityDocData( const memberDepth = (path: string): number => (path === "" ? 0 : path.split(".").length); const claimedByMatches: UsedByDoc[] = []; if (entity.subType === OBJECT_SUBTYPE_ENTITY) { - for (const walked of walkRequirements(root)) { + for (const walked of walkRequirements(root, opts.inLedger)) { // The SHALLOWEST member path among this requirement's targets that lands on this // entity: "" for an entity-grain claim, "status" for an L5 member claim. undefined // when no target is under this entity. diff --git a/server/typescript/packages/codegen-ts/src/generators/docs-file.ts b/server/typescript/packages/codegen-ts/src/generators/docs-file.ts index 13b121829f..d31d09847a 100644 --- a/server/typescript/packages/codegen-ts/src/generators/docs-file.ts +++ b/server/typescript/packages/codegen-ts/src/generators/docs-file.ts @@ -137,6 +137,7 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator { }), loadedRoot: rc.loadedRoot, ...(apiRefs !== undefined && { apiRefs }), + ...(ctx.inLedger !== undefined && { inLedger: ctx.inLedger }), }); return { path, content: renderDocPage(TEMPLATE_REF, payload, provider, path) }; }); diff --git a/server/typescript/packages/codegen-ts/src/generators/requirement-tests.ts b/server/typescript/packages/codegen-ts/src/generators/requirement-tests.ts index 716b0aec7d..55428d8310 100644 --- a/server/typescript/packages/codegen-ts/src/generators/requirement-tests.ts +++ b/server/typescript/packages/codegen-ts/src/generators/requirement-tests.ts @@ -157,7 +157,8 @@ export function requirementTests(opts: RequirementTestsOpts = {}): Generator { ); } - for (const walked of walkRequirements(ctx.loadedRoot)) { + // FR-023 — a dependency's requirement the project did not inherit is not its ledger. + for (const walked of walkRequirements(ctx.loadedRoot, ctx.inLedger)) { if (!filter(walked.view)) { uncovered.push(walked.view.path); continue; diff --git a/server/typescript/packages/codegen-ts/src/generators/requirements-file.ts b/server/typescript/packages/codegen-ts/src/generators/requirements-file.ts index 3e0933c960..f2255dfebb 100644 --- a/server/typescript/packages/codegen-ts/src/generators/requirements-file.ts +++ b/server/typescript/packages/codegen-ts/src/generators/requirements-file.ts @@ -48,7 +48,7 @@ export const requirementsFile = function requirementsFile( name: "requirements-file", target: opts?.target ?? DOCS_TARGET_NAME, generate: oncePerRun((_entities, ctx) => { - const rows = requirementRows(ctx.loadedRoot); + const rows = requirementRows(ctx.loadedRoot, ctx.inLedger); // The one early return that matters. Both renderers also return "" for an empty // ledger, so this is belt-and-braces — but the guarantee callers depend on is // "zero FILES", which only this line can provide. diff --git a/server/typescript/packages/codegen-ts/src/generators/requirements-view.ts b/server/typescript/packages/codegen-ts/src/generators/requirements-view.ts index 78ba50a29a..0929a206cf 100644 --- a/server/typescript/packages/codegen-ts/src/generators/requirements-view.ts +++ b/server/typescript/packages/codegen-ts/src/generators/requirements-view.ts @@ -73,14 +73,19 @@ function stringAttr(node: MetaData, name: string): string | undefined { } /** - * Project every `requirement.*` node — nested ones included — into render-ready rows. + * Project every `requirement.*` node in the project's ledger — nested ones included — into + * render-ready rows. `inLedger` is the collection's ledger predicate, as `walkRequirements` + * reads it: a dependency's requirement the project did not inherit is not listed. * * Returns `[]` for a model declaring no requirements, which is what lets the surface * emit NOTHING rather than an empty page, and is in turn what makes turning the surface * on by default a no-op for every project without a ledger. */ -export function requirementRows(root: MetaData): RequirementRow[] { - return walkRequirements(root).map((walked) => { +export function requirementRows( + root: MetaData, + inLedger?: (fqn: string) => boolean, +): RequirementRow[] { + return walkRequirements(root, inLedger).map((walked) => { const { node, view, targets } = walked; return { path: view.path, diff --git a/server/typescript/packages/codegen-ts/src/generators/shared-model-file.ts b/server/typescript/packages/codegen-ts/src/generators/shared-model-file.ts index 5381963a82..ffe79cb536 100644 --- a/server/typescript/packages/codegen-ts/src/generators/shared-model-file.ts +++ b/server/typescript/packages/codegen-ts/src/generators/shared-model-file.ts @@ -29,6 +29,9 @@ export interface SharedModelFileOpts { include: readonly string[]; /** Applied after `include`. */ exclude?: readonly string[]; + /** Publish the selected `requirement.*` nodes too, so a consumer can inherit them. + * Default false. `template.*` is never published. */ + requirements?: boolean; /** Which of the publisher's own source files may contribute. Default: the run's * own source files (`ctx.sourceFiles` — everything `files?` narrows). */ files?: readonly string[]; @@ -98,6 +101,7 @@ export function sharedModelFile(opts: SharedModelFileOpts): Generator { files, include: opts.include, ...(opts.exclude !== undefined ? { exclude: opts.exclude } : {}), + ...(opts.requirements !== undefined ? { requirements: opts.requirements } : {}), ...(ctx.registry !== undefined ? { registry: ctx.registry } : {}), }); diff --git a/server/typescript/packages/codegen-ts/src/index.ts b/server/typescript/packages/codegen-ts/src/index.ts index 27ad6f8d5b..91f840d332 100644 --- a/server/typescript/packages/codegen-ts/src/index.ts +++ b/server/typescript/packages/codegen-ts/src/index.ts @@ -388,6 +388,7 @@ export { requirementTestUnits, requirementTestIdentity, requirementTestIdentities, + requirementLedgerKey, witnessKeyCollisions, } from "./requirement-walk.js"; export type { diff --git a/server/typescript/packages/codegen-ts/src/reference/agent-docs.ts b/server/typescript/packages/codegen-ts/src/reference/agent-docs.ts index 77e6da4c0d..37972a25c3 100644 --- a/server/typescript/packages/codegen-ts/src/reference/agent-docs.ts +++ b/server/typescript/packages/codegen-ts/src/reference/agent-docs.ts @@ -344,7 +344,7 @@ export const agentDocsFile = function agentDocsFile(opts?: AgentDocsFileOpts): G } // ---- requirements.md - const requirements = renderAgentRequirementsPage(ctx.loadedRoot); + const requirements = renderAgentRequirementsPage(ctx.loadedRoot, ctx.inLedger); if (requirements !== "") files.push({ path: `${dir}/requirements.md`, content: requirements }); return files; diff --git a/server/typescript/packages/codegen-ts/src/reference/docs.ts b/server/typescript/packages/codegen-ts/src/reference/docs.ts index a619f02101..90409e20dc 100644 --- a/server/typescript/packages/codegen-ts/src/reference/docs.ts +++ b/server/typescript/packages/codegen-ts/src/reference/docs.ts @@ -149,6 +149,7 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator { }), loadedRoot: rc.loadedRoot, ...(apiRefs !== undefined && { apiRefs }), + ...(ctx.inLedger !== undefined && { inLedger: ctx.inLedger }), }); return { path, content: renderDocPage(ENTITY_PAGE_REF, payload, provider, path) }; }); diff --git a/server/typescript/packages/codegen-ts/src/reference/requirement-tests.ts b/server/typescript/packages/codegen-ts/src/reference/requirement-tests.ts index 914fc49b24..35f22e1f17 100644 --- a/server/typescript/packages/codegen-ts/src/reference/requirement-tests.ts +++ b/server/typescript/packages/codegen-ts/src/reference/requirement-tests.ts @@ -301,7 +301,8 @@ export function requirementTests(opts: RequirementTestsOpts = {}): Generator { ); } - for (const walked of walkRequirements(ctx.loadedRoot)) { + // FR-023 — a dependency's requirement the project did not inherit is not its ledger. + for (const walked of walkRequirements(ctx.loadedRoot, ctx.inLedger)) { if (!filter(walked.view)) { uncovered.push(walked.view.path); continue; diff --git a/server/typescript/packages/codegen-ts/src/reference/requirements.ts b/server/typescript/packages/codegen-ts/src/reference/requirements.ts index a1ca1d96c4..937d740a5f 100644 --- a/server/typescript/packages/codegen-ts/src/reference/requirements.ts +++ b/server/typescript/packages/codegen-ts/src/reference/requirements.ts @@ -64,7 +64,7 @@ export const requirementsFile = function requirementsFile( name: "requirements-file", target: opts?.target ?? DOCS_TARGET_NAME, generate: oncePerRun((_entities, ctx) => { - const rows = requirementRows(ctx.loadedRoot); + const rows = requirementRows(ctx.loadedRoot, ctx.inLedger); // The one early return that matters. Both renderers also return "" for an empty // ledger, so this is belt-and-braces — but the guarantee callers depend on is // "zero FILES", which only this line can provide. diff --git a/server/typescript/packages/codegen-ts/src/reference/shared-model.ts b/server/typescript/packages/codegen-ts/src/reference/shared-model.ts index a81388c4f2..357933e03e 100644 --- a/server/typescript/packages/codegen-ts/src/reference/shared-model.ts +++ b/server/typescript/packages/codegen-ts/src/reference/shared-model.ts @@ -21,7 +21,8 @@ // below reads the nearest package.json; swap it for your own source of // truth) and where the files land (`target`). Copied beside it, so yours // too: `buildSharedModel`, which loads the files, selects by `include` / -// `exclude` (never `requirement.*` or `template.*`), refuses a selection +// `exclude` (never `template.*`, and `requirement.*` only with +// `requirements: true`), refuses a selection // that is not closed or that needs vocabulary a consumer does not ship, and // serializes it; and `renderSharedModelFiles`, which names the two files, // hashes the artifact and writes the manifest. Those are what a consumer's @@ -53,6 +54,9 @@ export interface SharedModelFileOpts { include: readonly string[]; /** Applied after `include`. */ exclude?: readonly string[]; + /** Publish the selected `requirement.*` nodes too, so a consumer can inherit them. + * Default false. `template.*` is never published. */ + requirements?: boolean; /** Which of the publisher's own source files may contribute. Default: the run's * own source files (`ctx.sourceFiles`). */ files?: readonly string[]; @@ -124,6 +128,7 @@ export function sharedModelFile(opts: SharedModelFileOpts): Generator { files, include: opts.include, ...(opts.exclude !== undefined ? { exclude: opts.exclude } : {}), + ...(opts.requirements !== undefined ? { requirements: opts.requirements } : {}), ...(ctx.registry !== undefined ? { registry: ctx.registry } : {}), }); diff --git a/server/typescript/packages/codegen-ts/src/requirement-walk.ts b/server/typescript/packages/codegen-ts/src/requirement-walk.ts index 028fd89bb5..9b4fc55666 100644 --- a/server/typescript/packages/codegen-ts/src/requirement-walk.ts +++ b/server/typescript/packages/codegen-ts/src/requirement-walk.ts @@ -68,15 +68,28 @@ export function concernOf(node: MetaData): string { */ export const NO_CONCERN = "*"; +/** FR-023 — the key a ledger predicate (`GenContext.inLedger`) reads for a requirement: + * `::`, or the bare path when the effective package is empty. */ +export function requirementLedgerKey(view: Pick): string { + return view.package === "" ? view.path : `${view.package}::${view.path}`; +} + /** - * Depth-first walk of every `requirement.*` node, nested ones included. + * Depth-first walk of every `requirement.*` node in the project's ledger, nested ones + * included. `inLedger` is the collection's ledger predicate (`Collection.inLedger`), read + * at `requirementLedgerKey`: a dependency's requirement the project did not inherit is + * left out. Omitted, every loaded requirement is the ledger, which is right for a model + * loaded with no dependencies. * * Unresolvable `@implementedBy` references are skipped rather than thrown on — * resolution severity is `meta verify`'s job (it depends on `@status`, which is why * it cannot live in the loader), and codegen must not fail a build over a * diagnostic another command owns. */ -export function walkRequirements(root: MetaData): WalkedRequirement[] { +export function walkRequirements( + root: MetaData, + inLedger?: (fqn: string) => boolean, +): WalkedRequirement[] { const out: WalkedRequirement[] = []; const visit = (node: MetaData, prefix: string): void => { @@ -86,6 +99,10 @@ export function walkRequirements(root: MetaData): WalkedRequirement[] { // Same referrer-package basis the CLI's checks use, so a bare reference binds // package-locally under the ADR-0042 contract. const referrerPkg = effectiveRequirementPackage(node); + if (inLedger !== undefined && !inLedger(requirementLedgerKey({ package: referrerPkg, path }))) { + for (const child of node.children()) visit(child, path); + return; + } const targets: ResolvedClaim[] = []; for (const ref of req.implementedBy()) { @@ -350,10 +367,18 @@ export function requirementTestIdentity( // language ports, and these orders are pinned by a corpus all five ports run. const compareCodeUnits = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0); -/** Every test the generator would emit, sorted by id. */ +/** + * Every test the generator would emit for the project's ledger, sorted by id. Pass the + * collection's `inLedger`, as the generator receives it; omitted, every loaded + * requirement is the ledger (see `walkRequirements`). + */ export function requirementTestIdentities( root: MetaData, - opts: { grain?: RequirementTestGrain; filter?: (r: RequirementView) => boolean } = {}, + opts: { + grain?: RequirementTestGrain; + filter?: (r: RequirementView) => boolean; + inLedger?: (fqn: string) => boolean; + } = {}, ): RequirementTestIdentity[] { const filter = opts.filter ?? defaultRequirementTestFilter; // Checked here as well as per requirement, so a bad grain is refused even over a @@ -361,7 +386,7 @@ export function requirementTestIdentities( const grain = opts.grain ?? "concern"; assertRequirementTestGrain(grain); const out: RequirementTestIdentity[] = []; - for (const walked of walkRequirements(root)) { + for (const walked of walkRequirements(root, opts.inLedger)) { if (!filter(walked.view)) continue; for (const unit of requirementTestUnits(walked, grain).keys()) { out.push(requirementTestIdentity(walked, unit)); diff --git a/server/typescript/packages/codegen-ts/src/runner.ts b/server/typescript/packages/codegen-ts/src/runner.ts index d7c658499f..85054a2146 100644 --- a/server/typescript/packages/codegen-ts/src/runner.ts +++ b/server/typescript/packages/codegen-ts/src/runner.ts @@ -137,6 +137,12 @@ export interface RunGenOpts { * they pass straight through. */ scope?: (fqn: string) => boolean; + /** + * FR-023 — which requirements are this project's ledger, read with `::` + * (`Collection.inLedger`, passed straight through like `scope`). Threaded onto + * `GenContext.inLedger`. Undefined ⇒ every loaded requirement. + */ + inLedger?: (fqn: string) => boolean; /** * FR-023 §4.3 — the collection's own source files (`Collection.ownFiles`; never * a dependency's snapshot artifact), threaded onto `GenContext.sourceFiles` for @@ -945,6 +951,7 @@ export async function runGen(opts: RunGenOpts): Promise { // than per matched entity, where `matches` never runs. Absent scope ⇒ no // `select` at all, byte-identical to a project with no `scope` declared. ...(scope !== undefined && { select: scope }), + ...(opts.inLedger !== undefined && { inLedger: opts.inLedger }), config: { outDir: selfTarget.outDir, extStyle: config.extStyle, diff --git a/server/typescript/packages/codegen-ts/src/shared-model/build-shared-model.ts b/server/typescript/packages/codegen-ts/src/shared-model/build-shared-model.ts index eb61413788..3970674173 100644 --- a/server/typescript/packages/codegen-ts/src/shared-model/build-shared-model.ts +++ b/server/typescript/packages/codegen-ts/src/shared-model/build-shared-model.ts @@ -13,13 +13,19 @@ // `buildSharedModel` (design §4.3 steps 1 to 5), in order: // 1. Standalone load of `files` with the run's composed registry (the SAME vocabulary the // project's own metadata loaded with), strict. -// 2. Select top-level nodes: never `requirement.*` / `template.*` (a publisher's -// ledger and prompts are not a consumer's shapes), and matching the compiled -// include/exclude scope. +// 2. Select top-level nodes matching the compiled include/exclude scope. Never +// `template.*` (a publisher's prompts are not a consumer's shapes), and never +// `requirement.*` unless the publisher opts in with `requirements` (default off): +// a published ledger is design a consumer can choose to inherit, so publishing +// one is the publisher's decision, and an existing export keeps its bytes. // 3. Closure check: every `extends` target and every REF_BEARING_ATTR_NAMES value // of a selected node (and of its own descendants) must resolve to a SELECTED // node, else the selection is not self-contained and the build fails naming the -// (referrer, target) pairs. +// (referrer, target) pairs. A selected requirement's `@implementedBy` claims are +// followed too. They are deliberately not loader references (a planned claim +// may name a node that does not exist yet), so they are not in +// REF_BEARING_ATTR_NAMES, but an exported requirement that claimed a node the +// export leaves out would dangle in every consumer that inherits it. // 4. Serialize the selection with `serializeSharedDocument` — raw own-layer form, // `extends` preserved, sorted by resolution key. // 5. Re-load the emitted document standalone with CORE providers only, strict — a @@ -46,6 +52,9 @@ import { TYPE_REQUIREMENT, TYPE_TEMPLATE, METAMODEL_VERSION, + REQUIREMENT_ATTR_IMPLEMENTED_BY, + resolveClaimTarget, + effectiveRequirementPackage, } from "@metaobjectsdev/metadata"; import { FileSource } from "@metaobjectsdev/metadata/core"; import type { EmittedFile } from "../generator.js"; @@ -90,6 +99,9 @@ export interface SharedModelInput { readonly include: readonly string[]; /** Applied after `include`. */ readonly exclude?: readonly string[]; + /** Publish the selected `requirement.*` nodes as well. Default false: the export holds + * shapes only, exactly as before this option existed. `template.*` is never published. */ + readonly requirements?: boolean; /** The run's composed registry (`ctx.registry`), so the publisher's own * consumer-supplied providers are honoured exactly as they were for the project's * main load. Absent: core vocabulary. */ @@ -177,9 +189,27 @@ function checkClosure( const value = node.ownAttr(attrName); if (typeof value === "string") candidates.push(value); } + const targets: MetaData[] = []; for (const raw of candidates) { const resolved = resolveObjectRef(standaloneRoot, refOwner(raw), referrerPkg).node; - if (resolved === undefined) continue; // already validated at load — defensive only + if (resolved !== undefined) targets.push(resolved); // else already refused at load — defensive only + } + if (node.type === TYPE_REQUIREMENT) { + // `@implementedBy` resolves with the requirement's own resolver, in the + // requirement's effective package (ADR-0042), owner segment only: a member + // claim (`Customer.email`) is closed when its owner is selected. A claim that + // resolves nothing here names nothing the export could carry (a planned + // requirement may name a node that does not exist yet), so it is not a pair. + // ADR-0039 sanctioned own-only case, as for the ref-bearing attrs above. + const claims = node.ownAttr(REQUIREMENT_ATTR_IMPLEMENTED_BY); + const claimPkg = effectiveRequirementPackage(node); + for (const ref of Array.isArray(claims) ? claims : []) { + if (typeof ref !== "string") continue; + const owner = resolveClaimTarget(standaloneRoot, ref.split(CHILD_REF_SEPARATOR)[0] ?? "", claimPkg); + if (owner !== undefined) targets.push(owner); + } + } + for (const resolved of targets) { const targetKey = resolved.resolutionKey(); if (selectedKeys.has(targetKey)) continue; const dedupeKey = `${referrerKey}${DEDUPE_KEY_SEPARATOR}${targetKey}`; @@ -225,12 +255,14 @@ export async function buildSharedModel(input: SharedModelInput): Promise node.type !== TYPE_REQUIREMENT && node.type !== TYPE_TEMPLATE) + .filter((node) => node.type !== TYPE_TEMPLATE) + .filter((node) => input.requirements === true || node.type !== TYPE_REQUIREMENT) .filter((node) => matchesScope(node.resolutionKey(), compiled)); if (selected.length === 0) { + const dropped = input.requirements === true ? "template.*" : "requirement.* and template.*"; throw new Error( `sharedModelFile("${input.name}"): selected no nodes (include/exclude, always ` + - `excluding requirement.* and template.*) — nothing to publish. Check \`include\`.`, + `excluding ${dropped}) — nothing to publish. Check \`include\`.`, ); } @@ -238,10 +270,21 @@ export async function buildSharedModel(input: SharedModelInput): Promise n.resolutionKey())); const closureFailures = checkClosure(standaloneRoot, selected, selectedKeys); if (closureFailures.length > 0) { - const lines = closureFailures.map((p) => ` ${p.referrer} → ${p.target}`).join("\n"); + // Same sanctioned root-level own read as step 2: a template is never exported, so a + // reference to one can only be closed by excluding the referrer. + const templateKeys = new Set( + standaloneRoot.ownChildren().filter((n) => n.type === TYPE_TEMPLATE).map((n) => n.resolutionKey()), + ); + const lines = closureFailures + .map((p) => + templateKeys.has(p.target) + ? ` ${p.referrer} → ${p.target}: templates are never exported; exclude the referrer` + : ` ${p.referrer} → ${p.target}: include it or exclude the referrer`, + ) + .join("\n"); throw new Error( `sharedModelFile("${input.name}"): the selection is not closed — these references ` + - `point outside it; include it or exclude the referrer:\n${lines}`, + `point outside it:\n${lines}`, ); } diff --git a/server/typescript/packages/codegen-ts/test/requirement-tests-generator.test.ts b/server/typescript/packages/codegen-ts/test/requirement-tests-generator.test.ts index 78b595c477..e9b2d1e27a 100644 --- a/server/typescript/packages/codegen-ts/test/requirement-tests-generator.test.ts +++ b/server/typescript/packages/codegen-ts/test/requirement-tests-generator.test.ts @@ -59,6 +59,7 @@ const MODEL = { async function emit( opts: RequirementTestsOpts = {}, warn: (m: string) => void = () => {}, + inLedger?: (fqn: string) => boolean, ): Promise { const r = await new MetaDataLoader().load([ new InMemoryStringSource(JSON.stringify(MODEL)), @@ -72,6 +73,7 @@ async function emit( matches: () => true, config: {}, warn, + ...(inLedger !== undefined ? { inLedger } : {}), } as unknown as GenContext; return (await requirementTests(opts).generate(ctx)) as EmittedFile[]; } @@ -87,6 +89,22 @@ describe("requirementTests — fan-out", () => { }); }); +describe("requirementTests — the project's ledger (FR-023)", () => { + test("a requirement outside the ledger gets no stub, read by ::", async () => { + const seen: string[] = []; + const files = await emit({}, () => {}, (fqn) => { + seen.push(fqn); + return false; + }); + expect(files).toEqual([]); + expect(seen).toContain("acme::probe::links.slugField"); + }); + + test("a ledger admitting the requirement emits exactly as without one", async () => { + expect(await emit({}, () => {}, () => true)).toEqual(await emit()); + }); +}); + describe("requirementTests — policy belongs to the app", () => { test("the DEFAULT filter excludes L3, which is below the link floor", async () => { const files = await emit(); diff --git a/server/typescript/packages/codegen-ts/test/shared-model-conformance.test.ts b/server/typescript/packages/codegen-ts/test/shared-model-conformance.test.ts index 1beba82d42..639a3e0114 100644 --- a/server/typescript/packages/codegen-ts/test/shared-model-conformance.test.ts +++ b/server/typescript/packages/codegen-ts/test/shared-model-conformance.test.ts @@ -33,6 +33,7 @@ interface Case { readonly include: readonly string[]; readonly exclude?: readonly string[]; readonly version: string; + readonly requirements?: boolean; readonly providers?: readonly string[]; }; readonly expectArtifact?: string; @@ -65,7 +66,7 @@ function read(rel: string): string { function classify(err: Error): Refusal { if (/selected no nodes/.test(err.message)) return { reason: "empty-selection" }; if (/selection is not closed/.test(err.message)) { - const pairs = [...err.message.matchAll(/^ {2}(\S+) → (\S+)$/gm)].map((m) => ({ + const pairs = [...err.message.matchAll(/^ {2}(\S+) → (\S+):/gm)].map((m) => ({ referrer: m[1]!, target: m[2]!, })); @@ -82,6 +83,7 @@ async function publish(c: Case) { files: c.input.files.map((f) => resolve(CORPUS_DIR, f)), include: c.input.include, ...(c.input.exclude !== undefined ? { exclude: c.input.exclude } : {}), + ...(c.input.requirements !== undefined ? { requirements: c.input.requirements } : {}), ...(providers.length > 0 ? { registry: composeRegistry([...coreProviders, ...providers]) } : {}), }); return renderSharedModelFiles(model, c.input.version); diff --git a/server/typescript/packages/codegen-ts/test/shared-model-file.test.ts b/server/typescript/packages/codegen-ts/test/shared-model-file.test.ts index 6ee797c377..1dd4a24477 100644 --- a/server/typescript/packages/codegen-ts/test/shared-model-file.test.ts +++ b/server/typescript/packages/codegen-ts/test/shared-model-file.test.ts @@ -263,7 +263,7 @@ describe("sharedModelFile()", () => { await expect( gen(sharedModelFile({ name: "acme-common", include: ["acme::common::Secret"] }), tmp), ).rejects.toThrow( - /include it or exclude the referrer:[\s\S]*acme::common::Secret → acme::common::Address/, + /not closed[\s\S]*acme::common::Secret → acme::common::Address: include it or exclude the referrer/, ); }); @@ -299,6 +299,50 @@ describe("sharedModelFile()", () => { ); }); + test("requirements: true publishes the selected requirement, and the default leaves it out", async () => { + const opts = { name: "acme-common", include: ["acme::common::**"], exclude: ["acme::common::Secret"], version: "1.0.0" }; + await gen(sharedModelFile(opts), tmp); + expect(JSON.parse(readFileSync(join(tmp, "metaobjects.pkg.json"), "utf-8")).nodes) + .not.toContain("acme::common::KeepSecretsSafe"); + await gen(sharedModelFile({ ...opts, requirements: true }), tmp); + expect(JSON.parse(readFileSync(join(tmp, "metaobjects.pkg.json"), "utf-8")).nodes) + .toContain("acme::common::KeepSecretsSafe"); + expect(readFileSync(join(tmp, "acme-common.metaobjects.json"), "utf-8")).toContain('"requirement.functional"'); + }); + + test("a selected requirement claiming a template is refused: templates are never exported", async () => { + const fileC = join(tmp, "metaobjects", "meta.common-prompts.json"); + writeFileSync( + fileC, + JSON.stringify({ + "metadata.root": { + package: "acme::common", + children: [ + { "template.prompt": { name: "Greeting", "@payloadRef": "Address", "@textRef": "x/y" } }, + { + "requirement.functional": { + name: "GreetsCustomers", + "@level": 4, + "@status": "live", + "@statement": "A customer is greeted at their address.", + "@counterexample": "A customer never greeted.", + "@implementedBy": ["Greeting"], + }, + }, + ], + }, + }), + ); + const refusal = gen( + sharedModelFile({ name: "acme-common", include: ["acme::common::**"], files: [fileA, fileC], requirements: true }), + tmp, + ); + await expect(refusal).rejects.toThrow( + /acme::common::GreetsCustomers → acme::common::Greeting: templates are never exported; exclude the referrer/, + ); + await expect(refusal).rejects.not.toThrow(/Greeting: include it/); + }); + test("empty selection fails with a clear error", async () => { await expect( gen(sharedModelFile({ name: "acme-common", include: ["acme::nothing::**"] }), tmp), diff --git a/server/typescript/packages/sdk/src/collection.ts b/server/typescript/packages/sdk/src/collection.ts index 98803015db..75de1013f5 100644 --- a/server/typescript/packages/sdk/src/collection.ts +++ b/server/typescript/packages/sdk/src/collection.ts @@ -134,6 +134,13 @@ export interface Collection { * codegen output and never the coverage denominator (T18 ruling, all ports). */ readonly inCoverage: (fqn: string) => boolean; + /** + * FR-023 — is the requirement at `fqn` (its effective package, `::`, its dotted path) part + * of this project's ledger? Its own requirements always are; a dependency's are only when + * `requirements.inherit` NAMES the dependency's package (the `explicitlyIncludes` rule). + * Read by the requirement gate, its summary and lint, and the requirement-tests generator. + */ + readonly inLedger: (fqn: string) => boolean; /** Output filter for migrate/verify --db (`migrate.scope`). Undefined => the * command governs everything loaded, and that undefined is load-bearing: it * is what leaves the expected schema untouched (migrate-ts `scope.ts`). */ @@ -278,6 +285,7 @@ export async function resolveCollection( let specs: readonly SourceSpec[] = DEFAULT_SOURCES; let scopeSpec: Config["scope"]; let migrateSpec: string[] | undefined; + let inheritSpec: string[] | undefined; let dependencySpecs: readonly DependencySpec[] = []; let libraries: readonly string[] = []; let physicalNaming: PhysicalNaming = DEFAULT_PHYSICAL_NAMING; @@ -297,6 +305,7 @@ export async function resolveCollection( if (cfg.sources.length > 0) specs = cfg.sources; scopeSpec = cfg.scope; migrateSpec = cfg.migrate?.scope; + inheritSpec = cfg.requirements?.inherit; dependencySpecs = cfg.dependencies; libraries = cfg.libraries; physicalNaming = physicalNamingFromConfig(cfg); @@ -439,6 +448,12 @@ export async function resolveCollection( // and does not name it — see `explicitlyIncludes`. inScope: (fqn: string): boolean => matchesScope(fqn, scope) && inCoverage(fqn), inCoverage, + // An imported requirement joins the ledger only when `requirements.inherit` names its + // package; a wildcard reaches it and does not name it, as for `scope.include`. + inLedger: (fqn: string): boolean => { + const pkg = packageOfResolutionKey(fqn); + return !importedPackages.has(pkg) || explicitlyIncludes(inheritSpec, pkg); + }, // Undefined ONLY when the project declares no `migrate.scope` AND imports // nothing — migrate-ts reads that undefined as "govern everything loaded", // and it is what leaves the expected schema untouched. With a dependency diff --git a/server/typescript/packages/sdk/src/config.ts b/server/typescript/packages/sdk/src/config.ts index 714862c6dd..ce84adb21c 100644 --- a/server/typescript/packages/sdk/src/config.ts +++ b/server/typescript/packages/sdk/src/config.ts @@ -207,6 +207,20 @@ export const ConfigSchema = z.object({ }) .default({}), migrate: MigrateBlock.optional(), + /** + * FR-023 — which dependencies' requirements this project takes on as its own ledger. + * `inherit` lists scope patterns, and a pattern counts only when it NAMES a dependency's + * package literally (`acme::common::**` names `acme::common`; `**` names nothing), the rule + * `scope.include` follows. An imported requirement not named here is loaded, so an overlay + * of it resolves, and is otherwise left alone: not listed, checked, summarised or given a + * generated test. A separate key from `scope.include` on purpose: that one also selects a + * package for code generation. Read by every port's config reader. + */ + requirements: z + .strictObject({ + inherit: z.array(z.string().min(1)).optional(), + }) + .optional(), /** * How a metadata name becomes a physical database name when the metadata gives none * (ADR-0058). `columns` applies to a field with no `@column`; `tables` to an object whose diff --git a/server/typescript/packages/sdk/src/memory.ts b/server/typescript/packages/sdk/src/memory.ts index 32155f6ab5..10c8f6c91b 100644 --- a/server/typescript/packages/sdk/src/memory.ts +++ b/server/typescript/packages/sdk/src/memory.ts @@ -6,6 +6,7 @@ import { packageOfResolutionKey, ParseError, TYPE_OBJECT, + TYPE_REQUIREMENT, type ErrorSource, type LoaderError, type LoadResult, @@ -457,8 +458,10 @@ function refuseUnownedPackages( // ADR-0039 SANCTIONED own-accessor case: a root-level scan. `MetaRoot` has no // super, so own and effective children are the same set here — and the // question asked is precisely "what did this tree declare at the top level", - // which is the own layer by definition. - for (const node of root.ownChildrenOfType(TYPE_OBJECT)) { + // which is the own layer by definition. Requirements too: a publisher may export its + // ledger, and a new requirement in its package would be the publisher's, not this + // project's, to every gate that reads the ledger by package. + for (const node of [...root.ownChildrenOfType(TYPE_OBJECT), ...root.ownChildrenOfType(TYPE_REQUIREMENT)]) { const key = node.resolutionKey(); const pkg = packageOfResolutionKey(key); if (!packages.has(pkg) || nodes.has(key)) continue;