Documentation
¶
Overview ¶
Package reader implements the built-in local-reader adapter. It scans the filesystem for test cases, automation records, and task files to provide pipeline visibility without invoking external adapters.
Index ¶
- Variables
- func AttachTriageToDetail(projectRoot string, detail *PipelineDetailEntry, ...) error
- func AttachTriageToDetailFromScan(projectRoot string, detail *PipelineDetailEntry, diags IdentityDiagnostics, ...) error
- func AttachTriageToEntries(projectRoot string, entries []PipelineEntry, triageValues map[string]string, ...) error
- func AttachTriageToEntriesFromScan(projectRoot string, entries []PipelineEntry, diags IdentityDiagnostics, ...) error
- func ClassifyTriage(projectRoot, testCaseID, value, summary, defect, framework string, ...) (*triage.Record, error)
- func FolderTriagedCounts(projectRoot, defaultFramework string) (map[string]int, error)
- func GapsFolderSummaryWithDiagnostics(projectRoot string, defaultFramework string) ([]GapsFolderSummaryEntry, IdentityDiagnostics, error)
- func GapsWithDiagnostics(projectRoot string, scope *ScopeInfo, defaultFramework string, ...) (*GapReport, IdentityDiagnostics, error)
- func IsPathSafetyError(err error) bool
- func ListTriageForTCWithSnapshot(snap *testcase.Snapshot, projectRoot, tcID, valueFilter string, ...) ([]TriageView, IdentityDiagnostics, error)
- func ListTriageWithDiagnostics(projectRoot string, scope *ScopeInfo, valueFilter string, includeResolved bool) ([]TriageView, IdentityDiagnostics, error)
- func MapTargetDiagnostics(projectRoot, tcID, defaultFramework string, strictFramework bool) (report *MapReport, targetErr error, diags IdentityDiagnostics, err error)
- func MapTargetDiagnosticsWithSnapshot(snap *testcase.Snapshot, projectRoot, tcID, defaultFramework string, ...) (report *MapReport, targetErr error, diags IdentityDiagnostics, err error)
- func MapWithDiagnostics(projectRoot string, scope *ScopeInfo, defaultFramework string, ...) (*MapReport, IdentityDiagnostics, error)
- func PipelineDetailWithSnapshot(snap *testcase.Snapshot, projectRoot, testCaseID, defaultFramework string, ...) (*PipelineDetailEntry, IdentityDiagnostics, error)
- func PipelineFolderSummaryWithDiagnostics(projectRoot string, defaultFramework string, withTriage bool) ([]FolderSummaryEntry, IdentityDiagnostics, error)
- func PipelineStatusWithDiagnostics(projectRoot string, scope *ScopeInfo, defaultFramework string, ...) ([]PipelineEntry, IdentityDiagnostics, error)
- func ResolveTriage(projectRoot, testCaseID, framework string) (rec *triage.Record, alreadyResolved bool, err error)
- type Classification
- type CorruptWiringError
- type CurrencyTier
- type DeleteResult
- type FolderSummaryEntry
- type FrameworkEntry
- type FrameworkTriage
- type FrameworkTriageSnapshot
- type GapEntry
- type GapReport
- type GapsFolderSummaryEntry
- type IdentityDiagnostics
- type IncompleteReadError
- type MapEntry
- type MapReport
- type MapSummary
- type PathSafetyError
- type PipelineDetailEntry
- type PipelineEntry
- type PreservedArtefact
- type RequirementGroup
- type ResetResult
- type ScopeInfo
- type TriageView
- func ListTriage(projectRoot string, scope *ScopeInfo, valueFilter string, includeResolved bool) ([]TriageView, error)
- func ListTriageForTC(projectRoot, tcID, valueFilter string, includeResolved bool) ([]TriageView, error)
- func ShowTriage(projectRoot, testCaseID, framework string) (*TriageView, error)
Constants ¶
This section is empty.
Variables ¶
var ErrMapTargetNotFound = errors.New("map target not found")
ErrMapTargetNotFound is returned by MapTargetDiagnostics when the named target resolves to NotFound, so the CLI can render map's existing not-found wording.
Functions ¶
func AttachTriageToDetail ¶ added in v0.3.3
func AttachTriageToDetail(projectRoot string, detail *PipelineDetailEntry, triageValues map[string]string, filter string, requestedFramework string) error
AttachTriageToDetail decorates FrameworkEntry.Triage on a single-test-case detail entry, using the same rules as AttachTriageToEntries.
func AttachTriageToDetailFromScan ¶ added in v0.4.1
func AttachTriageToDetailFromScan(projectRoot string, detail *PipelineDetailEntry, diags IdentityDiagnostics, triageValues map[string]string, filter string, requestedFramework string) error
AttachTriageToDetailFromScan is AttachTriageToDetail for a command that already scanned .gtms/results. See AttachTriageToEntriesFromScan.
func AttachTriageToEntries ¶ added in v0.3.3
func AttachTriageToEntries(projectRoot string, entries []PipelineEntry, triageValues map[string]string, filter string, requestedFramework string) error
AttachTriageToEntries decorates FrameworkEntry.Triage on every per-test-case status entry. filter=="" attaches every record (active AND resolved) so per-TC JSON exposes lifecycle; filter!="" attaches only active records whose value matches, so a filtered view surfaces only matching classifications. triageValues supplies the friendly label best-effort (nil is fine -> labels omitted). The caller owns whether the attached data is also rendered in human output. requestedFramework is the EXPLICIT --framework value ("" when none was given). It gates only the BUG-193 entry-level manual carrier: a strict non-manual selection on a manual-only case must not surface the manual classification for rendering, filtering, or JSON (REV-170 CODEX-001).
func AttachTriageToEntriesFromScan ¶ added in v0.4.1
func AttachTriageToEntriesFromScan(projectRoot string, entries []PipelineEntry, diags IdentityDiagnostics, triageValues map[string]string, filter string, requestedFramework string) error
AttachTriageToEntriesFromScan is AttachTriageToEntries for a command that already scanned .gtms/results: diags comes from that scan, so the command scans once and its refusals are the only ones to report (section 8, CODEX-006).
func ClassifyTriage ¶ added in v0.3.3
func ClassifyTriage(projectRoot, testCaseID, value, summary, defect, framework string, values map[string]string) (*triage.Record, error)
ClassifyTriage writes (or reactivates and replaces) the triage record for the latest terminal result of one (test case, framework) pair.
values is the resolved permitted-value set from config.ResolveTriageValues. The precondition order is deliberate and matches the acceptance specs:
- ADR-024: ownership must be uniquely proven (Ambiguous/Unprovable refuse before any hash or write);
- value must be a configured key;
- framework must resolve through wiring (a missing --framework on a multi-framework TC is an ambiguity error naming the candidates);
- the test-case spec must resolve and be readable (its hash is captured);
- a terminal execution result must exist to classify.
Only after every precondition passes is any existing record strict-read (so a record this binary cannot understand blocks the overwrite) and the new record written atomically.
func FolderTriagedCounts ¶ added in v0.3.3
FolderTriagedCounts returns the per-folder count of test cases with at least one applicable active triage classification, deduped once per test case and framework-aware (defaultFramework restricts counting to that framework). It backs the root `gtms status --show-triage` TRIAGED column; the CLI calls it only under --show-triage so default status output is unchanged. Every folder that has test cases appears in the map (with 0 when none are triaged).
func GapsFolderSummaryWithDiagnostics ¶ added in v0.4.0
func GapsFolderSummaryWithDiagnostics(projectRoot string, defaultFramework string) ([]GapsFolderSummaryEntry, IdentityDiagnostics, error)
GapsFolderSummaryWithDiagnostics is the ENH-205 gaps folder summary on the snapshot: one snapshot per operation, affected identities left out of every per-folder count, named on stderr, exit 1 (tc-63407e55).
func GapsWithDiagnostics ¶ added in v0.4.0
func GapsWithDiagnostics(projectRoot string, scope *ScopeInfo, defaultFramework string, strictFramework bool) (*GapReport, IdentityDiagnostics, error)
GapsWithDiagnostics is the ENH-205 gaps operation on the snapshot. It resolves identity from ONE snapshot per operation and returns the gap report over the proven, unique, decodable owners plus the identity diagnostics for policy (e): a duplicated or unprovable test case appears in no category and no total, is named on stderr, and the command exits 1 (tc-3c5ae939).
func IsPathSafetyError ¶ added in v0.2.0
IsPathSafetyError delegates to pathsafe.IsPathSafetyError. Preserves the reader-package API surface for existing callers and tests.
func ListTriageForTCWithSnapshot ¶ added in v0.4.0
func ListTriageForTCWithSnapshot(snap *testcase.Snapshot, projectRoot, tcID, valueFilter string, includeResolved bool) ([]TriageView, IdentityDiagnostics, error)
ListTriageForTCWithSnapshot is ListTriageForTC against a snapshot the caller already built, so a qualified or bare `triage --list <tc-id>` runs its ownership check and this listing against ONE snapshot (ADR-024 5b "Qualified targets resolve once"). Spec existence is not a prerequisite for a bare record lookup; the orphan marker comes from the snapshot ("[spec missing]" == NotFound).
The single-target ownership rule is enforced HERE, not left to the caller (REV-184 CODEX-004): an ID whose spec is Ambiguous or Unprovable is refused with the typed *testcase.OwnershipError and no views, because a record keyed by that ID cannot be attributed to one test case (ADR-024 5b "Single-TC forms").
BUG-209 section 8: the diagnostics carry any refused handoff or results directory from the scan behind the result join, so the caller can warn and exit non-zero.
func ListTriageWithDiagnostics ¶ added in v0.4.0
func ListTriageWithDiagnostics(projectRoot string, scope *ScopeInfo, valueFilter string, includeResolved bool) ([]TriageView, IdentityDiagnostics, error)
ListTriageWithDiagnostics is the ENH-205 triage listing on the snapshot. It resolves each record's ID and the scope's identities from ONE snapshot per operation, and applies policy (e) point 8:
- A record whose ID resolves Ambiguous or Unprovable is left out (it cannot be attributed to one test case) and the identity is diagnosed.
- "[spec missing]" now means the snapshot returned NotFound for that ID, so a renamed owner is no longer reported missing.
- The root listing's scope is the whole tree: an Unprovable candidate tied to no record is still diagnosed, and the command exits 1.
- A folder listing selects records through the snapshot's in-scope proven owners; an Ambiguous ID with an owner in scope is excluded and diagnosed.
func MapTargetDiagnostics ¶ added in v0.4.0
func MapTargetDiagnostics(projectRoot, tcID, defaultFramework string, strictFramework bool) (report *MapReport, targetErr error, diags IdentityDiagnostics, err error)
MapTargetDiagnostics resolves the target of `map <tc-id>` and, when the target is proven, builds the whole-tree map plus the diagnostics scoped for the single-TC form (ADR-024 5b "Single-TC forms" -> map <tc-id>):
- targetErr != nil: the target itself is Ambiguous / Unprovable / NotFound / a display-field decode failure. The CLI refuses with empty stdout and exit 1. NotFound is signalled with ErrMapTargetNotFound so the CLI keeps map's wording.
- otherwise: report is the whole-tree proven map (the CLI filters it to the target's printed group), and diags carries the Ambiguous IDs whose owners fall in the printed group PLUS every tree-wide Unprovable / display-field failure. An Ambiguous ID outside the printed group does not affect map <tc-id>.
func MapTargetDiagnosticsWithSnapshot ¶ added in v0.4.0
func MapTargetDiagnosticsWithSnapshot(snap *testcase.Snapshot, projectRoot, tcID, defaultFramework string, strictFramework bool) (report *MapReport, targetErr error, diags IdentityDiagnostics, err error)
MapTargetDiagnosticsWithSnapshot is MapTargetDiagnostics against a snapshot the caller already built, so a qualified `map <folder>/<tc-id>` runs its scoped-owner check and this read against ONE snapshot (ADR-024 5b "Qualified targets resolve once").
func MapWithDiagnostics ¶ added in v0.4.0
func MapWithDiagnostics(projectRoot string, scope *ScopeInfo, defaultFramework string, strictFramework bool) (*MapReport, IdentityDiagnostics, error)
MapWithDiagnostics is the ENH-205 bulk map operation on the snapshot. It resolves identity from ONE snapshot per operation and returns the traceability report over the proven, unique, decodable owners plus the identity diagnostics for policy (e): a duplicated or unprovable test case is left out of every group, the unlinked section and the summary, named on stderr, and the command exits 1 (tc-197d8c3b).
func PipelineDetailWithSnapshot ¶ added in v0.4.0
func PipelineDetailWithSnapshot(snap *testcase.Snapshot, projectRoot, testCaseID, defaultFramework string, strictFramework bool) (*PipelineDetailEntry, IdentityDiagnostics, error)
PipelineDetailWithSnapshot is PipelineDetail against a snapshot the caller already built. ENH-205: a folder-qualified `status <folder>/<tc-id>` runs its scoped-owner check and this detail read against ONE snapshot, so the qualified operation performs exactly one project-wide enumeration (ADR-024 5b "Qualified targets resolve once, too").
BUG-209 section 8: the diagnostics carry any refused handoff or refused results directory found by the scan. A refused entry cannot be attributed to a test case, so it applies to this single-test-case read too: the caller shows the safe detail, warns and exits non-zero.
func PipelineFolderSummaryWithDiagnostics ¶ added in v0.4.0
func PipelineFolderSummaryWithDiagnostics(projectRoot string, defaultFramework string, withTriage bool) ([]FolderSummaryEntry, IdentityDiagnostics, error)
PipelineFolderSummaryWithDiagnostics is the ENH-205 folder-summary operation on the snapshot. It builds ONE project-wide snapshot, resolves identity once, and returns the per-folder summary plus the identity diagnostics for policy (e). withTriage folds the per-folder TRIAGED counts in from the SAME snapshot pass, so the no-argument `status --show-triage` operation -- which reaches both the summary and the triaged counts -- enumerates the tree once and diagnoses each affected identity once (ADR-024 5b "The operation, not the function, is the unit of migration"; tc-64663eb0 step 5).
func PipelineStatusWithDiagnostics ¶ added in v0.4.0
func PipelineStatusWithDiagnostics(projectRoot string, scope *ScopeInfo, defaultFramework string, strictFramework bool) ([]PipelineEntry, IdentityDiagnostics, error)
PipelineStatusWithDiagnostics is PipelineStatus plus the ADR-024 5b identity diagnostics for every in-scope test case that could not be resolved to a single proven, decodable owner. The CLI uses this variant so it can surface those identities on stderr and exit non-zero (policy (e)); PipelineStatus keeps its slimmer signature but returns *IncompleteReadError (no rows) when any identity is affected (REV-184 CODEX-004).
ENH-205: identity and enumeration come from ONE project-wide snapshot per operation (resolveScopedSpecs), not from the pre-migration scanTestCases walk. Only proven, unique, display-decodable owners become rows; affected identities are returned as diagnostics rather than silently dropped or double-counted.
func ResolveTriage ¶ added in v0.3.3
func ResolveTriage(projectRoot, testCaseID, framework string) (rec *triage.Record, alreadyResolved bool, err error)
ResolveTriage marks an existing triage record resolved. It depends only on a valid test case ID and an existing record: no configuration, spec, wiring, automation record, handoff, artefact, or hash is consulted, so a fresh clone whose transient handoffs are absent can still close tracked classifications.
With framework set, the exact record is selected. Without it, the sole record is resolved; multiple records require --framework, and no record is a clear error. Resolution is idempotent: an already-resolved record is returned unchanged (alreadyResolved=true) and the file is not rewritten, so repeated resolution is byte-for-byte stable.
Types ¶
type Classification ¶ added in v0.2.0
type Classification struct {
Tier CurrencyTier
StaleTestcaseHash bool
StaleArtefactHash bool // suppressed (false) when MissingArtefact is true
MissingArtefact bool
ArtefactPresent bool
}
Classification carries everything ENH-146 needs to render one (testcase, framework) wiring row.
type CorruptWiringError ¶ added in v0.3.3
type CorruptWiringError struct {
// TCID is the selected test case the corrupt record is attributed to.
TCID string
// Path is the wiring file, as found on disk.
Path string
// Err is the underlying parse/read failure.
Err error
}
CorruptWiringError is the F2 refusal: a wiring record attributed to a test case being deleted is malformed, unreadable, or declares an identity that disagrees with its filename. ADR-024 s1 makes that a data-integrity error, NEVER absence, so the whole delete plan aborts before any mutation. Callers detect it with errors.As and render it through output.Errorf like every other typed refusal.
func (*CorruptWiringError) Error ¶ added in v0.3.3
func (e *CorruptWiringError) Error() string
Error renders the diagnostic with control characters stripped from every repository-controlled field (ADR-024 s7), through the same testcase.SanitizeIdentityString every other typed identity diagnostic uses. The wrapped parse error is rendered with %q for the same reason: it can quote the offending file's bytes back at the user.
func (*CorruptWiringError) Unwrap ¶ added in v0.3.3
func (e *CorruptWiringError) Unwrap() error
Unwrap exposes the underlying parse failure to errors.Is / errors.As.
type CurrencyTier ¶ added in v0.2.0
type CurrencyTier int
CurrencyTier is the hash-currency classification of one wiring record.
const ( // TierCurrent — both hashes match current content AND artefact present. TierCurrent CurrencyTier = iota // TierStale — artefact present; at least one hash differs. TierStale // TierMissingArtefact — artefact path does not resolve on disk. // Artefact-hash cannot be computed in this state. TierMissingArtefact )
type DeleteResult ¶ added in v0.2.0
type DeleteResult struct {
TestCasesProcessed int
TestCaseSpecsRemoved int
AutomationRecords int
TestScripts int
TaskFiles int
ResultFiles int
ResultContracts int
FilesDeleted []string
PreservedArtefacts []PreservedArtefact
// BUG-209: a refused .gtms/results entry left untouched, or a refused results
// directory that stopped handoff removal. Either makes the cleanup incomplete,
// so the CLI names it and exits non-zero while the safe removals complete.
HandoffRefusals []*result.RefusedHandoffError
DirRefusal *result.RefusedDirError
}
DeleteResult describes what a delete operation did (or would do in dry-run mode).
Categories are generic and framework-agnostic:
- TestScripts: test scripts discovered via automation record artefact fields
- ResultFiles: result/output files discovered via automation record executed_artefact fields
ENH-128: replaced typed BATSScripts/JUnitResults fields with generic TestScripts/ResultFiles.
BUG-173: PreservedArtefacts records referenced test artefacts that delete did NOT remove. These are never counted among the deleted totals.
func DeleteArtifacts ¶ added in v0.2.0
func DeleteArtifacts(projectRoot string, scope *ScopeInfo, tcID string, keepSpec, force, dryRun bool) (*DeleteResult, error)
DeleteArtifacts traces and removes pipeline artifacts for the given test case(s).
If tcID is non-empty, only that single test case is deleted (scope is ignored). If tcID is empty, scope determines which test cases are deleted. When keepSpec is true, the test case spec file is preserved. When force is true (`--force-artefact-deletion`), referenced test artefacts become deletion candidates -- but an artefact referenced by any test case OUTSIDE the selected deletion set is still preserved (BUG-173). When dryRun is true, the plan is computed but no files are removed.
BUG-173: the complete operation is planned (buildDeletePlan) BEFORE any filesystem mutation, so bulk output is independent of TC iteration order and dry-run previews the same plan as the real run. The ENH-128 atomic path-safety precheck runs during planning: an unsafe selected artefact path aborts the whole operation before any removal.
func (*DeleteResult) Incomplete ¶ added in v0.4.1
func (r *DeleteResult) Incomplete() bool
Incomplete reports whether a BUG-209 refusal left the delete cleanup incomplete.
func (*DeleteResult) TotalFiles ¶ added in v0.2.0
func (r *DeleteResult) TotalFiles() int
TotalFiles returns the total number of files deleted (or that would be deleted).
type FolderSummaryEntry ¶ added in v0.2.0
type FolderSummaryEntry struct {
Folder string `json:"folder"`
Created int `json:"created"`
DraftCount int `json:"draft_count"`
Automated int `json:"automated"`
Executed int `json:"executed"`
// ENH-089: per-stage outcome breakdown for icon-forward summary.
// Passing, Failing, Errored count TCs whose selected automation record
// has the matching last-formal-result. InFlight counts TCs with an
// active execute task in gtms/tasks/in-progress/.
Passing int `json:"passing"`
Failing int `json:"failing"`
Errored int `json:"errored"`
Skipped int `json:"skipped"`
InFlight int `json:"in_flight"`
// BUG-043: count of TCs that have automation records under other frameworks
// but not the requested --framework. Zero when no framework filter is active.
FrameworkMismatch int `json:"framework_mismatch"`
// ENH-134: manual-coverage sub-state counts.
ManualPrepared int `json:"manual_prepared,omitempty"`
ManualRecorded int `json:"manual_recorded,omitempty"`
// ENH-202: per-folder count of test cases with at least one applicable
// active triage classification (deduped once per TC, framework-aware).
// It is a *int and json-omitempty so the ROOT status-summary JSON gains
// `triaged` ONLY under --show-triage (the CLI sets the pointer then, and
// leaves it nil otherwise -- see tc-db0624fc step 8). A non-nil pointer to
// 0 still serialises, so a requested zero count is visible.
Triaged *int `json:"triaged,omitempty"`
}
FolderSummaryEntry represents aggregate pipeline counts for one folder.
ENH-089 added Passing/Failing/Errored/InFlight to drive icon selection in the renderer (priority rule: ✗ > ● > ○ > ✓). Existing fields (Created/DraftCount/Automated/Executed) retain the same names and JSON keys for backward compatibility with existing JSON consumers and BATS assertions.
func PipelineFolderSummary ¶ added in v0.2.0
func PipelineFolderSummary(projectRoot string, defaultFramework string) ([]FolderSummaryEntry, error)
PipelineFolderSummary returns aggregate pipeline counts per folder. It scans all test cases recursively and groups by the immediate subfolder under gtms/test/cases/.
ENH-089: also populates Passing/Failing/Errored/InFlight for the icon-forward renderer. InFlight is sourced from active execute task files (gtms/tasks/in-progress/); outcome counts are sourced from automation-record result (was last-formal-result). The framework filter (ENH-075) continues to scope which automation records contribute outcome counts; in-flight tasks have no framework field so they count for any --framework value.
TODO(CON-023 / ENH-146): PipelineFolderSummary still routes through the transitional automationFrontmatter carrier (scanAutomationRecords + selectAutomationRecord). It is the last reader that has not been retargeted onto the wiring-aware picker (buildPipelineEntry + pickWiring). The carrier synthesises Status="developed" and Cycle=0 to keep this path compiling, which means: (a) folder-summary results remain deterministic per commit, (b) but folder-summary counts use the transitional carrier semantics, not the ENH-146 picker semantics. When folder-summary is converted to consume PipelineEntry / Frameworks[] directly, scanAutomationRecords and selectAutomationRecord can be retired alongside the automationFrontmatter struct fields marked with the related retirement TODO in types.go.
type FrameworkEntry ¶ added in v0.2.0
type FrameworkEntry struct {
Framework string `json:"framework"`
Wired bool `json:"wired"` // true for wiring-derived entries; false for the synthesized `manual` result-file entry (BUG-127)
WiringDrift string `json:"wiring_drift"` // "" | "testcase" | "artefact" | "both"
ArtefactPresent bool `json:"artefact_present"`
Artefact string `json:"artefact"`
// ENH-191: dual-provenance fields. Scoped to wiring-derived entries
// (Wired: true) only; the synthesized manual entry (BUG-127, Wired: false)
// gains neither field and its rendering is unchanged.
WiredAdapter string `json:"wired_adapter,omitempty"` // adapter stamped in the wiring record
LastRunAdapter string `json:"last_run_adapter,omitempty"` // adapter that produced the latest terminal result
// BUG-102: bootstrap state of the wiring record's artefact-hash.
// "pending" when artefact-hash is the uninitialised sentinel
// (wiring.PendingArtefactHash), "ready" when it is a real hash.
WiringBootstrap string `json:"wiring_bootstrap"`
// Overlay fields — joined from the latest terminal handoff under
// .gtms/results/ for (testcase, framework). nil/empty when no
// terminal result is joined.
LastExecutedHere string `json:"last_executed_here,omitempty"`
LastStatusHere string `json:"last_status_here,omitempty"` // "complete" | "error" | ""
LastResultHere string `json:"last_result_here,omitempty"` // "pass" | "fail" | "skip" | "error" | ""
GitCommit string `json:"git_commit,omitempty"`
GitBranch string `json:"git_branch,omitempty"`
GitDirty *bool `json:"git_dirty,omitempty"`
// Detail-view fields surfaced from the latest terminal result.
Summary string `json:"summary,omitempty"`
LogExcerpt string `json:"log_excerpt,omitempty"`
ExecutedBy string `json:"executed_by,omitempty"`
Environment string `json:"environment,omitempty"`
// ENH-202: the triage classification for THIS (test case, framework) pair,
// nested here so it can never be attributed to a sibling framework. nil when
// no triage record exists (or, under a --triage filter, when the record does
// not match the filter), so default per-TC JSON is unchanged by this field.
// Populated by AttachTriage (internal/reader/triage_visibility.go); the CLI
// gates whether it also renders in human output.
Triage *FrameworkTriage `json:"triage,omitempty"`
}
FrameworkEntry is one per-framework row inside a PipelineEntry's frameworks[] array. CON-023 / ENH-146.
type FrameworkTriage ¶ added in v0.3.3
type FrameworkTriage struct {
Value string `json:"value"`
Label string `json:"label,omitempty"`
Status string `json:"status"`
Summary string `json:"summary,omitempty"`
Defect string `json:"defect,omitempty"`
ClassifiedAt string `json:"classified_at"`
ResolvedAt string `json:"resolved_at,omitempty"`
Snapshot FrameworkTriageSnapshot `json:"snapshot"`
// ResultChangedSinceTriage is ALWAYS present -- true, false, or null. null
// ("no latest terminal result to compare against") is a distinct state a
// plain Boolean cannot express, so it carries no omitempty.
ResultChangedSinceTriage *bool `json:"result_changed_since_triage"`
// LatestResult is renderer-only (never serialised): the raw latest terminal
// result used by the single-TC detail view's
// "Snapshot: <snap>; latest result: <latest|unavailable>" line. Empty when
// no latest terminal result exists (comparison unavailable).
LatestResult string `json:"-"`
}
FrameworkTriage is the ENH-202 triage object nested under a FrameworkEntry. Its JSON field set mirrors the internal/cli triage read contract (triageShowJSON) minus the redundant test_case_id/framework: the object already sits under the framework entry it describes, so those would only invite cross-framework confusion.
type FrameworkTriageSnapshot ¶ added in v0.3.3
type FrameworkTriageSnapshot struct {
Task string `json:"task"`
Result string `json:"result"`
CompletedAt string `json:"completed_at,omitempty"`
Artefact string `json:"artefact,omitempty"`
ArtefactHash string `json:"artefact_hash,omitempty"`
TestcaseHashAtTriage string `json:"testcase_hash_at_triage,omitempty"`
}
FrameworkTriageSnapshot is the execution-provenance snapshot copied from the triage record. Field set matches the triage read contract's snapshot.
type GapEntry ¶
type GapEntry struct {
ID string `json:"id"`
Title string `json:"title"`
Since string `json:"since,omitempty"`
// ENH-134: manual-coverage sub-state. Populated on NoAutomation entries
// to disambiguate no-coverage from prepared-as-manual from recorded-as-manual.
ManualCoverage string `json:"manual_coverage,omitempty"`
}
GapEntry represents a single item in a gap category.
type GapReport ¶
type GapReport struct {
TotalTestCases int `json:"total_test_cases"`
NoTests []GapEntry `json:"no_tests"`
NoAutomation []GapEntry `json:"no_automation"`
CurrentlyFailing []GapEntry `json:"currently_failing"`
ExecutionErrors []GapEntry `json:"execution_errors"`
RuntimeSkipped []GapEntry `json:"runtime_skipped"`
StaleTestCaseHash []GapEntry `json:"stale_testcase_hash"`
StaleArtefactHash []GapEntry `json:"stale_artefact_hash"`
MissingArtefact []GapEntry `json:"missing_artefact"`
DriftDetected []GapEntry `json:"drift_detected"`
// ENH-202: the failure-specific triage partition for detailed gaps. These
// partition the existing CurrentlyFailing population exactly:
// CurrentlyFailingTriaged + CurrentlyFailingUntriaged == len(CurrentlyFailing).
// A failing TC is triaged only when its applicable active classification
// corresponds to a framework whose latest result is fail (a resolved record
// counts as untriaged). Always emitted, including zero -- no omitempty.
CurrentlyFailingTriaged int `json:"currently_failing_triaged"`
CurrentlyFailingUntriaged int `json:"currently_failing_untriaged"`
// Legacy Go-internal carriers (json:"-") — kept temporarily so
// existing CLI formatters compile during the transition. Always nil.
NeverExecuted []GapEntry `json:"-"`
SpecButNoRecord []GapEntry `json:"-"`
StaleExecution []GapEntry `json:"-"`
}
GapReport contains all coverage gap categories.
CON-023 / ENH-146: gap categories rebuilt on the wiring model.
NoTests — requirements with no TCs linked (unchanged)
NoAutomation — TCs with no wiring records (manual TCs included)
CurrentlyFailing — wiring units whose latest terminal result is "fail"
(manual rows excluded — manual fail surfaces via
NoAutomation.ManualCoverage and the status detail view)
ExecutionErrors — wiring units whose latest terminal handoff has
status: error (adapter failure, disjoint from
CurrentlyFailing per ENH-130; manual rows excluded)
RuntimeSkipped — wiring units whose latest terminal result is "skipped"
(manual rows excluded)
StaleTestCaseHash — wiring units where testcase-hash differs (ENH-117)
StaleArtefactHash — wiring units where artefact-hash differs (NEW)
MissingArtefact — wiring units whose artefact path does not resolve (NEW)
DriftDetected — manual TCs with drift-detected: true in result file
(the one category that IS manual-row-driven; checked
regardless of --framework filter, since spec drift
against a manual record is a maintenance signal
independent of the user's chosen wiring framework)
Counting discipline: each gap category produces at most one entry per TC. Multiple matching wiring records on the same TC are deduped — the TC appears once per category. Strict --framework filtering (ENH-082) restricts the result-based wiring-unit categories (CurrentlyFailing, ExecutionErrors, RuntimeSkipped, StaleTestCaseHash, StaleArtefactHash, MissingArtefact) to wiring records of the requested framework. DriftDetected is excluded from --framework filtering.
Retired (no longer surfaced): SpecButNoRecord, NeverExecuted, StaleExecution. "Not run here" is not a gap — it's the expected state on a fresh clone.
func Gaps ¶
func Gaps(projectRoot string, scope *ScopeInfo, defaultFramework string, strictFramework bool) (*GapReport, error)
Gaps returns all coverage gaps. Categories surfaced post-CON-023 / ENH-146:
- NoTests — requirements with no test cases linked
- NoAutomation — test cases with no wiring records (manual-only TCs included)
- CurrentlyFailing — wiring units whose latest terminal result is "fail"
- ExecutionErrors — wiring units whose latest terminal handoff has status: error (adapter failure, disjoint from CurrentlyFailing per ENH-130)
- RuntimeSkipped — wiring units whose latest terminal result is "skipped"
- StaleTestCaseHash — wiring units where testcase-hash differs from current spec content
- StaleArtefactHash — wiring units where artefact-hash differs from current artefact content
- MissingArtefact — wiring units whose artefact path does not resolve on disk
- DriftDetected — manual TCs with drift-detected: true in their result file
Retired per CON-023 / ENH-146: SpecButNoRecord, NeverExecuted, StaleExecution. "Not run here" is not a gap — it's the expected state on a fresh clone.
When scope is nil, all test cases are included. When scope is non-nil, only test cases within the scope directory are included. Wiring records are always global. strictFramework (ENH-082) honours an explicit --framework flag: when true and defaultFramework is non-empty, TCs without a matching wiring record for that framework are not classified into the per-wiring gap categories (CurrentlyFailing / ExecutionErrors / RuntimeSkipped / Stale* / MissingArtefact). NoAutomation classification is unchanged (driven by hasNonManualRecord).
type GapsFolderSummaryEntry ¶ added in v0.2.0
type GapsFolderSummaryEntry struct {
Folder string `json:"folder"`
Created int `json:"created"`
NotAutomated int `json:"not_automated"`
NotExecuted int `json:"not_executed"`
Failing int `json:"failing"`
Skipped int `json:"skipped"`
// BUG-043: count of TCs that have automation records under other frameworks
// but not the requested --framework. Zero when no framework filter is active.
FrameworkMismatch int `json:"framework_mismatch"`
// ENH-134: manual-coverage sub-state counts.
ManualPrepared int `json:"manual_prepared,omitempty"`
ManualRecorded int `json:"manual_recorded,omitempty"`
// ENH-117: count of TCs with stale testcase-hash.
StaleTestCaseHash int `json:"stale_testcase_hash,omitempty"`
// BUG-079: count of TCs with drift-detected: true in their manual result file.
DriftDetected int `json:"drift_detected,omitempty"`
// ENH-202: folder-wide triage partition. For every folder row,
// Triaged + Untriaged == Created, independent of execution result: a TC with
// one or more applicable active classifications is triaged (once), otherwise
// untriaged; a resolved record is not active and counts as untriaged. Both
// fields are ALWAYS emitted, including explicit zero -- no omitempty -- so a
// consumer never has to distinguish absent from zero.
Triaged int `json:"triaged"`
Untriaged int `json:"untriaged"`
}
GapsFolderSummaryEntry represents aggregate gap counts for one folder.
NotExecuted is retained on the JSON shape for compatibility but is no longer populated. CON-023 / ENH-146 retired "not run here" as a gap; counts always render as zero. The field will be removed in a later ENH.
func GapsFolderSummary ¶ added in v0.2.0
func GapsFolderSummary(projectRoot string, defaultFramework string) ([]GapsFolderSummaryEntry, error)
GapsFolderSummary returns aggregate gap counts per folder. It scans all test cases recursively and groups by the immediate subfolder under gtms/test/cases/. CON-023 / ENH-146: spec-file scanning was retired alongside the SpecButNoRecord category, and "not run here" is no longer counted as a gap. Folder summary counts come exclusively from wiring records overlaid with terminal result contracts.
type IdentityDiagnostics ¶ added in v0.4.0
type IdentityDiagnostics struct {
// contains filtered or unexported fields
}
IdentityDiagnostics carries every affected identity a bulk operation must surface under ADR-024 5b policy (e): an operation with any affected identity emits these on stderr and exits non-zero, while its normal output holds only the proven entries.
func (IdentityDiagnostics) Affected ¶ added in v0.4.0
func (d IdentityDiagnostics) Affected() bool
Affected reports whether any identity could not be resolved to a single proven, decodable owner in scope, OR any .gtms/results entry or directory was refused (BUG-209).
func (IdentityDiagnostics) Render ¶ added in v0.4.0
func (d IdentityDiagnostics) Render(w io.Writer) int
Render writes the per-identity diagnostics and the closing line to w, in the stable order ADR-024 5b point 3 requires: Ambiguous by ID, then Unprovable and display-field failures by path. Ambiguous/Unprovable text comes from the central testcase.OwnershipError rendering (section 7 sanitisation); display-field text is sanitised through the same central function. Returns the number of affected entries named.
type IncompleteReadError ¶ added in v0.4.0
type IncompleteReadError struct {
Diagnostics IdentityDiagnostics
}
IncompleteReadError is returned by the bulk read entry points that do not hand IdentityDiagnostics back to their caller (PipelineStatus, PipelineFolderSummary, FolderTriagedCounts, Map, Gaps, GapsFolderSummary, ListTriage) when any identity in scope is affected. ADR-024 5b forbids presenting an affected identity as absence, so those entry points return no rows and this typed error instead of partial rows as success (REV-184 CODEX-004). A caller that can render partial output under policy (e) uses the matching ...WithDiagnostics form.
func (*IncompleteReadError) Error ¶ added in v0.4.0
func (e *IncompleteReadError) Error() string
Error names every affected identity, in the same stable order and with the same central sanitisation as Render, on one diagnostic per line.
type MapEntry ¶
type MapEntry struct {
TestCaseID string `json:"test_case_id"`
Slug string `json:"slug"`
Title string `json:"title"`
CreateStatus string `json:"create_status"`
AutomateStatus string `json:"automate_status"`
ExecuteStatus string `json:"execute_status"`
LastResult string `json:"last_result"`
ArtefactPath string `json:"artefact_path,omitempty"`
Stale bool `json:"stale,omitempty"`
// ENH-134: manual-coverage sub-state (same semantics as PipelineEntry).
ManualCoverage string `json:"manual_coverage,omitempty"`
// BUG-043: frameworks available across all automation records for this TC.
AvailableFrameworks []string `json:"available_frameworks,omitempty"`
// BUG-079: drift diagnostic fields (same semantics as PipelineEntry).
DriftDetected bool `json:"drift_detected,omitempty"`
DriftDetectedAt string `json:"drift_detected_at,omitempty"`
TestCaseHashAtExecute string `json:"test_case_hash_at_execute,omitempty"`
// CON-023 / ENH-146 wiring shape — mirrors PipelineEntry.
Wired bool `json:"wired"`
ManualReady bool `json:"manual_ready"`
SelectedFramework string `json:"-"` // emitted via (Un)MarshalJSON as `selected_framework: null|string`
Frameworks []FrameworkEntry `json:"frameworks"`
}
MapEntry represents one test case in the traceability map.
CON-023 / ENH-145 / ENH-146 — Phase 3D wiring cutover:
The compact carriers (AutomateStatus / ExecuteStatus / LastResult / ArtefactPath / Stale / ManualCoverage / AvailableFrameworks / drift fields) remain on the JSON contract because they are pipeline-stage labels the existing human and JSON consumers depend on — not legacy automation-record lifecycle fields. They are now derived from wiring + the latest terminal result overlay rather than from the retired .automation.md surface.
The new fields (Wired / ManualReady / SelectedFramework / Frameworks[]) mirror PipelineEntry's ENH-146 shape so map JSON consumers see the same wiring-unit identity surface as `gtms status --json`.
Multi-framework discipline: Frameworks[] enumerates every wired framework for the TC; the compact LastResult / ExecuteStatus carry the worst-of-frameworks outcome so a picker-selected pass cannot hide a sibling framework's fail / error / skipped on the human row.
SelectedFramework stays a Go `string` (empty when none qualified) for ergonomic internal use; the JSON contract emits `null` for the empty case via MapEntry.MarshalJSON / UnmarshalJSON.
func (MapEntry) MarshalJSON ¶ added in v0.2.0
MarshalJSON emits the ENH-146 per-TC map entry contract. SelectedFramework serialises as `null` when empty (no qualifying wiring) and as the literal framework name otherwise. Mirrors PipelineEntry.MarshalJSON.
func (*MapEntry) UnmarshalJSON ¶ added in v0.2.0
UnmarshalJSON parses the ENH-146 map entry contract, accepting either `null` or a string for `selected_framework`. `null` and missing keys both clear any prior value on a reused struct. Mirrors PipelineEntry.UnmarshalJSON.
type MapReport ¶
type MapReport struct {
Groups []RequirementGroup `json:"groups"`
Unlinked []MapEntry `json:"unlinked"`
Summary MapSummary `json:"summary"`
}
MapReport contains the full traceability map grouped by requirement.
func Map ¶
func Map(projectRoot string, scope *ScopeInfo, defaultFramework string, strictFramework bool) (*MapReport, error)
Map returns a traceability report grouping test cases by their requirement field. When scope is nil, all test cases are included. When scope is non-nil, only test cases within the scope directory are included. Wiring records and tasks are always global. strictFramework (ENH-082) honours an explicit --framework flag in per-TC entries: when true and defaultFramework is non-empty, TCs without a matching wiring record render with no SelectedFramework and em-dashes for AUTOMATE/EXECUTE (no fallback). CON-023 / ENH-145 / ENH-146 -- Phase 3D: Automation identity comes from wiring (gtms/automation/wiring/); execution state comes from the latest terminal handoff in .gtms/results/; manual-only TCs surface via gtms/manual/records/. The map shares the Phase 3C wiring-aware reader path (buildPipelineEntry) with status, so the picker, terminal-overlay discipline, manual-ready signal, and per-framework entries are computed once. The map then applies a worst-of-frameworks override on the compact LastResult / ExecuteStatus carriers so a sibling-framework failure cannot hide behind a picker-selected pass on the human row.
type MapSummary ¶
type MapSummary struct {
TotalRequirements int `json:"total_requirements"`
TotalTestCases int `json:"total_test_cases"`
Automated int `json:"automated"`
Executed int `json:"executed"`
UnlinkedCount int `json:"unlinked_count"`
}
MapSummary provides aggregate statistics for the traceability map.
type PathSafetyError ¶ added in v0.2.0
type PathSafetyError = pathsafe.PathSafetyError
PathSafetyError is a type alias for pathsafe.PathSafetyError, preserving backward compatibility for callers that reference reader.PathSafetyError (e.g. internal/cli/delete.go). BUG-057: the canonical implementation now lives in internal/pathsafe/.
type PipelineDetailEntry ¶
type PipelineDetailEntry struct {
TestCaseID string `json:"testcase"`
Slug string `json:"slug,omitempty"`
Title string `json:"title,omitempty"`
Requirement string `json:"requirement,omitempty"`
CreateStatus string `json:"create_status,omitempty"`
Wired bool `json:"wired"`
ManualReady bool `json:"manual_ready"`
SelectedFramework string `json:"-"` // emitted via (Un)MarshalJSON as `selected_framework: null|string`
Frameworks []FrameworkEntry `json:"frameworks"`
// BUG-193: test-case-level triage carrier for a MANUAL-ONLY test case (see
// PipelineEntry.Triage). nil on wired cases, so wired-case detail JSON is
// unchanged. Populated by AttachTriageToDetail.
Triage *FrameworkTriage `json:"triage,omitempty"`
Tags []string `json:"tags,omitempty"`
// Per-stage timestamps for the detail view.
// CreateDate: date-only, sourced from test-case frontmatter `created:`.
// AutomateDate: date-only, derived from the LOCAL mtime of the selected
// wiring-record file. Reflects "last regenerated on this
// machine" — on a fresh clone (git checkout rewrites mtimes
// on MINGW64 and most Linux distros) it will equal checkout
// date, not commit date.
CreateDate string `json:"create_date,omitempty"`
AutomateDate string `json:"automate_date,omitempty"`
// ENH-077/ENH-123: diagnostic notes payload kept TOP-LEVEL on the
// detail entry (not inside frameworks[]) so the CLI text renderer
// prints the `Notes:` block under the file-paths section without
// reaching into the nested array. Sourced from the latest terminal
// result contract's `log:` / `notes-spill:` for the selected framework.
// (Per-framework summary / log_excerpt / executed_by / environment /
// git_* live in frameworks[] via FrameworkEntry.)
Notes string `json:"notes,omitempty"`
NotesSpill string `json:"notes_spill,omitempty"`
// BUG-079: manual-drift diagnostic fields (audit/diagnostic; raw RFC3339
// timestamps per the audit-field rendering rule).
DriftDetected bool `json:"drift_detected,omitempty"`
DriftDetectedAt string `json:"drift_detected_at,omitempty"`
TestCaseHashAtExecute string `json:"test_case_hash_at_execute,omitempty"`
// --- Legacy Go-internal carriers (json:"-") ---
// These power the CLI text renderer in internal/cli/status.go's
// runStatusDetail. JSON consumers see only the ENH-146 shape above
// (plus the diagnostic-notes / manual-drift carve-outs).
AutomateStatus string `json:"-"`
ExecuteStatus string `json:"-"`
LastResult string `json:"-"`
LastResultDate string `json:"-"`
Framework string `json:"-"`
ArtefactPath string `json:"-"`
LastRunPath string `json:"-"`
LastRunAt string `json:"-"`
Stale bool `json:"-"`
StaleTestCaseHash bool `json:"-"`
ManualCoverage string `json:"-"`
AvailableFrameworks []string `json:"-"`
}
PipelineDetailEntry provides detailed pipeline information for a single test case.
CON-023 / ENH-146: the JSON-visible shape mirrors the per-TC shape from PipelineEntry (testcase / wired / manual_ready / selected_framework / frameworks[]) plus detail-only metadata (tags, per-stage dates).
Result-contract carve-outs:
- summary / log_excerpt / executed_by / environment / git_commit / git_branch / git_dirty surface inside the selected framework's entry under frameworks[] (per FrameworkEntry).
- notes / notes_spill remain top-level detail fields because the CLI text renderer prints the diagnostic `Notes:` block under the file-paths section. Source: the latest terminal result contract's `log` and `notes-spill` for the selected framework.
Legacy table-renderer carriers (automate_status / execute_status / last_result / last_result_date / framework / stale / manual_coverage / available_frameworks / artefact_path / last_run_path / last_run_at) are retained on the Go struct (json:"-") so the CLI text formatter compiles, but are no longer emitted in --json.
SelectedFramework on the Go struct stays a `string`; the JSON contract emits `null` for the empty case via (Un)MarshalJSON below.
func PipelineDetail ¶
func PipelineDetail(projectRoot, testCaseID, defaultFramework string, strictFramework bool) (*PipelineDetailEntry, error)
PipelineDetail returns detailed pipeline information for a single test case. It always performs an unscoped (global) scan -- Convention 4: ID-based lookups are global. defaultFramework selects which wiring record to display when a TC has multiple. strictFramework (ENH-082) honours an explicit --framework flag: when true and defaultFramework is non-empty, a TC without a matching wiring record yields an empty selection, so the detail view shows em-dashes for AUTOMATE/EXECUTE instead of pretending another framework's record applies.
CON-023 / ENH-146: detail builds its per-TC view through the same wiring-aware path as PipelineStatus (buildPipelineEntry -> frameworks[]) so the --json shape is the per-TC ENH-146 contract with the selected framework's overlay fields surfaced inside frameworks[].
func (PipelineDetailEntry) MarshalJSON ¶ added in v0.2.0
func (d PipelineDetailEntry) MarshalJSON() ([]byte, error)
MarshalJSON emits the ENH-146 per-TC detail contract. SelectedFramework serialises as `null` when empty.
func (*PipelineDetailEntry) UnmarshalJSON ¶ added in v0.2.0
func (d *PipelineDetailEntry) UnmarshalJSON(data []byte) error
UnmarshalJSON parses the ENH-146 detail contract, accepting either `null` or a string for `selected_framework`. `null` and missing keys both clear any prior value when decoding into a reused struct.
type PipelineEntry ¶
type PipelineEntry struct {
TestCaseID string `json:"testcase"`
Slug string `json:"slug,omitempty"`
Title string `json:"title,omitempty"`
CreateStatus string `json:"create_status,omitempty"`
Wired bool `json:"wired"`
ManualReady bool `json:"manual_ready"`
SelectedFramework string `json:"-"` // emitted via (Un)MarshalJSON as `selected_framework: null|string`
// RequestedFramework is the EXPLICITLY requested framework for this view
// (the --framework flag), carried for applyTaskStatus so it can tell a manual
// view from an unmatched non-manual view (BUG-210 / REV-273). It is only set
// when the request was strict (strictFramework); defaultFramework alone is not
// a request. json:"-" AND absent from MarshalJSON, so it changes no JSON output.
RequestedFramework string `json:"-"`
Frameworks []FrameworkEntry `json:"frameworks"`
// BUG-193: test-case-level triage carrier for a MANUAL-ONLY test case, whose
// frameworks[] stays [] (ENH-146) so the manual triage object has no framework
// entry to nest under. On a WIRED test case the manual triage nests under the
// synthesised BUG-127 `manual` FrameworkEntry instead and this stays nil, so
// omitempty keeps default and wired-case JSON byte-identical (the
// triage-status-gaps-visibility suites assert `has("triage") == false` at this
// level for wired cases). Populated by AttachTriageToEntries.
Triage *FrameworkTriage `json:"triage,omitempty"`
// --- Legacy Go-internal carriers (json:"-") ---
// These power the existing TTY table renderer in internal/cli/.
// JSON consumers see only the ENH-146 shape above.
AutomateStatus string `json:"-"`
ExecuteStatus string `json:"-"`
LastResult string `json:"-"`
LastResultDate string `json:"-"`
LastRunAt string `json:"-"`
Framework string `json:"-"`
Stale bool `json:"-"`
StaleTestCaseHash bool `json:"-"`
ManualCoverage string `json:"-"`
AvailableFrameworks []string `json:"-"`
DriftDetected bool `json:"-"`
DriftDetectedAt string `json:"-"`
TestCaseHashAtExecute string `json:"-"`
}
PipelineEntry represents the pipeline status of a single test case.
CON-023 / ENH-146 pinned per-TC JSON shape:
testcase — TC ID
wired — at least one wiring record exists for this TC
manual_ready — manual-only TC (no wiring) with a primed manual
result file at gtms/manual/records/<tc>--manual.result.yaml
selected_framework — framework chosen by the hash-currency picker, or
null when no wiring framework qualifies (wired:false,
strict-framework miss, or no records)
frameworks — array of per-framework entries (see FrameworkEntry)
Legacy fields are retained as Go-internal carriers (json:"-") so the existing CLI formatters can render the table view during the transition window. JSON consumers see only the ENH-146 shape.
SelectedFramework on the Go struct stays a `string` (empty when none was chosen) so internal comparisons remain straightforward. The JSON contract emits `null` for the empty case via a custom (Un)MarshalJSON — see PipelineEntry.MarshalJSON / UnmarshalJSON below.
func PipelineStatus ¶
func PipelineStatus(projectRoot string, scope *ScopeInfo, defaultFramework string, strictFramework bool) ([]PipelineEntry, error)
PipelineStatus returns the pipeline status of test cases in the project. When scope is nil, it scans all test cases (backward compatible). When scope is non-nil, it scans only test cases within the scope directory. defaultFramework selects which wiring record to display when a TC has multiple. strictFramework (ENH-082) honours an explicit --framework filter: when true and defaultFramework is non-empty and pickWiring finds no wiring record for that framework, the entry has no selected framework -- SelectedFramework is empty (JSON-encoded as null) and the legacy Framework / AutomateStatus / ExecuteStatus / LastResult carriers remain at their "none"/"" defaults. Wired remains true whenever any wiring record exists for the TC, regardless of strict-framework selection: "wired" means "at least one wiring record exists for this TC", not "the requested framework is wired". CON-023 / ENH-146: identity comes from wiring (gtms/automation/wiring/); runtime overlay from terminal handoffs (.gtms/results/, status: complete or status: error only); manual-ready from gtms/manual/records/.
func (PipelineEntry) MarshalJSON ¶ added in v0.2.0
func (e PipelineEntry) MarshalJSON() ([]byte, error)
MarshalJSON emits the ENH-146 per-TC contract. SelectedFramework serialises as `null` when empty (no qualifying wiring) and as the literal framework name otherwise.
func (*PipelineEntry) UnmarshalJSON ¶ added in v0.2.0
func (e *PipelineEntry) UnmarshalJSON(data []byte) error
UnmarshalJSON parses the ENH-146 contract, accepting either `null` or a string for `selected_framework`. `null` (and missing) round-trip back to the empty string on the Go struct — including when unmarshalling into a reused (non-zero) struct, so a prior populated value never leaks past a `null` decode.
type PreservedArtefact ¶ added in v0.3.2
type PreservedArtefact struct {
Path string // project-relative, forward-slash
SurvivingTCs []string // sorted; empty => safe-default preserve
}
PreservedArtefact names a referenced test artefact that delete deliberately left on disk (BUG-173). The safe default preserves every referenced artefact; a forced deletion (`--force-artefact-deletion`) still preserves an artefact that a test case OUTSIDE the deletion set references.
SurvivingTCs is empty for the safe default (plain delete, no force). When a forced deletion is blocked by an external reference, SurvivingTCs holds the sorted set of referencing test case IDs outside the deletion set -- this drives the sharing warning.
type RequirementGroup ¶
type RequirementGroup struct {
Requirement string `json:"requirement"`
TestCases []MapEntry `json:"test_cases"`
}
RequirementGroup represents one requirement and all its test cases.
type ResetResult ¶ added in v0.2.0
type ResetResult struct {
TestCasesAffected int
AutomationRecordsCleared int
TaskFilesRemoved int
// BUG-209: a refused .gtms/results entry (an unsafe leaf) is left untouched
// and named; a refused results directory (an escaping link) stops all handoff
// cleanup. Either makes the cleanup incomplete, so the CLI names it and exits
// non-zero while completing every unrelated safe removal.
HandoffRefusals []*result.RefusedHandoffError
DirRefusal *result.RefusedDirError
}
ResetResult describes what a reset operation did (or would do in dry-run mode).
func ResetExecuteResults ¶ added in v0.2.0
func ResetExecuteResults(projectRoot string, scope *ScopeInfo, tcID string, dryRun bool) (*ResetResult, error)
ResetExecuteResults clears execute results for test cases matching the given scope or single TC ID. When dryRun is true, it counts affected items without modifying any files.
If tcID is non-empty, only that single test case is reset (scope is ignored). If tcID is empty, scope determines which test cases are reset.
func (*ResetResult) Incomplete ¶ added in v0.4.1
func (r *ResetResult) Incomplete() bool
Incomplete reports whether a BUG-209 refusal left the reset cleanup incomplete.
type ScopeInfo ¶
type ScopeInfo struct {
// ScanDir is the absolute path to scan for test cases.
// For shallow: use os.ReadDir on this directory.
// For recursive: use filepath.Walk starting from this directory.
ScanDir string
// RelPath is the scope directory relative to project root, using forward slashes.
// Examples: "gtms/test/cases/", "gtms/test/cases/login/", "gtms/test/cases/login/oauth/"
RelPath string
// Recursive is true when the -r flag was passed.
Recursive bool
}
ScopeInfo describes the resolved scope for a command invocation.
type TriageView ¶ added in v0.3.3
type TriageView struct {
Record *triage.Record
// ResultChanged compares the classified raw snapshot result against the
// latest terminal raw result: non-nil true when they differ, non-nil false
// when they match, and nil when no latest terminal handoff exists to compare
// against (comparison unavailable).
ResultChanged *bool
// SpecMissing is true when no test-case spec exists anywhere in the cases
// tree for the record's test case (an orphan). Computed for the root list
// and the test-case-target list (ENH-210) -- both query the record namespace
// rather than derive scope from specs -- whose human output marks such
// records "[spec missing]". A folder list is spec-scoped, so orphans never
// appear and SpecMissing stays false there.
SpecMissing bool
// Diagnostics carries the BUG-209 refusals found by ShowTriage's result join, so
// the show command can warn and exit non-zero. Unset on list views, whose
// refusals are returned by the list call itself.
Diagnostics IdentityDiagnostics
}
TriageView is one triage record joined to the terminal-result overlay for its (test case, framework) pair.
func ListTriage ¶ added in v0.3.3
func ListTriage(projectRoot string, scope *ScopeInfo, valueFilter string, includeResolved bool) ([]TriageView, error)
ListTriage enumerates, validates, filters, joins, and orders triage records for a scope. A nil scope is the root list (every triage record, including orphans). A non-nil scope is spec-scoped: test case IDs are discovered from the specifications under the scope, then each ID's records are enumerated.
The list is FAIL-CLOSED (ENH-201 item 14): every in-scope record is read and validated before any view is produced, so one malformed in-scope record fails the whole call with its path and no partial result. A malformed record outside a folder's scope is never read and so cannot poison that folder's list.
The result JOIN uses ONE canonical bulk terminal-result scan for the whole project (ENH-201 item 7); it must not scan per test case or per record.
func ListTriageForTC ¶ added in v0.3.3
func ListTriageForTC(projectRoot, tcID, valueFilter string, includeResolved bool) ([]TriageView, error)
ListTriageForTC lists every triage record stored for one test case, queried by its bare ID against the RECORD namespace (never via a spec), exactly as --show selects. It is the ENH-210 test-case-target list route: it lists all framework records for the test case, marks an orphaned record [spec missing] (SpecMissing computed), and inherits scopedTriageRecords' exact-body-identity attribution and relevant/unprovable fail-closed boundary. A prefix sibling (tc-foo--bar) is never attributed to the shorter ID; a malformed record whose filename could represent tcID fails the query closed with its path; a malformed record whose filename cannot represent tcID is never opened.
func ShowTriage ¶ added in v0.3.3
func ShowTriage(projectRoot, testCaseID, framework string) (*TriageView, error)
ShowTriage selects one triage record for (testCaseID, framework) using the shared selection rule, reads and validates it, and joins it to the latest terminal result. Selection is never lifecycle-filtered: a resolved record is returned directly (ENH-201 item 5). Selection reads no spec, wiring, or handoff; only the result JOIN consults the overlay, and its absence yields a nil comparison rather than an error.