pipeline

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: 18 Imported by: 0

Documentation

Overview

discover.go provides adapter-declared artefact discovery for the execute command's lazy automation-record creation (ENH-136).

When gtms execute encounters a test case with no automation record, the execute command calls TryAutoCreateRecord. If the resolved adapter declares an artefact-glob pattern, DiscoverArtefact walks the project tree to find matching artefact files. On exactly one match, CreateAutomationRecord is called to create the missing record so execution can continue.

The glob pattern supports {testcase} variable substitution and ** for recursive directory matching. filepath.Glob does NOT support **, so this package uses filepath.Walk with custom matching.

identity.go provides the executed-by precedence resolver introduced by ENH-125. The chain is:

  1. CLI flag (--executed-by)
  2. Environment variable (GTMS_EXECUTED_BY)
  3. git config user.name from the project repo

An empty result is acceptable — the field stays unset on records and the YAML marshaller omits the key via `omitempty`.

migrate.go provides a one-shot migration function for pre-release automation records that still use the old field names (ENH-123).

The migration renames YAML keys:

last-formal-result  -> result
last-formal-run     -> executed_artefact
last-formal-run-at  -> executed_at
log                 -> notes
log-spill           -> notes-spill
defect (string)     -> defect ([]string)

New fields (executed_by, environment) are left blank. The migration is idempotent: records already using new names are skipped.

Package pipeline bridges transient result contracts to permanent git-committed records. It creates automation records from completed automate tasks and updates them with execution results.

record.go provides a reusable record-write primitive for creating automation records from caller-supplied options. This is the shared logic used by gtms link (ENH-111) and, in the future, gtms automate (ENH-112/113).

The existing BuildAutomationRecord function in pipeline.go is tightly coupled to TaskFile + ResultContract. CreateAutomationRecord takes a RecordOptions struct instead, making it usable from any caller that has the required data.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AbsArtefactPath added in v0.2.0

func AbsArtefactPath(projectRoot, artefactPath string) string

AbsArtefactPath returns the absolute path for an artefact, resolving relative paths against projectRoot.

func BuildAutomationRecord

func BuildAutomationRecord(projectRoot string, tf *task.TaskFile, rc *result.ResultContract) error

BuildAutomationRecord creates or updates an automation record from a completed automate task. The record is stored at gtms/automation/records/{tc-id}.automation.md.

func CreateAutomationRecord added in v0.2.0

func CreateAutomationRecord(projectRoot string, opts RecordOptions) error

CreateAutomationRecord creates or overwrites an automation record. Shared logic:

  1. Ensure gtms/automation/records/ directory exists
  2. Check for existing record -- refuse without Force, increment cycle with Force
  3. Normalise artefact path (filepath.ToSlash)
  4. Compute artefact SHA-256 hash
  5. Build AutomationRecord struct with caller values + computed fields
  6. Write via WriteAutomationRecord

Returns an error if the record already exists and Force is false.

func DiscoverArtefact added in v0.2.0

func DiscoverArtefact(projectRoot, globPattern, testCaseID string) (string, error)

DiscoverArtefact performs adapter-declared artefact discovery for a test case. It substitutes {testcase} in the glob pattern, walks the project tree, and returns exactly one project-relative artefact path.

Returns ("", nil) when globPattern is empty (no discovery configured). Returns ("", error) on zero matches, multiple matches, or path-safety violations.

The glob pattern supports:

  • Standard filepath.Match wildcards (*, ?)
  • ** for recursive directory matching (zero or more levels)
  • {testcase} variable substitution

The walk skips .git/, .gtms/, and the sentinel parent directory per ADR-014.

func HashBytes added in v0.4.0

func HashBytes(data []byte) string

HashBytes returns the SHA-256 hash of data after line-ending normalization, truncated to 16 hex characters.

func HashFile added in v0.2.0

func HashFile(path string) (string, error)

HashFile returns the SHA-256 hash of the file at path, truncated to 16 hex chars. Used by execute (to store) and reader commands (to compare).

func MigrateAutomationRecords added in v0.2.0

func MigrateAutomationRecords(projectRoot string) (int, error)

MigrateAutomationRecords walks gtms/automation/records/ and migrates any records that still use the old field names to the new ENH-123 schema. Returns the count of records migrated. Records already in the new format are skipped (idempotent).

func ResolveArtefact added in v0.2.0

func ResolveArtefact(projectRoot, storedPath, testCaseID string) (string, error)

ResolveArtefact returns the actual path to an artefact file. It tries storedPath first (fast, exact). If the file exists on disk at the stored path, it is returned immediately — the basename is NOT checked for the TC ID (ENH-110: the basename check was dropped to support shared-file frameworks like Playwright grouped tests where the TC ID lives only in the test name, not the filename).

When the stored path is empty or the file does not exist on disk, the function falls back to globbing for files whose name contains the TC ID, excluding .git/, .gtms/, and the sentinel-discovered parent directory per ADR-014 + ENH-098/ADR-017.

Directory exclusion rules:

  • .git/ and .gtms/: basename-matched at any depth (historically safe).
  • Sentinel parent (e.g. "gtms/" or "testing/"): root-anchored only via filepath.Rel — nested directories with the same name are NOT excluded.

layout.ParentDir reads a synchronized snapshot of the configured layout.

Returns the resolved path, or error if zero or multiple matches found.

func ResolveExecutedBy added in v0.2.0

func ResolveExecutedBy(ctx context.Context, projectRoot, flag string) string

