Documentation
Data & telemetry
The governance report contract, field by field. This page is rendered from the same disclosure manifest checked against the CLI wire shape.
What leaves CI
The report carries source text in named fields: offending literals, messages that may quote them, structured rule facts, authored suppression and bypass reasons, and compiled package vocabulary. It never uploads whole files, whole source lines or function bodies.
Field family | Type | Purpose | Source carriage |
|---|---|---|---|
| schemaVersion | "fragments-governance-report:v1" | Pins the accepted wire shape and compatibility policy. | — |
| generatedAt | ISO-8601 string | Records when the CLI produced the report. | — |
| root.{workspaceRoot,packageRoot,packageName} | string fields | Identifies the scanned workspace and package roots. | — |
| hook.{installedAt,mode,agents[]} | installation metadata | Describes the local hook installation that produced evidence. | — |
| git.{baseRef,headSha,branch,repoFullName,pullRequestNumber} | Git and provider identifiers | Attaches results to the correct repository, commit and pull request. | — |
| summary.{filesScanned,rulesActive,presetsLoaded[],groupCount,occurrenceCount,ignoredCount,classnamesScanned,classnamesDynamic,classnamesResolved,totalFindings,errorCount,warnCount,infoCount,passed} | counts, verdict and active preset names | Reports scan volume and result totals without finding rows. | derived |
| summary.ignoredByReason.{reason} | configured reason name → count | Counts ignored findings by the reason configured by the repository. | derived |
| summary.countsBySeverity.{error,warn,info} | severity counts | Counts findings in each fixed severity bucket. | derived |
| summary.countsByCategory.{category} | configured category name → count | Counts findings by the rule categories present in the scan. | derived |
| summary.integrity.{status,declared,fatalForCi,blockingCapable,summary} | governance-integrity verdict | Explains whether the resolved policy is capable of enforcement. | derived |
| summary.integrity.families[].{id,armed,reason,remediation} | integrity-family status | Explains the enforcement readiness of each governance family. | derived |
| summary.integrity.families[].rules[] | rule identifiers | Names the active rules contributing to an integrity family. | derived |
| summary.integrity.armed[] | integrity-family identifiers | Names the governance families capable of enforcement. | derived |
| summary.integrity.remediations[] | remediation messages | Explains how to make an inert or degraded policy effective. | derived |
| summary.integrity.configDiagnostics[].{code,kind,severity,path,message} | configuration diagnostics | Reports inert or conflicting authored governance configuration. | structured-source |
| summary.integrity.roster.{configured,active,inert} | rule roster counts | Counts configured, active and inert governance rules. | derived |
| summary.countsByBaselineState.{baselined,new} | baseline-state counts | Separates accepted baseline debt from newly introduced findings. | derived |
| groups[].{groupId,ruleId,category,severity,packageRoot,filePath} | finding group metadata | Identifies each grouped rule failure and repository-relative path. | — |
| groups[].message | string | Explains the failure and may quote the offending source literal. | source-literal |
| groups[].normalizedOffense.kind | normalized-offense category | Names the kind of source offense represented by the group. | derived |
| groups[].normalizedOffense.raw | normalized source offense | Carries the exact offending source substring. | source-literal |
| groups[].normalizedOffense.canonical | normalized source offense | Carries the derived canonical representation of the offense. | derived |
| groups[].occurrences[].occurrenceId | stable occurrence identifier | Identifies one occurrence within a finding group. | derived |
| groups[].occurrences[].location.{file,line,column,endLine,endColumn} | repository-relative location | Places each occurrence at its exact file/line/column range. | — |
| groups[].occurrences[].area.{areaId,areaName,criticality,owners[],matchedGlob} | area identifiers, owners and criticality | Carries the configured product-area classification for the file. | structured-source |
| groups[].occurrences[].evidence[].factId | fact identifier | Links the occurrence to the extracted fact supporting it. | derived |
| groups[].occurrences[].evidence[].fact.kind | fact discriminator | Names the extracted rule-fact shape. | — |
| groups[].occurrences[].evidence[].fact.location.{file,line,column,endLine,endColumn} | repository-relative location | Locates the source-backed fact used as evidence. | — |
| groups[].occurrences[].evidence[].fact.{ruleSpecificField} | extensible rule-specific fact fields | Carries rule-specific parsed facts; fields may include selectors, properties and source values. | structured-source |
| groups[].suggestedReplacement.{kind,from,to,certainty,reason} | deterministic replacement | Carries the deterministic replacement the CLI can apply. | derived |
| groups[].suggestedReplacement.edit.{file,start,end,replacement} | deterministic edit range | Locates and describes the exact edit the CLI can apply. | derived |
| suppressions[].{id,kind,file,line,column,code,expiresOn,attachedLine,attachedTo,directive} | directive identity, location and attachment metadata | Reports matched in-source governance directives. | — |
| suppressions[].reason | authored directive reason | Carries the repository-authored reason for the suppression. | source-literal |
| bypassEvents[].{code,file,line} | rule code and source location | Records directives that actually bypassed a finding in this run. | — |
| bypassEvents[].reason | authored directive reason | Carries the repository-authored reason for the bypass. | source-literal |
| bypassEvents[].area.{areaId,areaName,criticality,matchedGlob} | configured product-area metadata | Classifies the bypass by its configured product area. | structured-source |
| hookEvents[].{eventId,kind,ruleId,code,file,mode,agent,timestamp,reasonClass} | bounded hook decision receipts | Reports deny, downgrade, suppression and fail-open decisions. | — |
| packageVocabularies[].{source,packageName,status,manifestPath,digest,commit} | compiled canonical-package vocabulary records | Publishes package vocabulary proposed by authoritative local discovery. | structured-source |
| packageVocabularies[].roots[].{name,members[]} | compiled component roots and members | Publishes the canonical component vocabulary discovered from the package. | structured-source |
| adoption.{metricVersion,adoptedUsages,ownableUsages} | versioned component-identity usage counts | Records the exact numerator and denominator used for adoption history. | derived |
| adoption.shadows[].{componentKey,displayName,canonicalTarget,usageCount} | bounded component-identity summaries | Explains which shadow components are moving the adoption curve without uploading source. | derived |
| health.{metricVersion,checkedSites,violatingSites} | versioned contract-site counts | Records how many sites contract-scope rules inspected and how many distinct sites carried a finding. | derived |
| health.populations.{componentUsages,tokenReferences} | per-population site counts | Names the measured populations behind the checked-site denominator. | derived |
| topology.areaImpact[].{areaId,areaName,beforeOpen,afterOpen,introduced,persistent,resolved} | area identifiers and before/after counts | Reports bounded product-area impact totals. | derived |
| contractHash | 64-character FCID | Pins the exact compiled contract enforced by the run. | derived |
| source | "ci" | Identifies the report producer. | — |
| gateRung | "ci" | "cli" | Identifies the enforcement rung that produced the verdict. | — |
| diffOnly | boolean | States whether the scan was restricted to changed files. | — |
| failOnWarnings | boolean | States whether warnings were gating for this run. | — |
What is never uploaded
Governance reports do not contain whole files, whole source lines, function bodies, secrets, environment variables, or dependency source. There is no source-excerpt upload option.
Direct repository access
Separately from the CI report, Fragments Cloud may read a connected repository file through the installed GitHub App to verify that a reported finding still exists at its claimed location. The read uses the repository permission granted at connection time; file contents are not persisted as governance-report data.
Versioning and DPA
fragments-governance-report:v1 is frozen. Compatible releases may add optional fields; removing, renaming, or changing the meaning of a field requires a new schema version. A data processing addendum is available on request from hello@usefragments.com.