Topology & Areas

Overview

A topology is an ordered list of areas declared in fragments.config.ts. Each area names a slice of your product — checkout, dashboard, admin — with a criticality, owners, and the file globs that belong to it. At scan time, resolveArea (from @fragments-sdk/core) maps each finding's file to its area, so every finding carries the area it came from.

That single mapping is what lets Fragments answer “where is the risk?” instead of just “how many findings?” — risk and coverage roll up per area, ranked by how much each area matters.

Define areas

Add a topology block to your config. Globs resolve relative to your app path by default (base: 'app'); set base: 'repo' to match from the repository root.

import { defineConfig } from '@fragments-sdk/core';

export default defineConfig({
  topology: {
    version: 1,
    base: 'app',
    areas: [
      {
        id: 'checkout',
        name: 'Checkout',
        criticality: 'revenue',
        owners: ['@payments-team'],
        files: ['src/checkout/**', 'src/cart/**'],
      },
      {
        id: 'dashboard',
        name: 'Dashboard',
        criticality: 'high',
        owners: ['@growth-team'],
        files: ['src/dashboard/**'],
      },
    ],
  },
});

Area fields

• id / name — a stable identifier and a human label for the area.
• criticality — one of low | medium | high | revenue | regulated. Drives how areas are ranked.
• owners — the teams or handles accountable for the area.
• files — the globs that belong to the area (the matched surface in v0).
• priority — optional tie-breaker when globs from different areas overlap a file.

Criticality

Criticality is the signal that turns a flat finding count into a prioritized view of risk. Areas are ranked criticality-first, so a single open finding in a regulated area outranks many in a low one.

• regulated — Compliance-bound surfaces (PII, payments, healthcare) where a violation carries legal or audit risk.
• revenue — Money paths — checkout, billing, pricing — where regressions directly cost revenue.
• high — Core product surfaces with broad user impact.
• medium — Important but non-critical areas.
• low — Internal tools, prototypes, and low-traffic surfaces.

How resolution works

For each finding, the engine matches its repo-relative file path against area globs and attaches the matching area. When globs overlap, the higher priority wins; files that match no area roll up under Unassigned.

Surfaces

Because every finding carries its area, Fragments Cloud surfaces risk by topology:

• Overview. An area-risk band ranks areas by open findings and criticality, so the highest-stakes surfaces rise to the top.
• Findings. Findings can be grouped and filtered by area, so a team can scope to just the surfaces it owns.
• Pull requests. Review comments carry the area a finding lands in, connecting a violation to its owners.

Findings still flow through the same engine and the same FUI codes — topology only changes how they are organized, not what they mean.