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
- Variables
- func IsReservedCasesCompanionPath(projectRoot, artifactRel string) bool
- func IsReservedCompanion(logicalBase string) bool
- func MatchesSpecFile(base, tcID string) bool
- func OwnerAbsFor(projectRoot string, owner *Owner) string
- func ResolveCreateTarget(projectRoot, configuredOutputDir, relativeFolder string) (string, error)
- func ResolveFolder(projectRoot, relativeFolder string) (string, error)
- func SanitizeIdentityString(s string) string
- func SnapshotBuildsForTest() int64
- func SplitQualifiedTarget(target string) (folder, id string)
- func ValidExecutionID(id string) bool
- type Candidate
- type CreateContainmentError
- type DecodeResult
- type Metadata
- type Outcome
- type Owner
- type OwnerEvidence
- type OwnershipError
- type Resolution
- type RetainedFieldFailure
- type SchemaFailure
- type SchemaFailureKind
- type ScopeAuthorityError
- type Snapshot
- func (s *Snapshot) KnownIDs() []string
- func (s *Snapshot) RequireFolderOwnership(scopeRel string, recursive bool) error
- func (s *Snapshot) RequireMutationAuthorityUnderScope(scopeRel, id string) error
- func (s *Snapshot) RequireOwner(id string) (*Owner, error)
- func (s *Snapshot) RequireOwnerUnderFolder(projectRoot, folder, id string) (*Owner, error)
- func (s *Snapshot) RequireOwnership(id string) error
- func (s *Snapshot) Resolve(id string) Resolution
- func (s *Snapshot) ResolveScopedOwner(id string) Resolution
- func (s *Snapshot) SelectFolder(scopeRel string, recursive bool) (ids []string, unprovable []Candidate)
- type UnprovableReason
Constants ¶
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 ¶
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.
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
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
IsReservedCompanion reports whether logicalBase is an exact reserved testcase companion name. The comparison is deliberately case-sensitive.
func MatchesSpecFile ¶ added in v0.3.2
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
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
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
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:
- Resolve the cases root beneath the (canonical) project root; reject an out-of-project cases-root symlink.
- Resolve the candidate folder beneath the canonical cases root; reject an out-of-tree folder symlink (root or intermediate component).
- 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
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
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
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.
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
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) Metadata ¶ added in v0.4.0
Metadata returns the normalized testcase fields from the snapshot read that proved this owner. Mutable slices and maps are copied before they leave Owner.
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
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
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
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
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
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
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
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
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 )