The web interface

The web interface is the interactive way to explore an analysis: an overview, an architecture map, history charts, the Time Machine, file and symbol browsers, hotspots, quality and security signals, findings with their evidence, reports, and comparisons. The same interface runs in three places:

Start it#

repodna serve

RepoDNA is listening on http://127.0.0.1:7878 (this machine only).

Open this link to sign in. It contains your session token, so do not share it:
  http://127.0.0.1:7878/?token=...

Press Ctrl+C to stop.

Open the printed link. The start page lets you:

• Analyze a repository: a local directory, a .zip or .tar.gz archive, or a Git URL, with a profile. Progress is shown while it runs, and the result is stored.
• Open a stored analysis from this machine. With more than eight, the newest are listed first, and a filter finds the others by name or location.
• Open an analysis file (repodna.json or .repodna), by choosing it or dropping it anywhere on the page, also while another analysis is open. The file is read locally and never uploaded.
• Open a recent analysis: the last five files you opened, kept in this browser so that they open again in one click. Remove them one by one, or forget them all or turn this off in Settings.
• Try the demo: RepoDNA's analysis of its own repository, bundled with the interface.

In the web version, Analyze a repository in this browser takes the place of the first item: see the web version.

Reloading the page keeps the analysis and the view you had open, in the web version too. A new tab starts on the start page.

repodna serve --no-scan disables starting analyses from the browser, and repodna serve --port 0 picks a free port.

Views#

Every chart has a table view, and severity is always written out, never shown by color alone. Download CSV under a table saves all of its rows, in the order shown, for a spreadsheet: numbers stay numbers, and text that a spreadsheet would run as a formula is written so that it does not run.

To print a view, or save it as PDF, use the browser's Print command, or Print this view in the command palette (Ctrl/Cmd + K), which the desktop app needs, having no print menu. The printout leaves out the buttons and links made for the screen, shows every column of wide tables, and is in the light theme whatever the theme on screen.

Finding your way#

• The numbers at the top of the overview open the view about them: files, code lines, commits, the architecture style, and findings.
• A view with four panels or more lists them under its title; choose one to go to it.
• Under each view, links lead to the previous and the next view, so an analysis can be read from the overview to the comparison. The [ and ] keys do the same.
• On a long page, Back to top appears at the bottom right once you have scrolled down.
• The sidebar shows how many findings the analysis has. Findings can also be opened filtered, for example #/findings?severity=warning or #/findings?category=security.

Search and keyboard shortcuts#

The theme follows your system setting unless you choose light or dark in the header.

Security#

The server is meant for one person on one machine:

• It listens on 127.0.0.1 only.
• Every API request needs the session token, either in the X-RepoDNA-Token header or in the SameSite=Strict, HttpOnly cookie set when you open the printed link. A new token is generated each time the server starts.
• Requests with a Host header other than the server's own address are refused, which defeats DNS rebinding.
• Requests that change something (starting or cancelling an analysis) are refused when their Origin is another site.
• Responses carry a restrictive Content Security Policy, and the interface loads nothing from other sites.

The interface's own files contain no data and are served without the token; everything about your repositories comes from the API.

The local API#

Everything the interface shows comes from a JSON API, which you can also use from scripts. Pass the token printed by repodna serve:

TOKEN=...   # from the printed link
curl -s -H "X-RepoDNA-Token: $TOKEN" http://127.0.0.1:7878/api/repositories

{id} is a repository identifier, name, or path, as for repodna targets. The artifact format is described by schemas/repodna-artifact.schema.json.

The web version#

https://sanskarin.github.io/RepoDNA/ is the interface hosted on GitHub Pages. It analyzes repositories itself, in the browser, with RepoDNA's analysis built as WebAssembly (the same Rust code as the command line, as the @sanskarin/repodna-wasm package publishes it):

• Choose a folder or Choose an archive (.zip, .tar, .tar.gz, or .tgz) on the start page, or drop one anywhere on the page, and pick a profile. The start page shows each stage as it runs and the files done, with Stop. The finished analysis opens like an analysis file and is kept with the recent analyses.
• Files are read in the page, only when the analysis opens them, so files that .gitignore excludes are never read, and nothing is uploaded. The repository's own repodna.toml applies, as on the command line.
• Browsers cannot run Git, so these analyses have no history: no commits, contributors, hotspots by change, or Time Machine. For those, use the command line or the desktop app, then open the result here.
• The first analysis downloads the analysis program, about 3 MB compressed, which the browser then keeps.

It also opens the bundled demo and analysis files you choose (repodna.json from repodna analyze --format json or repodna report, or a .repodna export), and on Reports & export makes the HTML and Markdown reports and the Project DNA card of an open analysis, as SVG or PNG, the same way. Files are read in the page and never uploaded.

Once opened, the web version keeps working without a connection: it keeps its page, its files, and the demo in the browser, and the analysis program once it has been used. A new version takes effect on the next visit online.

Browsers that can install web sites as apps, such as Chrome, Edge, and Safari, can install the web version (in Chrome, Install RepoDNA in the address bar or the menu; in Safari, Add to Dock or Add to Home Screen). It then opens in a window of its own, and in Chrome and Edge on a computer it can be chosen to open .repodna files from the file manager.

The Web version workflow builds and publishes it whenever the interface changes on main, and can be started by hand from the Actions tab. GitHub Pages must be turned on once, in the repository's Settings > Pages, with GitHub Actions as the source. With Deploy from a branch instead, GitHub also builds the branch on every push to main and publishes the repository's own files over the interface, so visitors get the README. The workflow then publishes the interface again as soon as that build finishes, and its runs carry a warning until the source is switched to GitHub Actions, which keeps the README from showing at all.

Hosting the interface yourself#

The quickest way is the container image that each release publishes, with the interface already built and served by nginx on port 8080:

docker run --rm -p 8080:8080 ghcr.io/sanskarin/repodna-web

See the web interface image. With Node.js 18 or later instead, the @sanskarin/repodna-web npm package serves the same interface on this machine, at http://127.0.0.1:8080/ (--port and --host change where):

npx @sanskarin/repodna-web

To build it yourself, note that the build in apps/web/dist uses relative paths and hash-based routing, so any static web host can serve it from any path, with no server configuration. To analyze in the browser, it needs the WebAssembly program, built first and named by REPODNA_ENGINE; without it, the web version opens files only:

npm ci
rustup target add wasm32-wasip1
cargo build --locked -p repodna-wasm --target wasm32-wasip1 --profile web-engine
REPODNA_ENGINE=target/wasm32-wasip1/web-engine/repodna-wasm.wasm npm run build -w @repodna/web
npm run preview -w @repodna/web      # or serve apps/web/dist with any static file server

A server that sends its own Content Security Policy must allow 'wasm-unsafe-eval' in script-src, as the interface's own policy does, and should send .wasm files as application/wasm.

On a hosting service such as Cloudflare Pages, Netlify, or Vercel, use npm ci && npm run build -w @repodna/web as the build command and apps/web/dist as the output directory. The build includes LICENSE.txt, NOTICE.txt, and THIRD-PARTY-NOTICES.txt, which the Licenses page shows.

Developing the interface#

See development.