Use this runbook to capture and review quality signals across the monorepo. The
dashboard job is lightweight and runs in CI (quality-metrics in
.github/workflows/quality-gates.yml), but can also be executed locally.
What is collected#
- Coverage:
coverage/coverage-summary.json(generated by your coverage run) lines percentage. - Suppressions: Counts of
eslint-disableand@ts-ignoreusages. - Technical debt markers:
TODO,FIXME, andBUGtag counts. - Dependency health: Number of outdated packages from
npm outdated. - Documentation coverage: Ratio of Markdown docs in
docs/vs. code files inservices/,sdk/,web/, andmobile/.
Prerequisites#
- Node 18+ with npm.
- Repo dependencies installed (
npm ciat repo root). - Optional but recommended: a recent coverage run that produced
coverage/coverage-summary.json.
How to run locally#
- Ensure coverage exists (optional but recommended):bash
npm run coverage:ci # or any task that writes coverage/coverage-summary.json - Capture the metrics snapshot:bash
npm run metrics:dashboard - Review the outputs:
- Latest snapshot:
reports/metrics/dashboard-latest.json - History (appends on every run):
reports/metrics/dashboard-history.json
- Latest snapshot:
CI behavior#
- Workflow:
quality-metricsjob in.github/workflows/quality-gates.yml. - Artifacts:
quality-dashboard(containsdashboard-latest.jsonanddashboard-history.json). - Coverage will be
nullif nocoverage/coverage-summary.jsonis present; run a coverage task before invoking the dashboard to populate it.
When the job fails#
- Inspect the job logs for the failing probe (coverage missing, npm outdated failures, or filesystem errors writing reports).
- Download the
quality-dashboardartifact to see the partial results and confirm which metric is missing. - Common fixes:
- Re-run coverage before metrics:
npm run coverage:ci && npm run metrics:dashboard. - Regenerate reports locally and commit if the script was updated.
- If
npm outdatedfails due to registry/network, re-run withnpm config set fetch-retries 3or retry the workflow.
- Re-run coverage before metrics:
Ownership and thresholds#
- Owners: Platform DX (default reviewers for
.github/workflows/quality-gates.yml). - Targets: Keep coverage ≥70%, drive suppression counts down over time, and
avoid growth in
TODO/FIXMEtags week over week. Escalate in#eng-qualityif debt metrics increase for two consecutive runs.
Interpreting results#
- Rising suppression or technical debt counts indicate code quality drift—schedule remediation.
- A non-null
dependency_health.outdated_count> 0 meansnpm outdatedfound packages to upgrade. - Low
documentation.doc_to_code_ratiosignals missing docs; prioritize writing or updating guides.