Skip to main content

Crate mlua_swarm_diag

Crate mlua_swarm_diag 

Source
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:

Clippyhere
LevelDiagLevel
DiagnosticDiagnostic
SuggestionSuggestion
ApplicabilityApplicability
Lint registryLintDecl / 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§

DiagSpan
Location of a Diagnostic inside 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 (see DiagSpan). Serialize-only: kind (and any DocsRef) are &'static str registry 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. uri is &'static str on purpose: every docs target is a bundled MCP resource compiled into the binary, so a dynamic string here would only enable dangling references. The mse:// scheme invariant is asserted by this crate’s tests over LINT_DECLS. Serialize-only (like Diagnostic): the &'static str fields make this a produce-side type — wire consumers read the JSON generically.
LintConfig
One layer of author-declared lint levels, with the entries that could not be honored kept aside instead of dropped.
LintDecl
Static declaration of one lint kind — the registry row. One LintDecl per kind, whatever stages that kind fires at (the per-stage level lives on the emitted Diagnostic; the decl carries the default).
Suggestion
A concrete recovery suggestion attached to a Diagnostic. Successor of the CLI’s FixHint (reason / patch_suggestion) with an explicit Applicability confidence grade.

Enums§

Applicability
Confidence grade of a Suggestion’s patch — the gate a future auto-apply surface (mse bp fix) switches on. Mirrors rustc / Clippy’s Applicability verbatim.
BpDoctorFamily
The bp_doctor lint family a DiagStage::BpDoctor diagnostic belongs to. One variant per family the tool reports today; new families (e.g. a ContextPolicyLint for GH #78) land here.
DiagElement
Which Blueprint element a DiagSpan points at. Serialized internally tagged ({"type": "Agent", "name": "greeter"}) so downstream renderers can switch on type.
DiagLevel
Severity of one Diagnostic. Mirrors Clippy’s Level, collapsed to the three bands the existing MSE surfaces actually use (bp_doctor’s INFO/WARN/BLOCK strings, compile-lint’s hard errors).
DiagStage
Which producing stage emitted a Diagnostic. Serialized internally tagged ({"type": "BpDoctor", "family": "WorkerBindingLint"}) so downstream renderers can switch on type without knowing every family.
LintCategory
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).
LintSetting
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.
ResolvedLint
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::kind values are drawn from here (asserted by the producing crates’ tests).

Functions§

flow_node_renamed
One flow-node-renamed finding for the legacy assign node at json_path (a JSONPath into the Blueprint document, e.g. $.flow.children[2]), as reported by stage.
is_compile_hard_error
Whether decl is a compile-stage hard error rather than a lint — i.e. its LintDecl::default_level is DiagLevel::Error, so Compiler::compile refuses the Blueprint and no author setting can change that at compile.
lint_decl
Look up the LintDecl for a kind key. None for unknown kinds — producers should treat that as a bug (every emitted Diagnostic::kind must be declared).
removed_spawner_hint_suggestion
The recovery attached to every removed-spawner-hint diagnostic, whichever stage emitted it.
resolve_level
Resolve the effective level of decl against the declared layers.