Skip to content

Commit 3c86664

Browse files
feat: Provide CLI progress UI
1 parent a0eced4 commit 3c86664

File tree

5 files changed

+627
-12
lines changed

5 files changed

+627
-12
lines changed

docs/pipeline-refactor-roadmap.md

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This document captures the long-term improvements we want to implement in the mo
1111

1212
## Workstreams
1313

14-
### 1. Pipeline Architecture & Orchestration - ✅ Completed
14+
### 1. Pipeline Architecture & Orchestration
1515

1616
| Task | Description | Dependencies | Effort |
1717
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------ |
@@ -21,6 +21,7 @@ This document captures the long-term improvements we want to implement in the mo
2121
| P1.4 | Provide a skip/only mechanism for partial runs (e.g. `--only=checks`) ✅ Completed Sep 2025 | P1.2 | S |
2222
| P1.5 | Final artifact schemas & validation — rollout completed and documented (see contributor guide & release notes) ✅ Completed Sep 2025 | P1.3 | M |
2323
| P1.6 | Consolidate shared schema definitions (shared `$defs` / generator) to keep stage contracts in sync ✅ Completed Sep 2025 | P1.3 | S |
24+
| P1.7 | Introduce orchestrator-wide progress rendering for every stage _(low priority; build on the Stage 5 indicator via shared progress utility + stage lifecycle events)_ | P1.2 | M |
2425

2526
### 2. Runtime & Codebase Consolidation - ✅ Completed
2627

