From 1e8533316b792aa7fd25091a74afbb185bb8eb46 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:48:29 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ABI-FFI-README.md => ABI-FFI-README.adoc | 244 +++++++++--------- ARCHITECTURE.adoc | 48 ++++ ARCHITECTURE.md | 47 ---- CHANGELOG.adoc | 73 +++--- CHANGELOG.md | 40 --- CODE_OF_CONDUCT.adoc | 24 ++ CODE_OF_CONDUCT.md | 27 -- CONTRIBUTING.adoc | 92 +++++++ CONTRIBUTING.md | 84 ------- GOVERNANCE.adoc | 60 +++++ GOVERNANCE.md | 60 ----- INSTALL.md => INSTALL.adoc | 306 ++++++++++++++--------- NAMING-CONVENTIONS.adoc | 193 ++++++++++++++ NAMING-CONVENTIONS.md | 166 ------------ PROOF-NEEDS.adoc | 12 + PROOF-NEEDS.md | 14 -- SECURITY.adoc | 23 ++ SECURITY.md | 25 -- TEST-NEEDS.adoc | 32 +++ TEST-NEEDS.md | 33 --- TOPOLOGY.md => TOPOLOGY.adoc | 39 ++- docs/tech-debt-2026-05-26.adoc | 66 +++++ docs/tech-debt-2026-05-26.md | 59 ----- llm-warmup-dev.adoc | 19 ++ llm-warmup-dev.md | 20 -- llm-warmup-user.adoc | 19 ++ llm-warmup-user.md | 20 -- 27 files changed, 957 insertions(+), 888 deletions(-) rename ABI-FFI-README.md => ABI-FFI-README.adoc (74%) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md rename INSTALL.md => INSTALL.adoc (64%) create mode 100644 NAMING-CONVENTIONS.adoc delete mode 100644 NAMING-CONVENTIONS.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (88%) create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index cbd9473..f883150 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License PMPL-1.0-or-later -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index aa1e8bd..cb66c8c 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,38 +1,41 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Changelog +== Changelog All notable changes to this project will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -== [2.0.0] - 2024-11-06 - -=== Added -- Complete Ada 2022 rewrite from Python -- Type-safe navigation system with compile-time guarantees -- Interactive directory navigation with depth limiting -- Bookmark system for frequently accessed locations -- Color-coded file type detection -- Configuration management with validation -- Error handling for permission-denied directories -- Command-line argument parsing -- Help and version information - -=== Changed -- Migrated from Python to Ada 2022 for enhanced reliability -- Improved error messages and user feedback -- Modernized terminal output with emojis and colors - -=== Technical Details -- Uses GNAT Ada compiler with Ada 2022 standard -- Implements unbounded strings for dynamic path handling -- Custom terminal abstraction for cross-platform compatibility -- Comprehensive type system for file categorization - -== [1.0.0] - Initial Python Version - -=== Added -- Basic directory tree navigation -- Python-based implementation +The format is based on https://keepachangelog.com/en/1.0.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [2.0.0] - 2024-11-06 + +==== Added + +* Complete Ada 2022 rewrite from Python +* Type-safe navigation system with compile-time guarantees +* Interactive directory navigation with depth limiting +* Bookmark system for frequently accessed locations +* Color-coded file type detection +* Configuration management with validation +* Error handling for permission-denied directories +* Command-line argument parsing +* Help and version information + +==== Changed + +* Migrated from Python to Ada 2022 for enhanced reliability +* Improved error messages and user feedback +* Modernized terminal output with emojis and colors + +==== Technical Details + +* Uses GNAT Ada compiler with Ada 2022 standard +* Implements unbounded strings for dynamic path handling +* Custom terminal abstraction for cross-platform compatibility +* Comprehensive type system for file categorization + +=== [1.0.0] - Initial Python Version + +==== Added + +* Basic directory tree navigation +* Python-based implementation diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 859e8a3..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,40 +0,0 @@ - -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [2.0.0] - 2024-11-06 - -### Added -- Complete Ada 2022 rewrite from Python -- Type-safe navigation system with compile-time guarantees -- Interactive directory navigation with depth limiting -- Bookmark system for frequently accessed locations -- Color-coded file type detection -- Configuration management with validation -- Error handling for permission-denied directories -- Command-line argument parsing -- Help and version information - -### Changed -- Migrated from Python to Ada 2022 for enhanced reliability -- Improved error messages and user feedback -- Modernized terminal output with emojis and colors - -### Technical Details -- Uses GNAT Ada compiler with Ada 2022 standard -- Implements unbounded strings for dynamic path handling -- Custom terminal abstraction for cross-platform compatibility -- Comprehensive type system for file categorization - -## [1.0.0] - Initial Python Version - -### Added -- Basic directory tree navigation -- Python-based implementation diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..96cf0cc --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,92 @@ +== Contributing to Tree Navigator + +Thank you for your interest in contributing to Tree Navigator! This +document provides guidelines and instructions for contributing. + +=== Development Setup + +==== Prerequisites + +* GNAT Ada compiler (GCC 12.0 or later with Ada 2022 support) +* GPRbuild +* Git + +==== Building from Source + +[source,bash] +---- +git clone https://github.com/yourusername/tree-navigator.git +cd tree-navigator +gprbuild -P tree_navigator.gpr +./bin/main +---- + +=== Code Style + +This project follows Ada 2022 standards with these conventions: + +* *Indentation*: 3 spaces (Ada standard) +* *Line length*: Keep under 100 characters where practical +* *Naming*: Use `+Snake_Case+` for identifiers +* *Comments*: Use `+--+` for single-line comments +* *Pragmas*: Place `+pragma Ada_2022;+` at the top of each file + +=== Project Structure + +.... +tree-navigator/ +├── src/ # Ada source files (.ads/.adb) +├── obj/ # Compiled objects (gitignored) +├── bin/ # Compiled executable (gitignored) +├── tree_navigator.gpr # GNAT project file +└── README.md +.... + +=== Testing + +Before submitting a pull request: + +[arabic] +. Ensure your code compiles without errors: + +[source,bash] +---- + gprbuild -P tree_navigator.gpr +---- + +[arabic, start=2] +. Test basic functionality: + +[source,bash] +---- + ./bin/main --help + ./bin/main +---- + +[arabic, start=3] +. Verify no new warnings are introduced + +=== Submitting Changes + +[arabic] +. Fork the repository +. Create a feature branch (`+git checkout -b feature/amazing-feature+`) +. Commit your changes (`+git commit -m 'Add amazing feature'+`) +. Push to the branch (`+git push origin feature/amazing-feature+`) +. Open a Pull Request + +=== Pull Request Guidelines + +* Provide a clear description of the changes +* Reference any related issues +* Ensure code compiles cleanly +* Update documentation if needed +* Add yourself to CONTRIBUTORS.md + +=== Code of Conduct + +Be respectful, constructive, and professional in all interactions. + +=== Questions? + +Open an issue for questions, bug reports, or feature requests. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 72748d8..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,84 +0,0 @@ - -# Contributing to Tree Navigator - -Thank you for your interest in contributing to Tree Navigator! This document provides guidelines and instructions for contributing. - -## Development Setup - -### Prerequisites - -- GNAT Ada compiler (GCC 12.0 or later with Ada 2022 support) -- GPRbuild -- Git - -### Building from Source -```bash -git clone https://github.com/yourusername/tree-navigator.git -cd tree-navigator -gprbuild -P tree_navigator.gpr -./bin/main -``` - -## Code Style - -This project follows Ada 2022 standards with these conventions: - -- **Indentation**: 3 spaces (Ada standard) -- **Line length**: Keep under 100 characters where practical -- **Naming**: Use `Snake_Case` for identifiers -- **Comments**: Use `--` for single-line comments -- **Pragmas**: Place `pragma Ada_2022;` at the top of each file - -## Project Structure -``` -tree-navigator/ -├── src/ # Ada source files (.ads/.adb) -├── obj/ # Compiled objects (gitignored) -├── bin/ # Compiled executable (gitignored) -├── tree_navigator.gpr # GNAT project file -└── README.md -``` - -## Testing - -Before submitting a pull request: - -1. Ensure your code compiles without errors: -```bash - gprbuild -P tree_navigator.gpr -``` - -2. Test basic functionality: -```bash - ./bin/main --help - ./bin/main -``` - -3. Verify no new warnings are introduced - -## Submitting Changes - -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request - -## Pull Request Guidelines - -- Provide a clear description of the changes -- Reference any related issues -- Ensure code compiles cleanly -- Update documentation if needed -- Add yourself to CONTRIBUTORS.md - -## Code of Conduct - -Be respectful, constructive, and professional in all interactions. - -## Questions? - -Open an issue for questions, bug reports, or feature requests. diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/INSTALL.md b/INSTALL.adoc similarity index 64% rename from INSTALL.md rename to INSTALL.adoc index 1da724e..2b7da3e 100644 --- a/INSTALL.md +++ b/INSTALL.adoc @@ -1,15 +1,13 @@ - -# Tree Navigator Installation Guide +== Tree Navigator Installation Guide Complete installation instructions for all platforms and methods. -## Quick Install +=== Quick Install -### Debian/Ubuntu -```bash +==== Debian/Ubuntu + +[source,bash] +---- # From PPA (recommended) sudo add-apt-repository ppa:hyperpolymath/tree-navigator sudo apt update @@ -18,20 +16,24 @@ sudo apt install tree-navigator # From DEB package wget https://gitlab.com/hyperpolymath/tree-navigator/-/releases/v2.0.0/downloads/tree-navigator_2.0.0_amd64.deb sudo dpkg -i tree-navigator_2.0.0_amd64.deb -``` +---- + +==== Fedora/RHEL/CentOS -### Fedora/RHEL/CentOS -```bash +[source,bash] +---- # From Copr (recommended) sudo dnf copr enable hyperpolymath/tree-navigator sudo dnf install tree-navigator # From RPM package sudo dnf install https://gitlab.com/hyperpolymath/tree-navigator/-/releases/v2.0.0/downloads/tree-navigator-2.0.0-1.x86_64.rpm -``` +---- -### Arch Linux -```bash +==== Arch Linux + +[source,bash] +---- # From AUR yay -S tree-navigator @@ -39,30 +41,38 @@ yay -S tree-navigator git clone https://aur.archlinux.org/tree-navigator.git cd tree-navigator makepkg -si -``` +---- + +==== macOS -### macOS -```bash +[source,bash] +---- # Homebrew brew install tree-navigator # MacPorts sudo port install tree-navigator -``` +---- -### Flatpak (Universal) -```bash +==== Flatpak (Universal) + +[source,bash] +---- flatpak install flathub com.gitlab.hyperpolymath.TreeNavigator flatpak run com.gitlab.hyperpolymath.TreeNavigator -``` +---- + +==== Snap (Universal) -### Snap (Universal) -```bash +[source,bash] +---- sudo snap install tree-navigator -``` +---- -### From Source -```bash +==== From Source + +[source,bash] +---- # Install dependencies sudo dnf install gcc-gnat gprbuild # Fedora sudo apt install gnat-13 gprbuild # Debian/Ubuntu @@ -77,67 +87,85 @@ sudo cp bin/main /usr/local/bin/tn sudo cp man/tree-navigator.1 /usr/local/share/man/man1/ sudo gzip /usr/local/share/man/man1/tree-navigator.1 sudo mandb -``` +---- + +=== Shell Alias Setup -## Shell Alias Setup +Tree Navigator installs as `+tree-navigator+`, but we recommend the +short alias *`+tn+`* (Tree Navigator). -Tree Navigator installs as `tree-navigator`, but we recommend the short alias **`tn`** (Tree Navigator). +==== Why `+tn+`? -### Why `tn`? +* ✅ Short and memorable +* ✅ Doesn’t conflict with existing commands +* ✅ Meaningful: **T**ree **N**avigator +* ✅ Fast to type +* ✅ Consistent across all shells -- ✅ Short and memorable -- ✅ Doesn't conflict with existing commands -- ✅ Meaningful: **T**ree **N**avigator -- ✅ Fast to type -- ✅ Consistent across all shells +==== Automatic Alias Installation -### Automatic Alias Installation -```bash +[source,bash] +---- # This adds the alias to your shell config automatically tree-navigator --install-alias -``` +---- -This will detect your shell and add `alias tn='tree-navigator'` to the appropriate config file. +This will detect your shell and add `+alias tn='tree-navigator'+` to the +appropriate config file. -### Manual Alias Setup +==== Manual Alias Setup -#### Bash -```bash +===== Bash + +[source,bash] +---- echo "alias tn='tree-navigator'" >> ~/.bashrc source ~/.bashrc -``` +---- + +===== Zsh -#### Zsh -```bash +[source,bash] +---- echo "alias tn='tree-navigator'" >> ~/.zshrc source ~/.zshrc -``` +---- -#### Fish -```bash +===== Fish + +[source,bash] +---- echo "alias tn='tree-navigator'" >> ~/.config/fish/config.fish source ~/.config/fish/config.fish -``` +---- + +===== Nushell -#### Nushell -```bash +[source,bash] +---- echo "alias tn = tree-navigator" >> ~/.config/nushell/config.nu -``` +---- -#### Tcsh -```bash +===== Tcsh + +[source,bash] +---- echo "alias tn tree-navigator" >> ~/.tcshrc source ~/.tcshrc -``` +---- + +===== Dash (add to profile) -#### Dash (add to profile) -```bash +[source,bash] +---- echo "alias tn='tree-navigator'" >> ~/.profile . ~/.profile -``` +---- + +==== Verify Installation -### Verify Installation -```bash +[source,bash] +---- # Full command tree-navigator --version @@ -146,10 +174,12 @@ tn --version # Both should output: # tree-navigator 2.0.0 (Ada 2022) -``` +---- -## Usage Examples -```bash +=== Usage Examples + +[source,bash] +---- # Export directory tree tn --export output.txt --max-depth 5 @@ -167,12 +197,14 @@ tn --help # View man page man tree-navigator -``` +---- -## System-Wide Installation (From Source) +=== System-Wide Installation (From Source) For manual system-wide installation: -```bash + +[source,bash] +---- # After building sudo install -m 755 bin/main /usr/local/bin/tn sudo install -m 644 man/tree-navigator.1 /usr/local/share/man/man1/ @@ -181,12 +213,14 @@ sudo mandb # Create symlink for full name sudo ln -s /usr/local/bin/tn /usr/local/bin/tree-navigator -``` +---- -Now both `tn` and `tree-navigator` will work! +Now both `+tn+` and `+tree-navigator+` will work! -## User-Only Installation (No Root) -```bash +=== User-Only Installation (No Root) + +[source,bash] +---- # Build gprbuild -P tree_navigator.gpr -XBuild_Mode=release @@ -206,12 +240,14 @@ gzip -f ~/.local/share/man/man1/tree-navigator.1 # Update MANPATH echo 'export MANPATH="$HOME/.local/share/man:$MANPATH"' >> ~/.bashrc source ~/.bashrc -``` +---- + +=== Uninstallation -## Uninstallation +==== Package Manager -### Package Manager -```bash +[source,bash] +---- # Debian/Ubuntu sudo apt remove tree-navigator @@ -226,10 +262,12 @@ flatpak uninstall com.gitlab.hyperpolymath.TreeNavigator # Snap sudo snap remove tree-navigator -``` +---- -### Manual -```bash +==== Manual + +[source,bash] +---- sudo rm -f /usr/local/bin/tn sudo rm -f /usr/local/bin/tree-navigator sudo rm -f /usr/local/share/man/man1/tree-navigator.1.gz @@ -238,12 +276,14 @@ sudo mandb # Remove alias from shell config # Edit ~/.bashrc, ~/.zshrc, etc. and remove the line: # alias tn='tree-navigator' -``` +---- + +=== Troubleshooting -## Troubleshooting +==== Command not found -### Command not found -```bash +[source,bash] +---- # Check if installed which tn which tree-navigator @@ -253,16 +293,20 @@ echo $PATH # Verify binary location ls -l /usr/local/bin/tn -``` +---- -### Permission denied -```bash +==== Permission denied + +[source,bash] +---- # Make executable chmod +x /usr/local/bin/tn -``` +---- + +==== Man page not found -### Man page not found -```bash +[source,bash] +---- # Update man database sudo mandb @@ -271,22 +315,26 @@ echo $MANPATH # Verify man page exists ls -l /usr/local/share/man/man1/tree-navigator.1.gz -``` +---- -## Dependencies +=== Dependencies -### Runtime (for binary packages) -- libgnat-13 or libgnat-15 +==== Runtime (for binary packages) -### Build (for source installation) -- GNAT Ada Compiler (GCC 13+) -- GPRbuild -- Make (optional) +* libgnat-13 or libgnat-15 -## Updating +==== Build (for source installation) -### Package Manager -```bash +* GNAT Ada Compiler (GCC 13+) +* GPRbuild +* Make (optional) + +=== Updating + +==== Package Manager + +[source,bash] +---- # Debian/Ubuntu sudo apt update && sudo apt upgrade tree-navigator @@ -295,20 +343,24 @@ sudo dnf upgrade tree-navigator # Arch yay -Syu tree-navigator -``` +---- + +==== From Source -### From Source -```bash +[source,bash] +---- cd tree-navigator git pull origin main gprbuild -P tree_navigator.gpr -XBuild_Mode=release sudo cp bin/main /usr/local/bin/tn -``` +---- -## Platform-Specific Notes +=== Platform-Specific Notes -### Fedora Silverblue / CoreOS -```bash +==== Fedora Silverblue / CoreOS + +[source,bash] +---- # Use Flatpak or toolbox flatpak install com.gitlab.hyperpolymath.TreeNavigator @@ -316,38 +368,42 @@ flatpak install com.gitlab.hyperpolymath.TreeNavigator toolbox create toolbox enter sudo dnf install tree-navigator -``` +---- + +==== NixOS -### NixOS -```nix +[source,nix] +---- # In configuration.nix environment.systemPackages = with pkgs; [ tree-navigator ]; -``` +---- + +==== Windows (WSL) -### Windows (WSL) -```bash +[source,bash] +---- # Use Ubuntu/Debian instructions in WSL sudo apt install tree-navigator -``` +---- -## Getting Help +=== Getting Help -- **Documentation:** https://gitlab.com/hyperpolymath/tree-navigator/-/wikis/home -- **Issues:** https://gitlab.com/hyperpolymath/tree-navigator/-/issues -- **Man Page:** `man tree-navigator` -- **Built-in Help:** `tn --help` +* *Documentation:* +https://gitlab.com/hyperpolymath/tree-navigator/-/wikis/home +* *Issues:* https://gitlab.com/hyperpolymath/tree-navigator/-/issues +* *Man Page:* `+man tree-navigator+` +* *Built-in Help:* `+tn --help+` -## Next Steps +=== Next Steps -After installation: -1. Read the [User Guide](https://gitlab.com/hyperpolymath/tree-navigator/-/wikis/User-Guide) -2. Try the examples: `tn --help` -3. Set up shell completion (if available) -4. Explore interactive mode: `tn` +After installation: 1. Read the +https://gitlab.com/hyperpolymath/tree-navigator/-/wikis/User-Guide[User +Guide] 2. Try the examples: `+tn --help+` 3. Set up shell completion (if +available) 4. Explore interactive mode: `+tn+` ---- +''''' -**Installed successfully?** Share your experience or report issues at: +*Installed successfully?* Share your experience or report issues at: https://gitlab.com/hyperpolymath/tree-navigator/-/issues diff --git a/NAMING-CONVENTIONS.adoc b/NAMING-CONVENTIONS.adoc new file mode 100644 index 0000000..ee3b512 --- /dev/null +++ b/NAMING-CONVENTIONS.adoc @@ -0,0 +1,193 @@ +== Tree Navigator Naming Conventions + +=== Project Naming + +==== Repository Name + +*Use hyphens:* `+tree-navigator+` - URLs: +`+gitlab.com/group/tree-navigator+` - Clone: +`+git clone git@gitlab.com:group/tree-navigator.git+` - Directory: +`+cd tree-navigator+` + +==== GPR Project File + +*Use hyphens:* `+tree-navigator.gpr+` + +[source,bash] +---- +gprbuild -P tree-navigator.gpr +---- + +*Note:* Inside the GPR file, the project name can use underscores: + +[source,ada] +---- +project Tree_Navigator is + -- This is fine, it's Ada convention +end Tree_Navigator; +---- + +==== Executable Name + +*Use hyphens:* `+tree-navigator+` + +[source,bash] +---- +./bin/main # During development +/usr/local/bin/tree-navigator # When installed +---- + +==== Package Names + +*Use hyphens:* - DEB: `+tree-navigator_2.0.0_amd64.deb+` - RPM: +`+tree-navigator-2.0.0-1.x86_64.rpm+` - Tarball: +`+tree-navigator-2.0.0-linux-x86_64.tar.gz+` + +=== Ada Source Files + +==== File Names + +*Use underscores:* (Ada standard convention) + +.... +src/ +├── main.adb +├── tree_printer.ads +├── tree_printer.adb +├── file_types.ads +├── file_types.adb +└── ... +.... + +==== Package Names in Code + +*Use underscores:* (Ada requirement) + +[source,ada] +---- +package Tree_Printer is +package File_Types is +---- + +==== Directory Structure + +.... +tree-navigator/ ← hyphen (repository) +├── tree-navigator.gpr ← hyphen (project file) +├── src/ +│ ├── tree_printer.ads ← underscore (Ada source) +│ └── tree_printer.adb ← underscore (Ada source) +├── obj/ ← no separator needed +├── bin/ +│ └── main ← no separator needed +└── man/ + └── tree-navigator.1 ← hyphen (command name) +.... + +=== Docker & Containers + +*Use hyphens:* + +[source,bash] +---- +docker build -t tree-navigator:latest . +docker run tree-navigator --help +---- + +*Registry:* + +.... +registry.gitlab.com/group/tree-navigator:latest +.... + +=== Environment Variables + +*Use underscores (POSIX convention):* + +[source,bash] +---- +TREE_NAVIGATOR_CONFIG=/etc/tree-navigator/config +TREE_NAVIGATOR_CACHE_DIR=/var/cache/tree-navigator +---- + +=== Configuration Files + +*Use hyphens:* + +.... +~/.config/tree-navigator/ +├── config.toml +├── bookmarks.txt +└── history.txt +.... + +=== URLs & Endpoints + +*Use hyphens:* + +.... +https://tree-navigator.io +https://docs.tree-navigator.io +https://api.tree-navigator.io/v1/export +.... + +=== Git References + +*Use hyphens:* + +[source,bash] +---- +# Branches +git checkout feature/tree-export +git checkout bugfix/memory-leak + +# Tags +git tag v2.0.0-rc1 +git tag v2.0.0-beta +---- + +=== Summary + +[cols=",,",options="header",] +|=== +|Context |Convention |Example +|Repository |hyphen |`+tree-navigator+` +|GPR file |hyphen |`+tree-navigator.gpr+` +|Ada sources |underscore |`+tree_printer.ads+` +|Ada packages |underscore |`+Tree_Printer+` +|Executable |hyphen |`+tree-navigator+` +|Packages (DEB/RPM) |hyphen |`+tree-navigator_2.0.0_amd64.deb+` +|Docker images |hyphen |`+tree-navigator:latest+` +|Config dirs |hyphen |`+~/.config/tree-navigator/+` +|Env vars |underscore |`+TREE_NAVIGATOR_CONFIG+` +|URLs |hyphen |`+tree-navigator.io+` +|Man pages |hyphen |`+tree-navigator.1+` +|=== + +=== Why Different Conventions? + +[arabic] +. *Hyphens for user-facing names*: Easier to type, URL-friendly, modern +convention +. *Underscores for Ada*: Required by Ada language specification for file +names +. *Underscores for environment variables*: POSIX shell convention +(hyphens not allowed) +. *Consistency within each domain*: URLs all use hyphens, Ada all uses +underscores + +=== Migration Checklist + +When renaming from `+tree_navigator+` to `+tree-navigator+`: + +* [ ] Rename repository on GitLab/GitHub +* [ ] Update local git remote URL +* [ ] Rename `+.gpr+` file +* [ ] Update all build scripts +* [ ] Update CI/CD configurations +* [ ] Update README and documentation +* [ ] Update Docker files +* [ ] Update deployment scripts +* [ ] Keep Ada source files unchanged (they’re correct as-is) +* [ ] Clean and rebuild: `+gprbuild -P tree-navigator.gpr+` +* [ ] Test installation and man page diff --git a/NAMING-CONVENTIONS.md b/NAMING-CONVENTIONS.md deleted file mode 100644 index e874749..0000000 --- a/NAMING-CONVENTIONS.md +++ /dev/null @@ -1,166 +0,0 @@ - -# Tree Navigator Naming Conventions - -## Project Naming - -### Repository Name -**Use hyphens:** `tree-navigator` -- URLs: `gitlab.com/group/tree-navigator` -- Clone: `git clone git@gitlab.com:group/tree-navigator.git` -- Directory: `cd tree-navigator` - -### GPR Project File -**Use hyphens:** `tree-navigator.gpr` -```bash -gprbuild -P tree-navigator.gpr -``` - -**Note:** Inside the GPR file, the project name can use underscores: -```ada -project Tree_Navigator is - -- This is fine, it's Ada convention -end Tree_Navigator; -``` - -### Executable Name -**Use hyphens:** `tree-navigator` -```bash -./bin/main # During development -/usr/local/bin/tree-navigator # When installed -``` - -### Package Names -**Use hyphens:** -- DEB: `tree-navigator_2.0.0_amd64.deb` -- RPM: `tree-navigator-2.0.0-1.x86_64.rpm` -- Tarball: `tree-navigator-2.0.0-linux-x86_64.tar.gz` - -## Ada Source Files - -### File Names -**Use underscores:** (Ada standard convention) -``` -src/ -├── main.adb -├── tree_printer.ads -├── tree_printer.adb -├── file_types.ads -├── file_types.adb -└── ... -``` - -### Package Names in Code -**Use underscores:** (Ada requirement) -```ada -package Tree_Printer is -package File_Types is -``` - -### Directory Structure -``` -tree-navigator/ ← hyphen (repository) -├── tree-navigator.gpr ← hyphen (project file) -├── src/ -│ ├── tree_printer.ads ← underscore (Ada source) -│ └── tree_printer.adb ← underscore (Ada source) -├── obj/ ← no separator needed -├── bin/ -│ └── main ← no separator needed -└── man/ - └── tree-navigator.1 ← hyphen (command name) -``` - -## Docker & Containers - -**Use hyphens:** -```bash -docker build -t tree-navigator:latest . -docker run tree-navigator --help -``` - -**Registry:** -``` -registry.gitlab.com/group/tree-navigator:latest -``` - -## Environment Variables - -**Use underscores (POSIX convention):** -```bash -TREE_NAVIGATOR_CONFIG=/etc/tree-navigator/config -TREE_NAVIGATOR_CACHE_DIR=/var/cache/tree-navigator -``` - -## Configuration Files - -**Use hyphens:** -``` -~/.config/tree-navigator/ -├── config.toml -├── bookmarks.txt -└── history.txt -``` - -## URLs & Endpoints - -**Use hyphens:** -``` -https://tree-navigator.io -https://docs.tree-navigator.io -https://api.tree-navigator.io/v1/export -``` - -## Git References - -**Use hyphens:** -```bash -# Branches -git checkout feature/tree-export -git checkout bugfix/memory-leak - -# Tags -git tag v2.0.0-rc1 -git tag v2.0.0-beta -``` - -## Summary - -| Context | Convention | Example | -|---------|-----------|---------| -| Repository | hyphen | `tree-navigator` | -| GPR file | hyphen | `tree-navigator.gpr` | -| Ada sources | underscore | `tree_printer.ads` | -| Ada packages | underscore | `Tree_Printer` | -| Executable | hyphen | `tree-navigator` | -| Packages (DEB/RPM) | hyphen | `tree-navigator_2.0.0_amd64.deb` | -| Docker images | hyphen | `tree-navigator:latest` | -| Config dirs | hyphen | `~/.config/tree-navigator/` | -| Env vars | underscore | `TREE_NAVIGATOR_CONFIG` | -| URLs | hyphen | `tree-navigator.io` | -| Man pages | hyphen | `tree-navigator.1` | - -## Why Different Conventions? - -1. **Hyphens for user-facing names**: Easier to type, URL-friendly, modern convention -2. **Underscores for Ada**: Required by Ada language specification for file names -3. **Underscores for environment variables**: POSIX shell convention (hyphens not allowed) -4. **Consistency within each domain**: URLs all use hyphens, Ada all uses underscores - -## Migration Checklist - -When renaming from `tree_navigator` to `tree-navigator`: - -- [ ] Rename repository on GitLab/GitHub -- [ ] Update local git remote URL -- [ ] Rename `.gpr` file -- [ ] Update all build scripts -- [ ] Update CI/CD configurations -- [ ] Update README and documentation -- [ ] Update Docker files -- [ ] Update deployment scripts -- [ ] Keep Ada source files unchanged (they're correct as-is) -- [ ] Clean and rebuild: `gprbuild -P tree-navigator.gpr` -- [ ] Test installation and man page diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d5132f --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index fd95f90..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,14 +0,0 @@ - -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..1288150 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,23 @@ +== Security Policy + +=== Supported Versions + +Use this section to tell people about which versions of your project are +currently being supported with security updates. + +[cols=",",options="header",] +|=== +|Version |Supported +|5.1.x |:white_check_mark: +|5.0.x |:x: +|4.0.x |:white_check_mark: +|< 4.0 |:x: +|=== + +=== Reporting a Vulnerability + +Use this section to tell people how to report a vulnerability. + +Tell them where to go, how often they can expect to get an update on a +reported vulnerability, what to expect if the vulnerability is accepted +or declined, etc. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 062acbd..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -Use this section to tell people about which versions of your project are -currently being supported with security updates. - -| Version | Supported | -| ------- | ------------------ | -| 5.1.x | :white_check_mark: | -| 5.0.x | :x: | -| 4.0.x | :white_check_mark: | -| < 4.0 | :x: | - -## Reporting a Vulnerability - -Use this section to tell people how to report a vulnerability. - -Tell them where to go, how often they can expect to get an update on a -reported vulnerability, what to expect if the vulnerability is accepted or -declined, etc. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..e455408 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,32 @@ +== TEST-NEEDS.md — tree-navigator + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Zig FFI tests |1 |`+ffi/zig/test/integration_test.zig+` +|Test infrastructure |Present |`+tests/+` directory structure +|=== + +=== What’s Covered + +* [x] Zig FFI integration tests +* [x] Test framework infrastructure + +=== Still Missing (for CRG B+) + +* [ ] Tree traversal unit tests +* [ ] Navigation algorithm tests +* [ ] Property-based tree generation +* [ ] Performance benchmarks +* [ ] Edge case handling tests + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/tree-navigator && cargo test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 2f6ce68..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,33 +0,0 @@ - -# TEST-NEEDS.md — tree-navigator - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Zig FFI tests | 1 | `ffi/zig/test/integration_test.zig` | -| Test infrastructure | Present | `tests/` directory structure | - -## What's Covered - -- [x] Zig FFI integration tests -- [x] Test framework infrastructure - -## Still Missing (for CRG B+) - -- [ ] Tree traversal unit tests -- [ ] Navigation algorithm tests -- [ ] Property-based tree generation -- [ ] Performance benchmarks -- [ ] Edge case handling tests - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/tree-navigator && cargo test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 5b5b1c0..19f7c46 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Tree Navigator — Project Topology -# Tree Navigator — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ DEVELOPER / USER │ │ (CLI Interface / Interactive) │ @@ -41,11 +37,11 @@ │ Justfile Automation .machine_readable/ │ │ GPRBuild / Ada 2022 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE ENGINE (ADA) @@ -66,25 +62,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Production tool stable -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... CLI Command ──────► Filter Engine ──────► Tree Printer ──────► Export File │ │ │ │ ▼ ▼ ▼ ▼ Interactive UI ──► Path Navigator ───► Categorization ──► Terminal Output -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..4ccc62f --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,66 @@ +== Tech-Debt Audit — tree-navigator — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+2026-05-22+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 15 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 +.... + +*Total markers:* 0. *Severity:* `+>00+`. + +*Recommended next move:* none — no proof-debt markers detected. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+PMPL-1.0-or-later+` +|Manifest licence |`+NONE+` +|Body classifier |`+PMPL-1.0-or-later+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |422 +|`+docs/+` files |1 +|`+docs/+` LoC |36 +|CHANGELOG.md |Y +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+readme=422 docs=1/36+` +|=== + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 1c8adb7..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,59 +0,0 @@ - -# Tech-Debt Audit — tree-navigator — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `2026-05-22`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 15 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 0. **Severity:** `>00`. - -**Recommended next move:** none — no proof-debt markers detected. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `PMPL-1.0-or-later` | -| Manifest licence | `NONE` | -| Body classifier | `PMPL-1.0-or-later` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 422 | -| `docs/` files | 1 | -| `docs/` LoC | 36 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `readme=422 docs=1/36` | - - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..f4f4abf --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — tree-navigator (Developer) + +=== What is tree-navigator? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: PMPL-1.0-or-later +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 2eb5f04..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — tree-navigator (Developer) - -## What is tree-navigator? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: PMPL-1.0-or-later -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..fba9b9a --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — tree-navigator (User) + +=== What is tree-navigator? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: PMPL-1.0-or-later +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 51b38b3..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — tree-navigator (User) - -## What is tree-navigator? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: PMPL-1.0-or-later -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture