werkcrappit/docs/adr/0007-codecharta-export.md

# ADR 0007: CodeCharta Export From the Finished Report

- Status: accepted
- Date: 2026-10-02
- PR: #13

## Context

RFC 0001 asks for a CodeCharta `cc.json` 2.x file: packages as districts, classes as buildings, with LOC, complexity and Mutation-CRAP per class.
`mutation-crap.json` holds complexity and Mutation-CRAP per method, but no line numbers per method and no dependencies.
The RFC wants the export to be a step after the analysis, without a dependency on PIT's listener lifecycle, and `mutation-crap.json` to stay unchanged.

Two sources for the missing class data were possible:

1. The PIT plugin writes the class data it already reads into the report or a second file.
2. The export reads the original class files again.

## Decision

The export is a Gradle task after `pitest`, `mutationCrapCodeCharta`, not part of `check`.
It reads `mutation-crap.json` and, for the line numbers, the original class files named in `provenance.classFiles`.

- Complexity and Mutation-CRAP come only from the report; the task computes neither again.
- Before it uses a class file, the task compares its SHA-256 with the one in the report.
  A different or missing file stops the task with a message to run `pitest` again, so the LOC always belongs to the bytes PIT analysed (`@MC-CC-016`).
- The line numbers come from JaCoCo Core over those bytes, the same version and the same static analysis as the complexity.
- The logic lives in `de.javagil.werkcrappit.pit.codecharta`; the Gradle task only reads and writes files.

Why not option 1: it changes the report contract for a visualization, and it puts work into every PIT run that only the export needs.
Reading the class files again costs milliseconds per class, and RFC step 2 needs the bytecode anyway for the dependencies.

## Class Metrics

A building is a top-level class: its nested, inner, local and anonymous classes (`Outer$Inner`, `Outer$1`) belong to it.
One building is one source file, as a reader of the code sees it.
Since PR#17 every top-level class in the report's code roots is a building, unless `werkcrappit.excludeClasses` or `codeCharta.excludeClasses` excludes it (`@MC-CC-024`).
The counted methods of a building are its methods that are not `EXCLUDED`.
A class outside the PIT run, for example one PIT's `excludedClasses` leaves out, gets its complexity and lines from the same static JaCoCo analysis the PIT plugin uses, and no `mutation_crap` (`@MC-CC-022`).
CodeCharta `vis-2.7.0` reads a missing metric as 0 when it loads a file, so such a building shows green, as if well tested; PR#17 wrongly expected grey.
Every real Mutation-CRAP is at least 1, as it is at least C, so the viewer rule "flatten where `mutation_crap` < 1" matches exactly the unscored buildings and draws them flat and grey; the report page and the metric's description say so (PR#19).
A file cannot carry that rule, and the viewer takes no rule from its URL.

Since PR#20 the report page links, by default, a CodeCharta built from a fork with a fix: it records the metrics a file has no value for and shows such a file grey, keeping area and height (`@MC-CC-026`).
The fork is `git.javagil.de/mi/codecharta`, branch `mihoe/missing-metrics-stay-missing`, served statically at `https://javagil.de/codecharta/`; the fix is offered to MaibornWolff upstream, and the default goes back to the original once it is released there.
Since PR#23 the link also sets the colour range, `colorFrom` and `colorTo`, and `colorMode=absolute`, URL parameters of the fork (`mihoe/color-range-url-params`, offered upstream as well): red from the gate's `maxMutationCrap` on, green below its half, without a limit 5 and 10 (`@MC-CC-029`).
Since PR#29 red starts at 90 % of the limit, 9 for 10, so that the city warns before the build fails; `codeCharta.colorRedFrom` sets another start (`@MC-CC-029`, `@MC-CC-030`).
Since PR#35 yellow starts at half of `colorRedFrom` when that is set, not at half of the limit (`@MC-CC-030`).
A limit used as a ratchet, such as 650 on the way to 15, had swallowed yellow: half of it lay above red, and yellow was capped at red.
`codeCharta.colorYellowFrom` sets the start of yellow itself, at most where red starts (`@MC-CC-031`).
CodeCharta's default colour mode, a weighted gradient, already turns a value from three quarters of the range towards red, so hsadmin-ng's 9.3 looked red under a limit of 10; the absolute mode has hard steps.
It shows a value of exactly the limit red, although the gate lets it pass.
CodeCharta otherwise starts with thirds of the range of values, and one outlier, such as 182 in Halo, turns every other building green.
The range cannot go into the file: `cc.json` 2.0 carries no view settings, and its schema refuses unknown fields.
`werkcrappit { codeCharta { viewerUrl } }` chooses another viewer, for example the original at `https://codecharta.com/visualization/app/index.html`.
Why a fork: the original viewer cannot show "no score" apart from "good" without taking the building's height away.
CodeCharta is under the BSD-3-Clause license, so the fork keeps its copyright notice and license text, and the served viewer must carry them beside it, together with the notice that it is modified.
Its class file is not in the report, so its SHA-256 cannot be checked; it is read as it lies in the code root.
A class without code, such as a Spring Data repository interface, is a building of its `rloc` only (`@MC-CC-023`).
Until PR#17 a building needed a counted method; that left out interfaces, repositories and classes of Lombok code only, and the area understated a package such as `hs.office` of hsadmin-ng.

