From f619ddbea3eab4ef431dc2015c3b8dba8febc793 Mon Sep 17 00:00:00 2001 From: Kirill Mokevnin Date: Wed, 18 Nov 2026 22:09:28 -0500 Subject: [PATCH] docs: say dependency, not edge, in user-facing text Refs #218 Co-Authored-By: Claude Opus 5.5 --- docs/adoption.md | 4 ++-- docs/commands.md | 2 +- docs/configuration.md | 2 +- docs/languages.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/adoption.md b/docs/adoption.md index e6d2050..d8403f6 100644 --- a/docs/adoption.md +++ b/docs/adoption.md @@ -11,7 +11,7 @@ ## Reporting on a part of the project -`--component ` and `--scope ` narrow the report to the files of a component or the files under a path; given together, a file has to satisfy both. The whole project is still read, because cycles, limits and every edge need all of it, so the run is not faster: the violations and the baseline's stale entries are those of the part (a violation is the part's when a line of its evidence is: a cycle through it, a name it re-exports), while the counters and the evidence gaps describe what was read, the whole project. Code outside the part that no indexer read can hide a cycle or a reach chain through it, so `--require-evidence` fails on it too; accept it in `uncovered_ok` when that is meant. With `--watch` the cache makes the reruns fast. +`--component ` and `--scope ` narrow the report to the files of a component or the files under a path; given together, a file has to satisfy both. The whole project is still read, because cycles, limits and every dependency between components need all of it, so the run is not faster: the violations and the baseline's stale entries are those of the part (a violation is the part's when a line of its evidence is: a cycle through it, a name it re-exports), while the counters and the evidence gaps describe what was read, the whole project. Code outside the part that no indexer read can hide a cycle or a reach chain through it, so `--require-evidence` fails on it too; accept it in `uncovered_ok` when that is meant. With `--watch` the cache makes the reruns fast. ## Monorepos @@ -127,7 +127,7 @@ The report ends with the new dependencies between components that the change bri An inline suppression the change relies on is listed too, under `Inline suppressions in this change` and in `suppressions` in JSON: one whose directive is on a changed line (a new exception, even over an old violation), and one that excuses a violation the change is held to (a new import under an old directive). It does not fail the change; a reviewer sees what was silenced, where and why (see [Suppressions](configuration.md#suppressions)). -`--plan ` (or `-` for stdin) compares the change with the plan an agent judged beforehand with `easement propose --plan`, in the same format. It looks at imports file by file, not at component edges: each import the change added that crosses a component boundary (a file of no component is a side of its own) or names an external module, and that no entry of the plan names, is listed under `Not in the plan` as `file:line -> target`; each entry the code at head lacks, a source file that does not exist among them, under `Planned, not in the code`. An entry covers an import of the same source file when it names the target file or a directory holding it, or the external module, a package covering its submodules as in `forbid_external`. An import is new as a dependency between components is new above: when every line of it is changed. The imports of the merge-base are not read, so an edited import line counts as new too, and an import pointed at another file is new however little of the line changed. Only the code read is compared: files no indexer covered (the evidence gaps name them) and files `exclude` or `target_only` keep from the checks are left out, and under `--scope` or `--component` only files in scope are. The verdict and the exit code do not change. `--format json` gives `plan.unplanned` (with `from`, `line`, `to` or `external`, `component` and `target_component`) and `plan.unrealized` (entries as the plan writes them), `--format github` a notice per unplanned import at its line and one listing the unrealized entries; `sarif` and `junit` leave it out. `--plan` needs `--diff` (exit 2 without it). +`--plan ` (or `-` for stdin) compares the change with the plan an agent judged beforehand with `easement propose --plan`, in the same format. It looks at imports file by file, not at dependencies between components: each import the change added that crosses a component boundary (a file of no component is a side of its own) or names an external module, and that no entry of the plan names, is listed under `Not in the plan` as `file:line -> target`; each entry the code at head lacks, a source file that does not exist among them, under `Planned, not in the code`. An entry covers an import of the same source file when it names the target file or a directory holding it, or the external module, a package covering its submodules as in `forbid_external`. An import is new as a dependency between components is new above: when every line of it is changed. The imports of the merge-base are not read, so an edited import line counts as new too, and an import pointed at another file is new however little of the line changed. Only the code read is compared: files no indexer covered (the evidence gaps name them) and files `exclude` or `target_only` keep from the checks are left out, and under `--scope` or `--component` only files in scope are. The verdict and the exit code do not change. `--format json` gives `plan.unplanned` (with `from`, `line`, `to` or `external`, `component` and `target_component`) and `plan.unrealized` (entries as the plan writes them), `--format github` a notice per unplanned import at its line and one listing the unrealized entries; `sarif` and `junit` leave it out. `--plan` needs `--diff` (exit 2 without it). A change to the policy is part of the change. `--diff` loads the policy at the merge-base, with the files it extends and its diagram, and judges it on the same code: a violation the new policy produces and the old one did not fails the change although no import line moved. A grant removed or a prohibition added shows up this way, while editing an unrelated rule surfaces no old debt. The header says `and what the change to the policy causes`, and `--format json` lists the changed policy inputs in `diff.policy_changed`. diff --git a/docs/commands.md b/docs/commands.md index 06fc579..a5059d0 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -117,7 +117,7 @@ What they do to the graph: `--plan ` (or `-` for stdin) judges several at once, a JSON list of `{"from": ..., "to": ...}` and `{"from": ..., "external": ...}`, and lays them over the graph together: two proposals that are allowed alone can close a cycle together, and the consequence names both. `--format json` gives `proposals` (one decision each: `allowed`, `rejected`, `unowned`, `excluded` or `target_only`, with `grant`, `rule`, `message`, `because` and `public_surface`) and `consequences` (each with `witness` and the indexes of its `proposals`), with `narrowed`, `evidence_gaps`, `accepted_gaps` and `cached` as in `check`. Once the code is written, `easement check --diff --plan ` takes the same file and lists the imports the change added that the plan did not name and the planned ones the code lacks (see [Diff mode](adoption.md#diff-mode-judging-a-pull-request)). -The baseline and suppressions never apply: they are for code that is already written. A source no component owns is `unowned`, a rejection (`orphan`) under `strict` unless `unowned` lists it; a source `exclude` hides is `excluded`, and one `target_only` names is `target_only`: `check` never reads their imports, so no rule judges them. A cycle names every proposal that makes an edge of its group of components, not only those on the shortest cycle shown. A test-only part of a file (Rust's `#[cfg(test)]`) cannot be proposed: only the test globs make a path test code, and the report notes it for such a file. The graph's evidence gaps (files no indexer read, test code not told apart) carry over. `--no-graph` judges the decisions alone, without scanning the project, and says so in `narrowed`, as a narrowing of kind `no_graph` limited to the dependency decisions: the cycles, reach chains, limits and diagram arrows the proposals cause are not judged. It exits 0 when every decision and consequence passes, 1 when one fails (a rule in `warn` is reported but does not fail), and 2 and 3 as `check` does; it takes `--config`, `--no-cache` and `--cache-only` like `check`. +The baseline and suppressions never apply: they are for code that is already written. A source no component owns is `unowned`, a rejection (`orphan`) under `strict` unless `unowned` lists it; a source `exclude` hides is `excluded`, and one `target_only` names is `target_only`: `check` never reads their imports, so no rule judges them. A cycle names every proposal that makes a dependency within its group of components, not only those on the shortest cycle shown. A test-only part of a file (Rust's `#[cfg(test)]`) cannot be proposed: only the test globs make a path test code, and the report notes it for such a file. The graph's evidence gaps (files no indexer read, test code not told apart) carry over. `--no-graph` judges the decisions alone, without scanning the project, and says so in `narrowed`, as a narrowing of kind `no_graph` limited to the dependency decisions: the cycles, reach chains, limits and diagram arrows the proposals cause are not judged. It exits 0 when every decision and consequence passes, 1 when one fails (a rule in `warn` is reported but does not fail), and 2 and 3 as `check` does; it takes `--config`, `--no-cache` and `--cache-only` like `check`. ## policy diff --git a/docs/configuration.md b/docs/configuration.md index 609c19e..8e2a9fe 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -475,7 +475,7 @@ components: because: the fake channel never gets into a release build ``` -A component with `part` owns that part of the files `in` matches, and the file itself stays with the component that has none. What turns a feature on is a dependency on it: an item of another feature (`fake = ["storage-api/fake"]` reaches the feature `fake` of `storage-api`, and the package), `features = ["fake"]` in a dependency table, and `default = ["fake"]`, which is the crate's own dependency on its feature, since `default` stays the package itself. A weak `x?/f` reaches the feature `f` of `x` and not `x`. An `optional = true` dependency belongs to what turns it on: the features that name it (`dep:x`, `x/f`) and the implicit feature named after it, which exists unless a `dep:x` names it; the crate does not depend on it until then. The external crates a feature turns on are judged as the component that owns the feature, so `forbid_external` on the crate does not cover a crate only a feature of another component enables. A name in a feature that no dependency table declares is no edge, and `default` as an item is the package itself. `default-features = false` is not modelled. A `part` that no file of the scan has (a typo, `packages` left off) owns nothing and no rule on it judges anything, so it fails as `unmatched` at its line in `easement.yml`, naming the part it likely means; `optional: true` accepts it. A component with a `part` cannot be `isolated`. +A component with `part` owns that part of the files `in` matches, and the file itself stays with the component that has none. What turns a feature on is a dependency on it: an item of another feature (`fake = ["storage-api/fake"]` reaches the feature `fake` of `storage-api`, and the package), `features = ["fake"]` in a dependency table, and `default = ["fake"]`, which is the crate's own dependency on its feature, since `default` stays the package itself. A weak `x?/f` reaches the feature `f` of `x` and not `x`. An `optional = true` dependency belongs to what turns it on: the features that name it (`dep:x`, `x/f`) and the implicit feature named after it, which exists unless a `dep:x` names it; the crate does not depend on it until then. The external crates a feature turns on are judged as the component that owns the feature, so `forbid_external` on the crate does not cover a crate only a feature of another component enables. A name in a feature that no dependency table declares is no dependency, and `default` as an item is the package itself. `default-features = false` is not modelled. A `part` that no file of the scan has (a typo, `packages` left off) owns nothing and no rule on it judges anything, so it fails as `unmatched` at its line in `easement.yml`, naming the part it likely means; `optional: true` accepts it. A component with a `part` cannot be `isolated`. ### Names of types diff --git a/docs/languages.md b/docs/languages.md index 42377f8..cc7c799 100644 --- a/docs/languages.md +++ b/docs/languages.md @@ -149,5 +149,5 @@ uncovered_ok: 1. Walk the project. For Go, TypeScript, Python, Rust, PHP, Java, C# and Ruby run the SCIP indexer and read the index; for Kotlin and Swift parse each file with tree-sitter and collect imports. 2. Turn every reference to a module into a dependency on a file inside the project, or on an external module. -3. Map both ends to components and check each edge against the rules. +3. Map both ends to components and check each dependency against the rules. 4. Compare violations with the baseline and report.