Documentation
¶
Overview ¶
Package finders processes domain query structs into results. Finders encapsulate the actual read logic and hold injected dependencies. Pure reads — no side effects of their own (though injected dependencies may perform IO, e.g. the LLM call behind the pre-flight runner).
Index ¶
- Constants
- type Finder
- func (f *Finder) Lint(q query.LintQuery) (*query.LintResult, error)
- func (f *Finder) List(q query.ListQuery) (*query.ListResult, error)
- func (f *Finder) LoadGraph(dir string) (*model.Graph, error)
- func (f *Finder) LoadWIPMarkers(graphDir string) ([]*model.WIPMarker, error)
- func (f *Finder) Preflight(ctx context.Context, q query.PreflightQuery) (*query.PreflightResult, error)
- func (f *Finder) SchemaStatus(ctx context.Context, q query.SchemaStatusQuery) (*query.SchemaStatusResult, error)
- func (f *Finder) Show(q query.ShowQuery) (*query.ShowResult, error)
- func (f *Finder) SkillStatus(ctx context.Context, q query.SkillStatusQuery) (*query.SkillStatusResult, error)
- func (f *Finder) Status(q query.StatusQuery) (*query.StatusResult, error)
- func (f *Finder) SyncStatus(ctx context.Context, q query.SyncStatusQuery) (model.SyncStatus, error)
- func (f *Finder) WIPList(q query.WIPListQuery) (*query.WIPListResult, error)
- type GitSyncer
- type Options
Constants ¶
const GraphCommitGrepPattern = "^sdd:"
GraphCommitGrepPattern is the commit-message prefix emitted by every SDD handler (handler_new_entry, handler_summarize, handler_wip_start, handler_wip_done, handler_lint_fix, handler_rewrite, handler_init). The sync finder counts commits matching this pattern on either side of the local/upstream divergence to report graph activity.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Finder ¶
type Finder struct {
// contains filtered or unexported fields
}
Finder holds dependencies and config shared across query methods. Config is a snapshot taken at construction time — short-lived CLI means a single read at the composition root is sufficient. Nil means no config is available (fresh repo, read-only commands, tests); finder methods degrade gracefully.
func (*Finder) Lint ¶
Lint returns every entry in the graph that has at least one warning, alongside the total warning count. Pure read — graph validation runs at graph-construction time, this just collects the results. Also checks summary hash staleness.
func (*Finder) LoadGraph ¶
LoadGraph reads all .md files from dir (hierarchical YYYY/MM/ layout) and builds the graph.
func (*Finder) LoadWIPMarkers ¶
LoadWIPMarkers reads all marker files from the wip/ subdirectory of graphDir.
func (*Finder) Preflight ¶
func (f *Finder) Preflight(ctx context.Context, q query.PreflightQuery) (*query.PreflightResult, error)
Preflight runs the pre-flight validator against the given query. Runs Go-side mechanical checks first (see mechanicalPreflight), then delegates to the llm package for rubric-based checks, merging the findings so callers see a unified view. Returns an error only for infrastructure failures.
Mechanical checks cover participant coverage (AC 6), actor canonical write-once (AC 5), and role canonical-match + refs-head (AC 7) per plan d-cpt-d34. The former LLM-judged participant-drift check is retired in favor of the mechanical canonical check.
The language-drift check receives the configured graph language from config (see Finder.language). Empty means no language check (English default); a locale code activates the check against description prose.
func (*Finder) SchemaStatus ¶ added in v0.2.0
func (f *Finder) SchemaStatus(ctx context.Context, q query.SchemaStatusQuery) (*query.SchemaStatusResult, error)
SchemaStatus reads .sdd/meta.json (if present) and evaluates its compatibility fields against the calling binary's version and schema version. Pure read; no side effects.
When meta.json is absent the result reports MetaExists = false and Compatible = true — an uninitialised graph is the init command's responsibility, not the write gate's.
func (*Finder) Show ¶
Show resolves the entries named in q and returns groups with upstream and downstream chains. The heavy lifting (tree traversal, dedup, depth limiting) is delegated to model.Graph.BuildShowTree.
func (*Finder) SkillStatus ¶ added in v0.2.0
func (f *Finder) SkillStatus(ctx context.Context, q query.SkillStatusQuery) (*query.SkillStatusResult, error)
SkillStatus loads the embedded skill bundle for the query's target, then walks each entry to compare its embedded content against the file on disk. Classification happens in model.ComputeSkillStatus — the finder only supplies inputs.
func (*Finder) Status ¶
func (f *Finder) Status(q query.StatusQuery) (*query.StatusResult, error)
Status assembles the per-section snapshots used by the status view. Pure read — every section comes from in-memory graph filters.
func (*Finder) SyncStatus ¶ added in v0.3.0
func (f *Finder) SyncStatus(ctx context.Context, q query.SyncStatusQuery) (model.SyncStatus, error)
SyncStatus processes a SyncStatusQuery into a SyncStatus. Cooldown is read from the finder's Config; callers supply SDDDir for the last-fetch marker. The finder touches last-fetch on every successful attempt and on terminal failure states (no remote, no upstream, fetch failure) so transient environment issues don't re-poll on every command.
func (*Finder) WIPList ¶
func (f *Finder) WIPList(q query.WIPListQuery) (*query.WIPListResult, error)
WIPList loads every active WIP marker from the wip/ subdirectory of q.GraphDir. Returns an empty result (not an error) when no markers exist.
type GitSyncer ¶ added in v0.3.0
type GitSyncer interface {
// InRepo reports whether the process is inside a git working tree.
InRepo(ctx context.Context) bool
// HasRemote reports whether the repository has at least one remote configured.
HasRemote(ctx context.Context) bool
// UpstreamRef returns the upstream ref name for the current branch
// (e.g. "origin/main"). Empty string + nil error means the branch has
// no upstream configured.
UpstreamRef(ctx context.Context) (string, error)
// Fetch runs `git fetch` with no args. A non-nil error means the fetch
// attempt failed (network, auth, etc.).
Fetch(ctx context.Context) error
// CountCommits counts commits in rangeSpec whose messages match the
// given grep pattern (ERE). rangeSpec is a git log range such as
// "HEAD..@{u}" or "@{u}..HEAD".
CountCommits(ctx context.Context, rangeSpec, grepPattern string) (int, error)
// MergeTreePredict simulates a three-way merge in memory and returns
// the list of paths that would conflict. An empty slice means clean.
// The merge base is computed by git internally from (ourRef, theirRef)
// — this keeps the surface compatible with git 2.38 (the explicit
// --merge-base flag was added in 2.40).
MergeTreePredict(ctx context.Context, ourRef, theirRef string) ([]string, error)
}
GitSyncer is the git surface consumed by the sync finder. Production shells out via exec.Command; tests inject stubs. Methods return errors only for unexpected failures — missing-repo / missing-remote / missing-upstream are expressed through the dedicated boolean / string predicates (InRepo, HasRemote, UpstreamRef) so the finder can report distinct SyncStates rather than collapsing everything into errors.
Source Files