Skip to content

Commit 53ea17e

Browse files
Merge pull request #234 from refactorfirst/feature-parity-features-added
#233 Bring the HTML Report to parity with https://refactorfirst.github.io/ reports
2 parents 9a4fe3a + 625eae9 commit 53ea17e

125 files changed

Lines changed: 56051 additions & 9880 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.coderabbit.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
language: en-US
2+
3+
reviews:
4+
profile: chill
5+
path_filters:
6+
- "!junit4-report.html"
7+
- "!fxgl-report.html"

‎.gitattributes‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
# Windows-style line endings: every text file uses CRLF in the working tree.
2+
# Git normalizes to LF inside the repository; `eol=crlf` re-applys CRLF on checkout.
3+
# The shell scripts below are the only LF exceptions (Unix exec requires LF).
4+
* text=auto eol=crlf
5+
16
# From https://github.com/gitattributes/gitattributes/blob/master/Java.gitattributes
27
# Java sources
38
*.java text diff=java

‎.github/workflows/e2e.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Report E2E
2+
3+
permissions:
4+
contents: read
5+
6+
on:
7+
push:
8+
branches: [ main ]
9+
pull_request:
10+
branches: [ main ]
11+
12+
jobs:
13+
e2e:
14+
runs-on: ubuntu-latest
15+
16+
steps:
17+
- name: Check out Git repository
18+
uses: actions/checkout@v4
19+
20+
- name: Set up JDK 25
21+
uses: actions/setup-java@v4
22+
with:
23+
java-version: '25'
24+
distribution: 'temurin'
25+
cache: maven
26+
27+
- name: Set up Node.js
28+
uses: actions/setup-node@v4
29+
with:
30+
node-version: 22
31+
32+
- name: Generate Fixture Reports
33+
run: mvn -B -pl report -am install -Dtest=SampleReportGenerationTest -DfailIfNoTests=false
34+
35+
- name: Install Playwright Browsers
36+
run: |
37+
cd report/e2e
38+
npm install
39+
npx playwright install --with-deps chromium
40+
41+
- name: Run E2E Tests
42+
run: |
43+
cd report/e2e
44+
npx playwright test

‎.github/workflows/js-tests.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Report JS Tests
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
js-tests:
14+
runs-on: ubuntu-latest
15+
16+
steps:
17+
- name: Check out Git repository
18+
uses: actions/checkout@v4
19+
20+
- name: Set up Node.js
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: 22
24+
25+
- name: Build With Maven
26+
run: mvn -B -pl report -am install -DskipTests
27+
28+
- name: Run Report JavaScript Tests
29+
run: mvn -B -pl report -P js-tests verify

‎.github/workflows/maven-pr.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,18 @@ jobs:
2525
java-version: ${{ matrix.java-version }}
2626
distribution: 'zulu'
2727

28+
- name: Set up Node.js
29+
uses: actions/setup-node@v4
30+
with:
31+
node-version: 22
32+
2833
- name: Build With Maven
2934
run: mvn -B verify
3035

36+
- name: Run Report JavaScript Tests
37+
38+
run: mvn -B -pl report -am -P js-tests verify
39+
3140

3241
# Comment "Build With Maven" and uncomment the below when you want a snapshot build to be deployed
3342
# *********Don't forget to switch to Java 1.8 as well********

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -215,3 +215,4 @@ buildNumber.properties
215215
# End of https://www.toptal.com/developers/gitignore/api/java,maven,intellij,eclipse
216216

217217
/jreleaser-cli.jar
218+
report/e2e/node_modules/

‎.refactorfirst/refactor-first.json‎

Lines changed: 2181 additions & 2052 deletions
Large diffs are not rendered by default.

‎AGENTS.md‎