ResolveExecutedBy applies the ENH-125 precedence chain to determine the identity to record on permanent records. The function never returns an error: any failure (no git, no user.name configured, etc.) yields an empty string and the caller writes nothing.

projectRoot is used as the working directory for the git invocation so repository-local config overrides global config consistently.

func UpdateExecutionResult

func UpdateExecutionResult(projectRoot string, tf *task.TaskFile, rc *result.ResultContract) error

UpdateExecutionResult updates an automation record with execution results.

func WriteAutomationRecord

func WriteAutomationRecord(path string, record *AutomationRecord) error

WriteAutomationRecord writes an automation record to the given path as markdown with YAML frontmatter.

Types

type AutoCreateOptions added in v0.2.0

type AutoCreateOptions struct {
	TestCaseID   string // required: TC ID (e.g. "tc-abc12345")
	Framework    string // required: framework name from adapter resolution
	AdapterName  string // required: resolved adapter name for provenance
	Branch       string // optional: current git branch
	ArtefactGlob string // the glob pattern from adapter config (empty = no discovery)
}

AutoCreateOptions carries caller-provided values for lazy record creation at execute time. The execute command populates this from the resolved adapter and current git state.

type AutomationRecord

type AutomationRecord struct {
	RecordCommon     `yaml:",inline"`
	Artefact         string `yaml:"artefact,omitempty"`
	Adapter          string `yaml:"adapter,omitempty"`
	LastDevResult    string `yaml:"last-dev-result,omitempty"` // pass, fail, or error
	Attempts         int    `yaml:"attempts,omitempty"`
	Summary          string `yaml:"summary,omitempty"`
	NotesSpill       string `yaml:"notes-spill,omitempty"` // ENH-077: relative path to .gtms/logs/{task-id}.log when notes was truncated (was log-spill)
	Cycle            int    `yaml:"cycle"`
	ExecutedArtefact string `yaml:"executed_artefact,omitempty"` // path to executed artefact (was last-formal-run)
	ArtefactHash     string `yaml:"artefact-hash,omitempty"`
	TestCaseHash     string `yaml:"testcase-hash,omitempty"` // ENH-117: SHA-256 of the test case spec at record-write time
	ResultsFile      string `yaml:"results-file,omitempty"`  // ENH-109: pointer to per-test results YAML in gtms/execution/
}

AutomationRecord represents a permanent automation record stored in gtms/automation/records/. It embeds RecordCommon for the shared field schema and adds automation-specific fields.

func FindAutomationRecord

func FindAutomationRecord(projectRoot, testCaseID, framework string) (*AutomationRecord, string, error)

FindAutomationRecord looks for a framework-qualified automation record for the given test case ID. The framework parameter determines which record to find (e.g. "bats" -> tc-xxx--bats.automation.md). Returns the record and its path, or nil if not found.

func ReadAutomationRecord

func ReadAutomationRecord(path string) (*AutomationRecord, error)

ReadAutomationRecord reads an automation record from the given path.

func TryAutoCreateRecord added in v0.2.0

func TryAutoCreateRecord(projectRoot string, opts AutoCreateOptions) (*AutomationRecord, string, error)

TryAutoCreateRecord attempts lazy record creation when no automation record exists and the resolved adapter declares artefact discovery. Called by the execute command at both missing-record gates.

Returns the created record and its path, or (nil, "", nil) when auto-create is not applicable (empty glob pattern). Returns (nil, "", error) on discovery or creation failure.

type RecordCommon added in v0.2.0

type RecordCommon struct {
	TestCase    string   `yaml:"testcase"`
	Framework   string   `yaml:"framework,omitempty"`
	Status      string   `yaml:"status"`                // developed, accepted
	Result      string   `yaml:"result,omitempty"`      // pass, fail, error, or skipped (was last-formal-result)
	ExecutedAt  string   `yaml:"executed_at,omitempty"` // RFC3339 UTC timestamp (was last-formal-run-at)
	ExecutedBy  string   `yaml:"executed_by,omitempty"` // CI runner identity or tester name
	Environment string   `yaml:"environment,omitempty"` // target environment (staging, production, etc.)
	Branch      string   `yaml:"branch,omitempty"`
	Defect      []string `yaml:"defect,omitempty"` // linked defect IDs (was string; ENH-123 changed to array)
	Notes       string   `yaml:"notes,omitempty"`  // diagnostic output / tester notes (was log)
}

RecordCommon holds fields shared between automation records and (future) manual result records. Both embed RecordCommon to share a uniform schema for dashboard rendering. Introduced by ENH-123 as a CON-020 prerequisite.

type RecordOptions added in v0.2.0

type RecordOptions struct {
	TestCase      string // required: TC ID (e.g. "tc-abc123")
	Framework     string // required: framework name (e.g. "playwright")
	Artefact      string // required: path to test file
	Adapter       string // required: provenance (e.g. "manual-link", "claude-playwright")
	LastDevResult string // required: "linked", "verified", "pass", "fail", "error"
	Branch        string // optional: current git branch
	Summary       string // optional: adapter output summary
	Log           string // optional: adapter log output
	Environment   string // ENH-125: optional target environment (e.g. staging, production)
	ExecutedBy    string // ENH-125: optional pre-resolved identity (flag → env → git user.name)
	Force         bool   // if true, overwrite existing record and clear execute history
}

RecordOptions carries caller-provided values for record creation. The primitive handles shared plumbing: directory creation, existing-record detection, cycle counting, path normalisation, artefact hashing, write.

Jump to

Keyboard shortcuts

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