@@ -50,7 +51,7 @@ This document captures the long-term improvements we want to implement in the mo
5051
| P4.1 | Split checks into a registry with metadata (category, severity, auto-fixable) ✅ Completed Oct 2025 | P2.3 | M |
5152
| P4.2 | Add configuration file to toggle check groups (`fast`, `deep`, optional ESLint/ncu`) ✅ Completed Oct 2025 | P4.1 | S |
5253
| P4.3 | Create sample dataset + regression tests for check outputs (golden files), reusing the curated fixtures where possible ✅ Completed Oct 2025 | P4.1 | M |
53-
| P4.4 | Provide CLI progress UI and Markdown summary per run | P1.2 | S |
54+
| P4.4 | Provide CLI progress UI and Markdown summary per run ✅ Completed Oct 2025 | P1.2 | S |
5455
| P4.5 | Add rule detecting modules that rely on MagicMirror core dependencies without declaring them ([#78](https://github.com/MagicMirrorOrg/MagicMirror-3rd-Party-Modules/issues/78)) | P4.1 | M |
5556
| P4.6 | Check README install/update sections for copyable fenced command blocks ([#54](https://github.com/MagicMirrorOrg/MagicMirror-3rd-Party-Modules/issues/54)) | P4.1 | S |
5657
| P4.7 | Recommend `npm ci --omit=dev` when modules expose devDependencies in instructions ([#53](https://github.com/MagicMirrorOrg/MagicMirror-3rd-Party-Modules/issues/53)) | P4.1 | S |
@@ -98,10 +99,10 @@ Routine reminders for keeping the written guidance in sync with the code:
9899

99100
Immediate action items:
100101

101-
1. Provide the CLI progress UI and Markdown summary per run (P4.4).
102-
2. Add the dependency-declaration rule for core MagicMirror usage (P4.5).
103-
3. Audit README install/update sections for copyable fenced command blocks (P4.6).
104-
4. Recommend `npm ci --omit=dev` when modules list devDependencies in instructions (P4.7).
102+
1. Add the dependency-declaration rule for core MagicMirror usage (P4.5).
103+
2. Audit README install/update sections for copyable fenced command blocks (P4.6).
104+
3. Recommend `npm ci --omit=dev` when modules list devDependencies in instructions (P4.7).
105+
4. Flag modules with multi-year inactivity that are not marked `outdated` and nudge maintainers to review status (P4.8).
105106

106107
---
107108

docs/pipeline/check-modules-reference.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This page consolidates the material that previously lived in the P2.3 rollout do
88

99
- ✅ TypeScript implementation is the default Stage 5 runner.
1010
- ✅ Comparison harness (`npm run checkModules:compare`) can execute multiple commands, capture artifacts, and (when two runs complete) produce diffs for analysis.
11+
- ✅ CLI progress indicator renders live module throughput and emits a per-run Markdown summary under `.pipeline-runs/check-modules/`.
1112
- 🔄 Follow-ups tracked here: extend harness diff coverage (README/HTML artifacts) and define warning/failure thresholds ahead of diff gating in CI.
1213

1314
## Check group configuration
@@ -24,6 +25,13 @@ The Stage 5 runner reads `scripts/check-modules/check-groups.config.json` to de
2425

2526
> The runner logs whenever overrides are applied so CI output records which groups were disabled.
2627
28+
## CLI progress & run summaries
29+
30+
- When the stage runs interactively (TTY), it now renders a single-line progress gauge on `stderr`. Disable it with `CHECK_MODULES_DISABLE_PROGRESS=1` or `CHECK_MODULES_PROGRESS=off` if you prefer the legacy log spam.
31+
- Every execution writes a Markdown + JSON summary to `.pipeline-runs/check-modules/<run-id>/`. The Markdown combines toggle state, aggregate stats, and the top modules with issues; the JSON mirrors the key metrics for tooling.
32+
- Artifact links inside the summary resolve relative to the run directory, making it easy to inspect `website/result.md`, `modules.json`, and `stats.json` produced by the run.
33+
- The harness (`npm run checkModules:compare`) preserves these summaries as well, so comparison batches keep a human-readable trail.
34+
2735
## Rule inventory
2836

2937
These are the rule IDs currently implemented by the TypeScript checker. Keep this table synchronized with the rule registry schema when adding or modifying checks.
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
import {
2+
buildRunSummaryMarkdown,
3+
formatRunDuration
4+
} from "../run-summary.js";
5+
6+
import assert from "node:assert/strict";
7+
import test from "node:test";
8+
9+
test("formatRunDuration formats durations", () => {
10+
assert.equal(formatRunDuration(-5), "unknown");
11+
assert.equal(formatRunDuration(0), "<1s");
12+
assert.equal(formatRunDuration(650), "<1s");
13+
assert.equal(formatRunDuration(1500), "2s");
14+
assert.equal(formatRunDuration(61_000), "1m 1s");
15+
assert.equal(formatRunDuration(7_500_000), "2h 5m");
16+
});
17+
18+
test("buildRunSummaryMarkdown includes key sections", () => {
19+
const startedAt = new Date("2025-10-04T10:00:00Z");
20+
const finishedAt = new Date("2025-10-04T10:01:30Z");
21+
22+
const markdown = buildRunSummaryMarkdown({
23+
runId: "test-run",
24+
startedAt,
25+
finishedAt,
26+
stats: {
27+
moduleCounter: 12,
28+
modulesWithIssuesCounter: 3,
29+
issueCounter: 8,
30+
modulesWithImageCounter: 5,
31+
repositoryHoster: {
32+
github: 9,
33+
gitlab: 3
34+
},
35+
maintainer: {
36+
alice: 4,
37+
bob: 3,
38+
carol: 2
39+
}
40+
},
41+
config: {
42+
groups: {
43+
fast: true,
44+
deep: false
45+
},
46+
integrations: {
47+
npmCheckUpdates: true,
48+
npmDeprecatedCheck: false,
49+
eslint: true
50+
}
51+
},
52+
configSources: [
53+
{kind: "default", path: "/tmp/check-groups.config.json", applied: true},
54+
{kind: "local", path: "/tmp/check-groups.config.local.json", missing: true}
55+
],
56+
artifactLinks: [
57+
{label: "result.md", path: "../../website/result.md"},
58+
{label: "stats.json", path: "../../website/data/stats.json"}
59+
],
60+
issueSummaries: [
61+
{
62+
name: "Module A",
63+
url: "https://example.com/a",
64+
issues: ["Issue one", "Issue two"]
65+
},
66+
{
67+
name: "Module B",
68+
issues: ["Issue"]
69+
}
70+
],
71+
disabledToggles: ["deep", "npmDeprecatedCheck"],
72+
issueSummaryLimit: 1
73+
});
74+
75+
assert.ok(markdown.includes("Run ID: `test-run`"));
76+
assert.ok(markdown.includes("Duration: 1m 30s"));
77+
assert.ok(markdown.includes("| groups.deep | ❌ |"));
78+
assert.ok(markdown.includes("- [result.md](../../website/result.md)"));
79+
assert.ok(markdown.includes("1. [Module A](https://example.com/a) — 2 issues"));
80+
assert.ok(markdown.includes("…and 1 additional module with issues"));
81+
assert.ok(markdown.includes("Top maintainers"));
82+
assert.ok(markdown.includes("Repository hosts"));
83+
assert.ok(markdown.includes("Config sources"));
84+
assert.ok(markdown.endsWith("full issue breakdown.\n"));
85+
});

0 commit comments

Comments
 (0)