Lines changed: 74 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -93,14 +93,14 @@ package/class hierarchy. The pipeline is single-sourced:
9393
render) and flagged packages survive pruning and single-child collapse. The
9494
Cycle Map stays cycle-scoped: it flags only the break-up packages inside the
9595
displayed cycle.
96-
- **Three synthesis implementations must stay byte-identical** (their goldens
97-
mirror each other): Java `NestedDotBuilder` (`NestedDotBuilderTest`), the
98-
inline copy in `report/src/main/resources/viewer/index.html` (self-contained
99-
standalone viewer; pinned by `ViewerScriptTest`), and the report page's
100-
`lib/hierarchy-dot.js` (refactorfirst-page repo, pinned by
101-
`tests/unit/hierarchy-dot.test.js`) — each in both the class/cycle mode
96+
- **Two synthesis implementations must stay byte-identical**: Java
97+
`NestedDotBuilder` (`NestedDotBuilderTest`) and `rf-hierarchy-dot.js`
98+
(cross-pinned by `hierarchy-dot.test.cjs` against the
99+
`golden/hierarchy-dot/*.dot` goldens) — each in both the class/cycle mode
102100
(`buildNestedDot`/`hierarchyToDot`) and the package mode
103-
(`buildPackageDot`/`packageHierarchyToDot`). The page copies add an
101+
(`buildPackageDot`/`packageHierarchyToDot`). The standalone viewer
102+
(`viewer/index.html`, `ViewerScriptTest`) migrates to `rf-hierarchy-dot.js`
103+
post-release. The page copies add an
104104
`edgeFontColor` option: vizdom bakes label `fontcolor` into fill-only
105105
glyph paths at parse time, so the dark palette re-synthesizes with
106106
`fontcolor = "#9fb0c0"` on edges. Node and cluster labels sit on vizdom's
@@ -210,6 +210,73 @@ back to returning the Java-only DTO with a `log.warn`
210210
(`"Kotlin analysis failed; falling back to Java-only graph"`). This fallback
211211
is for build failures, not for "Kotlin is absent".
212212

