Model quality scorecards
Quality evaluates logical entities and attributes without mutating the model. Scores are integer basis points (0–10000) and are useful for comparing changes, not for asserting that data is complete or secure.
Metric formulas and weights
| Metric | Weight | Denominator and pass condition |
|---|---|---|
| Definitions | 20% | Entity/attribute description has at least the configured number of Unicode characters after trimming |
| Naming | 20% | Applicable naming rules produce no finding on the object |
| Keys | 20% | Entity has a nonempty primary key whose members exist and are non-null |
| Connectivity | 15% | Entity participates in a relationship, many-to-many association or generalization |
| Lint | 15% | Twice the scope object count; subtract 2 per error and 1 per included warning, clamping at zero; required-classification errors are counted in Classification to prevent duplicate penalties |
| Classification | 10% | Every required classification rule has a valid level for each entity/attribute |
Every coverage score is (passed * 10000 + total/2) / total, clamped to 10000; zero denominator receives full credit. The overall score is the weighted metric sum rounded half up. The default definition threshold is 10 Unicode scalar values; accepted thresholds are 1–1000.
Areas and findings
Overall includes every logical entity and attribute. Each named subject area includes only its member entities and their attributes; connectivity considers incident relationships regardless of other areas. Area names sort canonically. JSON records metric names, weights, numerator, denominator, score and sorted failure findings. Text displays the six metrics and named area summaries.
CLI, reports, RPC and browser
bluep quality devdata/models/quality
bluep quality devdata/models/quality --json
bluep quality . --minimum-definition-chars 12 --no-warnings
bluep quality . --from HEAD~10 --to HEAD
bluep report devdata/models/quality --template quality --format csv
The quality report family supports text, Markdown, HTML, CSV, XLSX and PDF. XLSX/PDF contain summary, metrics, findings and optional trend tables. JSON-RPC exposes quality.run. The browser's Quality panel reads GET /api/quality with optional query parameters and displays overall and per-area metrics; with Git revisions it plots an accessible SVG polyline. All quality operations are read-only and require only View permission in team mode.
First-parent Git trend
Trend calculation uses git rev-list --first-parent --reverse, reads each historical model using Git objects (no checkout or worktree changes), deduplicates identical canonical model snapshots, and records full commit ids, Unix timestamps and overall scores. Revisions beginning with a hyphen are rejected. The model directory must be confined to the Git repository. Missing model paths and invalid revision ranges are errors.
Interpretation and limitations
The six metrics are advisory coverage measures rather than evidence of database correctness, privacy or performance. Naming and lint findings depend on configured rules. An empty scope receives full coverage by convention. History only includes Git commits reachable on the selected first-parent path and cannot infer undocumented design intent. No autofix or remote history service is provided.