- `complexity`: the sum of the JaCoCo complexities of the counted methods; omitted when none has a complexity.
  When only some have one, the partial sum is exported and the task names the buildings concerned in a warning.
- `rloc` (since PR#16, the area): the lines of the building's source file that are neither blank nor comment only, as `ccsh` counts them.
  `package`, `import` and annotation lines count: they are written and read like any other line, and every reference to elsewhere adds to what a reader must keep in mind.
  Code a processor such as Lombok generates is not in the file and never counts.
  The export finds the file through the bytecode's source file name in the source roots of the `main` source set; without it there is no `rloc` and a warning names the class.
  Another top-level class in the same file gets no `rloc`, so no line counts twice.
  This takes back the decision below that `rloc` is not needed: it was taken on the misunderstanding that only blank lines and comments differ.
- `executable_lines` (eLOC; called `loc` until PR#16): the number of distinct source lines on which JaCoCo finds instructions of the counted methods; omitted without line information.
  This is executable LOC from the bytecode, not a count of the lines in the source file.
  Blank lines and comments never count, as no instruction lies on them; neither do imports, annotations and declarations without code.
  So it is at most `rloc`; in CodeCharta's own vocabulary `loc` means all lines, blank and comment included, which is why the name `loc` was given up.
  Area and height so describe the same code.
  Without line information the task warns once with the number of buildings concerned; CodeCharta draws them without area.
- `mutation_crap`: the highest Mutation-CRAP of the counted methods in state `SCORED`, rounded to 4 decimals as in the report; omitted when no method is scored.
  The maximum is compared exactly; it is a visualization aggregate, not a class metric, and the gate never uses it.
  When other counted methods are `INCONCLUSIVE`, the maximum of the scored ones is still exported, and the task names the buildings concerned in a warning (`@MC-CC-014`).

- `max_method_complexity`: the highest complexity among the counted methods.
- `method_count`: the number of counted methods; `scored_method_count`: those in state `SCORED`.
- `mutant_count`: all mutants of the counted methods, every status included.

Which method sets the color stays in `mutation-crap.md`; a CodeCharta metric is a number only.
When `maxMutationCrap` is set, the description of `mutation_crap` names it; the color scale is set in the viewer.

A missing value is omitted, never written as 0.

A nested class whose top-level class has no counted method still makes the building of that top-level class (`@MC-CC-015`).
Methods that JaCoCo filters, for example many generated by the Kotlin compiler, are `EXCLUDED` in the report and so count for neither LOC nor complexity.

Packages are nested folders; since PR#15 a chain of folders with one sub-folder each and no class becomes one folder named by the dotted packages, `net.hostsharing.hsadminng`, as an IDE compacts middle packages (`@MC-CC-017`).
Such a chain adds levels without showing anything.

CodeCharta computes a folder's value itself: the sum of its children for an `absolute` metric, their median for a `relative` one; it knows no maximum.
Since PR#15 `mutation_crap` and `max_method_complexity` are `relative`, all other metrics `absolute` (`@MC-CC-018`).
Summed, the maxima of a large package lay far above any color threshold, so the package was red although every package below it was green.
The median shows the typical class; an outlier stays visible as its red building.

The root folder is named `root`, as `ccsh` names it; `meta.projectName` is the `analysisContext` of the report, for example `:app:pitest`.

## Format

- Target: CodeCharta visualization `vis-2.7.0` (2026-09-28), `apiVersion` `2.0`.
  Its schema (`visualization/app/codeCharta/util/ccJson2Schema.json` at commit `2af9db04`) is pinned as a test resource; tests validate against it without network access, together with the viewer's own checks for unique IDs and unique siblings.
  The rendering in the viewer is a manual probe, recorded in `docs/compatibility.md`.
- Node ID: the first 16 hex characters of SHA-256 over the type name and the canonical path, as CodeCharta's `NodeId` computes it (`"File" + "/shop/domain/Order"`).
- `meta.checksum`: MD5 over the compact `{"files":…,"lenses":…}`, as `ccsh` computes it.
  The viewer takes the checksum as an opaque identity and does not compute it again.
- The file name is `mutation-crap.cc.json`, indented like the report, so it can be read and diffed.
  Since PR#14 it lies in a report directory of its own, `build/reports/codecharta`, with an `index.html` that links it and the viewer.
  A CI server lists a report directory by its index page; so Werkator shows the code city without a change of its own, where a file beside PIT's report stayed unlisted.
  The page is self-contained, without external resources, as a sandboxed artifact view requires.
  Since PR#18 an inline script links "Open in CodeCharta" with the file's absolute URL as the viewer's parameter `file` (`@MC-CC-025`): the page does not know its own address, and only a script can turn the relative name into one.
  The viewer fetches the file in the reader's browser, so the server must allow `https://codecharta.com` by CORS and serve the file without a login; Werkator, whose private repositories need a cookie the browser does not send there, is not changed for it.
- Children, metrics and descriptors are written in a fixed order, so the same inputs give the same bytes.

## Consequences

- The export needs the class files of the PIT run; after a new compile without a new PIT run it stops instead of mixing two builds.
- A report of an unfinished run is refused; a report with an incomplete scope is exported with a warning, without the unreadable classes' LOC.
- A newer CodeCharta version with a changed schema needs a new pinned schema and a new entry in `docs/compatibility.md`.

## Dependency Edges (RFC Step 2, PR#22)

- A references B when B appears anywhere in A's class file, as `jdeps` sees it: super types, field and method descriptors, generic signatures, annotations, and in the code calls, field accesses, `new`, casts, `instanceof`, `catch`, class literals and method handles.
  The `InnerClasses` and nest attributes are left out: they list classes, they do not use them.
- A reference of a nested class counts for its top-level class; references within one building are dropped.
- One edge per ordered pair of buildings; its `dependencies` counts the distinct things of B that A uses: B as a type counts 1, every method and every field of B used counts 1 each.
  This is stable against code the compiler duplicates, such as `finally` blocks and bridge methods.
- A reference to a class without a building is dropped silently, whether it is a library, the JDK, or an own class outside the city.
- By default (`codeCharta.levelization`) the edges carry `isCyclic` and `isPointingUpwards`, and the dependency lens the `level` of every node, computed as `ccsh dependencyparser` does:
  an edge is cyclic when its buildings reach each other; levels are local to a folder, its edges lifted to its direct children, cycles broken by dropping the edge into the child with the least incoming weight;
  an edge points upwards when, under the lowest folder holding both ends, its target's child has a level as high as or higher than its source's.
  The released viewer `vis-2.7.0` refuses these fields; `levelization = false` leaves them out, and the file stays valid for it.
- The edges are checked against both pinned schemas: with levelization against CodeCharta `main` at 364a7449a, which the default viewer is built from; without against `vis-2.7.0`.

## Commit and Source Links (RFC Step 3, PR#24)

- `meta.commitHash` is the full SHA of `git rev-parse HEAD` in the project directory; a configured value overrides it, for example from a CI variable.
  Without git and without a configured value there is no `commitHash`.
- With uncommitted changes the HEAD commit is still exported, and the task warns that the analysed code may differ from it.
- A source link exists only with a configured template; there is no default and no rule for a particular Git host.
  Its placeholders are `{commit}`, `{path}` (the source file relative to the Git root, found in the `main` source set) and `{line}`.
- `{line}` is the first line of the method with the highest Mutation-CRAP, else the smallest first line of the counted methods: a click leads to the hotspot.
  A class without any method with code, an interface say, is linked at line 1 (PR#25); before, it got no link, 43 of hsadmin-ng's 267 buildings.
- A template without a commit to fill in stops the task; a building whose source file is not found gets no link, and the task counts these in one warning.

Since PR#37 the city carries cohesion and coupling (RFC 0002): `lcom4` relative, `efferent_coupling` and `afferent_coupling` absolute, from the report's section `classes`; the report page links the city coloured by each of the three dimensions (`@MC-CK-008`, `@MC-CK-009`).

Since PR#50 the export also writes `structure.html`, the level diagrams of RFC 0003,
from the same tree, dependencies and `Levelization`;
`codeCharta.levelization = false` leaves the flags and levels out of the city only, the page always has them.
Since PR#51 it also writes `matrix.html`, the expandable dependency matrix of the same data.

Since PR#40 the export also writes one CodeCharta scenario per view, Mutation-CRAP, cohesion and coupling, each with its colour band; the Mutation-CRAP link passes them with the parameter `scenario`, which the fork reads (`mihoe/scenario-url-param`), and the page offers them for import by hand (`@MC-CC-032` to `@MC-CC-034`).