claims

Documentation

Overview

Package claims extracts the checkable assertions a document makes about its own repository.

A skill body naming `make verify` or `bw sync` claims those commands exist. Nothing checks it: `lint` covers links, and reachability is a separate question, so commands are the uncovered half.

The environment boundary, which is the whole reason this package is small

Finding a command-shaped claim in a body is a pure text function and lives here. **Resolving one to an executable is environment-dependent and does not.** Link resolution can be answered from the tree; command resolution depends on `$PATH`, on what is installed, and on the shell — so a kernel that answered it would be answering differently on every machine, and a caller could not tell a missing command from a missing toolchain.

Evidence out, policy to the caller: the same boundary `skilllens` draws. This package imports nothing outside the standard library and `TestImportsNothing` says so, because a boundary with no check is a comment.

Index

• func Commands(spans []string) []string

Functions

func Commands

func Commands(spans []string) []string

Commands reports the shell commands a document claims its repository supports.

Requires: spans are inline code-span contents, as markdown.Doc.CodeSpans collects them. Passing arbitrary strings is not an error and will simply find fewer. Ensures: deduplicated and sorted, so two runs over one document agree and a caller can diff two documents' claims. Empty rather than nil when nothing qualifies. Pure — no filesystem, no `$PATH`, no execution.

A span qualifies when it contains whitespace and its first token looks like an executable name. The whitespace requirement is what excludes the large majority of code spans, which are identifiers, filenames, and flags quoted inline.

**Both error directions are real and the choice between them is deliberate.** `make verify` and `./scripts/build.sh --fast` are found. Not found: `SKILL.md` and `go` (no arguments), `foo.Bar()` (not an executable name), `x = 1` (an expression), `var Doc struct` (a declaration — see hasUpper), and `git push origin HEAD` (a real command, lost to the same rule). What still slips through is a code span holding lowercase prose — `the make verify step` — which reports a command named "the".

A missed command is a check that never runs, silently; a false one is a warning naming something obviously wrong, which a reader discards in a second. The heuristic errs toward finding fewer, and the consumer's finding is advisory for that reason.