testcase

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

Documentation

Overview

Package testcase provides shared, path-safe test-case spec resolution.

BUG-059: extracted from duplicated private helpers in pipeline and cli packages to provide a single canonical check used by all write paths (link, automate, execute).

REV-115: the folder-qualified lookup, and every candidate spec match, are resolved under the canonical cases directory via pathsafe.ResolveUnderRoot. A symlink under gtms/test/cases/ that resolves OUTSIDE the cases directory -- whether as the scope directory (root or intermediate component) or as an individual spec file -- is rejected, so no caller can be tricked into operating on an out-of-tree spec. Symlinks that resolve back INSIDE the cases directory (legitimate in-tree aliases) remain supported.

REV-116: the cases directory itself is validated under the project root before it is trusted as that containment boundary. If gtms/test/cases is a symlink resolving outside the project, resolution fails closed; an in-project alias is canonicalised to its in-tree target and still works.

Index

Constants

View Source
const (
	// PhraseOutsideTestCases is the refusal phrase for a default (no output-dir)
	// create target that resolves outside the canonical test-case root.
	PhraseOutsideTestCases = "resolves outside the test cases directory"
	// PhraseOutsideProject is the refusal phrase for a configured output-dir that
	// resolves outside the canonical project root.
	PhraseOutsideProject = "resolves outside the project"
)

Stable containment phrases (BUG-214 target contract). Exported-as-constants so tests assert against the same strings the error carries.

Variables

View Source
var ErrFolderNotFound = errors.New("test case folder not found")

ErrFolderNotFound signals that a folder was safely resolved to an in-tree location but does not exist (or is not a directory). It is DISTINCT from a containment/safety failure (a *pathsafe.PathSafetyError), so callers can continue classification on a genuine miss while STILL rejecting an out-of-tree symlink instead of silently treating it as "empty". Test with errors.Is.

View Source
var ErrOwnerNotFound = errors.New("test case owner not found")

ErrOwnerNotFound signals that no candidate proved the requested identity -- the NotFound outcome of ADR-024 s4, and ONLY that. It is never returned for an Ambiguous or Unprovable lookup, so a mutating caller can never read an identity failure as absence-and-permission-to-create (REV-156 CLAUDE-002). Test with errors.Is; the concrete error wraps it and carries the command's own wording.

Functions

func IsReservedCasesCompanionPath added in v0.4.0

func IsReservedCasesCompanionPath(projectRoot, artifactRel string) bool

IsReservedCasesCompanionPath reports whether a project-relative artifact is an exact reserved companion at any level beneath the configured cases tree. Containment is decided from the resolved logical parent; a leaf symlink's target does not change the result.

func IsReservedCompanion added in v0.4.0

func IsReservedCompanion(logicalBase string) bool

IsReservedCompanion reports whether logicalBase is an exact reserved testcase companion name. The comparison is deliberately case-sensitive.

func MatchesSpecFile added in v0.3.2

func MatchesSpecFile(base, tcID string) bool

MatchesSpecFile reports whether base names a test-case SPEC file whose id component is EXACTLY the bare tcID: a Markdown file named "<tcID>.md", or "<tcID>-<slug>.md" where the slug is not itself an id extension.

This is the SINGLE authoritative predicate behind Snapshot.Resolve's relevance shortlist for Unprovable candidates (ResolveSpec and FindAllSpecs, which once shared it, were deleted under ENH-205 / REV-184 CODEX-003). Keeping the guard, the existence check, and the mutation on ONE predicate is load-bearing: if they drift (as they did in REV-121/REV-122), a prefixed non-spec file like "tc-x-notes.txt" can either invent a false duplicate or, worse, satisfy a scoped-existence check and let a qualified operation broaden to the global ID and delete the real spec in another folder. base must be a filename (no path); tcID is a bare id.

