docs: freeze config discovery on ProjectDirs as it stands #149

Merged

natsukium merged 2 commits from docs/freeze-config-discovery-137 into main 2026-09-06 02:14:29 +09:00

Conversation 0 Commits 2 Files changed 3 +84 -27

natsukium commented 2026-09-06 02:06:38 +09:00

Owner

Copy link

Fixes #137.

Freezes felis's config discovery on ProjectDirs as it already behaves: the
reference and explanation docs now state the per-platform lookup path and the
reasoning behind keeping it, so the current behavior is a documented contract
rather than an accident of the dependency. The config suite's discovery and io
tests now also run on Windows, pinning the platform path the docs describe.

Doc cascade: docs/reference/config.md gains the resulting facts, and
docs/explanation/architecture/control-surfaces.md carries the decision record
(rationale, rejected alternatives, revisit trigger).

Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed
by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high

Deferred

• The new Windows-only test and the un-gated relative-path test compile only
  under the mingw cross shell or CI's Windows runner — nix develop .#windows
  was out of bounds for this run and ConPTY/Windows behavior never runs on this
  host; the code is plain std path handling reviewed by hand, and CI's Windows
  job is the real check.
• The Windows discovery test asserts the APPDATA env var as a proxy for the
  known-folder API that ProjectDirs actually queries — the test's own doc
  comment discloses this, and the reference prose describes the mechanism
  correctly as the known-folder API, so no doc states a falsehood. A tighter,
  non-env-var verification is hardening beyond #137's acceptance criteria.

Fixes #137. Freezes felis's config discovery on `ProjectDirs` as it already behaves: the reference and explanation docs now state the per-platform lookup path and the reasoning behind keeping it, so the current behavior is a documented contract rather than an accident of the dependency. The config suite's discovery and io tests now also run on Windows, pinning the platform path the docs describe. Doc cascade: `docs/reference/config.md` gains the resulting facts, and `docs/explanation/architecture/control-surfaces.md` carries the decision record (rationale, rejected alternatives, revisit trigger). Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high ## Deferred - The new Windows-only test and the un-gated relative-path test compile only under the mingw cross shell or CI's Windows runner — `nix develop .#windows` was out of bounds for this run and ConPTY/Windows behavior never runs on this host; the code is plain std path handling reviewed by hand, and CI's Windows job is the real check. - The Windows discovery test asserts the `APPDATA` env var as a proxy for the known-folder API that `ProjectDirs` actually queries — the test's own doc comment discloses this, and the reference prose describes the mechanism correctly as the known-folder API, so no doc states a falsehood. A tighter, non-env-var verification is hardening beyond #137's acceptance criteria.

natsukium added 2 commits 2026-09-06 02:06:38 +09:00

docs: freeze config discovery on ProjectDirs as it stands ... 0bd268ad93

The `config.toml` search paths become impossible to move once 1.0 ships,
so the choice between them had to be made now: felis keeps
`directories::ProjectDirs` as the sole resolver and overrides no
platform's answer.

Record the two rejected alternatives where a future reader will look for
them, because both read as obvious fixes to the table: flattening
`%APPDATA%\felis\config\config.toml` makes felis' config path the one
call in the tree that second-guesses the resolver the cache, runtime and
state slots still trust, and an XDG fallback on macOS buys a precedence
rule and a two-candidate `config path` for a platform v0.1.0 does not
gate, when `--config` already serves that user.

Refs #137

cli: run the config suite's discovery and io tests on Windows ... f98dd4a4cc

Three tests in the config suite were `cfg(unix)` for three unrelated
reasons, which left Windows without any check on the very paths the
reference table now freezes.

Discovery genuinely cannot be redirected on Windows, since the
known-folder API behind `%APPDATA%` reads no environment variable, so it
gains a twin that asserts the reported spelling of the frozen row and
never touches the file. The unreadable-file case drops `PermissionsExt`
for a directory at the selected path: that fails the read everywhere and
is not defeated by running as root, which the mode bits were. The
relative-selection case only needed `canonicalize` reduced to the
non-verbatim form a child's `current_dir` can echo back.

Refs #137

natsukium merged commit f98dd4a4cc into main 2026-09-06 02:14:29 +09:00

natsukium deleted branch docs/freeze-config-discovery-137 2026-09-06 02:14:29 +09:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!149

No description provided.