Module discovery 

Discovery: which files of the repository are declarative sources, and of which kind.

Nothing here walks .ai/ looking for interesting files. The repository declares its source classes in sources.yaml under the manifest’s knowledge section, each class a pathspec and a kind, and discovery enumerates exactly those. Two implementations of the enumeration exist: the version-control index, which the contract prescribes, and a filesystem walk with the same glob semantics for a checkout git cannot describe.

Why the declaration and not a walk

A walk of .ai/ would have to guess what a file is from where it sits, which makes the directory layout part of the contract and makes adding a file a change to the reader. Declaring the classes instead means a repository can add a kind — a pathspec and a kind name in sources.yaml, a schema under .ai/repo/knowledge/ — and this executable serves it without being rebuilt.

The two enumerations

VcsIndex asks git for the tracked files, which is the layer’s contract and the only mode DiscoveryKind declares: what is not tracked is not part of the layer. The one layer that sentence cannot describe is a layer none of which is tracked — a personal layer (ADR 0145), or one created a minute ago and not committed yet: its tracked set is empty by construction, so layer_is_untracked says so and the work tree is read. FileSystem walks the tree with the same glob semantics, for a checkout git cannot describe — a scratch fixture, a tree with no commits. The index records which one it used, so an answer can never be silently about a different file set than the caller expected.

use majordomus_cli::discovery::{DiscoveryKind, Sources};

let declaration = "\
version: 1
sources:
  - id: rules
    kind: rule
    discovery: vcs
    pathspec: ':(glob).ai/repo/rules/**/*.md'
    required: false
";
let sources = Sources::parse(std::path::Path::new("sources.yaml"), declaration).unwrap();
assert_eq!(sources.sources.len(), 1);
assert_eq!(sources.sources[0].kind, "rule");
assert_eq!(sources.sources[0].discovery, DiscoveryKind::Vcs);

Modules

glob

The :(glob) pathspec subset the repository’s sources.yaml is written in.

Structs

DiscoveredFile

A file discovered through a class, before it is read.

FileSystem

A walk of the work tree with :(glob) semantics: for a checkout that is not a git work tree, or when untracked files are wanted deliberately. Symlinks are never followed and the checkout-local half of the layer is never a source.

SourceClass

One class of sources.yaml.

Sources

sources.yaml, typed: the classes in declared order.

VcsIndex

The version-control index: tracked files only, as the contract prescribes. The index is read from git once per build (git ls-files, every tracked path) and each class’s :(glob) pathspec is matched in process with the same matcher the filesystem walk uses; one subprocess per repository instead of one per class.

Enums

DiscoveryKind

How a class enumerates its files; vcs is the only discovery the contract knows.

Constants

CONTEXT_KIND

The kind whose class the manifest’s context.documents names are reserved for.

GLOB_PREFIX

The prefix every pathspec carries: * never crosses a directory separator.

SOURCES_FILE

The file, under the knowledge section, that declares the source classes.

SOURCES_VERSION

The version: of sources.yaml this executable reads.

Traits

DiscoverySource

How the files matching a pathspec are enumerated. The trait exists because two enumerations are shipped and the caller chooses one explicitly.

Functions

discover

Run every class of sources through source, in declared class order, each class’s files sorted by path. A file two classes both match is kept under the first and reported.

layer_is_untracked

Whether git has never been given the layer under root: its manifest is on disk and the index holds no entry for it.