natsukium/gloss
Watch
1
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

Discover pages and their option prefixes instead of listing them by hand #2

New issue
Open
opened 2026-09-12 02:38:50 +09:00 by natsukium · 1 comment
natsukium commented 2026-09-12 02:38:50 +09:00
Owner
Copy link

documents.nix names every page by hand, and each entry hand-writes the
prefixes whose options it wants indexed and the packages it wants positions
for. The header nav is a flat list of every page.

That is fine for five documents and unusable for a repository with hundreds of
.nix files: the list becomes a second source of truth that drifts from the
tree, and a flat nav of 218 entries is not navigable.

Three separate things are needed:

  • A page list derived from the tree — a glob, or the set of files an evaluation
    actually touched.
  • prefixes derived from what the file itself declares or defines. The
    evaluator already knows: option.declarationPositions says which file
    declares an option and definitionsWithLocations says which file defines it,
    so the set of options a page cares about is computable rather than written
    down. packages cannot be derived this way — pkgs is not enumerable — so
    it stays declared.
  • A hierarchical index that follows the directory tree, rather than every page
    in the header.
`documents.nix` names every page by hand, and each entry hand-writes the `prefixes` whose options it wants indexed and the `packages` it wants positions for. The header `nav` is a flat list of every page. That is fine for five documents and unusable for a repository with hundreds of `.nix` files: the list becomes a second source of truth that drifts from the tree, and a flat nav of 218 entries is not navigable. Three separate things are needed: - A page list derived from the tree — a glob, or the set of files an evaluation actually touched. - `prefixes` derived from what the file itself declares or defines. The evaluator already knows: `option.declarationPositions` says which file declares an option and `definitionsWithLocations` says which file defines it, so the set of options a page cares about is computable rather than written down. `packages` cannot be derived this way — `pkgs` is not enumerable — so it stays declared. - A hierarchical index that follows the directory tree, rather than every page in the header.
natsukium commented 2026-09-12 13:06:17 +09:00
Author
Owner
Copy link

Tested the evaluator route for deriving prefixes and it does not work: walking the whole options tree while touching only files/declarations is not total on aarch64-darwin. tryEval around every node still dies with attribute 'google-chrome-beta' missing (home-manager's chromium module), because a missing attribute is not caught by tryEval. And there is no API for the list of modules an evaluation collected.

Revised plan, in three parts:

  1. Page list from a glob over the tree, with a hierarchical nav that follows the directory structure.
  2. prefixes derived statically. extract.py already resolves every identifier a file touches to a config.* / options.* path, so the set of those paths is the file's prefixes. Total, cheap, and independent of the evaluator. packages stays declared.
  3. Membership of a file in an evaluation (needed for #3/#4) comes from evaluating the derived prefixes and checking whether the file appears in the resulting files/declarations.

documents.nix then names evaluations, not pages.

Tested the evaluator route for deriving `prefixes` and it does not work: walking the whole `options` tree while touching only `files`/`declarations` is not total on aarch64-darwin. `tryEval` around every node still dies with `attribute 'google-chrome-beta' missing` (home-manager's chromium module), because a missing attribute is not caught by `tryEval`. And there is no API for the list of modules an evaluation collected. Revised plan, in three parts: 1. Page list from a glob over the tree, with a hierarchical nav that follows the directory structure. 2. `prefixes` derived statically. `extract.py` already resolves every identifier a file touches to a `config.*` / `options.*` path, so the set of those paths is the file's prefixes. Total, cheap, and independent of the evaluator. `packages` stays declared. 3. Membership of a file in an evaluation (needed for #3/#4) comes from evaluating the derived prefixes and checking whether the file appears in the resulting `files`/`declarations`. `documents.nix` then names evaluations, not pages.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
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/gloss#2
No description provided.