Repo Graph

repo-graph

Paths. analysis-results/… and progress-tracker/… in this skill are the default workspace layout. They resolve through locations.yaml in $TRAUST_CONFIG_HOME (docs/setup.md, Storage locations); substitute your configured roots.

Build a directed graph of the entire Hybrid Platforms source-code portfolio and overlay security-findings coverage on it. One command, five artefacts.

What it produces

Written to --out (default ../analysis-results/graph/):

repo-graph-stats.md and repo-graph.html embed the standard population block (python3 -m traust.cli corpus) for cross-dashboard reconciliation.

Node types

segment → release / product → product-version → category → repo → findings plus owner-team → repo (dashed) and repo → repo-ref (ref layer, below).

Repo nodes are coloured by max triaged severity across all linked findings dirs (CRITICAL red · HIGH orange · MEDIUM yellow · LOW green · none grey) and carry attrs.tp_total, attrs.findings_dirs, attrs.findings ∈ {audit,triage,tm,none,…}.

Edge relations

Ref layer (branch-awareness Phase 2)

Where an inventory CSV row declares a Source Branch, the builder ALSO emits an optional first-class ref node — id ref:<host>/<org>/<name>@<branch>, kind repo-ref, label <org>/<name>@<branch>, attrs.branch — deduplicated to one node per unique (repo, branch) regardless of how many rows mention it. Refs exist only where inventories declare branches (release-payload and catalog segments carry Source Branch; groups/services rows normally do not). The layer is strictly additive: repo-node identity, all pre-existing edges/attrs, hub degrees in stats.md, and the HTML view are unchanged — which is why the parallel edge uses the distinct rel ships_ref instead of reusing ships (every existing ships consumer stays byte-identical and can never double-count a branch-carrying row).

Queries this unlocks:

# repos shipping release-4.19 from a (non-default) inventory branch
jq -r '.nodes[]|select(.type=="repo-ref" and .attrs.branch=="release-4.19")
       |.label' repo-graph.json

# every branch an inventory declares for one repo
jq -r --arg r github.com/openshift/api \
  '.edges[]|select(.rel=="has_ref" and .from=="repo:"+$r)|.to' repo-graph.json

# which release/version/category ships a specific repo@branch
jq -r '.edges[]|select(.rel=="ships_ref" and
       .to=="ref:github.com/openshift/api@release-4.19")|.from' repo-graph.json

Per-ref enrichment (dependencies, PQC posture at the ref) is Phase 3 — repo-ref nodes pass through portfolio-graph spine ingest as inert kind='repo-ref' rows; every existing enrichment stage filters kind='repo' and ignores them.

Procedure

$ARGUMENTS are passed straight through to build_repo_graph.py. From the traust/ checkout:

1. Resolve paths. If the user supplied --inputs / --findings / --out, honour them; otherwise use defaults relative to the harness checkout (the inputs inventory, ../analysis-results/findings, ../analysis-results/graph).

2. Run the builder:

   python3 harnessing/repo-graph/scripts/build_repo_graph.py $ARGUMENTS
   

   The script discovers audit reports through the corpus resolver (python3 -m traust.cli corpus, the single definition of report discovery): a depth-tolerant walk of the findings tree that includes shallow findings/<repo>/ dirs and excludes symlink aliases. It hard-fails if the resolver cannot load. Each report's JSON is indexed for metadata.repository (preferring the sibling *-findings-current.json cumulative report from the track-findings skill when present — findings nodes then carry dispositions, resolved_findings, open_findings, and false_positives attributes, and stats.md reports ledger coverage), ingests all inventory CSVs from the non-excluded segments, links repos to findings (exact URL match, then a guarded name-only fallback that refuses dirs whose recorded URL points at a different repo), and writes all five outputs.

3. Report the summary. Read repo-graph-stats.md back to the user and call out:

   • node/edge totals and coverage %
   • the top-3 hub repos
   • repos_without_findings count — these are gap targets for secure-code-audit.

4. If the user asked to "open" or "view" the graph, run open <out>/repo-graph.html.

Answering questions from the graph

Once repo-graph.json exists, common queries:

# repos with no findings coverage
jq -r '.nodes[]|select(.type=="repo" and .attrs.findings=="none")|.label' repo-graph.json

# every product/release that ships a given repo
jq -r --arg r github.com/openshift/kube-rbac-proxy \
  '.edges[]|select(.rel=="ships" and .to=="repo:"+$r)|.from' repo-graph.json

# repos owned by a team, sorted by TP
jq -r --arg t "OpenShift Storage" \
  '[.edges[]|select(.rel=="owned-by" and .from=="owner-team:"+$t)|.to] as $r
   | .nodes[]|select(.id as $i|$r|index($i))
   | "\(.attrs.tp_total // 0)\t\(.label)"' repo-graph.json | sort -rn

Excluding segments

--exclude is repeatable; default is ansible. To also drop a catalog segment named operators: --exclude ansible --exclude operators.

Segment kinds

Which layout a segment uses is declared in <inputs>/inventory.yaml (traust.inventory), never inferred from the directory name. An undeclared segment is groups — the layout /add-inputs writes. release-payload segments become release nodes, catalog segments product → product-version nodes, groups/services segments product nodes per group directory.

Integrations

repo-graph.json is the spine /portfolio-graph builds on (L0), and the graph's ships edges drive per-product reporting in the PQC and findings dashboards. /drift-watch flags the graph stale when the inputs inventory HEAD moves. The DOT/GEXF/HTML renders are human-terminal.