From 348a00bcf38e7f34471baea377247ca7fe78a5c4 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 09:32:03 +0000 Subject: [PATCH] refactor(root): move root artefacts to their canonical locations Applies the estate root-shape rollout: files that are not root-level by necessity move to where their tooling and the estate canon expect them, and every reference to them is updated in the same change. * .github/hooks/validate-a2ml.sh (from .githooks/validate-a2ml.sh) -> .github/hooks/validate-a2ml.sh * .github/hooks/validate-k9.sh (from .githooks/validate-k9.sh) -> .github/hooks/validate-k9.sh * .github/workflows/dogfood-gate.yml * QUICKSTART-MAINTAINER.adoc * build/guix.scm (from guix.scm) -> build/guix.scm * .github/CONTRIBUTING.md (new) * CONTRIBUTING.adoc (deleted) Verified with `git apply --check` against current main before committing; no behaviour change intended, the Justfile entry points keep working. --- .github/CONTRIBUTING.md | 285 ++++++++++++++++++ {.githooks => .github/hooks}/validate-a2ml.sh | 0 {.githooks => .github/hooks}/validate-k9.sh | 0 .github/workflows/dogfood-gate.yml | 4 +- CONTRIBUTING.adoc | 250 --------------- QUICKSTART-MAINTAINER.adoc | 2 +- guix.scm | 28 -- 7 files changed, 288 insertions(+), 281 deletions(-) create mode 100644 .github/CONTRIBUTING.md rename {.githooks => .github/hooks}/validate-a2ml.sh (100%) rename {.githooks => .github/hooks}/validate-k9.sh (100%) delete mode 100644 CONTRIBUTING.adoc delete mode 100644 guix.scm diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..3d1d8d7 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,285 @@ +# Contributing to panic-attack + +Thank you for your interest in contributing to panic-attack! This +document provides guidelines and information for contributors. + +## Code of Conduct + +This project follows the Contributor Covenant Code of Conduct. By +participating, you are expected to uphold this code. Please report +unacceptable behavior to +[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk. + +## How to Contribute + +### Reporting Bugs + +Before creating bug reports, please check the existing issues to avoid +duplicates. When creating a bug report, include: + +- **Clear title** describing the issue + +- **Detailed description** of the problem + +- **Steps to reproduce** the behavior + +- **Expected behavior** vs actual behavior + +- **Environment** (OS, Rust version, panic-attack version) + +- **Logs or error messages** if applicable + +### Suggesting Enhancements + +Enhancement suggestions are tracked as GitHub issues. When creating an +enhancement suggestion: + +- **Use a clear and descriptive title** + +- **Provide a detailed description** of the proposed feature + +- **Explain why this enhancement would be useful** to most users + +- **List any alternatives** you’ve considered + +### Pull Requests + +1. **Fork the repository** and create your branch from `main` + +2. **Follow the coding standards** described below + +3. **Add tests** for any new functionality + +4. **Update documentation** including README, rustdoc, and examples + +5. **Ensure all tests pass** (`cargo` `test`) + +6. **Ensure zero warnings** (`cargo` `build` `--release`) + +7. **Run clippy** (`cargo` `clippy` `--` `-D` `warnings`) + +8. **Format code** (`cargo` `fmt`) + +9. **Write a clear commit message** following the project’s commit + style + +## Development Setup + +### Prerequisites + +- Rust 1.85.0 or later (MSRV) + +- Cargo + +- Git + +- just (optional, for task automation) + +### Building + +``` bash +git clone https://github.com/hyperpolymath/panic-attack.git +cd panic-attack +cargo build +``` + +### Running Tests + +``` bash +# Run all tests +cargo test + +# Run readiness tests (machine-verifiable CRG grades) +just readiness + +# Run readiness summary (pass/fail per grade) +just readiness-summary + +# Run with verbose output +cargo test -- --nocapture + +# Run specific test +cargo test test_name +``` + +### Running Locally + +``` bash +cargo run -- assail ./examples/vulnerable_program.rs --verbose +``` + +## Coding Standards + +### Rust Style + +- Follow the [Rust Style Guide](https://doc.rust-lang.org/1.0.0/style/) + +- Use `cargo` `fmt` for consistent formatting + +- Use `cargo` `clippy` to catch common mistakes + +- Maximum line length: 100 characters (flexible for readability) + +### Documentation + +- All public APIs must have rustdoc comments + +- Include examples in rustdoc where appropriate + +- Keep comments up-to-date with code changes + +- Use `//!` for module-level documentation + +- Use `///` for item-level documentation + +### Testing + +- Write unit tests for all non-trivial functions + +- Write integration tests for user-facing features + +- Aim for 80% code coverage + +- Test edge cases and error conditions + +- Use descriptive test names: + `test___` + +- Readiness tests use CRG grade prefixes: `readiness_d_`, + `readiness_c_`, `readiness_b_` + +### Commit Messages + +Follow the Conventional Commits specification: + + : + + [optional body] + + [optional footer] + +Types: - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation +changes - `test`: Adding or updating tests - `refactor`: Code +refactoring - `perf`: Performance improvements - `chore`: Maintenance +tasks + +Example: + + feat: add Latin-1 fallback for non-UTF-8 files + + Implements encoding_rs fallback when UTF-8 decoding fails. + Verbose mode logs skipped files. Fixes handling of vendored + C files with non-ASCII author names. + + Closes #42 + +## Project Structure + + panic-attack/ + ├── src/ + │ ├── main.rs # CLI entry point (clap) — 20 subcommands + │ ├── lib.rs # Library API + │ ├── types.rs # Core types (49 languages, 25 categories) + │ ├── assail/ # Static analysis engine + │ │ ├── analyzer.rs # 49-language analyzer with per-file detection + │ │ └── patterns.rs # Language-specific attack patterns + │ ├── kanren/ # miniKanren-inspired logic engine + │ │ ├── core.rs # Unification, substitution, fact DB + │ │ ├── taint.rs # Source-to-sink taint analysis + │ │ ├── crosslang.rs # FFI boundary vulnerability chains + │ │ └── strategy.rs # Risk-weighted search prioritisation + │ ├── attack/ # 6-axis stress testing + │ │ ├── executor.rs # Attack execution engine + │ │ └── strategies.rs # Per-axis attack strategies + │ ├── signatures/ # Logic-based bug signature detection + │ │ ├── engine.rs # SignatureEngine (use-after-free, deadlock, etc.) + │ │ └── rules.rs # Detection rules + │ ├── report/ # Report generation and output + │ │ ├── generator.rs # AssaultReport builder + │ │ └── formatter.rs # Output formatting (text, JSON, YAML, Nickel, SARIF) + │ ├── assemblyline.rs # Batch scanning with rayon parallelism + BLAKE3 + │ ├── notify.rs # Notification pipeline (markdown + GitHub issues) + │ ├── attestation/ # Cryptographic attestation chain + │ │ ├── intent.rs # Pre-execution commitment + │ │ ├── evidence.rs # Rolling hash accumulator + │ │ ├── seal.rs # Post-execution binding + │ │ ├── chain.rs # Chain builder orchestration + │ │ └── envelope.rs # A2ML envelope wrapper + │ ├── ambush/ # Ambient stressors + DAW-style timeline + │ ├── amuck/ # Mutation combinations + │ ├── abduct/ # Isolation + time-skew + │ ├── adjudicate/ # Campaign verdict aggregation + │ ├── axial/ # Reaction observation + │ ├── a2ml/ # AI manifest protocol + │ ├── panll/ # PanLL event-chain export + │ ├── storage/ # Filesystem + VerisimDB persistence + │ ├── i18n/ # Multi-language support (ISO 639-1, 10 languages) + │ └── diagnostics.rs # Self-check (version, fleet, attestation, panicbot) + ├── tests/ # Integration + readiness tests + ├── examples/ # Example programs + ├── .machine_readable/ # SCM checkpoint files + bot directives + └── .github/workflows/ # CI/CD workflows + +## RSR Compliance + +This project follows RSR (Reproducible Software Repositories) standards: + +### Critical Invariants + +1. **SCM files in .machine_readable/ only** - Never put STATE.scm, + ECOSYSTEM.scm, or META.scm in the repository root + +2. **AI manifest required** - AI.a2ml must be present and up-to-date + +3. **License consistency** - All files must use MPL-2.0 (SPDX header) + +4. **Author attribution** - Jonathan D.A. Jewell + [j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk + +### Updating Checkpoint Files + +When making significant changes, update: - +`.machine_readable/STATE.scm` - Current state, completion %, next +actions - `.machine_readable/ECOSYSTEM.scm` - If adding new dependencies +or integrations - `.machine_readable/META.scm` - If making architectural +decisions (ADRs) + +## Release Process + +1. Update version in `Cargo.toml` + +2. Update `CHANGELOG.md` with changes since last release + +3. Update `.machine_readable/STATE.scm` with new version + +4. Run full test suite: `cargo` `test` + +5. Run readiness tests: `just` `readiness-summary` + +6. Create git tag: `git` `tag` `-a` `vX.Y.Z` `-m` `"Release` `vX.Y.Z"` + +7. Push tag: `git` `push` `origin` `vX.Y.Z` + +8. GitHub Actions will create the release + +## Getting Help + +- **Documentation**: See README.md and DESIGN.md + +- **Issues**: Check existing issues or create a new one + +- **Email**: [j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk + +- **Roadmap**: See ROADMAP.md for future plans + +## License + +By contributing to panic-attack, you agree that your contributions will +be licensed under the MPL-2.0 license. See the LICENSE file for details. + +## Recognition + +Contributors will be acknowledged in: - CHANGELOG.md for their specific +contributions - GitHub contributors page - Release notes + +Thank you for contributing to panic-attack! diff --git a/.githooks/validate-a2ml.sh b/.github/hooks/validate-a2ml.sh similarity index 100% rename from .githooks/validate-a2ml.sh rename to .github/hooks/validate-a2ml.sh diff --git a/.githooks/validate-k9.sh b/.github/hooks/validate-k9.sh similarity index 100% rename from .githooks/validate-k9.sh rename to .github/hooks/validate-k9.sh diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index b772a40..145225a 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -41,7 +41,7 @@ jobs: - name: Validate A2ML manifests if: steps.detect.outputs.count > 0 - run: bash .githooks/validate-a2ml.sh + run: bash .github/hooks/validate-a2ml.sh - name: Write summary run: | A2ML_COUNT="${{ steps.detect.outputs.count }}" @@ -86,7 +86,7 @@ jobs: - name: Validate K9 contracts if: steps.detect.outputs.k9_count > 0 - run: bash .githooks/validate-k9.sh + run: bash .github/hooks/validate-k9.sh - name: Write summary run: | K9_COUNT="${{ steps.detect.outputs.k9_count }}" diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index a5f1d98..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,250 +0,0 @@ -== Contributing to panic-attack - -Thank you for your interest in contributing to panic-attack! This -document provides guidelines and information for contributors. - -=== Code of Conduct - -This project follows the Contributor Covenant Code of Conduct. By -participating, you are expected to uphold this code. Please report -unacceptable behavior to j.d.a.jewell@open.ac.uk. - -=== How to Contribute - -==== Reporting Bugs - -Before creating bug reports, please check the existing issues to avoid -duplicates. When creating a bug report, include: - -* *Clear title* describing the issue -* *Detailed description* of the problem -* *Steps to reproduce* the behavior -* *Expected behavior* vs actual behavior -* *Environment* (OS, Rust version, panic-attack version) -* *Logs or error messages* if applicable - -==== Suggesting Enhancements - -Enhancement suggestions are tracked as GitHub issues. When creating an -enhancement suggestion: - -* *Use a clear and descriptive title* -* *Provide a detailed description* of the proposed feature -* *Explain why this enhancement would be useful* to most users -* *List any alternatives* you’ve considered - -==== Pull Requests - -[arabic] -. *Fork the repository* and create your branch from `+main+` -. *Follow the coding standards* described below -. *Add tests* for any new functionality -. *Update documentation* including README, rustdoc, and examples -. *Ensure all tests pass* (`+cargo test+`) -. *Ensure zero warnings* (`+cargo build --release+`) -. *Run clippy* (`+cargo clippy -- -D warnings+`) -. *Format code* (`+cargo fmt+`) -. *Write a clear commit message* following the project’s commit style - -=== Development Setup - -==== Prerequisites - -* Rust 1.85.0 or later (MSRV) -* Cargo -* Git -* just (optional, for task automation) - -==== Building - -[source,bash] ----- -git clone https://github.com/hyperpolymath/panic-attack.git -cd panic-attack -cargo build ----- - -==== Running Tests - -[source,bash] ----- -# Run all tests -cargo test - -# Run readiness tests (machine-verifiable CRG grades) -just readiness - -# Run readiness summary (pass/fail per grade) -just readiness-summary - -# Run with verbose output -cargo test -- --nocapture - -# Run specific test -cargo test test_name ----- - -==== Running Locally - -[source,bash] ----- -cargo run -- assail ./examples/vulnerable_program.rs --verbose ----- - -=== Coding Standards - -==== Rust Style - -* Follow the https://doc.rust-lang.org/1.0.0/style/[Rust Style Guide] -* Use `+cargo fmt+` for consistent formatting -* Use `+cargo clippy+` to catch common mistakes -* Maximum line length: 100 characters (flexible for readability) - -==== Documentation - -* All public APIs must have rustdoc comments -* Include examples in rustdoc where appropriate -* Keep comments up-to-date with code changes -* Use `+//!+` for module-level documentation -* Use `+///+` for item-level documentation - -==== Testing - -* Write unit tests for all non-trivial functions -* Write integration tests for user-facing features -* Aim for 80% code coverage -* Test edge cases and error conditions -* Use descriptive test names: -`+test___+` -* Readiness tests use CRG grade prefixes: `+readiness_d_+`, -`+readiness_c_+`, `+readiness_b_+` - -==== Commit Messages - -Follow the Conventional Commits specification: - -.... -: - -[optional body] - -[optional footer] -.... - -Types: - `+feat+`: New feature - `+fix+`: Bug fix - `+docs+`: -Documentation changes - `+test+`: Adding or updating tests - -`+refactor+`: Code refactoring - `+perf+`: Performance improvements - -`+chore+`: Maintenance tasks - -Example: - -.... -feat: add Latin-1 fallback for non-UTF-8 files - -Implements encoding_rs fallback when UTF-8 decoding fails. -Verbose mode logs skipped files. Fixes handling of vendored -C files with non-ASCII author names. - -Closes #42 -.... - -=== Project Structure - -.... -panic-attack/ -├── src/ -│ ├── main.rs # CLI entry point (clap) — 20 subcommands -│ ├── lib.rs # Library API -│ ├── types.rs # Core types (49 languages, 25 categories) -│ ├── assail/ # Static analysis engine -│ │ ├── analyzer.rs # 49-language analyzer with per-file detection -│ │ └── patterns.rs # Language-specific attack patterns -│ ├── kanren/ # miniKanren-inspired logic engine -│ │ ├── core.rs # Unification, substitution, fact DB -│ │ ├── taint.rs # Source-to-sink taint analysis -│ │ ├── crosslang.rs # FFI boundary vulnerability chains -│ │ └── strategy.rs # Risk-weighted search prioritisation -│ ├── attack/ # 6-axis stress testing -│ │ ├── executor.rs # Attack execution engine -│ │ └── strategies.rs # Per-axis attack strategies -│ ├── signatures/ # Logic-based bug signature detection -│ │ ├── engine.rs # SignatureEngine (use-after-free, deadlock, etc.) -│ │ └── rules.rs # Detection rules -│ ├── report/ # Report generation and output -│ │ ├── generator.rs # AssaultReport builder -│ │ └── formatter.rs # Output formatting (text, JSON, YAML, Nickel, SARIF) -│ ├── assemblyline.rs # Batch scanning with rayon parallelism + BLAKE3 -│ ├── notify.rs # Notification pipeline (markdown + GitHub issues) -│ ├── attestation/ # Cryptographic attestation chain -│ │ ├── intent.rs # Pre-execution commitment -│ │ ├── evidence.rs # Rolling hash accumulator -│ │ ├── seal.rs # Post-execution binding -│ │ ├── chain.rs # Chain builder orchestration -│ │ └── envelope.rs # A2ML envelope wrapper -│ ├── ambush/ # Ambient stressors + DAW-style timeline -│ ├── amuck/ # Mutation combinations -│ ├── abduct/ # Isolation + time-skew -│ ├── adjudicate/ # Campaign verdict aggregation -│ ├── axial/ # Reaction observation -│ ├── a2ml/ # AI manifest protocol -│ ├── panll/ # PanLL event-chain export -│ ├── storage/ # Filesystem + VerisimDB persistence -│ ├── i18n/ # Multi-language support (ISO 639-1, 10 languages) -│ └── diagnostics.rs # Self-check (version, fleet, attestation, panicbot) -├── tests/ # Integration + readiness tests -├── examples/ # Example programs -├── .machine_readable/ # SCM checkpoint files + bot directives -└── .github/workflows/ # CI/CD workflows -.... - -=== RSR Compliance - -This project follows RSR (Reproducible Software Repositories) standards: - -==== Critical Invariants - -[arabic] -. *SCM files in .machine_readable/ only* - Never put STATE.scm, -ECOSYSTEM.scm, or META.scm in the repository root -. *AI manifest required* - AI.a2ml must be present and up-to-date -. *License consistency* - All files must use MPL-2.0 (SPDX header) -. *Author attribution* - Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk - -==== Updating Checkpoint Files - -When making significant changes, update: - -`+.machine_readable/STATE.scm+` - Current state, completion %, next -actions - `+.machine_readable/ECOSYSTEM.scm+` - If adding new -dependencies or integrations - `+.machine_readable/META.scm+` - If -making architectural decisions (ADRs) - -=== Release Process - -[arabic] -. Update version in `+Cargo.toml+` -. Update `+CHANGELOG.md+` with changes since last release -. Update `+.machine_readable/STATE.scm+` with new version -. Run full test suite: `+cargo test+` -. Run readiness tests: `+just readiness-summary+` -. Create git tag: `+git tag -a vX.Y.Z -m "Release vX.Y.Z"+` -. Push tag: `+git push origin vX.Y.Z+` -. GitHub Actions will create the release - -=== Getting Help - -* *Documentation*: See README.md and DESIGN.md -* *Issues*: Check existing issues or create a new one -* *Email*: j.d.a.jewell@open.ac.uk -* *Roadmap*: See ROADMAP.md for future plans - -=== License - -By contributing to panic-attack, you agree that your contributions will -be licensed under the MPL-2.0 license. See the LICENSE file for details. - -=== Recognition - -Contributors will be acknowledged in: - CHANGELOG.md for their specific -contributions - GitHub contributors page - Release notes - -Thank you for contributing to panic-attack! diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index 6327b33..512a4e3 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -32,7 +32,7 @@ Output: `target/release/panic-attack` [source,bash] ---- -guix build -f guix.scm +guix build -f build/guix.scm ---- === Nix diff --git a/guix.scm b/guix.scm deleted file mode 100644 index 6f2434f..0000000 --- a/guix.scm +++ /dev/null @@ -1,28 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Guix development environment. -;; Usage: guix shell -D -f guix.scm - -(use-modules (guix packages) - (guix build-system gnu) - (guix licenses) - (gnu packages base) - (gnu packages bash) - (gnu packages zig) - (gnu packages base) - (gnu packages java) - (gnu packages node) - (gnu packages rust) - (gnu packages golang) - (gnu packages python) - (gnu packages cmake)) - -(package - (name "panic-attack") - (version "0.1.0") - (source #f) - (build-system gnu-build-system) - (inputs (list coreutils bash zig make openjdk node rust go python cmake)) - (synopsis "panic-attack") - (description "panic-attack — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/panic-attack") - (license ((@@ (guix licenses) license) "MPL-2.0" "https://github.com/hyperpolymath/palimpsest-license")))