From c46563845cdd9c931bb263c93b3759a87cb0f043 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 29 Sep 2026 17:44:06 +0200 Subject: [PATCH] build: add reproducible release packaging --- .gitignore | 1 + CHANGELOG.md | 22 ++++++++++++ CODE_OF_CONDUCT.md | 15 ++++++++ CONTRIBUTING.md | 22 ++++++++++++ Cargo.toml | 6 ++++ Jenkinsfile | 16 ++++++--- README.md | 2 ++ SECURITY.md | 22 ++++++++++++ docs/README.md | 2 ++ docs/dependencies.md | 10 +++--- docs/releasing.md | 33 +++++++++++++++++ scripts/package-release.sh | 72 ++++++++++++++++++++++++++++++++++++++ tasks.md | 2 +- 13 files changed, 215 insertions(+), 10 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 docs/releasing.md create mode 100755 scripts/package-release.sh diff --git a/.gitignore b/.gitignore index 6963cc4..3bac384 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,7 @@ target/ # Added by cargo /target +/dist/ # Local implementation journal (intentionally not committed) /recap.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..fd3d2fc --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,22 @@ +# Changelog + +All notable changes to John Slop are recorded here. The format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases use +[Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.1.0] - 2026-09-29 + +### Added + +- Local, explainable heuristic analysis with bounded evidence confidence. +- Layered embedded, user, named, explicit, and CLI configuration. +- File, directory, ZIP, office-container, and stdin input adapters with limits. +- Human, graphical Miette, concise, and versioned JSON detector output. +- Conservative Unicode-to-ASCII formatter with check, diff, and atomic write. +- Stdio LSP replacement diagnostics and versioned quick fixes. +- Runnable examples, reviewed fixtures, fuzz targets, benchmarks, and CI gates. + +[Unreleased]: https://git.dandaedre.com/idle-org/john_slop/compare/v0.1.0...HEAD +[0.1.0]: https://git.dandaedre.com/idle-org/john_slop/releases/tag/v0.1.0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..68b6aa3 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,15 @@ +# Code of Conduct + +John Slop uses the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). + +Be respectful, specific, and evidence-led. Harassment, discriminatory language, +personal attacks, doxxing, sexualized conduct, and sustained disruption are not +acceptable in project spaces. Maintainers may edit, remove, or reject comments, +commits, issues, and other contributions that violate these expectations, and +may temporarily or permanently restrict participation. + +Report conduct concerns privately to the repository owner through the hosting +service profile. Reports will be reviewed promptly and handled with discretion; +the maintainer will disclose information only when necessary to investigate or +protect participants. This project does not tolerate retaliation against a +reporter acting in good faith. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fefedd3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,22 @@ +# Contributing + +Contributions should preserve John Slop's explainable, local-first product +boundary. Findings must describe observable signals without asserting AI +authorship, model identity, or personal characteristics. + +1. Open an issue for behavior or public-contract changes before investing in a + large patch. +2. Create a focused branch and add tests at the lowest useful layer. +3. Update user documentation, samples, and stable output snapshots together. +4. Run the quality, supply-chain, fuzz-smoke, or benchmark commands relevant to + the change as documented in [Development](docs/development.md). +5. Submit small conventional commits and explain rule false-positive tradeoffs. + +New heuristic rules require a stable lowercase kebab-case ID, conservative +positive and realistic near-miss fixtures, scopes, a rationale and help text, +and evaluation-corpus review. Default weights or thresholds require the +documented sign-off process in [Evaluation](docs/evaluation.md). + +By participating, contributors agree to follow the +[Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities through +[SECURITY.md](SECURITY.md), not a public issue. diff --git a/Cargo.toml b/Cargo.toml index b8ae146..b2149df 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -50,3 +50,9 @@ tower = { version = "0.5.3", default-features = false, features = ["util"] } [[bench]] name = "core" harness = false + +[profile.release] +codegen-units = 1 +lto = "thin" +panic = "abort" +strip = "symbols" diff --git a/Jenkinsfile b/Jenkinsfile index 0c934d0..5351246 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -11,6 +11,7 @@ pipeline { TARPAULIN_VERSION = '0.37.4' CARGO_AUDIT_VERSION = '0.22.2' CARGO_DENY_VERSION = '0.20.2' + CARGO_CYCLONEDX_VERSION = '0.5.9' } stages { @@ -72,6 +73,11 @@ pipeline { if [ "${INSTALLED_DENY}" != "cargo-deny ${CARGO_DENY_VERSION}" ]; then cargo install cargo-deny --locked --version "${CARGO_DENY_VERSION}" fi + + INSTALLED_CYCLONEDX="$(cargo cyclonedx --version 2>/dev/null || true)" + if [ "${INSTALLED_CYCLONEDX}" != "cargo-cyclonedx-cyclonedx ${CARGO_CYCLONEDX_VERSION}" ]; then + cargo install cargo-cyclonedx --locked --version "${CARGO_CYCLONEDX_VERSION}" + fi ''' } } @@ -216,10 +222,8 @@ pipeline { echo "Building John Slop release binaries..." - cargo build \ - --locked \ - --release \ - --all-features + VERSION="$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -n 1)" + scripts/package-release.sh "${VERSION}" echo echo "Release build completed." @@ -227,7 +231,9 @@ pipeline { ls -lh \ target/release/john-slop \ target/release/john-slop-fmt \ - target/release/john-slop-lsp + target/release/john-slop-lsp \ + dist/*.tar.gz \ + dist/*.sha256 ''' } } diff --git a/README.md b/README.md index defc044..bb6d4ad 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,8 @@ untrusted inputs, but John Slop is not a sandbox or malware scanner. - [Performance benchmarks](docs/benchmarks.md) - [Dependency and binary review](docs/dependencies.md) - [Design decision records](docs/decisions/) +- [Contributing](CONTRIBUTING.md), [security](SECURITY.md), and + [release procedure](docs/releasing.md) - [Background reading](docs/background.md) - [Ambiguous and invisible Unicode data sources](docs/unicode-confusables.md) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e579920 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,22 @@ +# Security policy + +The current supported line is `0.1.x`. Older snapshots and untagged forks do not +receive security fixes. + +Do not open a public issue for a suspected vulnerability. Use the repository +host's private security-advisory/reporting interface when available. Otherwise, +contact the repository owner privately through the hosting profile and request +a secure channel. Include the affected version/commit, operating system, impact, +minimal reproduction, and whether details have been shared elsewhere. Do not +include private documents processed by John Slop. + +The maintainer will acknowledge a report within seven days, assess scope and +severity, coordinate a fix and disclosure date when confirmed, and credit the +reporter if requested. This is a best-effort volunteer response target, not a +service-level guarantee. + +John Slop processes untrusted text and archives but is not a sandbox. Archive +limits and path validation reduce exposure; reports that bypass those limits, +cause unintended writes, leak document contents, corrupt protocol output, or +execute code are in scope. False-positive disagreements and requests for new +heuristics belong in the normal issue tracker. diff --git a/docs/README.md b/docs/README.md index d6c8950..21b9f42 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,6 +32,8 @@ the details needed to use, embed, and develop John Slop: evidence required before introducing parallelism. - [Dependency and binary review](dependencies.md) records feature choices, advisory/license policy, unsafe boundaries, and release-size measurements. +- [Release procedure](releasing.md) defines tagged reproducible packaging, + checksums, build provenance, and CycloneDX SBOM generation. - [Background](background.md) collects external context on observable signs of low-care AI-assisted writing. - [Ambiguous and invisible Unicode references](unicode-confusables.md) records diff --git a/docs/dependencies.md b/docs/dependencies.md index 7b09e44..b4edc5e 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -37,13 +37,15 @@ when dependencies change. ## Release size baseline -Before release-profile stripping, the all-feature Linux binaries measured: +Before release-profile stripping, the all-feature Linux binaries measured 6.21, +5.84, and 9.38 MB. The finalized thin-LTO, single-codegen-unit, +abort-on-panic, symbol-stripped profile measures: | Binary | Bytes | | --- | ---: | -| `john-slop` | 6,209,424 | -| `john-slop-fmt` | 5,835,264 | -| `john-slop-lsp` | 9,375,456 | +| `john-slop` | 3,542,544 | +| `john-slop-fmt` | 3,322,944 | +| `john-slop-lsp` | 4,756,688 | These are build-specific engineering measurements, not promised download sizes. The release procedure records final sizes and emits checksums and an SBOM beside diff --git a/docs/releasing.md b/docs/releasing.md new file mode 100644 index 0000000..b175808 --- /dev/null +++ b/docs/releasing.md @@ -0,0 +1,33 @@ +# Release procedure + +Releases are built from a clean, reviewed Linux checkout with the exact Rust +toolchain recorded in `BUILD-INFO`. + +1. Ensure `CHANGELOG.md`, `Cargo.toml`, `Cargo.lock`, documentation, and the + version badge agree; run every command in `docs/development.md`. +2. Run normal Criterion sampling and the fuzz targets appropriate to changes. +3. Commit the release preparation and create signed or annotated tag `vX.Y.Z`. +4. Check out that tag and install the pinned SBOM tool: + + ```sh + cargo install cargo-cyclonedx --locked --version 0.5.9 + scripts/package-release.sh X.Y.Z + ``` + +5. Run the packaging command a second time in a fresh checkout with the same + Rust version and compare the archive SHA-256 digest. +6. Inspect `BUILD-INFO`, `SHA256SUMS`, the CycloneDX 1.5 JSON SBOM, binary help, + archive contents, and recorded sizes. Sign the archive and checksum if a + signing identity is available. +7. Publish the archive, archive checksum, SBOM, changelog excerpt, and signature + together. Never publish an untagged or dirty build as a release. + +`SOURCE_DATE_EPOCH` comes from the tagged commit. The release profile uses thin +LTO, one codegen unit, abort-on-panic, and symbol stripping; GNU tar normalizes +entry order, timestamps, ownership, and gzip metadata. Reproducibility still +depends on the same target, Rust toolchain, linker, and system libraries, all of +which must be recorded or controlled by the release environment. + +The packaging smoke test produced byte-identical archives in two consecutive +runs on the Milestone 7 development host and validated both archive and internal +checksums plus the CycloneDX 1.5 schema markers. diff --git a/scripts/package-release.sh b/scripts/package-release.sh new file mode 100755 index 0000000..6c335cf --- /dev/null +++ b/scripts/package-release.sh @@ -0,0 +1,72 @@ +#!/bin/sh +set -eu + +repository_dir=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) +cd "$repository_dir" + +manifest_version=$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -n 1) +release_version=${1:-$manifest_version} +if [ "$release_version" != "$manifest_version" ]; then + echo "release version $release_version does not match Cargo.toml $manifest_version" >&2 + exit 2 +fi + +target_triple=$(rustc -vV | sed -n 's/^host: //p') +source_date_epoch=$(git log -1 --format=%ct) +export SOURCE_DATE_EPOCH="$source_date_epoch" + +bundle_name="john_slop-${release_version}-${target_triple}" +bundle_dir="dist/${bundle_name}" +archive_path="dist/${bundle_name}.tar.gz" + +if [ -e "$bundle_dir" ] || [ -e "$archive_path" ]; then + echo "release output already exists for $bundle_name; move it aside first" >&2 + exit 2 +fi + +mkdir -p "$bundle_dir" +cargo build --locked --release --all-features + +for binary in john-slop john-slop-fmt john-slop-lsp; do + cp "target/release/$binary" "$bundle_dir/$binary" +done +cp README.md CHANGELOG.md LICENSE "$bundle_dir/" + +cargo cyclonedx \ + --manifest-path Cargo.toml \ + --all-features \ + --format json \ + --spec-version 1.5 \ + --target "$target_triple" \ + --override-filename sbom.cdx +mv sbom.cdx.json "$bundle_dir/sbom.cdx.json" + +commit=$(git rev-parse HEAD) +rust_version=$(rustc --version) +cargo_version=$(cargo --version) +{ + echo "version=$release_version" + echo "commit=$commit" + echo "target=$target_triple" + echo "source_date_epoch=$source_date_epoch" + echo "rustc=$rust_version" + echo "cargo=$cargo_version" +} >"$bundle_dir/BUILD-INFO" + +( + cd "$bundle_dir" + sha256sum john-slop john-slop-fmt john-slop-lsp sbom.cdx.json >SHA256SUMS +) + +tar \ + --sort=name \ + --mtime="@$source_date_epoch" \ + --owner=0 \ + --group=0 \ + --numeric-owner \ + -cf - \ + -C dist \ + "$bundle_name" | gzip -n >"$archive_path" +sha256sum "$archive_path" >"${archive_path}.sha256" + +echo "$archive_path" diff --git a/tasks.md b/tasks.md index a6951e2..828cf5b 100644 --- a/tasks.md +++ b/tasks.md @@ -227,7 +227,7 @@ same config. Add parallelism only if measurement shows a benefit and output remains ordered. - [x] Review dependency features, licenses, advisories, unsafe code, and release binary size. Generate an SBOM/checksums if releases distribute binaries. -- [ ] Add changelog, contribution guide, code of conduct, security reporting +- [x] Add changelog, contribution guide, code of conduct, security reporting instructions, release profile, and reproducible release procedure. - [ ] Run a false-positive review against the evaluation corpus and require an explicit sign-off before changing default rule weights or thresholds.