chore(build-codegen): Phase-9 gap closure — 6 missed env vars + Set-by column + per-crate rustdoc#301
Merged
Conversation
…ude_*! doc-comments Three surgical fixes to scripts/dev/build_codegen_audit.sh detection regexes uncovered by the Phase-9 gap-closure audit (post-PR #300): 1. _extract_env_var_names() now also matches: * (std::)?env::var_os("NAME") -- the absence-checking idiom used in uffs-core + uffs-mft for UFFS_CACHE_PROFILE, UFFS_REBUILD_CHILDREN_ALWAYS, UFFS_SKIP_ORPHANS. * const NAME: &str = "VAR"; -- const-name indirection. When the read site uses env::var(Self::FOO) (non-literal), the literal value lives only in the const declaration. Detection is gated to known env-var prefixes (UFFS_/RUST_/XDG_/CARGO_) to avoid flagging arbitrary string consts. Catches UFFS_HOT_TO_WARM_IDLE_SECS, UFFS_SEARCH_MAX_CONCURRENCY, UFFS_USN_REFRESH_INTERVAL_SECS. 2. count_includes() now skips doc-comment + block-comment lines using the same filter as _extract_env_var_names() and requires the macro to be invoked ("!("), not merely mentioned. Fixes the prior over-count of 2 -> 1 for crates/uffs-text/src/case_fold.rs (the doc-comment on line 27 was being counted as a use site alongside the real include_bytes!("upcase_default.bin") on line 28). Caveat documented inline: bare-local indirection (let foo = "UFFS_X"; env::var(foo);) is NOT detected. No such pattern exists in the workspace as of 2026-05-19. Result: workspace baseline corrected from 36 -> 42 distinct env-var names and from 2 -> 1 include_*! site. Per-crate counts updated across the policy doc + final report in subsequent commits on this branch. Refs #298.
… corrected defaults Gap-closure follow-up to PR #300 — addresses gaps A, E and stale-default corrections identified by the deep audit against playbook \u00a71013-1078 + plan \u00a70.2 item 5. Changes to docs/architecture/code-quality/build_codegen_policy.md: 1. \u00a73.5 env-var contract extended: * Documents the four detection shapes the audit script supports (env::var, env::var_os, env!/option_env!, const-name indirection). * Requires every \u00a75 row to carry the 'Set by' field listing the expected writer (Cargo / OS / operator / CI workflow / test harness / etc). 2. \u00a75 registry rewritten: * 6 new rows in \u00a75.4 (UFFS runtime knobs) for env vars the audit script missed pre-fix (commit 339a1be in this branch): - UFFS_CACHE_PROFILE (uffs-core + uffs-mft, env::var_os) - UFFS_HOT_TO_WARM_IDLE_SECS (uffs-daemon, const indirection) - UFFS_REBUILD_CHILDREN_ALWAYS (uffs-mft, env::var_os) - UFFS_SEARCH_MAX_CONCURRENCY (uffs-daemon, const indirection) - UFFS_SKIP_ORPHANS (uffs-mft, env::var_os) - UFFS_USN_REFRESH_INTERVAL_SECS (uffs-daemon, const indirection) * New 'Set by' column on all 7 sub-tables. * Corrected stale defaults: UFFS_PARKED_TO_COLD_IDLE_SECS 300 -> 86400 (24 h), UFFS_WARM_TO_PARKED_IDLE_SECS 60 -> 300 (5 min) - matching the actual pub(crate) const values in crates/uffs-daemon/src/cache/policy.rs. * Source-header SHA bumped to aeb9807 (post-#300). * Footer total: 36 -> 42 distinct env-var names; sub-counts rewritten (\u00a75.4 grew 9 -> 15). 3. \u00a72 lint-posture surface count updated: 36 -> 42. 4. \u00a710 decisions log: * 9-gap row added describing the 5-gap delta + 2-default correction. * 9b/9c/9d/9e/9f/9g rows retro-tagged 'this PR' -> '#300' (they all merged in PR #300; only the new 9-gap row carries the 'this PR' marker for the current branch). Rule-1 adherence: zero suppression hacks; doc-only. Rule-3 adherence: no source code or public API change. Refs #298.
Phase-9 gap closure (refs #298): document the two CARGO_CFG_* env vars the script reads, plus a consolidated files/tools/platform inputs- explicit block, per plan acceptance criterion 3 + playbook section 1049-1056. Doc-only. Zero behavior change.
Phase-9 gap-closure (refs #298) -- per-crate # Environment sections cross-linked to build_codegen_policy.md section 5. Sections (one per affected crate, content tailored to env vars that crate actually reads): * uffs-cli/src/main.rs (5 runtime vars; build-time vars cross-ref to build.rs section). * uffs-client/src/lib.rs (5 vars incl XDG_RUNTIME_DIR + UFFS_CLIENT_*). * uffs-core/src/lib.rs (1 var -- UFFS_CACHE_PROFILE, 8 read sites). * uffs-daemon/src/lib.rs (10 vars incl 4 const-indirect cache-tier knobs + UFFS_SEARCH_MAX_CONCURRENCY). * uffs-mcp/src/lib.rs (4 vars incl UFFS_MCP_AUTH_TOKEN). * uffs-mft/src/lib.rs (12 vars incl 3 env::var_os dev knobs). * uffs-security/src/lib.rs (2 vars -- UFFS_DEV, USERNAME). Each section: 4-column Markdown table (Env var / Type / Default / Notes), INTERNAL / STANDARD / CARGO semver class tag per row, inline call-out for env::var_os shape and for const-indirect read paths. Doc-only. Zero behavior change. cargo check on all 7 crates green. cargo fmt applied to satisfy line-wrap. Refs #298.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #300 (Phase-9 build/codegen/env-var policy). Deep audit
against playbook §1013-1078 and
progress.txtPhase 9 plan §0.2 + §1them with a doc-only changeset plus one audit-script bug fix; no
runtime behavior changes.
§5 Set bycolumn required by plan §0.2 item 5 was missingbuild_codegen_policy.md §5.# Environmentrustdoc sections (plan §1 row 9f deliverable) were deferreduffs-cli/main.rs,uffs-client/lib.rs,uffs-core/lib.rs,uffs-daemon/lib.rs,uffs-mcp/lib.rs,uffs-mft/lib.rs,uffs-security/lib.rs.crates/uffs-cli/build.rsrustdoc missing the env-var listing required by plan §2 criterion 3 ("build inputs explicit")# Environment+# Inputs / tools / platformsections.count_includesover-countedinclude_*!use sites by 1 (doc-comment on line 27 ofcrates/uffs-text/src/case_fold.rswas being counted alongside the realinclude_bytes!)count_includes()to filter doc-comment + block-comment lines and require!(invocation._extract_env_var_namesmissedenv::var_os(\"NAME\")+ const-name indirection patterns, causing 6 env vars to be absent from §5Quantitative delta
include_*!use sites§5.4 UFFS runtime knobsentries6 newly-detected env vars
All landed in
§5.4 UFFS runtime knobs:UFFS_CACHE_PROFILEenv::var_os(\"…\").is_some()UFFS_HOT_TO_WARM_IDLE_SECSHOT_TO_WARM_IDLE_ENV)UFFS_REBUILD_CHILDREN_ALWAYSenv::var_os(\"…\").is_some()UFFS_SEARCH_MAX_CONCURRENCYSelf::SEARCH_CONCURRENCY_ENV)UFFS_SKIP_ORPHANSenv::var_os(\"…\").is_some()UFFS_USN_REFRESH_INTERVAL_SECSUSN_REFRESH_INTERVAL_ENV)Stale-default corrections (during §5.4 rewrite)
pub(crate) const)UFFS_PARKED_TO_COLD_IDLE_SECSUFFS_WARM_TO_PARKED_IDLE_SECSCommits (atomic, 4 total)
fix(audit): detect env::var_os + const-name indirection + filter include_*! doc-commentsscripts/dev/build_codegen_audit.sh.let foo = \"UFFS_X\"; env::var(foo);) is NOT detected, but no such pattern exists in the workspace as of 2026-05-19.docs(build-codegen-policy): add 6 missed env vars + 'Set by' column + corrected defaults§3.5env-var contract extended to document four detection shapes + require "Set by" field.§5rewritten with new column, 6 new rows, corrected defaults.§10decisions log: 9-gap row added; retro-tagged 9b-9g rows with PR docs(architecture): add build_codegen_policy.md + CONTRIBUTING cross-link (refs #298) #300.docs(cli): add Environment section to uffs-cli/build.rs rustdoc# Environment,# Inputs / tools / platform).docs(crates): add Environment rustdoc section to 7 crate rootsbuild_codegen_policy.md §5registry per playbook §1049-1056.Rule adherence
#[allow(rustdoc::*)], zero lint disables. Two real broken intra-doc-links (fs::daemon_socket_path→fs::set_file_permissions_owner_only,daemon_spawn::ElevationPolicy→ described in prose sincedaemon_spawnispub(crate)) fixed at root.\$UFFS_TEST_ENV_NEVER_SET_12345sentinel still correctly excluded by prod-only globs; verified post-fix.Verification
bash scripts/dev/build_codegen_audit.sh→ 42 distinct env-var names ✅cargo checkworkspace +RUSTDOCFLAGS=\"-D warnings\" cargo doc --no-deps --workspace✅Refs #298, follows #300.