REV-158 CLAUDE-003: a "<tcID>--..." filename is a LONGER id (tc-x--legacy), not tcID plus a slug, and must NOT match. A bare HasPrefix made an unreadable extended-ID sibling relevant to its shorter prefix, so a malformed tc-11111111--legacy.md refused every operation on the unrelated tc-11111111 -- exactly the cross-identity coupling BUG-188 exists to remove, and which the wiring side of the same change already avoided (wiring.TCFromNameForScope).

func OwnerAbsFor added in v0.3.3

func OwnerAbsFor(projectRoot string, owner *Owner) string

OwnerAbsFor joins a project root with an owner's project-relative spec path. Kept here so consumers do not hand-roll the join with the wrong separator.

func ResolveCreateTarget added in v0.4.1

func ResolveCreateTarget(projectRoot, configuredOutputDir, relativeFolder string) (string, error)

ResolveCreateTarget checks a create target for containment at the admission boundary and returns the authoritative absolute output directory the caller must write into (BUG-214 Owner Decisions 3 and 7).

It never creates anything -- the caller performs MkdirAll on the returned path -- and it must be called BEFORE any folder, task file, result contract or adapter process is created, so a refusal leaves the project unchanged.

Two modes:

  • configuredOutputDir == "": the default, folder-derived location. Two-stage containment mirrors testcase.ResolveFolder but WITHOUT the must-exist stat, because create legitimately admits an absent leaf below a real in-tree ancestor: 1. resolve the cases root beneath the (canonical) project root; 2. resolve relativeFolder beneath the canonical cases root. Either stage escaping, a broken link, or an inspection error is refused with PhraseOutsideTestCases. A genuinely-absent leaf under a real in-tree ancestor is returned as a creatable path.

  • configuredOutputDir != "": the configured output-dir. It must resolve inside the canonical project root; an escape (`..`, linked parent), a broken link, or an inspection error is refused with PhraseOutsideProject.

pathsafe.ResolveUnderRoot canonicalises the root (evaluating symlinks) before comparing, so a project reached through a link resolves consistently and is accepted. The returned path is canonical and absolute; nothing downstream recomputes it from the raw input (Decision 7).

func ResolveFolder added in v0.3.2

func ResolveFolder(projectRoot, relativeFolder string) (string, error)

ResolveFolder resolves a cases-relative folder to its canonical absolute path under the project-owned test-cases directory, or returns an error. It is the single authoritative folder resolver -- folderExists (classifier), IsBulkFolder, DiscoverTestCases, and the read/scope paths all delegate here so no folder consumer scans a raw, unchecked, symlink-followable path (REV-119 CODEX-001).

Order:

  1. Resolve the cases root beneath the (canonical) project root; reject an out-of-project cases-root symlink.
  2. Resolve the candidate folder beneath the canonical cases root; reject an out-of-tree folder symlink (root or intermediate component).
  3. Verify the resolved path exists and is a directory.

Returns:

  • (canonicalAbsPath, nil) for an existing, in-tree, contained directory;
  • ("", ErrFolderNotFound-wrapped) for a safely-resolved but absent folder;
  • ("", containment error) for any out-of-tree / unsafe resolution.

func SanitizeIdentityString added in v0.3.3

func SanitizeIdentityString(s string) string

SanitizeIdentityString is the shared rendering-boundary sanitiser ADR-024 s7 requires: "Identity errors carry structured fields and sanitise untrusted IDs and paths at their CENTRAL rendering boundary. Callers do not reproduce raw formatting."

It is exported so a typed identity diagnostic in another package renders through THIS function rather than growing a second copy of the rule -- see link.WiringIdentityMismatchError (REV-159 CODEX-005). One implementation is the point; a duplicate is how the two drift apart.

func SnapshotBuildsForTest added in v0.4.0

func SnapshotBuildsForTest() int64

SnapshotBuildsForTest returns the number of buildSnapshot calls so far. Test-only observability for the bounded-enumeration property; production must not depend on it.

func SplitQualifiedTarget added in v0.3.3

func SplitQualifiedTarget(target string) (folder, id string)

SplitQualifiedTarget splits a possibly folder-qualified target into its folder and bare id. A bare target yields an empty folder.

func ValidExecutionID added in v0.3.3

func ValidExecutionID(id string) bool

ValidExecutionID reports whether id satisfies the positive TC-ID grammar. It is the boundary check every path/adapter/shell-bound identity must pass (ADR-024 s6; tc-b127e260). Quoting is defence in depth, not a substitute.

Types

type Candidate added in v0.3.3

type Candidate struct {
	LogicalRel    string // project-relative, forward-slash (entry path)
	CanonicalRel  string // project-relative, forward-slash (resolved target)
	CanonicalAbs  string // canonical absolute path of the resolved target
	BodyID        string // grammar-valid parsed test_case_id; retained through schema failure
	Unprovable    bool
	Reason        UnprovableReason // meaningful only when Unprovable
	SchemaFailure *SchemaFailure   // strict schema failure, when schema caused Unprovable
	DecodeFailure *SchemaFailure   // normalized decode failure retained for reader diagnostics
	Metadata      Metadata         // normalized fields from the snapshot's single decode
	// Frontmatter is the leading frontmatter region of a parsed candidate file (the
	// bytes up to and including the closing delimiter line), exactly as the
	// enumeration read it. It is set only when BodyID is set. It lets a bulk reader
	// decode a proven owner's display fields from THIS enumeration's read instead of
	// opening every owner file a second time -- which, for an unscoped operation, was
	// a second project-wide pass (ADR-024 5a/5b: at most one per operation). It is
	// retained bytes of one immutable enumeration, not a cache: it is never shared
	// across snapshots and never re-validated.
	//
	// It is a string, not a []byte, so a caller holding a Resolution cannot mutate
	// the snapshot's storage (REV-186 CODEX-001). Aliases of one canonical file
	// share ONE retained value: buildSnapshot keeps the first copy per
	// CanonicalRel and hands the same string to every alias (REV-186 CODEX-002).
	Frontmatter string
}

