Documentation
¶
Overview ¶
Package config resolves where the library lives and how the tool behaves.
Override order, highest first: the --db flag, FILIATION_DB, the config file, then a per-user application data directory (ADR-006). One library per user, not one per directory — a database in the working directory produces a scattering of half-built graphs, and the whole product thesis is a library that accumulates over years.
Because the default location differs per OS, the CLI prints the path on first run. Without that, users cannot find their own data.
Configuration is resolved, never prompted for. config has to work from a test, an MCP server and a web handler, none of which have a terminal — so it reports (FirstRun, Warnings) and the front door does the asking. Save is how an answer given once survives to the next run.
A leaf package, with one exception: it imports internal/errs, so that a bad config file arrives at the CLI as errs.ErrInvalidConfig rather than as an opaque string. errs imports nothing itself, so this cannot create a cycle, and without the exception the sentinel package cannot do its job.
Index ¶
Constants ¶
const ( // DefaultMaxNodes is the primary control on how large a graph may grow. // 500 is large enough to be a map of a literature and small enough to // finish in well under a minute, and it costs 5 credits of a 1,000/day // allowance (D11). Depth is only a secondary guard: at the measured 70-100 // references per STEM paper, depth 2 alone is ~5,000 nodes, so this number // is what actually stops an expansion. DefaultMaxNodes = 500 // DefaultMaxDepth stops a run that would otherwise wander a long way from // the seed before the node budget bites. It is rarely the binding limit. DefaultMaxDepth = 3 // DefaultMaxRefsPerWork caps how many candidates one work may contribute to // the frontier. A review article citing 800 papers would otherwise consume // an entire budget by itself. It does not cap edges: every reference is // recorded, because they arrive free inside the response and throwing them // away would falsify the graph. DefaultMaxRefsPerWork = 100 // FileName is the config file, and DBName the library, both inside the // directory chosen by ADR-006. FileName = "filiation.toml" DBName = "library.db" )
Defaults. Every one of these is a number the user may override; none of them is a limit of the tool.
const EnvDB = "FILIATION_DB"
EnvDB overrides the library path from the environment. It sits between the --db flag and the config file.
Variables ¶
This section is empty.
Functions ¶
func DefaultCacheDir ¶
DefaultCacheDir is where the HTTP response cache lives unless told otherwise.
It is deliberately not beside the library. The cache is regenerable and the library is not, so it goes where each OS expects disposable data — %LocalAppData% on Windows, ~/Library/Caches on macOS, $XDG_CACHE_HOME or ~/.cache on Linux — where cleanup tools and backup exclusions already treat it as such.
func DefaultDir ¶
DefaultDir is the per-user directory holding the config file and, unless told otherwise, the library beside it.
os.UserConfigDir is stdlib and already correct on all three targets — %AppData% on Windows, ~/Library/Application Support on macOS, and $XDG_CONFIG_HOME or ~/.config on Linux — so the adrg/xdg dependency suggested by ADR-006 is not taken. One library per user, not one per directory: a database in the working directory produces a scattering of half-built graphs, and the product thesis is a library that accumulates over years.
Types ¶
type Config ¶
type Config struct {
// DBPath is absolute. Everything downstream may open it without further
// cleaning.
DBPath string
// ContactEmail is sent to OpenAlex as mailto. It is optional: the spikes
// measured byte-identical rate-limit headers with and without it (D11), so
// requiring it would punish the user for a politeness that buys them
// nothing. Absent, Warnings says so once and the tool runs.
ContactEmail string
MaxNodes int
MaxDepth int
MaxRefsPerWork int
// ConfigPath is where the file was looked for, whether or not it existed.
// The CLI needs it to tell the user which file to edit.
ConfigPath string
// FirstRun reports that no config file was found. The CLI uses it to offer
// a choice of library location and to print where the library lives —
// without that, users cannot find their own data, because the default
// differs on every OS (ADR-006).
FirstRun bool
}
Config is the resolved configuration: what the tool will actually do, after the flag, the environment, the file and the defaults have been reconciled.
func Load ¶
Load resolves configuration from, highest priority first: the --db flag, the FILIATION_DB environment variable, the config file, then the defaults (ADR-006).
Precedence is applied per field, not per source. A config file that sets only max_nodes keeps that value even when --db is also passed.
A missing config file is the normal case on a first run and is not an error. A malformed one is: falling back to defaults would let a typo in max_nodes silently expand a graph nobody asked for.
func (*Config) Save ¶
Save writes the config file, creating its directory if needed.
It is how a location chosen on first run survives to the second. Choosing is not this package's job: config never prompts, because it has to work where there is no terminal. The front door asks; this records the answer.
type Options ¶
type Options struct {
// DBFlag is the value of --db, empty when the flag was not passed. It wins
// over every other source.
DBFlag string
// Dir is the directory holding the config file. Empty means the per-user
// default from DefaultDir.
Dir string
}
Options are the inputs to Load that do not come from the config file.
Both fields exist mainly so tests can run without reading or writing the real user configuration directory, which ADR-006 names as the cost of defaulting to a per-user location.
Source Files