Expand description
Unified Clippy-style diagnostic model for the mlua-swarm authoring-time feedback surface (GH #79).
§Why this crate exists
MSE checks the same class of Blueprint invariants at several stages —
compile-lint (mse bp build / bp_build), post-register lint
(bp_doctor), launch pre-flight, runtime, $file/$agent_md ref
resolution — and each stage historically produced its own ad-hoc
shape (a typed CompileError enum, a substring-matched FixHint,
per-family serde_json::Value blobs). This crate is the shared
vocabulary those stages converge on, mirroring Clippy’s design:
| Clippy | here |
|---|---|
Level | DiagLevel |
Diagnostic | Diagnostic |
Suggestion | Suggestion |
Applicability | Applicability |
Lint registry | LintDecl / LINT_DECLS |
#[allow] / #[warn] / #[deny] | LintSetting / LintConfig / resolve_level |
§Boundary discipline
This crate depends on no other mlua-swarm crate (serde only), so
it can sit between producers (mlua-swarm’s
impl From<&CompileError> for Diagnostic) and consumers
(mlua-swarm-cli’s bp_doctor response, renderers, future
mse bp fix tooling) without either side coupling to the other’s
internals. Historically the CLI re-parsed the compiler’s
pre-formatted error strings via contains(...) precisely to avoid
that coupling — this crate is the typed replacement for that
substring seam.
§Adding a new lint
The 4-step recipe (declare in LINT_DECLS → document → produce →
test) is documented in the bundled MCP resource
mse://guides/lint-diagnostic-model.
Structs§
- Diag
Span - Location of a
Diagnosticinside the Blueprint document — MSE’s analogue of a source span. Blueprints are JSON documents, not source text, so the “span” is an element identity plus an optional JSONPath refinement. - Diagnostic
- One diagnostic finding — the unified shape every MSE feedback stage
produces. Field-by-field mirror of Clippy’s
Diagnostic, adapted to a JSON-document world (seeDiagSpan). Serialize-only:kind(and anyDocsRef) are&'static strregistry keys, so this type is constructed by producers, never parsed back — wire consumers read the JSON generically. - DocsRef
- Stable pointer into the bundled
mse://docs surface.uriis&'static stron purpose: every docs target is a bundled MCP resource compiled into the binary, so a dynamic string here would only enable dangling references. Themse://scheme invariant is asserted by this crate’s tests overLINT_DECLS. Serialize-only (likeDiagnostic): the&'static strfields make this a produce-side type — wire consumers read the JSON generically. - Lint
Config - One layer of author-declared lint levels, with the entries that could not be honored kept aside instead of dropped.
- Lint
Decl - Static declaration of one lint kind — the registry row. One
LintDeclper kind, whatever stages that kind fires at (the per-stage level lives on the emittedDiagnostic; the decl carries the default). - Suggestion
- A concrete recovery suggestion attached to a
Diagnostic. Successor of the CLI’sFixHint(reason/patch_suggestion) with an explicitApplicabilityconfidence grade.
Enums§
- Applicability
- Confidence grade of a
Suggestion’spatch— the gate a future auto-apply surface (mse bp fix) switches on. Mirrors rustc / Clippy’sApplicabilityverbatim. - BpDoctor
Family - The
bp_doctorlint family aDiagStage::BpDoctordiagnostic belongs to. One variant per family the tool reports today; new families (e.g. aContextPolicyLintfor GH #78) land here. - Diag
Element - Which Blueprint element a
DiagSpanpoints at. Serialized internally tagged ({"type": "Agent", "name": "greeter"}) so downstream renderers can switch ontype. - Diag
Level - Severity of one
Diagnostic. Mirrors Clippy’sLevel, collapsed to the three bands the existing MSE surfaces actually use (bp_doctor’sINFO/WARN/BLOCKstrings, compile-lint’s hard errors). - Diag
Stage - Which producing stage emitted a
Diagnostic. Serialized internally tagged ({"type": "BpDoctor", "family": "WorkerBindingLint"}) so downstream renderers can switch ontypewithout knowing every family. - Lint
Category - Coarse lint grouping — Clippy-style categories, collapsed to the
five MSE needs as a baseline (finer user-facing
#[allow]-style control is a declared non-goal of GH #79). - Lint
Setting - Author-declared level for one lint kind or group — the diag-side twin
of
mlua_swarm_schema::LintSetting(same three lowercase wire literals). The twin exists because this crate depends on no other mlua-swarm crate: the schema owns the Blueprint-side vocabulary, this crate owns resolution, and the consumer (bp_doctor) maps one onto the other. - Resolved
Lint - Outcome of resolving one lint kind against the declared layers.
Constants§
- LINT_
DECLS - The static lint registry: one entry per lint kind across every
stage. This is the single source that enumerates all lints for docs
generation and future opt-out surfaces;
Diagnostic::kindvalues are drawn from here (asserted by the producing crates’ tests).
Functions§
- flow_
node_ renamed - One
flow-node-renamedfinding for the legacyassignnode atjson_path(a JSONPath into the Blueprint document, e.g.$.flow.children[2]), as reported bystage. - is_
compile_ hard_ error - Whether
declis a compile-stage hard error rather than a lint — i.e. itsLintDecl::default_levelisDiagLevel::Error, soCompiler::compilerefuses the Blueprint and no author setting can change that at compile. - lint_
decl - Look up the
LintDeclfor a kind key.Nonefor unknown kinds — producers should treat that as a bug (every emittedDiagnostic::kindmust be declared). - removed_
spawner_ hint_ suggestion - The recovery attached to every
removed-spawner-hintdiagnostic, whichever stage emitted it. - resolve_
level - Resolve the effective level of
declagainst the declared layers.