Candidate is one directory entry the snapshot walk visited under gtms/test/cases/. LogicalRel is where the entry appears (a symlink's own path); CanonicalRel/CanonicalAbs is its resolved physical target.

func (Candidate) IsAlias added in v0.3.3

func (c Candidate) IsAlias() bool

IsAlias reports whether the entry is a symlink whose resolved target lies at a different logical location (an alias, not the physical owner).

type CreateContainmentError added in v0.4.1

type CreateContainmentError struct {
	// Phrase is the stable containment phrase (one of the two above).
	Phrase string
	// Input is the raw target that was refused (folder arg or output-dir value).
	Input string
	// Cause is the underlying pathsafe resolution failure.
	Cause error
}

CreateContainmentError is the create-admission-boundary refusal (BUG-214). It is returned by ResolveCreateTarget when a create target resolves outside its containment boundary -- whether via a `..` escape, a link whose target leaves the boundary, a broken link, or an inspection error on an existing component.

Its Error() carries one of the two stable phrases the BUG-214 specs assert on:

  • "resolves outside the test cases directory" for the default, folder-derived target (no configured output-dir);
  • "resolves outside the project" for a configured output-dir.

The phrase is a load-bearing substring: the acceptance specs grep stderr for it. Keep it exact. The underlying *pathsafe.PathSafetyError is preserved via Unwrap so callers can still inspect the cause.

func (*CreateContainmentError) Error added in v0.4.1

func (e *CreateContainmentError) Error() string

func (*CreateContainmentError) Unwrap added in v0.4.1

func (e *CreateContainmentError) Unwrap() error

type DecodeResult added in v0.4.0

type DecodeResult struct {
	Metadata         Metadata
	ParsedIdentity   string
	DeclaresIdentity bool
	Failure          *SchemaFailure
}

DecodeResult retains identity evidence even when strict schema validation fails. ParsedIdentity is authored text and is never trimmed or lowercased.

func DecodeCandidate added in v0.4.0

func DecodeCandidate(data []byte) DecodeResult

DecodeCandidate strictly decodes one already-read physical testcase candidate. It performs no discovery, ownership resolution, or filesystem I/O.

type Metadata added in v0.4.0

type Metadata struct {
	TestCaseID  string
	Title       string
	Requirement string
	Priority    string
	Created     string
	Tags        []string
	Updated     string
	Status      string
	TestType    string
}

Metadata is the normalized testcase document model. Scalar values retain the exact text authored in YAML, irrespective of the scalar's resolved YAML tag.

type Outcome added in v0.3.3

type Outcome int

Outcome is the explicit result of an ownership lookup (ADR-024 s4).

const (
	// OutcomeNotFound: no candidate proves the requested identity.
	OutcomeNotFound Outcome = iota
	// OutcomeUniqueOwner: exactly one canonical physical owner proves it.
	OutcomeUniqueOwner
	// OutcomeAmbiguous: more than one canonical physical owner proves it.
	OutcomeAmbiguous
	// OutcomeUnprovable: a relevant candidate cannot be read or identified safely.
	OutcomeUnprovable
)

type Owner added in v0.3.3

type Owner struct {
	// contains filtered or unexported fields
}

Owner is one proven, uniquely-owned test case: its id, the spec that owns it, and where that spec physically lives.

func ResolveOwner added in v0.3.3

func ResolveOwner(projectRoot, target string) (*Owner, error)

ResolveOwner builds one snapshot and resolves a single target -- bare ("tc-abc123") or folder-qualified ("folder/tc-abc123") -- to its proven owner.

It is the entry point for a caller that owns a whole operation and needs the owner to hand onward. A caller that already holds a snapshot uses RequireOwner or RequireOwnerUnderFolder instead of building a second one.

func (*Owner) DecodeFailure added in v0.4.0

func (o *Owner) DecodeFailure() *SchemaFailure

DecodeFailure returns normalized decode evidence retained by the snapshot.

func (*Owner) ID added in v0.3.3

func (o *Owner) ID() string

ID returns the bare, grammar-valid TC id this Owner proves.

func (*Owner) Metadata added in v0.4.0

func (o *Owner) Metadata() Metadata

Metadata returns the normalized testcase fields from the snapshot read that proved this owner. Mutable slices and maps are copied before they leave Owner.

func (*Owner) SpecAbs added in v0.3.3

func (o *Owner) SpecAbs() string

SpecAbs returns the owning spec's canonical absolute path, for reading and hashing. It is already containment-checked and symlink-resolved, so a consumer hashing or reading through it cannot be redirected out of the project.

func (*Owner) SpecRel added in v0.3.3

func (o *Owner) SpecRel() string

SpecRel returns the owning spec's project-relative, forward-slash path. This is the form recorded in task files, wiring, and adapter context -- what a human or an adapter sees.

type OwnerEvidence added in v0.4.0

type OwnerEvidence struct {
	LogicalRel    string
	Metadata      Metadata
	DecodeFailure *SchemaFailure
}

OwnerEvidence carries the one-read decoder result for one physical owner in an Ambiguous resolution. Readers use it without reopening or reparsing specs.

type OwnershipError added in v0.3.3

type OwnershipError struct {
	// ID is the TC id the operation was about. REV-158 CLAUDE-007: it holds a TC
	// id or nothing. A candidate found by SCOPE rather than by id has no id to
	// report -- that is why it is unprovable -- so ID stays empty and Scope
	// carries the folder instead.
	ID            string
	Outcome       Outcome
	Owners        []string         // Ambiguous
	Path          string           // Unprovable
	Scope         string           // Unprovable found by scope: the folder that selected it
	Reason        UnprovableReason // Unprovable
	SchemaFailure *SchemaFailure
}

OwnershipError is the typed, centrally-sanitised diagnostic a consumer returns when ownership is not uniquely proven (ADR-024 s7). Callers render it once; they do not reproduce raw formatting.

func OwnershipErrorFor added in v0.3.3

func OwnershipErrorFor(res Resolution) *OwnershipError

OwnershipErrorFor builds an OwnershipError from a non-unique Resolution, or nil for UniqueOwner.

func UnprovableInScope added in v0.3.3

func UnprovableInScope(scopeRel string, c Candidate) *OwnershipError

UnprovableInScope builds the diagnostic for a candidate that an operation selected because it lies in the requested SCOPE, not because its filename or body matched a requested id.

REV-158 CLAUDE-007: the four call sites for this used to build the error with ID set to the candidate's PATH, so Error() rendered "ownership of test case ID 'gtms/test/cases/feat/README.md' cannot be proved from gtms/test/cases/feat/README.md" -- labelling a path as a TC id and then repeating it, which buries the repair sentence and means a user grepping for a TC id finds a path. ADR-024 s7 requires typed diagnostics whose fields carry the right facts.

func (*OwnershipError) Error added in v0.3.3

func (e *OwnershipError) Error() string

Error renders a non-empty, actionable diagnostic with control characters sanitised out of the id and paths.

type Resolution added in v0.3.3

type Resolution struct {
	Outcome            Outcome
	ID                 string
	OwnerLogicalRel    string   // UniqueOwner: the real owner's project-relative path
	OwnerCanonicalAbs  string   // UniqueOwner: canonical absolute path for reading/hashing
	OwnerFrontmatter   string   // UniqueOwner: the owner's frontmatter region as this snapshot read it
	OwnerMetadata      Metadata // UniqueOwner: normalized metadata from the same snapshot decode
	OwnerDecodeFailure *SchemaFailure
	AmbiguousEvidence  []OwnerEvidence
	Owners             []string // Ambiguous: sorted logical paths of every physical owner
	UnprovablePath     string   // Unprovable: candidate logical path
	Reason             UnprovableReason
	SchemaFailure      *SchemaFailure
}

Resolution is the outcome of an ownership lookup, carrying everything a consumer needs to act, refuse, or diagnose.

type RetainedFieldFailure added in v0.4.0

type RetainedFieldFailure struct {
	Key          string
	DeclaredKind string
	FoundKind    string
}

RetainedFieldFailure describes one retained field whose YAML node kind does not match ADR-025.

type SchemaFailure added in v0.4.0

type SchemaFailure struct {
	Kind         SchemaFailureKind
	Key          string
	Value        string
	DeclaredKind string
	FoundKind    string
	Detail       string
	// RetainedFields records every wrong-kind retained field in fixed decoder
	// order. Key, DeclaredKind, and FoundKind remain the first failure for
	// pinned diagnostics.
	RetainedFields []RetainedFieldFailure
}

SchemaFailure is a typed strict-decoder failure. The structured fields are retained so ownership and create-validation callers can render their own established envelopes without parsing Error text.

func (*SchemaFailure) Error added in v0.4.0

func (f *SchemaFailure) Error() string

type SchemaFailureKind added in v0.4.0

type SchemaFailureKind int

SchemaFailureKind identifies a strict testcase document failure.

const (
	SchemaFailureNoFrontmatterBlock SchemaFailureKind = iota + 1
	SchemaFailureMissingSchemaDiscriminator
	SchemaFailureMalformedSchemaDiscriminator
	SchemaFailureUnsupportedSchemaVersion
	SchemaFailureWrongConceptType
	SchemaFailureMissingTestCategory
	SchemaFailureDuplicateYAMLKey
	SchemaFailureWrongTypeRetainedField
	SchemaFailureMalformedYAML
)

type ScopeAuthorityError added in v0.3.3

type ScopeAuthorityError struct {
	ID        string // the bare TC id the user targeted
	Scope     string // the project-relative folder the user named
	OwnerPath string // where the proven owner physically lives
}

ScopeAuthorityError signals that a folder-qualified DESTRUCTIVE target named a place the spec is merely REACHABLE from, not the place it lives. It is a typed, centrally-sanitised diagnostic (ADR-024 s7); callers render it once.

func (*ScopeAuthorityError) Error added in v0.3.3

func (e *ScopeAuthorityError) Error() string

type Snapshot added in v0.3.3

type Snapshot struct {
	// contains filtered or unexported fields
}

Snapshot is one immutable project-wide enumeration of the spec tree.

func NewSnapshot added in v0.3.3

func NewSnapshot(projectRoot string) (*Snapshot, error)

NewSnapshot builds one immutable project-wide snapshot of the spec tree.

One operation builds ONE snapshot and passes the resolved owner forward (ADR-024 s5, internal/testcase/owner.go). There is deliberately no cache here: a cache would make re-resolution cheap rather than unnecessary, and would leave every consumer holding a bare id and its own idea of what that id means. It would also carry real hazards for the sake of that cheapness -- process-global state, an unenforced "reads only" constraint, no nesting guard, and a stale window if an adapter writes a spec mid-operation.

A missing cases directory yields an empty snapshot (not an error); an out-of-project cases-root symlink or an inaccessible cases root fails closed.

func (*Snapshot) KnownIDs added in v0.3.3

func (s *Snapshot) KnownIDs() []string

KnownIDs returns every provable body identity in the snapshot, sorted and deduplicated. It is the set of identities that DEMONSTRABLY exist in this project.

Its purpose is disambiguating a filename that could grammatically belong to more than one id -- "tc-x--legacy--bats" reads as either (tc-x, legacy--bats) or (tc-x--legacy, bats). Knowing that tc-x--legacy exists settles it. Callers use it to decide RELEVANCE for records whose own body cannot be read; it never establishes identity for a record that can be read, which stays body-authoritative (ADR-024 s1).

func (*Snapshot) RequireFolderOwnership added in v0.3.3

func (s *Snapshot) RequireFolderOwnership(scopeRel string, recursive bool) error

RequireFolderOwnership refuses a bulk mutating operation over scopeRel (a canonical project-relative folder) when any in-scope candidate is Unprovable or any selected id is Ambiguous/Unprovable project-wide. scopeRel must already be canonically resolved (directory aliases followed; host case applied).

func (*Snapshot) RequireMutationAuthorityUnderScope added in v0.3.3

func (s *Snapshot) RequireMutationAuthorityUnderScope(scopeRel, id string) error

RequireMutationAuthorityUnderScope is the DESTRUCTIVE counterpart to RequireOwnerUnderFolder, for a folder-qualified delete or reset.

REV-158 CLAUDE-001. Reachability and authority are different questions, and a destructive command needs the second one. RequireOwnerUnderFolder answers "did the user name a place this spec can be reached from", which is right for a read or a lookup and deliberately tolerant of an in-tree alias. A single-TC delete plan used only that gate and then removed the owner's CANONICAL file, so with beta/tc-22222222-beta.md real and alpha/tc-22222222-linked.md a symlink to it, `gtms delete alpha/tc-22222222` exited 0 and deleted the file in BETA, leaving a dangling link in alpha. `gtms reset alpha/tc-22222222` reached the same gate. That is ADR-024 s3's explicit prohibition -- "removing the link never removes the target merely because it was reached through that link" -- and it is BUG-185's own failure class, destroying out-of-scope data, arrived at through an alias instead of a duplicate id.

Authority therefore requires the proven owner to physically LIVE under the requested scope, which is the same rule SelectFolder applies when it excludes aliases from folder selection. A directory alias still works: the scope is canonically resolved before this comparison, so naming a linked directory resolves to the real one (ADR-024 s3). A spec symlink inside the folder it points into also still works, because the owner really is there.

scopeRel is a canonical project-relative folder path. An empty scope means the target was unqualified and imposes no scope requirement. NotFound is not an authority failure -- delete and reset still clean orphaned flat state keyed by an exact id whose spec is already gone -- so it returns nil and leaves the existence wording to the command.

func (*Snapshot) RequireOwner added in v0.3.3

func (s *Snapshot) RequireOwner(id string) (*Owner, error)

RequireOwner resolves id to its proven unique owner from THIS snapshot.

Returns:

  • (owner, nil) for UniqueOwner;
  • (nil, ErrOwnerNotFound-wrapped) when nothing proves the identity;
  • (nil, *OwnershipError) for Ambiguous or Unprovable.

A mutating caller must treat every non-nil error as a refusal. Only ErrOwnerNotFound means "absent", and even that is not by itself permission to create -- that judgement belongs to the command.

func (*Snapshot) RequireOwnerUnderFolder added in v0.3.3

func (s *Snapshot) RequireOwnerUnderFolder(projectRoot, folder, id string) (*Owner, error)

RequireOwnerUnderFolder is RequireOwner for a FOLDER-QUALIFIED target: the proven owner must additionally be reachable under the requested folder, either as its real file or through an in-tree alias physically located there.

Reachability is not ownership. It answers "did the user name a place this spec can be reached from", using the LOGICAL path, while ownership stays a project-wide question answered by body identity. Keeping them separate is what stops a symlink from granting authority over a spec that lives elsewhere (ADR-024 s3).

func (*Snapshot) RequireOwnership added in v0.3.3

func (s *Snapshot) RequireOwnership(id string) error

RequireOwnership returns a typed OwnershipError when id is Ambiguous or Unprovable, and nil for UniqueOwner or NotFound. It is the shared pre-mutation / pre-invocation guard for a single-TC mutating consumer (automate, execute, prime, triage): NotFound is left to each command's own existence wording.

func (*Snapshot) Resolve added in v0.3.3

func (s *Snapshot) Resolve(id string) Resolution

Resolve answers project-wide ownership for a requested bare TC id. Relevance for Unprovable candidates is the filename shortlist of id (MatchesSpecFile). Precedence: a relevant Unprovable candidate wins (fail closed), then owner count decides NotFound / UniqueOwner / Ambiguous.

func (*Snapshot) ResolveScopedOwner added in v0.4.0

func (s *Snapshot) ResolveScopedOwner(id string) Resolution

ResolveScopedOwner answers ownership for an id a BULK operation selected by scope (ADR-024 5b "Relevance and outcomes in a bulk operation"). A bulk operation has no requested id, so section 4a's filename-shortlist arm is vacuous and only the scope arm applies: an Unprovable candidate is relevant only when it lies inside the selected scope, and those are diagnosed by SelectFolder, never here. This therefore decides on owner count alone -- NotFound / UniqueOwner / Ambiguous (project-wide) -- and never returns Unprovable. It exists so an Unprovable file OUTSIDE the scope whose filename happens to match an in-scope owner's id cannot turn that owner into a silent absence (REV-184 CLAUDE-001). Per-id readers (single-TC forms, triage record attribution) keep using Resolve.

func (*Snapshot) SelectFolder added in v0.3.3

func (s *Snapshot) SelectFolder(scopeRel string, recursive bool) (ids []string, unprovable []Candidate)

SelectFolder returns the body ids of the REAL physical owners whose logical path lies within scopeRel (recursive: any descendant; shallow: a direct child), and the Unprovable candidates whose logical path lies in the same scope. scopeRel is the project-relative, forward-slash path of the ALREADY canonically-resolved scope directory (so a directory alias is resolved and host case-sensitivity is decided by the OS before this call). A spec-file symlink (IsAlias) never confers its target's membership.

type UnprovableReason added in v0.3.3

type UnprovableReason int

UnprovableReason classifies why ownership could be neither proved nor disproved. Each maps to a repair sentence appropriate to THAT failure -- a single generic message would send the user to the wrong repair for four of five cases (BUG-185 acceptance).

const (
	// ReasonUnreadable: the candidate spec could not be read (permissions/encoding).
	ReasonUnreadable UnprovableReason = iota
	// ReasonMalformed: the candidate's YAML frontmatter could not be parsed.
	ReasonMalformed
	// ReasonMissingID: the candidate parsed but declares no test_case_id.
	ReasonMissingID
	// ReasonGrammarInvalid: the candidate's test_case_id fails the positive grammar.
	ReasonGrammarInvalid
)

Jump to

Keyboard shortcuts

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