213+
## Report architecture (templates + assets pipeline)
214+
215+
Both HTML reports render from Mustache templates through a shared pipeline:
216+
`ReportModelBuilder` → `RefactorFirstReportDTO` → `ViewModelFactory` → `TemplateEngine`
217+
(`com.github.mustachejava`, 0.9.14) → `MinifyHtml` (optional) → `ReportWriter`.
218+
219+
- **`templates/refactor-first-report.mustache`** (interactive) and
220+
**`templates/refactor-first-simple-report.mustache`** (strictly HTML, no scripts —
221+
for `$GITHUB_STEP_SUMMARY`) live in `report/src/main/resources/templates/`. The allowed
222+
Mustache subset (no lambdas, no client-side partials) and engine-parity rules are
223+
documented in `templates/README.md`; `DualEngineGoldenTest` +
224+
`mustache.dual-engine.test.cjs` pin Java mustache.java and vendored mustache.js to the
225+
same bytes for the fixture view model (golden:
226+
`src/test/resources/golden/mustache/`).
227+
- **`assets/`** carries the classpath JS/CSS the interactive report embeds:
228+
`AssetInliner` injects them at the `<!-- rf:inlined-css -->` / `<!-- rf:inlined-js -->`
229+
template markers in a deterministic order (CSS: palette → tables → graphs → report;
230+
JS: core → theme → hierarchy-dot → tables → csv → copy → charts → graphs → main), each
231+
block marked with an `rf:asset:<name>` id comment. Nothing is ever loaded via a local
232+
`src=`/`href=` — the report is a single self-contained file that opens via `file://`.
233+
- **`rf-data` payload**: `RfDataBlock` embeds the serialized DTO as
234+
`<script type="application/json" id="rf-data">` (escaped by `DataEmbedder`: `</` →
235+
`<\/`, U+2028/U+2029 escaped). Every widget reads this payload through
236+
`window.RF` (`rf-core.js`); no data is baked into JS template literals.
237+
- **Theming**: `rf-palette.css` is the palette source of truth — `PaletteParityTest` +
238+
`palette-parity.test.cjs` pin every token to `palette.json` and the two duplicated dark
239+
blocks byte-identical. Theme switching is pure CSS (`:has(#rf-theme-…:checked)` +
240+
`prefers-color-scheme`); `rf-theme.js` only persists `localStorage['rf-theme']` and
241+
republishes changes (never touches styles). Canvas-drawn colors re-resolve via the
242+
`RF.theme` pub-sub (`redrawCharts`/`redrawGraphs`).
243+
- **WCAG 2.2 AA is continuously tested**: `WcagStructureTest` (structure/landmarks/
244+
focus contract), `TableControlsWcagTest` (table control names/live regions/target
245+
sizes), `ThemeWcagTest` (radio pills), `SimpleReportWcagTest`,
246+
`StrictHtmlComplianceTest` (no scripts/handlers/iframes/javascript: URIs on the simple
247+
report — permanent gate), `contrast.test.cjs` (contrast math from the palette),
248+
`keyboard-parity.test.cjs`, and the `wcag-axe.spec.js` E2E (zero violations, both
249+
reports, light + dark, before/after interaction).
250+
- **E2E** (`report/e2e/`, Playwright chromium): fixture reports are generated into
251+
`report/target/e2e/` by `SampleReportGenerationTest` (interactive unminified/minified,
252+
Kotlin-disharmony legs, junit4-fixture leg, simple leg) and opened via `file://`.
253+
254+
## Graphs: client-side synthesis + hover model (two implementations)
255+
256+
The interactive report's Class/Package/Cycle maps and popups render from the rf-data
257+
payload's inline **hierarchy** trees. DOT synthesis has exactly two implementations that
258+
must stay byte-identical (cross-pinned):
259+
260+
- Java **`NestedDotBuilder`** (the golden; pinned by `NestedDotBuilderTest`), and
261+
- JS **`rf-hierarchy-dot.js`** (pinned by `hierarchy-dot.test.cjs` against
262+
`src/test/resources/golden/hierarchy-dot/*.dot` generated from the parity fixture).
263+
264+
The standalone viewer (`viewer/index.html`) still carries its own inline copy, pinned by
265+
`ViewerScriptTest`; it migrates to `rf-hierarchy-dot.js` post-release (§12.3 follow-up).
266+
Both palettes synthesize from the same bytes — dark mode adds only
267+
`fontcolor = "#9fb0c0"` edge labels (vizdom bakes label color into fill-only glyph
268+
paths); break-up cluster colors are re-driven by CSS (`rf-graphs.css`), never baked.
269+
270+
Hover highlights: `rf-graphs-vizdom.js` derives the neighborhood from the vizdom
271+
`<title>` texts and toggles `rf-hover-*` classes (amber edge/focus, green in, blue out,
272+
mutual partners amber; `focusin`/`focusout` keyboard parity), styled by `rf-graphs.css`
273+
from the palette; Sigma 2D mirrors the model via node/edge reducers
274+
(`rf-graphs-sigma.js`, dark hover renderer `#1a2330` label box); the 3D popup
275+
(`rf-graphs-3d.js`) always uses the dark accent set (its WebGL canvas paints its own
276+
background) with O(changed) sprite recolors and the `<4000` threshold guard. Failed CDN
277+
widgets surface a visible aria-live notice (`announceWidgetFailure`) instead of silent
278+
breakage.
279+
213280
## Testing Notes
214281
- **TDD is required when implementing code.** Write tests before production code using the red-green-refactor cycle. Use the Given-When-Then format for test structure.
215282
- JUnit 5 with parameterized tests

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ coverage (JaCoCo aggregation)
6262

6363
**cost-benefit-calculator** — Orchestrates the full pipeline: runs effort-ranker and change-proneness-ranker, combines scores into `RankedDisharmony` objects. Main orchestration class: `CostBenefitCalculator`.
6464

65-
**report** — Generates HTML (with embedded bubble charts), CSV, and JSON output. Reports with >4000 classes switch to a simplified 3D viewer.
65+
**report** — Generates the interactive HTML report, the strictly-HTML simple report, CSV, and JSON output. Both HTML reports render from Mustache templates (`templates/`) with all assets inlined from classpath files (`assets/`) by `AssetInliner`; the interactive report embeds the report DTO as the `rf-data` JSON payload and synthesizes its graphs client-side (Chart.js bubble charts, vizdom class/package/cycle maps, Sigma 2D and 3D force-graph popups with a colored hover model, light/dark/system theming, table filtering/sorting/pagination/CSV/copy). Reports with >4000 classes switch to a simplified 3D viewer. See AGENTS.md for the template/asset architecture and test map.
6666

