Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/adoption.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ A key given next to `<<` wins over the merged one, and a list is replaced, not j

## In CI

`--format` picks the report: `text` (default), `json`, `sarif` (GitHub Code Scanning), `github` (annotations on the changed files, with a warning for each part of the code the check could not read, a notice when the run judges only a part by design (`--diff`, `--component`, `--scope`) and a notice when the indexes came from the cache) and `junit` (a failed test case per violation). `sarif` gives what a run leaves out (the narrowing, each evidence gap with its files, the cache) as notifications of its invocation, errors under `--require-evidence`; `junit` gives them in `<system-out>`, and under `--require-evidence` a failed test case per evidence gap.
`--format` picks the report: `text` (default), `json`, `sarif` (GitHub Code Scanning), `github` (annotations on the changed files) and `junit` (a failed test case per violation). Each note a run makes of itself has one kind, which every format names alike: `narrowed` (the run judges only a part by design: `--diff`, `--component`, `--scope`), `evidence-gap` (code the check could not read or judge), `accepted-gap` (an `uncovered_ok` entry, with its reason and files), `unused-allowance` (under `--suggest`) and `cache` (the indexes came from the cache). `github` titles each annotation `easement <kind>`: a narrowing, an accepted gap (one per `uncovered_ok` entry) and the cache are notices, an evidence gap a warning, or an error under `--require-evidence`. `sarif` gives them as notifications of its invocation, each with its kind as `descriptor.id` (declared in `tool.driver.notifications`) and its files as locations, evidence gaps as errors under `--require-evidence`. `junit` gives them in `<system-out>`, each line opening with its kind (`narrowed: …`, `evidence gap: …; to close: …`, `accepted gap (uncovered_ok: …) because …; files: …`), and under `--require-evidence` a failed test case per evidence gap; an accepted gap is never a failed test case.

The repository is a GitHub Action:

