From 3e87282b2194cd60dfb514b8c6aae9fe05788f70 Mon Sep 17 00:00:00 2001 From: Austin Schaefer Date: Thu, 17 Sep 2026 13:22:40 +0200 Subject: [PATCH] Move high-level docs into docs/, matching doubleo7's convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SPEC.md and ARCHITECTURE.md were sitting at the repo root alongside Cargo.toml/Makefile.toml/packages.d — moved both into docs/ (doubleo7 already does this for its own supplementary docs, so this matches an existing convention in the fleet rather than inventing a new one). Updated every doc-comment cross-reference across src/*.rs and Makefile.toml (23 references) to the new docs/SPEC.md / docs/ ARCHITECTURE.md paths. The two files' own cross-references to each other didn't need changing — they're still same-directory relative references. Also updated the project reference memory pointing at ARCHITECTURE.md's location, so it doesn't go stale pointing at a path that no longer exists. Co-Authored-By: Claude Sonnet 5 --- Makefile.toml | 2 +- ARCHITECTURE.md => docs/ARCHITECTURE.md | 0 SPEC.md => docs/SPEC.md | 0 src/builder.rs | 6 +++--- src/config.rs | 8 ++++---- src/hash.rs | 2 +- src/main.rs | 6 +++--- src/pipeline.rs | 4 ++-- src/publisher.rs | 2 +- src/sanity.rs | 4 ++-- src/state.rs | 4 ++-- src/test_support.rs | 2 +- src/verifier.rs | 6 +++--- 13 files changed, 23 insertions(+), 23 deletions(-) rename ARCHITECTURE.md => docs/ARCHITECTURE.md (100%) rename SPEC.md => docs/SPEC.md (100%) diff --git a/Makefile.toml b/Makefile.toml index bd75029..a5b2556 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -37,7 +37,7 @@ args = ["test"] # orchestration too (hence its own low number) — its one pure decision # function (decide_tier_action) is unit tested and should stay visible in # this report; excluding the whole file would hide that signal along with -# the untested parts. See ARCHITECTURE.md > "separate pure decision logic +# the untested parts. See docs/ARCHITECTURE.md > "separate pure decision logic # from I/O." [tasks.coverage-report] command = "cargo" diff --git a/ARCHITECTURE.md b/docs/ARCHITECTURE.md similarity index 100% rename from ARCHITECTURE.md rename to docs/ARCHITECTURE.md diff --git a/SPEC.md b/docs/SPEC.md similarity index 100% rename from SPEC.md rename to docs/SPEC.md diff --git a/src/builder.rs b/src/builder.rs index ff87c26..8ce0021 100644 --- a/src/builder.rs +++ b/src/builder.rs @@ -36,7 +36,7 @@ pub struct BuildResult { /// artifact, then runs `makepkg` in `build_dir`. /// /// Deliberately one fixed "prebuilt binary" shape, not a templating engine -/// — see SPEC.md > Scaling > Template reuse. Covers the two shapes the two +/// — see docs/SPEC.md > Scaling > Template reuse. Covers the two shapes the two /// currently-tracked packages actually need: a bare-binary download /// (scaleway-cli) and a tarball containing a same-named directory (uv). /// Extend when a third real shape shows up rather than guessing at @@ -71,7 +71,7 @@ pub fn build(req: &BuildRequest, build_dir: &Path) -> Result { } /// Builds the PKGBUILD text for `req`, validating every upstream-controlled -/// string first (see SPEC.md > Architecture > Builder: "strict validation +/// string first (see docs/SPEC.md > Architecture > Builder: "strict validation /// on any upstream-controlled string ... never unescaped interpolation"). /// Pure and side-effect-free so it's testable without invoking `makepkg`. fn generate_pkgbuild(req: &BuildRequest) -> Result { @@ -155,7 +155,7 @@ fn archive_stem(asset_name: &str) -> Option<&str> { /// `asset_name` (via `install_source`) and `binary_name` end up embedded /// so `${srcdir}`/`${pkgdir}` can expand. A single check covering both /// contexts is safer than trying to remember which fields land in which -/// quoting style. See SPEC.md > Architecture > Builder ("never unescaped +/// quoting style. See docs/SPEC.md > Architecture > Builder ("never unescaped /// interpolation"). fn validate_shell_safe(field: &str, value: &str) -> Result<()> { if value.contains(['\'', '\n', '$', '`', '\\']) { diff --git a/src/config.rs b/src/config.rs index e8c5874..9a61e95 100644 --- a/src/config.rs +++ b/src/config.rs @@ -16,7 +16,7 @@ struct PackageFile { pub struct Package { pub repo: String, /// Exact GitHub release asset name (still not a glob — see - /// SPEC.md > Architecture > Fetcher), optionally containing a + /// docs/SPEC.md > Architecture > Fetcher), optionally containing a /// `{version}` placeholder for projects whose asset names embed the /// version (e.g. `scaleway-cli_{version}_linux_amd64`). Substituted via /// `checker::version_from_tag` before matching. @@ -29,7 +29,7 @@ pub struct Package { /// the repo name). Defaults to the package name when omitted. pub binary_name: Option, /// Post-build correctness check (not a security control — see - /// SPEC.md > Verification trust tiers). Runs `command` against the + /// docs/SPEC.md > Verification trust tiers). Runs `command` against the /// freshly built binary and confirms `version_regex`'s capture group /// matches the version pkgwatch believes it just built. pub sanity_check: Option, @@ -53,7 +53,7 @@ pub struct SanityCheck { #[serde(tag = "method", rename_all = "kebab-case")] pub enum Verification { /// Tier 4: proves transport integrity only, not authorship. See - /// SPEC.md > Verification trust tiers. `checksum_asset_pattern` may + /// docs/SPEC.md > Verification trust tiers. `checksum_asset_pattern` may /// also contain a `{version}` placeholder, same as `asset_pattern`. SameOriginSha256 { checksum_asset_pattern: String }, /// Tier 2: GitHub build-provenance attestation, verified via `gh @@ -71,7 +71,7 @@ impl Verification { } /// Loads every `*.toml` file in `dir` (the `packages.d/` layout from -/// SPEC.md > Scaling to many packages), keyed by package name. +/// docs/SPEC.md > Scaling to many packages), keyed by package name. pub fn load_packages_dir(dir: &Path) -> Result> { let mut out = Vec::new(); for entry in std::fs::read_dir(dir).with_context(|| format!("reading {}", dir.display()))? { diff --git a/src/hash.rs b/src/hash.rs index 548a04c..854b99d 100644 --- a/src/hash.rs +++ b/src/hash.rs @@ -1,5 +1,5 @@ //! Two functions, shared by two real callers (`verifier`, `builder`) — -//! not a general-purpose utils dump. See ARCHITECTURE.md > "organize by +//! not a general-purpose utils dump. See docs/ARCHITECTURE.md > "organize by //! pipeline stage, not by layer" for why that distinction matters. use anyhow::{Context, Result}; diff --git a/src/main.rs b/src/main.rs index 6ccf360..300ac6b 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,6 +1,6 @@ //! Entry point: parses `argv` and dispatches to `pipeline`. Nothing here //! makes a network/subprocess call or contains a decision worth a test — -//! see ARCHITECTURE.md > "main is a dispatcher, not the program." +//! see docs/ARCHITECTURE.md > "main is a dispatcher, not the program." mod builder; mod checker; @@ -20,8 +20,8 @@ use anyhow::{Result, bail}; /// check -> fetch -> verify -> build -> sanity-check -> publish, for /// whatever is in packages.d/. Tier 1-3 passes auto-publish; tier 4-6 -/// passes queue for `pkgwatch review`. See SPEC.md > Architecture for what -/// each stage does, and ARCHITECTURE.md for how the code implementing it +/// passes queue for `pkgwatch review`. See docs/SPEC.md > Architecture for what +/// each stage does, and docs/ARCHITECTURE.md for how the code implementing it /// is organized. fn main() -> Result<()> { let args: Vec = std::env::args().skip(1).collect(); diff --git a/src/pipeline.rs b/src/pipeline.rs index 0fa0408..8d0b037 100644 --- a/src/pipeline.rs +++ b/src/pipeline.rs @@ -1,7 +1,7 @@ //! Orchestrates one run of check -> fetch -> verify -> build -> //! sanity-check -> publish across every configured package, plus the //! `review` subcommand for tier 4-6 approvals. The only module that calls -//! more than one other pipeline-stage module — see ARCHITECTURE.md > "main +//! more than one other pipeline-stage module — see docs/ARCHITECTURE.md > "main //! is a dispatcher, not the program" for why this lives here and not in //! `main.rs`. @@ -73,7 +73,7 @@ pub fn run_check() -> Result<()> { /// What to do about a package after verification, derived purely from the /// verification outcome and whether this exact version is already queued -/// for review — no I/O. See ARCHITECTURE.md > "separate pure decision +/// for review — no I/O. See docs/ARCHITECTURE.md > "separate pure decision /// logic from I/O." #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum TierAction { diff --git a/src/publisher.rs b/src/publisher.rs index 89b3c04..7bb7f79 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -8,7 +8,7 @@ use std::path::{Path, PathBuf}; use std::process::Command; /// Pacman's system-wide config — hardcoded like the rest of this tool's -/// Arch/Manjaro-specific assumptions (see SPEC.md > Scope). +/// Arch/Manjaro-specific assumptions (see docs/SPEC.md > Scope). const PACMAN_CONF: &str = "/etc/pacman.conf"; /// Copies the built package into `repo_dir` and runs `repo-add` against diff --git a/src/sanity.rs b/src/sanity.rs index eab4f7a..b56efda 100644 --- a/src/sanity.rs +++ b/src/sanity.rs @@ -1,6 +1,6 @@ //! Post-build correctness check: runs the freshly built binary and //! confirms it reports the version pkgwatch believes it just built. Not a -//! security control — see SPEC.md > Verification trust tiers. +//! security control — see docs/SPEC.md > Verification trust tiers. use crate::config::SanityCheck; use anyhow::{Context, Result, bail}; @@ -14,7 +14,7 @@ use std::process::Command; /// whatever's already on the system. Confirms `check.version_regex`'s /// capture group matches `expected_version`. /// -/// Correctness check only, not a security control — see SPEC.md > +/// Correctness check only, not a security control — see docs/SPEC.md > /// Verification trust tiers. Catches checker bugs and mangled/wrong-asset /// downloads, not malicious releases. pub fn run(check: &SanityCheck, pkg_bin_dir: &Path, expected_version: &str) -> Result<()> { diff --git a/src/state.rs b/src/state.rs index cdfe7b3..70dbbb2 100644 --- a/src/state.rs +++ b/src/state.rs @@ -8,7 +8,7 @@ use std::path::Path; /// Last-known-published version per package, so re-runs don't re-flag a /// version already handled. Deliberately just one file per package for /// now — this is where a real review-queue persistence layer plugs in -/// later (see SPEC.md > Architecture > Reviewer queue). +/// later (see docs/SPEC.md > Architecture > Reviewer queue). pub fn load_last_version(state_dir: &Path, name: &str) -> Option { std::fs::read_to_string(state_dir.join(format!("{name}.version"))) .ok() @@ -22,7 +22,7 @@ pub fn save_last_version(state_dir: &Path, name: &str, version: &str) -> Result< } /// Tag currently awaiting human review for a tier 4-6 package (see -/// SPEC.md > Architecture > Reviewer queue), if any. Separate from +/// docs/SPEC.md > Architecture > Reviewer queue), if any. Separate from /// `load_last_version`/`save_last_version`: approving a review doesn't /// mean future versions auto-publish, so the two must be tracked /// independently. diff --git a/src/test_support.rs b/src/test_support.rs index 4ffaa5f..49b701a 100644 --- a/src/test_support.rs +++ b/src/test_support.rs @@ -1,6 +1,6 @@ //! Test-only fixture helpers shared across modules' `#[cfg(test)]` code //! (`publisher`, `sanity`) — not production code, and not built outside -//! `cargo test`. See ARCHITECTURE.md > "organize by pipeline stage, not +//! `cargo test`. See docs/ARCHITECTURE.md > "organize by pipeline stage, not //! by layer": this exists to remove one specific piece of duplication //! (two near-identical copies of "write an executable shell script"), not //! as a general test-utils dump. diff --git a/src/verifier.rs b/src/verifier.rs index 85f7168..7ffa4d9 100644 --- a/src/verifier.rs +++ b/src/verifier.rs @@ -1,7 +1,7 @@ //! Runs the trust-tier-specific check declared for a package against a //! downloaded artifact, and reports a pass/fail plus the tier it implies. //! The only module that knows what each `Verification::method` actually -//! proves — see SPEC.md > Verification trust tiers. +//! proves — see docs/SPEC.md > Verification trust tiers. use crate::checker::version_from_tag; use crate::config::Verification; @@ -19,7 +19,7 @@ pub struct VerificationResult { } /// Runs the verification method declared for a package against a -/// downloaded artifact. See SPEC.md > Verification trust tiers for what +/// downloaded artifact. See docs/SPEC.md > Verification trust tiers for what /// each tier does and does not prove. pub fn verify( client: &reqwest::blocking::Client, @@ -59,7 +59,7 @@ pub fn verify( passed, justification: if passed { "same-origin sha256 matched — proves transport integrity only, \ - not authorship (see tier 4 in SPEC.md)" + not authorship (see tier 4 in docs/SPEC.md)" .into() } else { format!("sha256 mismatch: expected {expected}, got {actual}")