6767
**cli** — PicoCLI-based executable. Entry: `org.hjug.refactorfirst.Main` → `ReportCommand`.
6868

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,16 @@ It scans your Git repository and generates a single page application by running:
1111
Code map viewers are powered by [3D Force Graph](https://vasturiano.github.io/3d-force-graph), [sigma.js](https://www.sigmajs.org/), and [GraphViz DOT](https://graphviz.org/docs/layouts/dot/) using [Vizdom](https://github.com/vizdom-dev/vizdom) to render the DOT graph.
1212
<br>If there are more than 4000 classes + relationships, a simplified 3D viewer will be available to avoid page load slowdowns. Features will be toggleable in the 3D UI in a future release.
1313

14+
### Report features
15+
The generated `refactor-first-report.html` is a **single self-contained file** — open it directly from disk (`file://`), no server needed. It includes:
16+
- **Light / dark / system theme** (system is the default) with pure-CSS switching and persistence
17+
- **Chart.js bubble charts** (priority vs. effort per disharmony; click a bubble to open the source file)
18+
- **Table toolkit**: sticky headers, filtering with a live match count, three-state column sorting, pagination for long tables, CSV export (RFC 4180 + formula-injection neutralization), and click-to-copy cells with keyboard support
19+
- **Colored graph hover model**: hovering an edge/node highlights its neighborhood (amber/green/blue by direction) in the SVG maps, the Sigma 2D popup and the 3D popup; keyboard focus reproduces the pointer hover
20+
- **WCAG 2.2 AA conformance** — see the accessibility statement below
21+
22+
**Accessibility statement (WCAG 2.2 AA):** the generated reports target WCAG 2.2 Level AA and are continuously tested for it (structure, contrast, keyboard operation, and axe-core scans on every fixture — see `report/e2e/specs/wcag-axe.spec.js`). Known limitations: the 3D graph canvas has a text alternative via the tables and the 2D map rather than within the canvas, and third-party CDN widgets (Chart.js, sigma.js, 3d-force-graph, vizdom) are outside this report's control; the report degrades gracefully to readable tables when they are unavailable.
23+
1424
## How to Use RefactorFirst Quickly
1525
Run the command below in your Java project's top-level directory. You'll need Git, Java 17 (or newer) and Maven 3 installed. This command will analyze Maven and non-Maven projects:
1626
```bash
@@ -112,7 +122,7 @@ Specify with -D if running on the command line. e.g. ```-DbackEdgeAnalysisCount
112122
|showDetails|Shows God Class metrics| false |
113123
|backEdgeAnalysisCount|Number of back edges in a cycle to analyze. <br>If total number of back edges is greater than the value specified, it analyzes the number of minimum weight edges specified.<br>**If 0 is specified, all back edges will be analyzed**| 50 |
114124
|analyzeCycles|Analyzes the 10 largest cycles (will be configurable in the future)| true |
115-
|minifyHtml|Minifies the generated HTML report. Only available on ```htmlReport``` and ```simpleHtmlReport``` goals. May cause issues with large reports.| false |
125+
|minifyHtml|Minifies the generated HTML report with [minify-html](https://github.com/wilsonzlin/minify-html). Only available on ```htmlReport``` and ```simpleHtmlReport``` goals. Both reports are verified to stay fully functional after minification (round-trip tested in CI and E2E). May cause issues with very large reports.| false |
116126
|excludeTests|Exclude test classes from analysis| true |
117127
|testSrcDirectory|Excludes classes containing this pattern from analysis| ```src/test``` |
118128
|projectName|The name of your project to be displayed on the report| Your Maven project name |

0 commit comments

Comments
 (0)