Expand Down
2 changes: 1 addition & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -349,7 +349,7 @@ rules:
- { name: "db.Client", because: use db.Scoped so every query is tenant-bound }
```

`forbid_symbol` names what a component must not use, as `module.Name`: the module by its whole path or by the end of it, cut where its language cuts module names, in every language alike (`example.com/app/tags.DeleteIn` or `tags.DeleteIn` in Go, `app::db::client::Client` or `client::Client` in Rust, `app.db.client.Client` or `client.Client` in Python); a short end may match several modules, and the item covers each. A member of a type (a method, a variant, a constant) follows the type it is used through: `db.Client.Query` in Go, `std::sync::atomic::Ordering.Relaxed` in Rust, `Shop::Db::Client.query` in Ruby. `public_symbols` is the other side: other components may use only these names from the component's packages (`only Scoped and Tx`). Both are `symbol` violations at the line of the use and can be suppressed inline. A `forbid_symbol` name that matches no symbol of the index, while one of the same name is defined in a namespace under its qualifier (`I18n.locale` is defined as `I18n::Base.locale`), can never fire, so it fails as `unmatched` at its line in the policy, with the name it probably means, as an `in` pattern that matches no file does. A name the index has never seen stays silent, since forbidding what the code does not use yet is what the rule is for; and nothing is said while the index is partial.
`forbid_symbol` names what a component must not use, as `module.Name`: the module by its whole path or by the end of it, cut where its language cuts module names, in every language alike (`example.com/app/tags.DeleteIn` or `tags.DeleteIn` in Go, `app::db::client::Client` or `client::Client` in Rust, `app.db.client.Client` or `client.Client` in Python); a short end may match several modules, and the item covers each. A member of a type (a method, a variant, a constant) follows the type it is used through: `db.Client.Query` in Go, `std::sync::atomic::Ordering.Relaxed` in Rust, `Shop::Db::Client.query` in Ruby. `public_symbols` is the other side: other components may use only these names from the component's packages (`only Scoped and Tx`). Both are `symbol` violations at the line of the use and can be suppressed inline. A `forbid_symbol` name that matches no symbol of the index, while one of the same name is defined in a namespace under its qualifier (`I18n.locale` is defined as `I18n::Base.locale`), can never fire, so it fails as `unmatched` at its line in the policy, with the name it probably means, as an `in` pattern that matches no file does. A name the index has never seen stays silent, since forbidding what the code does not use yet is what the rule is for; and nothing is said while an evidence gap leaves the index short.

A top-level `forbid_symbol` of the same shape applies to every checked file: components and the files that belong to no component (`unowned` in `strict` mode) alike, and a component's own list adds to it. Write a name forbidden across the project once, instead of in every rule:

Expand Down
2 changes: 1 addition & 1 deletion docs/languages.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ Indexers are slow (a second or two for a small project, ten or more for a big on
- **Kept:** the newest 32 indexes of each directory and indexer, and 4 GiB in all: past that the least recently used indexes go, whatever directory they belong to.
- **Not looked at:** dependencies outside the project (`node_modules`, `vendor/`, the Go module cache, the Python environment: `.venv`, `venv`, `.tox`, `.nox`), and the toolchain an indexer calls on the `PATH` (`go`, `python3`, `dotnet`, the JDK, Maven). After changing them without touching a lock file, run `easement check --no-cache`. An indexer run through rustup or a mise shim is known by the binary that rustup or mise runs in the directory of the index; other proxies (Volta, proto) are not resolved, so after switching a toolchain behind them run `--no-cache` too.

`--format json` reports `stats.indexed` and `stats.from_cache`. When an index came from the cache, the report says so, in `cached` of `--format json` and in a line of the text, with what the key leaves out and that `--no-cache` indexes again. Every command that reads the indexes (`check`, `baseline`, `impact`, `why`, `suggest`, `graph`, `review`, `propose`, `init`) takes `--no-cache` and `--cache-only`. `impact` (`cached` in its JSON), `why`, `suggest` and `baseline` say it the same way; `graph` and `suggest --patch`, whose output is a diagram or a patch, say it on stderr, with `graph` naming there the reasons its graph may be partial too.
`--format json` reports `stats.indexed` and `stats.from_cache`. When an index came from the cache, the report says so, in `cached` of `--format json` and in a line of the text, with what the key leaves out and that `--no-cache` indexes again. Every command that reads the indexes (`check`, `baseline`, `impact`, `why`, `suggest`, `graph`, `review`, `propose`, `init`) takes `--no-cache` and `--cache-only`. `impact` (`cached` in its JSON), `why`, `suggest` and `baseline` say it the same way; `graph` and `suggest --patch`, whose output is a diagram or a patch, say it on stderr, with `graph` listing there, as every other command does, the evidence gaps that leave dependencies out of the drawing (with how to close each and its files) and the accepted gaps with their reasons: an accepted file is unread all the same, so a drawing without its dependencies counts it as both.

`--cache-only` runs no indexer and exits 3 when an index is not cached. `easement doctor --cache` asks the same of the cache without a check: it says, per index, whether it is cached and why not, and exits 3 on a miss. A CI job can call it first and set up an indexer's toolchain (the Go module cache, `npm install`) only on a miss; the dependencies an indexer needs are checked only when it runs, since a cached index was written with them in place.

Expand Down
2 changes: 1 addition & 1 deletion easement.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@
]
},
"uncovered_ok": {
"description": "Source files that no indexer covers and that may stay that way (globs, each with the reason). Others are listed in the report as not covered, and the result is marked partial.",
"description": "Source files that no indexer covers and that may stay that way (globs, each with the reason): accepted gaps, still listed in the report. Others are evidence gaps.",
"type": "array",
"items": {
"$ref": "#/definitions/Accepted"
Expand Down
2 changes: 1 addition & 1 deletion skills/easement/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Run `easement check`. It exits 0 when the code matches the config, 1 on violatio
- `--format json` gives the same report as data. `narrowed` lists what you asked to judge alone (`--diff`, `--component`, `--scope`). `evidence_gaps` lists code the check could not read or judge, each with its files, the place of each part where it knows them (`places`: `file`, `line`, `specifier`), and how to close it: a pass says nothing about that code, so say so and name the files. `accepted_gaps` lists files `uncovered_ok` accepts, with its reason: they are unread too, but by decision. `suppressions` lists each inline suppression the run honoured, at its directive, with the violations it `excused`: they do not fail, but one your change relies on is listed, so name it in your summary. When `cached` is set, the indexes came from the cache; after changing dependencies outside the project without a lock file, run `easement check --no-cache`.
- On exit 2, read the message. For a missing indexer or missing dependencies, run `easement doctor`.
- When your change touches the policy (`easement.yml`, a file it extends, its diagram, the baseline), run `easement review --base <base>` and put what it says in the pull request: the pairs of components newly permitted or rejected, the surfaces widened, the baseline entries and `exclude`, `uncovered_ok` or `warn` entries added. It always exits 0; `check` is the gate.
- `easement impact --diff <base>` lists every file that depends on your change, the nearest first, each with the shortest chain of imports from it to the changed file it reaches: run the tests among them, the nearest first. When it says `Partial`, files no indexer read or files the change deletes may hide more. `Cached:` means the indexes came from the cache; `--no-cache` indexes again.
- `easement impact --diff <base>` lists every file that depends on your change, the nearest first, each with the shortest chain of imports from it to the changed file it reaches: run the tests among them, the nearest first. When it lists `Evidence gaps`, files no indexer read or files the change deletes may hide more; files listed under `Accepted gaps` are unread too. `Cached:` means the indexes came from the cache; `--no-cache` indexes again.

## When the check fails

Expand Down
42 changes: 32 additions & 10 deletions src/commands.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ use std::path::{Path, PathBuf};
use anyhow::{Context, Result};

use crate::baseline::{Baseline, Verdict};
use crate::components::ComponentMap;
use crate::components::{AcceptedGap, ComponentMap};
use crate::policy::Policy;
use crate::project::{self, Analysis, Project};
use crate::{
Expand Down Expand Up @@ -481,11 +481,36 @@ pub fn policy(config: &Path) -> Result<resolved::ResolvedPolicy> {
}

/// A drawing of the components and the dependencies between them, with what
/// it leaves out apart from it.
/// it leaves out apart from it. `--focus` narrows nothing: the drawing shows
/// what it draws.
pub struct Drawn {
pub diagram: String,
/// The evidence gaps and the cache note, for a channel other than the diagram's.
pub notes: Vec<String>,
/// The gaps that leave dependencies out of the drawing, every file no
/// indexer read among them, `uncovered_ok` or not.
pub evidence_gaps: Vec<report::EvidenceGap>,
/// Files no indexer read that `uncovered_ok` accepts, by the entry that accepts them.
pub accepted_gaps: Vec<AcceptedGap>,
/// Set when indexes came from the cache: what their key leaves out and how
/// to index again.
pub cached: Option<String>,
}

impl Drawn {
/// What the drawing leaves out, for a channel other than the diagram's: the
/// gaps as every command says them, then the cache note.
pub fn notes(&self) -> String {
let mut out = report::gap_lines(
&self.evidence_gaps,
&self.accepted_gaps,
"an arrow through this code may be missing from the drawing",
false,
false,
);
if let Some(note) = &self.cached {
out.push_str(&format!("easement: {note}\n"));
}
out
}
}

/// Draws the components, or only `focus` and the ones it shares an arrow with.
Expand All @@ -500,11 +525,6 @@ pub fn graph(
project.config().require_component(name)?;
}
let analysis = project.analyze(cache)?;
let notes = report::evidence_gaps(&analysis.stats)
.into_iter()
.map(|gap| format!("partial: {}", gap.message))
.chain(report::cache_note(&analysis.stats))
.collect();
Ok(Drawn {
diagram: graph::render(
format,
Expand All @@ -513,7 +533,9 @@ pub fn graph(
&analysis.violations,
focus,
),
notes,
evidence_gaps: report::graph_gaps(&analysis.stats, &analysis.unindexed),
cached: report::cache_note(&analysis.stats),
accepted_gaps: analysis.accepted,
})
}

Expand Down
3 changes: 1 addition & 2 deletions src/config/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -105,8 +105,7 @@ pub struct Config {
#[serde(default)]
pub unowned: Vec<String>,
/// Source files that no indexer covers and that may stay that way (globs, each with the
/// reason). Others are listed in the report as not covered, and the result is marked
/// partial.
/// reason): accepted gaps, still listed in the report. Others are evidence gaps.
#[serde(default)]
pub uncovered_ok: Vec<Accepted>,
/// Settings of an indexer, by the language it reads: `go: { tags: [race] }` indexes Go
Expand Down
4 changes: 1 addition & 3 deletions src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -443,9 +443,7 @@ fn run(cli: Cli) -> Result<Outcome> {
} => {
let drawn = commands::graph(&config, format, focus.as_deref(), &mut cache(flags))?;
// On stderr: stdout is the diagram itself.
for note in &drawn.notes {
eprintln!("easement: {note}");
}
eprint!("{}", drawn.notes());
print!("{}", drawn.diagram);
Ok(Outcome::Passed)
}
Expand Down
7 changes: 3 additions & 4 deletions src/propose.rs
Original file line number Diff line number Diff line change
Expand Up @@ -804,10 +804,9 @@ impl Report {
Some(_) => format!("{failing} failing graph consequence(s)"),
None => "graph not judged".to_string(),
},
if self.coverage.confidence() == report::Confidence::Partial {
" (partial)"
} else {
""
match self.coverage.summary() {
reasons if reasons.is_empty() => String::new(),
reasons => format!(" ({reasons})"),
}
));
out
Expand Down
Loading