Review application A.4.3

Code quality

This page explains the code quality dashboard: the map of both repositories' code, the places it suggests to clean up, and the test and coverage results of the commit the site runs. It also defines the criticality of a module and the statuses of the results. To run the checks yourself or maintain the module catalog, see A4.4 Running the quality checks.

The module catalog (quality/modules.yml in each repository) divides the code into modules. A module is a group of files with one responsibility, such as snapshot publication or the query API. The catalog assigns every source file to exactly one module and records the module's criticality, owner, invariants, entry points, dependencies, documentation and tests. The result bundle connects engine and application modules through a declared contract instead of shared code.

The CI run of each commit measures every module and builds the code map. The dashboard shows what CI measured on the commit the site runs: it downloads that commit's file from GitHub, so nothing is committed and no command runs before a deployment. How the evidence reaches the site explains this and what the server needs.

Criticality

Criticality is a maintained judgment, not a measurement. It answers one question: what would the worst plausible defect in this module do? It never depends on how well the module is tested; do not lower it to accommodate weak tests.

Criticality The worst defect in the module Modules
critical Publishes wrong, incomplete or lost data, or blocks recovery or deployment Snapshot publication, schema and deployment, matching core, result production
high Shows wrong results or stops data from refreshing, while the published data stays recoverable Query API, review UI, pipeline orchestration, engine input integrations
medium Degrades presentation, documentation or tooling; data and results stay correct Documentation delivery, styles and assets
low Is cosmetic or only affects developer convenience None

Criticality raises the documentation a module must have. critical and high modules must record invariants and an explanation page, and critical modules also a reference page; the catalog check fails without them. The report's Docs column also expects a decision record for critical modules.

Read the dashboard

The dashboard at /quality combines the static code map of both repositories with the test, coverage, clone and architecture results for the running commit. When GitHub has no results for the running commit, the page says so and names the commit; missing results are never shown as a pass. A local run (quality/evidence.json) overrides the CI results and is marked Local run; a local map built alone (python scripts/quality.py map) has no test results and is marked Map only.

The code map

scripts/quality.py builds the code map statically across three levels (Modules, Files and Functions):

  • Modules. An arc from module A to module B counts the static code references from A into B: Python imports and calls, shared browser-script globals, template script loads, HTTP requests from scripts and templates to Flask routes, and templates rendered, extended or included. A plain navigation link (such as a navbar entry or redirect(url_for(...))) is not counted as a code dependency. Solid grey arcs are declared in quality/modules.yml; orange dashed arcs are undeclared code dependencies; dotted grey arcs are declared dependencies with no static reference; dotted purple links connect a module to a cross-repository contract such as the result bundle.
  • Files. Edges connect files that reference each other, coloured by whether the dependency is within one module (grey), across a declared module dependency (navy) or across an undeclared one (orange dashed). Dashed black edges connect files that share a duplicated code block. Files over 1,000 lines are ringed.
  • Functions. Edges connect functions and classes to the functions they call or reference in Python and in browser scripts. Hollow dots mark functions and classes with no static references in production code.

The colour encodings and module palette are defined in the shared token file and mirrored in static/js/quality/rendering.js for canvas rendering.

Cleanup candidates

These are places to inspect, not gate failures:

List What it holds How it is found
Functions nothing mentions Functions and classes with no static reference in production code The identifier appears nowhere else in the production code, templates or inline HTML strings of either repository. Functions referenced only by tests are still flagged. Only functions and classes are listed: a variable, or the object a script publishes on window, is not. Flask routes, catalog entry points, decorated Python functions, dunder methods, migration steps and constructors are excluded because a framework calls them.
Copied code Identical or near-identical blocks of at least 10 lines and 70 tokens jscpd, the same detector behind the Duplicated blocks column
Files over 1,000 lines Long source files Line counts of Python, JavaScript, CSS and template files

Because unused-function detection matches by identifier name across production files, an unused function that shares its name with a used one is not flagged, and a function called only via a dynamically constructed name is flagged; verify dynamic callers before deleting.

Module boundaries

Lists disagreements between quality/modules.yml and the static graph: undeclared dependencies, circular module dependencies, private Python names (prefixed with _) imported or called across modules, and declared dependencies without static code references.

What the map cannot see

Lists references where static analysis is incomplete and records the limits of the parser:

  • Python calls resolve only through local definitions and imports; method calls on objects (self.save()) and dynamic dispatch are not resolved.
  • Browser scripts are parsed with espree. A script's top-level declarations, window properties and members of shared namespaces (MapComponents.MapCore, etc.) are treated as exports. A global read by another script links to its unique exporter; globals exported by multiple scripts are flagged as ambiguous, and the analyser does not verify whether both scripts load on the same page.
  • Flask routes are extracted from @route decorators (and verified against the registered Flask URL map in tests). Literal URL strings and url_for endpoints link to matching routes, with runtime path expressions matching single path segments. Requests whose URL or template name is a runtime variable (for example read from a data- attribute or passed into a helper wrapper) are listed under URLs and templates chosen at runtime, which can leave a reachable route listed under Routes nothing in the code reaches.
  • Database tables, external services and template context variables are not traced, so a dotted declared dependency can reflect a real data dependency rather than a stale catalog entry.

Read the results

CI results by module has one row for each module:

Column Meaning
Criticality Declared in the catalog, as described in Criticality
Tests Result of the tests associated with the module. Skipped tests or declared test files without results need attention.
Branch coverage Share of the module's runtime code branches the tests executed, also drawn as a bar. Not applicable to modules without runtime code, such as styles.
Duplicated blocks Code clones of at least 10 lines and 70 tokens that touch the module, found by jscpd. The status says whether any is new since the reviewed baseline.
Docs Required catalog slots filled: owner, review date, invariants and the documentation the module's criticality requires
Architecture Whether the module's imports respect the enforced boundaries, such as the application never importing the engine

There is no combined quality score. Each column stands on its own, and a high percentage does not replace the publication, rollback and contract tests that the invariants call for.

Statuses

Status Meaning
pass The recorded check or comparison passed
fail Executed tests or an enforced rule failed
measured A valid measurement is available; the percentage is not itself a pass or fail
attention Needs review: skipped or missing declared tests, or a new duplicated block
not measured The input for this measurement was not collected
not applicable There is nothing to measure, for example no runtime code in a styles module
invalid The evidence cannot be trusted, such as incomplete coverage

The pill beside the results says Checks failed when a required check failed. Otherwise it says Complete when every module has its test and coverage results, and Partial when some are absent. It describes the measurements, not the quality of the code.

Code

File Role
quality/modules.yml The module catalog
scripts/quality.py Catalog check, measurements and code map; writes quality/evidence.json
.github/workflows/tests.yml Runs the checks and publishes each commit's evidence
backend/services/quality_report.py Loads the evidence of the running commit
backend/blueprints/quality.py The dashboard page and its /api/quality data
static/js/quality/code-map.js Reads the code map: dependencies, findings, graphs and the layout of each level
static/js/quality/rendering.js Colours, the map's elements and styles, the legend, panels and tables
static/js/quality/dashboard.js The page: loads the evidence, keeps the level and the modules in focus, answers clicks and search