reader

package
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 22 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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:

  1. ADR-024: ownership must be uniquely proven (Ambiguous/Unprovable refuse before any hash or write);
  2. value must be a configured key;
  3. framework must resolve through wiring (a missing --framework on a multi-framework TC is an ambiguity error naming the candidates);
  4. the test-case spec must resolve and be readable (its hash is captured);
  5. 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

func FolderTriagedCounts(projectRoot, defaultFramework string) (map[string]int, error)

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

func IsPathSafetyError(err error) bool

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:

  1. NoTests — requirements with no test cases linked
  2. NoAutomation — test cases with no wiring records (manual-only TCs included)
  3. CurrentlyFailing — wiring units whose latest terminal result is "fail"
  4. ExecutionErrors — wiring units whose latest terminal handoff has status: error (adapter failure, disjoint from CurrentlyFailing per ENH-130)
  5. RuntimeSkipped — wiring units whose latest terminal result is "skipped"
  6. StaleTestCaseHash — wiring units where testcase-hash differs from current spec content
  7. StaleArtefactHash — wiring units where artefact-hash differs from current artefact content
  8. MissingArtefact — wiring units whose artefact path does not resolve on disk
  9. 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).

func (*GapReport) TotalGaps

func (r *GapReport) TotalGaps() int

TotalGaps returns the total number of gaps across all categories.

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

func (e MapEntry) MarshalJSON() ([]byte, error)

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

func (e *MapEntry) UnmarshalJSON(data []byte) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址