Documentation
¶
Overview ¶
Package ciaudit checks repository CI/CD files for explicit coverage gates and build-once artifact promotion. It is deliberately read-only so the same audit can run locally, in CI, or across a workstation fleet.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WorkflowMechanisms ¶ added in v0.91.0
WorkflowMechanisms reports which verification mechanisms one workflow actually runs.
`batch-verification-runs-what-ci-runs` allows a local run to name a mechanism as skipped only after proving CI carries it. That proof has to be a read of the workflow, not an assumption: an unverified "CI owns it" is the 17-occurrence lesson reintroduced as a false assurance, which is worse than no gate at all.
The mechanism names match what a verification run reports as skipped.
func WorkflowMechanismsWithReuse ¶ added in v0.91.0
WorkflowMechanismsWithReuse additionally reports whether the workflow calls a REUSABLE workflow whose body WB cannot see.
A `uses:` callee lives in another repository, so WB cannot tell whether it runs a mechanism. That is "unverified", never "absent": reporting a mechanism as unguarded because the callee is opaque asserts something WB does not know, which is the same false-assurance failure in the other direction.
Types ¶
type Concurrency ¶ added in v0.87.0
type Concurrency struct {
// Workflow is the repository-relative workflow path.
Workflow string `json:"workflow"`
// Name is the workflow's declared name, when it has one.
Name string `json:"name,omitempty"`
// PullRequest is true when the workflow runs on pull_request events, and
// therefore runs on a stream branch's draft pull request.
PullRequest bool `json:"pull_request"`
// Push is true when the workflow runs on push events.
Push bool `json:"push"`
// Group is the concurrency group expression, empty when the workflow
// declares no concurrency at all.
Group string `json:"group,omitempty"`
// CancelInProgress is the declared value; false covers both "declared
// false" and "not declared", which Declared distinguishes.
CancelInProgress bool `json:"cancel_in_progress"`
// Declared is true when the workflow declares a concurrency block.
Declared bool `json:"declared"`
// RefKeyed is true when the group expression varies per ref or per pull
// request, which is what makes cancellation scoped to one stream branch
// rather than to the whole repository.
RefKeyed bool `json:"ref_keyed"`
}
Concurrency is one workflow's cancel-in-progress policy.
A stream branch is force-pushed on every rebase, so without a concurrency group keyed to the branch a superseded push races its predecessor instead of cancelling it: the same commit range is built twice and the fleet pays for both. `push-hook-defers-to-ci-on-stream-branches` moves local cost to CI and therefore obliges WB to bound CI, which starts with proving the cancellation is configured at all.
func StreamConcurrency ¶ added in v0.87.0
func StreamConcurrency(root string) ([]Concurrency, error)
StreamConcurrency reads every workflow under .github/workflows and reports the pull-request workflows a stream branch's draft pull request would trigger, with their concurrency policy.
It is deliberately a typed YAML read rather than a regular expression: the value being checked (`cancel-in-progress: true` under a ref-keyed group) is exactly the kind of nested structure a text match reports as present when it is declared for a different job.
func (Concurrency) Cancels ¶ added in v0.87.0
func (concurrency Concurrency) Cancels() bool
Cancels reports whether this workflow cancels a superseded run for the branch it is building.
type Finding ¶
type Finding struct {
Code string `json:"code"`
Message string `json:"message"`
File string `json:"file,omitempty"`
}
func CompareCoverageFloors ¶ added in v0.122.0
CompareCoverageFloors implements lesson:l10-coverage-floors-are-raised-with-real-tests-never-lowered-to-fit: a numeric coverage threshold is a ratchet, and a floor lowered quietly in a branch is exactly the shape the lesson names ("lowering the bar was easier than restructuring the test").
It compares every numeric `min_test_coverage_percent` in root's workflow files against the same file's value on the fetched target branch, and reports any threshold that dropped as a Finding. Unlike Audit, this function is not read-only in the no-process sense: it runs `git fetch` and `git show` against root, because "the fetched target" is a comparison this package cannot make from local files alone — root's own doc comment (see audit.go) describes Audit itself as read-only; this sibling function is the one exception, confined to this file, and only ever runs on explicit request (a non-empty target), never as part of Audit.
It is a deliberate no-op — returning (nil, nil) — when root's current branch already equals target: auditing main against itself has nothing to compare.
type Report ¶
type Report struct {
Path string `json:"path"`
HasGo bool `json:"has_go"`
HasFrontend bool `json:"has_frontend"`
HasDeploy bool `json:"has_deploy"`
GoCoverageThreshold bool `json:"go_coverage_threshold"`
FrontendCoverageThreshold bool `json:"frontend_coverage_threshold"`
ArtifactPromotion bool `json:"artifact_promotion"`
Findings []Finding `json:"findings"`
}
Source Files