docs(architecture): add build_codegen_policy.md + CONTRIBUTING cross-link (refs #298)#300
Merged
Merged
Conversation
…link (refs #298) Phase 9c+9d+9e+9f+9g closeout: workspace policy doc for build scripts, proc-macro crates, declarative macros, codegen binaries, and the environment-variable surface. Mirrors the structure established by `panic_policy.md` (5e), `allocation_policy.md` (6f), `trait_policy.md` (7g), and `dependency_policy.md` (8c). Doc contents: - \u00a71 The rule (one-liner + 4 class tables: B1-B3 build.rs / M1-M3 macros / C1-C2 codegen) - \u00a72 Lint posture (0 new clippy lints; positive contract via `build_codegen_audit.sh` + 4 existing `*-drift` gates) - \u00a73 Per-section contracts (build.rs / proc-macro / macro_rules / codegen / env-var) \u2014 the \u00a7988-mirror sub-contracts - \u00a74 Hygiene rules (6 rules covering no-new-build.rs / no-new-proc-macro / no-control-flow-hiding / no-new-codegen-without- drift-detector / no-new-env-var-without-registry / naming conventions) - \u00a75 Environment variable registry \u2014 36 distinct names across 7 scope categories (build-time / standard-runtime / logging / UFFS runtime / UFFS client / build-release / test-only) - \u00a76 Per-crate registry (build.rs / proc-macro / macro_rules / codegen tables) - \u00a77 Anti-patterns (8 rejected patterns) - \u00a78 Audit cadence (per-phase + per-introduction + annual) - \u00a79 Cross-references - \u00a710 Decisions log (8 entries 9a-9g) CONTRIBUTING.md edit: adds a new \u00a7"Build, codegen, and env-var policy" section between the existing \u00a7"Feature flag and dependency policy" and \u00a7"Docs map" sections. Cross-links to the new policy doc. Mirrors the 15-line summary shape of the 4 existing policy sections. Companion findings (local-only, gitignored): - docs/dev/baseline/2026-05-19/phase_9_build_audit_findings.md - docs/dev/baseline/2026-05-19/phase_9_macro_audit_findings.md - docs/dev/baseline/2026-05-19/phase_9_codegen_inventory.md Tracking issue: #298. Rule-1 adherence: zero `#[allow]` introductions; zero clippy lint changes; zero source code modifications. Doc-only PR. The single existing `#[allow(clippy::expect_used)]` in `crates/uffs-cli/build.rs` is documented in the new policy doc \u00a73.1 as the workspace-approved `panic_policy.md` \u00a71 exception for build-host failure modes. Rule-3 adherence: preserves behavior \u2014 no source code changed, no public API changed, no observable behavior changed.
This was referenced May 19, 2026
githubrobbi
added a commit
that referenced
this pull request
May 20, 2026
…y column + per-crate rustdoc (#301) * fix(audit): detect env::var_os + const-name indirection + filter include_*! 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. * docs(build-codegen-policy): add 6 missed env vars + 'Set by' column + 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. * docs(cli): add Environment section to uffs-cli/build.rs rustdoc 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. * docs(crates): add Environment rustdoc section to 7 crate roots 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
Phase 9c+9d+9e+9f+9g closeout — workspace policy doc for build scripts, proc-macro crates, declarative macros, codegen binaries, and the environment-variable surface. Mirrors the structure established by:
panic_policy.md(Phase 5e)allocation_policy.md(Phase 6f)trait_policy.md(Phase 7g)dependency_policy.md(Phase 8c)Tracking issue: #298.
Doc structure (10 sections, 383 LOC)
build_codegen_audit.sh+ 4 existing*-driftgatesCurrent posture documented (SHA
0433065c7, Phase 9 entry)build.rs(uffs-cli) \u2014 class B2 + B3 (MSVC-gated PE resource embedding +/DELAYLOADlinker args).macro_rules!declarations \u2014 all inuffs-mft, 5 \u00d7 M1 (binary-read helpers) + 1 \u00d7 M2+M3 (drive_letter_consts!).gen-hooks,gen-workflow,manifest-audit\u2014 all drift-detected) + 1 \u00d7 C2 (ci-pipeline\u2014 release orchestrator).CONTRIBUTING.md edit
Adds a new \u00a7"Build, codegen, and env-var policy" section (15 lines) between the existing \u00a7"Feature flag and dependency policy" and \u00a7"Docs map" sections. Cross-links to the new policy doc. Mirrors the 15-line summary shape of the 4 existing policy sections.
Companion findings (local-only, gitignored \u2014 not part of this PR)
docs/dev/baseline/2026-05-19/phase_9_build_audit_findings.md(9b verdict: PASS, no drift)docs/dev/baseline/2026-05-19/phase_9_macro_audit_findings.md(9d verdict: PASS, no drift; 1 refactor candidate deferred)docs/dev/baseline/2026-05-19/phase_9_codegen_inventory.md(9e verdict: PASS, no drift)Rule-1 adherence
Zero
#[allow]introductions; zero clippy lint changes; zero source code modifications. Doc-only PR. The single existing#[allow(clippy::expect_used)]incrates/uffs-cli/build.rsis documented in the new policy doc \u00a73.1 as the workspace-approvedpanic_policy.md\u00a71 exception for build-host failure modes (does not change in this PR).Rule-3 adherence
Preserves behavior \u2014 no source code changed, no public API changed, no observable behavior changed.
Out-of-scope (deferred to follow-ups)
# Environmentrustdoc sections for the 6 crates that read env vars (uffs-cli,uffs-client,uffs-daemon,uffs-mcp,uffs-mft,uffs-security). Phase 8 split the same pattern across two PRs (docs(features): document feature contracts per playbook §988 (Phase 8b, refs #195) #293 rustdoc + docs(architecture): add dependency_policy.md and CONTRIBUTING.md cross-link (Phase 8c, refs #195) #294 policy doc); this PR is the policy-doc PR. The rustdoc additions can land as a follow-up; the registry in \u00a75 is already the canonical source-of-truth.read_uN!macros \u2192Cursorstruct refactor \u2014 documented as a deferred Phase-13 candidate inphase_9_macro_audit_findings.md\u00a75.1.Closes #298 only at Phase-9 closeout (this PR is 9c-9g; final report + issue close land in 9h).