diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 5ae9913..ddeeeb5 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -6,7 +6,7 @@ Copyright (c) Jonathan D.A. Jewell ### Allowed Languages (Primary → Fallback) - **Systems/ML**: Rust -- **Web/Scripts**: ReScript → TypeScript (legacy only) +- **Web/Scripts**: AffineScript → TypeScript (legacy only) - **TUI**: Ada/SPARK - **WordPress**: PHP (with security CI) - **LSP**: Java (exception for IDE compatibility) @@ -19,7 +19,7 @@ Copyright (c) Jonathan D.A. Jewell ### Package Management - **Primary**: Guix (guix.scm) -- **Fallback**: Nix (flake.nix) +- **Fallback**: Guix (flake.guix) ### Security Requirements - No MD5/SHA1 for security (use SHA256+) diff --git a/.claude/PROJECT.adoc b/.claude/PROJECT.adoc new file mode 100644 index 0000000..380f81f --- /dev/null +++ b/.claude/PROJECT.adoc @@ -0,0 +1,33 @@ +== File Soup - Claude Code Instructions + +This repository contains the File Soup file management utility. + +=== Project Structure + +.... +file-soup/ +├── .claude/ # AI assistant instructions +├── .git/ # Version control +├── .gitignore # Git ignore rules +├── .editorconfig # Editor configuration +└── ... # Utility files +.... + +=== Build Commands + +Refer to project-specific documentation. + +=== Coding Conventions + +* Follow hyperpolymath standards +* All code must have SPDX license headers +* Use approved languages only (see CLAUDE.md) +* Document all non-obvious decisions + +=== Security + +* No hardcoded secrets +* All secrets through environment variables or secret management +* SHA-pinned dependencies where applicable +* HTTPS only, no HTTP URLs +* No MD5/SHA1 for security purposes diff --git a/.claude/PROJECT.md b/.claude/PROJECT.md deleted file mode 100644 index 44ae675..0000000 --- a/.claude/PROJECT.md +++ /dev/null @@ -1,33 +0,0 @@ -# File Soup - Claude Code Instructions - -This repository contains the File Soup file management utility. - -## Project Structure - -``` -file-soup/ -├── .claude/ # AI assistant instructions -├── .git/ # Version control -├── .gitignore # Git ignore rules -├── .editorconfig # Editor configuration -└── ... # Utility files -``` - -## Build Commands - -Refer to project-specific documentation. - -## Coding Conventions - -- Follow hyperpolymath standards -- All code must have SPDX license headers -- Use approved languages only (see CLAUDE.md) -- Document all non-obvious decisions - -## Security - -- No hardcoded secrets -- All secrets through environment variables or secret management -- SHA-pinned dependencies where applicable -- HTTPS only, no HTTP URLs -- No MD5/SHA1 for security purposes diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4d9ae2f..07f9937 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -44,8 +44,8 @@ updates: schedule: interval: "weekly" - # Nix flakes - - package-ecosystem: "nix" + # Guix flakes + - package-ecosystem: "guix" directory: "/" schedule: interval: "weekly" diff --git a/.machine_readable/contractiles/Justfile b/.machine_readable/contractiles/Justfile index d08a6ff..0c2598a 100644 --- a/.machine_readable/contractiles/Justfile +++ b/.machine_readable/contractiles/Justfile @@ -60,7 +60,7 @@ build *args: # cargo build {{args}} # Rust # mix compile {{args}} # Elixir # zig build {{args}} # Zig - # deno task build {{args}} # Deno/ReScript + # deno task build {{args}} # Deno/AffineScript @echo "Build complete" # Build in release mode with optimizations @@ -364,7 +364,7 @@ state-phase: @grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" # =============================================================================== -# GUIX & NIX +# GUIX & GUIX # =============================================================================== # Enter Guix development shell (primary) @@ -375,9 +375,9 @@ guix-shell: guix-build: guix build -f guix.scm -# Enter Nix development shell (fallback) -nix-shell: - @if [ -f "flake.nix" ]; then nix develop; else echo "No flake.nix"; fi +# Enter Guix development shell (fallback) +guix-shell: + @if [ -f "flake.guix" ]; then guix develop; else echo "No flake.guix"; fi # =============================================================================== # HYBRID AUTOMATION 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 new file mode 100644 index 0000000..f378874 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,73 @@ +== Changelog + +All notable changes to `+filesoup+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: add Justfile and TOPOLOGY.md (RSR compliance) +* feat: add RSR template structure and project metadata +* feat: create filesoup monorepo with fslint plugin API and SDK + +==== Fixed + +* fix(ci): pin upload-artifact to valid SHA in hypatia-scan.yml (Refs +standards#48) (#14) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (standards#85) +(#12) +* fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build +drift) (#11) +* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + +Comment-step gate) (#9) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#7) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix: correct email jonathan.jewell → j.d.a.jewell +* fix: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement +* fix: SPDX headers (AGPL→PMPL), email, author name + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: align documentation with FSLint vision and architecture + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#16) +* ci: bump actions/upload-artifact SHA to current v4 (#6) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: fix workflow-linter YAML parse error + self-flag bug +* ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench +filename allowlists (#5) + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 52cbc17..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,67 +0,0 @@ - - -# Changelog - -All notable changes to `filesoup` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: add Justfile and TOPOLOGY.md (RSR compliance) -- feat: add RSR template structure and project metadata -- feat: create filesoup monorepo with fslint plugin API and SDK - -### Fixed - -- fix(ci): pin upload-artifact to valid SHA in hypatia-scan.yml (Refs standards#48) (#14) -- fix(ci): bump a2ml/k9-validate-action pins to canonical (standards#85) (#12) -- fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build drift) (#11) -- fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + Comment-step gate) (#9) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#7) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix: correct email jonathan.jewell → j.d.a.jewell -- fix: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement -- fix: SPDX headers (AGPL→PMPL), email, author name - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: align documentation with FSLint vision and architecture - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#16) -- ci: bump actions/upload-artifact SHA to current v4 (#6) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: fix workflow-linter YAML parse error + self-flag bug -- ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench filename allowlists (#5) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..b5c21cc --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +filesoup a harassment-free experience for everyone, regardless of age, +body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/filesoup/discussions[Discussion] (for +general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 082baff..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in filesoup a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/filesoup/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..3fe8661 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/filesoup.git cd filesoup + +== Using Guix (recommended for reproducibility) + +guix develop + +== Or using toolbox/distrobox + +toolbox create filesoup-dev toolbox enter filesoup-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +filesoup/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # Library code +(Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) ├── plugins/ +# Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) ├── docs/ # +Documentation (Perimeter 3) │ ├── architecture/ # ADRs, specs (Perimeter +2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ # Examples +(Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ # Test +suite (Perimeter 2-3) ├── .well-known/ # Protocol files (Perimeter 1-3) +├── .github/ # GitHub config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── +workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # +This file ├── GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── +README.adoc ├── SECURITY.md ├── flake.guix # Guix flake (Perimeter 1) +└── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/filesoup/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/filesoup/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/filesoup/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/filesoup/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 41f68ef..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/filesoup.git -cd filesoup - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create filesoup-dev -toolbox enter filesoup-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -filesoup/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/filesoup/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/filesoup/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/filesoup/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/filesoup/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index 5ea8811..e54d994 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -108,7 +108,7 @@ but no detection logic is wired yet. | `file-soup/examples/` | Code examples for plugin authors | `PROOF-NEEDS.md` | Formal verification backlog for this repo | `Justfile` | Build recipes: `just build`, `just test`, `just fuzz`, `just lint` -| `flake.nix` / `guix.scm` | Reproducible environment definitions +| `flake.guix` / `guix.scm` | Reproducible environment definitions | `contractiles/` | Contractile trust/dust/intend check files | `.machine_readable/` | A2ML state, meta, ecosystem, agentic manifests |=== 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/Justfile b/Justfile index d08a6ff..0c2598a 100644 --- a/Justfile +++ b/Justfile @@ -60,7 +60,7 @@ build *args: # cargo build {{args}} # Rust # mix compile {{args}} # Elixir # zig build {{args}} # Zig - # deno task build {{args}} # Deno/ReScript + # deno task build {{args}} # Deno/AffineScript @echo "Build complete" # Build in release mode with optimizations @@ -364,7 +364,7 @@ state-phase: @grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" # =============================================================================== -# GUIX & NIX +# GUIX & GUIX # =============================================================================== # Enter Guix development shell (primary) @@ -375,9 +375,9 @@ guix-shell: guix-build: guix build -f guix.scm -# Enter Nix development shell (fallback) -nix-shell: - @if [ -f "flake.nix" ]; then nix develop; else echo "No flake.nix"; fi +# Enter Guix development shell (fallback) +guix-shell: + @if [ -f "flake.guix" ]; then guix develop; else echo "No flake.guix"; fi # =============================================================================== # HYBRID AUTOMATION diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index 48d9781..86e986e 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,47 +1,156 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the maintainers of FSLint, their responsibilities, +and contact information. -== Current Maintainers +=== Current Maintainers -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Lead Maintainer + +* *Name*: FSLint Contributors +* *Role*: Project Lead, Architecture, Releases +* *GitHub*: @Hyperpolymath +* *Email*: maintainers@fslint.org +* *Focus*: Overall project direction, core architecture, release +management + +=== Maintainer Responsibilities + +==== Core Responsibilities + +[arabic] +. *Code Review*: Review and merge pull requests +. *Issue Triage*: Respond to and categorize issues +. *Releases*: Coordinate and publish releases +. *Security*: Respond to security reports within 48 hours +. *Community*: Foster inclusive, welcoming environment -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] +==== Component Ownership + +[cols=",,",options="header",] +|=== +|Component |Maintainer |Focus Area +|Core (fslint-core) |Lead |Scanner, cache, config +|CLI (fslint-cli) |Lead |Commands, output formats +|Plugin API |Lead |Trait system, plugin loader +|Plugins |Community |Individual plugin maintenance +|Documentation |Community |README, guides, examples +|CI/CD |Lead |GitHub Actions, releases |=== -== Responsibilities +=== Becoming a Maintainer + +==== Path to Maintainership + +[arabic] +. *Contributor* (TPCF Perimeter 3: Community Sandbox) +* Submit quality PRs +* Help with issue triage +* Participate in discussions +. *Trusted Contributor* (TPCF Perimeter 2: Blessed Garden) +* Consistent high-quality contributions over 3+ months +* Deep understanding of codebase +* Demonstrated good judgment +. *Maintainer* (TPCF Perimeter 1: Inner Sanctum) +* Nominated by existing maintainer +* Vote by current maintainers (2/3 majority) +* Commit to ongoing engagement + +==== Expectations + +* *Response Time*: Triage issues within 7 days +* *PR Review*: Review assigned PRs within 14 days +* *Availability*: Communicate planned absences +* *Conduct*: Uphold Code of Conduct at all times + +=== Emeritus Maintainers + +Maintainers who have stepped down but contributed significantly: + +_None yet_ + +=== Tri-Perimeter Contribution Framework (TPCF) + +FSLint uses TPCF for graduated access control: + +==== Perimeter 3: Community Sandbox (Open) + +* *Access*: Fork, PR, issues, discussions +* *Review*: All changes reviewed by Perimeter 1/2 +* *Goal*: Safe experimentation without commitment + +==== Perimeter 2: Blessed Garden (Trusted) + +* *Access*: Triage issues, review PRs, branch push +* *Earned*: 3+ months quality contributions +* *Goal*: Distributed maintenance workload + +==== Perimeter 1: Inner Sanctum (Core Team) + +* *Access*: Merge to main, releases, security +* *Earned*: Long-term trust, deep expertise +* *Goal*: Strategic direction, critical decisions + +=== Decision Making + +==== Minor Decisions + +* *Who*: Any maintainer +* *Examples*: Bug fixes, documentation, minor features +* *Process*: Single maintainer approval + +==== Major Decisions + +* *Who*: 2/3 maintainer vote +* *Examples*: Breaking changes, architecture, licensing +* *Process*: RFC → Discussion → Vote → Implementation + +==== Critical Decisions + +* *Who*: Unanimous maintainer agreement +* *Examples*: Project direction, governance changes +* *Process*: Extended RFC → Community input → Consensus + +=== Communication Channels + +* *GitHub Issues*: Bug reports, feature requests +* *GitHub Discussions*: General questions, RFCs +* *Email*: maintainers@fslint.org (private matters) +* *Security*: security@fslint.org (vulnerabilities) + +=== Conflict Resolution + +[arabic] +. *Direct Communication*: Attempt to resolve directly +. *Mediation*: Involve another maintainer +. *Vote*: If unresolved, put to maintainer vote +. *Code of Conduct*: Serious violations → enforcement -Maintainers are responsible for: +=== Maintainer Meetings -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +* *Frequency*: Monthly (as needed) +* *Format*: Asynchronous (GitHub Discussions) +* *Topics*: Roadmap, issues, community health +* *Minutes*: Published in Discussions -== Becoming a Maintainer +=== Stepping Down -Contributors who demonstrate: +Maintainers can step down at any time: -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +[arabic] +. *Notice*: 2 weeks preferred (not required) +. *Transition*: Hand off responsibilities +. *Emeritus*: Listed with appreciation +. *Return*: Welcome to return anytime -May be invited to become maintainers at the discretion of existing maintainers. +=== Contact -== Decision Making +* *All Maintainers*: maintainers@fslint.org +* *Individual*: See GitHub profiles +* *Public*: GitHub Issues/Discussions -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +''''' -== Contact +*Last Updated*: 2025-11-22 -For questions about project governance, open an issue or contact the maintainers listed above. +*Governance Version*: 1.0 diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index 859cc9c..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,154 +0,0 @@ - -# Maintainers - -This document lists the maintainers of FSLint, their responsibilities, and contact information. - -## Current Maintainers - -### Lead Maintainer - -- **Name**: FSLint Contributors -- **Role**: Project Lead, Architecture, Releases -- **GitHub**: @Hyperpolymath -- **Email**: maintainers@fslint.org -- **Focus**: Overall project direction, core architecture, release management - -## Maintainer Responsibilities - -### Core Responsibilities - -1. **Code Review**: Review and merge pull requests -2. **Issue Triage**: Respond to and categorize issues -3. **Releases**: Coordinate and publish releases -4. **Security**: Respond to security reports within 48 hours -5. **Community**: Foster inclusive, welcoming environment - -### Component Ownership - -| Component | Maintainer | Focus Area | -|-----------|------------|------------| -| Core (fslint-core) | Lead | Scanner, cache, config | -| CLI (fslint-cli) | Lead | Commands, output formats | -| Plugin API | Lead | Trait system, plugin loader | -| Plugins | Community | Individual plugin maintenance | -| Documentation | Community | README, guides, examples | -| CI/CD | Lead | GitHub Actions, releases | - -## Becoming a Maintainer - -### Path to Maintainership - -1. **Contributor** (TPCF Perimeter 3: Community Sandbox) - - Submit quality PRs - - Help with issue triage - - Participate in discussions - -2. **Trusted Contributor** (TPCF Perimeter 2: Blessed Garden) - - Consistent high-quality contributions over 3+ months - - Deep understanding of codebase - - Demonstrated good judgment - -3. **Maintainer** (TPCF Perimeter 1: Inner Sanctum) - - Nominated by existing maintainer - - Vote by current maintainers (2/3 majority) - - Commit to ongoing engagement - -### Expectations - -- **Response Time**: Triage issues within 7 days -- **PR Review**: Review assigned PRs within 14 days -- **Availability**: Communicate planned absences -- **Conduct**: Uphold Code of Conduct at all times - -## Emeritus Maintainers - -Maintainers who have stepped down but contributed significantly: - -*None yet* - -## Tri-Perimeter Contribution Framework (TPCF) - -FSLint uses TPCF for graduated access control: - -### Perimeter 3: Community Sandbox (Open) - -- **Access**: Fork, PR, issues, discussions -- **Review**: All changes reviewed by Perimeter 1/2 -- **Goal**: Safe experimentation without commitment - -### Perimeter 2: Blessed Garden (Trusted) - -- **Access**: Triage issues, review PRs, branch push -- **Earned**: 3+ months quality contributions -- **Goal**: Distributed maintenance workload - -### Perimeter 1: Inner Sanctum (Core Team) - -- **Access**: Merge to main, releases, security -- **Earned**: Long-term trust, deep expertise -- **Goal**: Strategic direction, critical decisions - -## Decision Making - -### Minor Decisions - -- **Who**: Any maintainer -- **Examples**: Bug fixes, documentation, minor features -- **Process**: Single maintainer approval - -### Major Decisions - -- **Who**: 2/3 maintainer vote -- **Examples**: Breaking changes, architecture, licensing -- **Process**: RFC → Discussion → Vote → Implementation - -### Critical Decisions - -- **Who**: Unanimous maintainer agreement -- **Examples**: Project direction, governance changes -- **Process**: Extended RFC → Community input → Consensus - -## Communication Channels - -- **GitHub Issues**: Bug reports, feature requests -- **GitHub Discussions**: General questions, RFCs -- **Email**: maintainers@fslint.org (private matters) -- **Security**: security@fslint.org (vulnerabilities) - -## Conflict Resolution - -1. **Direct Communication**: Attempt to resolve directly -2. **Mediation**: Involve another maintainer -3. **Vote**: If unresolved, put to maintainer vote -4. **Code of Conduct**: Serious violations → enforcement - -## Maintainer Meetings - -- **Frequency**: Monthly (as needed) -- **Format**: Asynchronous (GitHub Discussions) -- **Topics**: Roadmap, issues, community health -- **Minutes**: Published in Discussions - -## Stepping Down - -Maintainers can step down at any time: - -1. **Notice**: 2 weeks preferred (not required) -2. **Transition**: Hand off responsibilities -3. **Emeritus**: Listed with appreciation -4. **Return**: Welcome to return anytime - -## Contact - -- **All Maintainers**: maintainers@fslint.org -- **Individual**: See GitHub profiles -- **Public**: GitHub Issues/Discussions - ---- - -**Last Updated**: 2025-11-22 - -**Governance Version**: 1.0 diff --git a/PROJECT_SUMMARY.adoc b/PROJECT_SUMMARY.adoc new file mode 100644 index 0000000..52425c6 --- /dev/null +++ b/PROJECT_SUMMARY.adoc @@ -0,0 +1,361 @@ +== FSLint Project Summary + +=== Overview + +FSLint is a cross-platform file system intelligence tool with a +Notepad++-style plugin architecture. Built in Rust for maximum +performance and safety. + +=== Project Statistics + +* *Total Lines of Code*: ~10,000+ +* *Crates*: 4 core + 8 plugins = 12 total +* *Languages*: Rust, Shell, PowerShell, Docker, YAML +* *Tests*: Unit tests + Integration tests +* *Documentation*: 6 major documents + inline docs + +=== Architecture + +==== Core Crates (4) + +[arabic] +. *fslint-plugin-api* - Plugin trait system and core types +. *fslint-plugin-sdk* - Helper utilities for plugin development +. *fslint-core* - Scanner, plugin loader, config system, caching +. *fslint-cli* - CLI interface with multiple output formats + +==== Plugins (8) + +[arabic] +. *git-status* ✅ - Git repository status and branch information +. *file-age* ✅ - Recent modification highlighting (< 7 days) +. *grouping* ✅ - File categorization (node_modules, media, etc.) +. *version-detection* - Versioned file detection (file_v1, file_v2, +file_final) +. *ocr-status* - PDF text layer detection +. *ai-detection* - AI-generated image detection via EXIF +. *duplicate-finder* - Hash-based duplicate detection (SHA-256) +. *secret-scanner* - API key and secret detection (10+ patterns) + +=== Key Features + +==== Core Functionality + +* ✅ Directory scanning with configurable depth +* ✅ Plugin architecture (enable/disable individually) +* ✅ Smart caching by (path, mtime, size) +* ✅ Query engine with powerful filtering +* ✅ Multiple output formats (table, JSON, simple) +* ✅ .gitignore support +* ✅ Hidden file tracking and warnings +* ✅ System directory protection + +==== Performance + +* ✅ Result caching for fast re-scans +* ✅ Configurable max-depth limiting +* ✅ Lazy plugin execution +* ✅ Benchmarking suite + +==== Security + +* ✅ Secret scanner (AWS keys, GitHub tokens, JWT, etc.) +* ✅ Hidden file ratio warnings +* ✅ System directory protection +* ✅ Path traversal prevention + +==== Developer Experience + +* ✅ Comprehensive plugin API +* ✅ Helper SDK for common operations +* ✅ Configuration system +* ✅ Error handling with context +* ✅ Unit and integration tests + +=== Documentation + +==== User Documentation + +[arabic] +. *README.md* - Complete feature documentation with examples +. *docs/QUICKSTART.md* - 5-minute getting started guide +. *CHANGELOG.md* - Version history +. *LICENSE-MIT* + *LICENSE-APACHE* - Dual licensing + +==== Developer Documentation + +[arabic] +. *CONTRIBUTING.md* - Development guidelines and standards +. *docs/PLUGIN_DEVELOPMENT.md* - Comprehensive plugin development guide +. *CLAUDE.md* - Context for AI assistant +. *Inline documentation* - Extensive rustdoc comments + +=== Infrastructure + +==== CI/CD + +* ✅ GitHub Actions workflow for testing +* ✅ Multi-platform builds (Linux, macOS, Windows) +* ✅ Security audit +* ✅ Code coverage +* ✅ Automated releases + +==== Installation + +* ✅ Unix installation script (install.sh) +* ✅ Windows installation script (install.ps1) +* ✅ Uninstall script +* ✅ Docker support +* ✅ docker-compose configuration + +==== Development Tools + +* ✅ Makefile for common tasks +* ✅ Development helper script (dev.sh) +* ✅ Release helper script (release.sh) +* ✅ Benchmark suite + +=== Example Configurations + +[arabic] +. *config-minimal.toml* - Essential plugins only +. *config-full.toml* - All plugins enabled +. *config-security.toml* - Security-focused +. *config-development.toml* - Development workflow + +=== Testing + +==== Test Coverage + +* ✅ Unit tests in all core crates +* ✅ Unit tests in all plugins +* ✅ Integration tests for CLI +* ✅ Benchmark suite + +==== Test Categories + +[arabic] +. *Core functionality* - Scanner, config, cache +. *Plugin API* - Trait implementations +. *CLI commands* - scan, plugins, enable, disable, query +. *Output formats* - table, JSON, simple +. *Query engine* - Filter syntax +. *Safety features* - Hidden file warnings, system directories + +=== File Structure + +.... +file-soup/ +├── crates/ # Core Rust crates +│ ├── fslint-plugin-api/ +│ ├── fslint-plugin-sdk/ +│ ├── fslint-core/ +│ └── fslint-cli/ +├── plugins/ # Plugin implementations +│ ├── git-status/ +│ ├── file-age/ +│ ├── grouping/ +│ ├── version-detection/ +│ ├── ocr-status/ +│ ├── ai-detection/ +│ ├── duplicate-finder/ +│ └── secret-scanner/ +├── docs/ # Documentation +│ ├── QUICKSTART.md +│ └── PLUGIN_DEVELOPMENT.md +├── examples/ # Example configurations +│ ├── config-minimal.toml +│ ├── config-full.toml +│ ├── config-security.toml +│ └── config-development.toml +├── scripts/ # Installation and development scripts +│ ├── install.sh +│ ├── install.ps1 +│ ├── uninstall.sh +│ ├── dev.sh +│ └── release.sh +├── benches/ # Benchmarks +│ └── scanner_benchmark.rs +├── .github/workflows/ # CI/CD +│ ├── ci.yml +│ └── release.yml +├── Dockerfile # Docker support +├── docker-compose.yml +├── Makefile # Build automation +├── README.md # Main documentation +├── CONTRIBUTING.md # Contribution guidelines +├── CHANGELOG.md # Version history +├── CLAUDE.md # AI assistant context +└── Cargo.toml # Workspace configuration +.... + +=== Commands Implemented + +==== CLI Commands + +[arabic] +. *scan* - Scan directory with plugins +* Options: `+--format+`, `+--query+` +* Example: `+fslint scan . --format json+` +. *plugins* - List all plugins +* Shows: name, status, description +* Example: `+fslint plugins+` +. *enable* - Enable a plugin +* Example: `+fslint enable secret-scanner+` +. *disable* - Disable a plugin +* Example: `+fslint disable grouping+` +. *config* - Show configuration +* Displays: enabled plugins, scanner settings +* Example: `+fslint config+` +. *query* - Query files with filters +* Filters: `+name:+`, `+ext:+`, `+newest:+`, `+tag:+`, `+size_gt:+`, +`+size_lt:+` +* Example: `+fslint query "ext:rs tag:age"+` + +=== Output Formats + +==== 1. Table Format (Default) + +.... +File Git Age Group Other +--------------------------------------------------------------------------------- +src/main.rs Modified Today - - +package.json Clean This week - - +.... + +==== 2. JSON Format + +[source,json] +---- +[ + { + "path": "/path/to/file", + "size": 1234, + "results": [...] + } +] +---- + +==== 3. Simple Format + +.... +src/main.rs [Modified, Today] +package.json [Clean, This week] +.... + +=== Query Language + +Powerful filtering syntax: + +* `+name:config+` - Match filename +* `+ext:rs+` - Match extension +* `+newest:true+` - Return newest file +* `+tag:media+` - Match plugin tag +* `+size_gt:1024+` - Files larger than size +* `+git-status:Modified+` - Match plugin result + +Combine filters: + +[source,bash] +---- +fslint query "name:report ext:pdf newest:true" +---- + +=== Performance Characteristics + +==== Scanning Performance + +* Small projects (< 100 files): ~50ms +* Medium projects (< 1000 files): ~500ms +* Large projects (< 10000 files): ~5s +* Cache hit rate: 90%+ on re-scans + +==== Resource Usage + +* Memory: ~10-50 MB typical +* CPU: Minimal (single-threaded) +* Disk: Caching minimal overhead + +=== Future Roadmap (from handover) + +==== Phase 2 + +* WASM plugin runtime support +* Parallel file scanning +* macOS bundle collapsing +* Shell extension integration + +==== Phase 3 + +* Shadow navigation for symlinks +* Virtual filesystem across disks/cloud +* Email attachment integration +* Focus mode filters + +==== Additional Plugins + +* Malware scanner +* License detector +* Dependency analyzer +* Code complexity metrics + +=== Technical Debt + +* OCR-status plugin is placeholder (needs PDF library integration) +* AI-detection could use more sophisticated heuristics +* Parallel scanning not yet implemented +* WASM runtime integration pending + +=== Lessons Learned + +[arabic] +. *Trait-based architecture*: Flexible and extensible +. *Smart caching*: Crucial for performance +. *Error handling*: Anyhow + thiserror combination works well +. *Testing*: Integration tests catch CLI issues early +. *Documentation*: Essential for onboarding and adoption + +=== Deployment Targets + +* ✅ Cargo (crates.io) +* ✅ Docker Hub +* 🔄 Homebrew (pending) +* 🔄 winget (pending) +* 🔄 Shell extensions (future) + +=== Innovation + +FSLint is genuinely innovative - no existing tool provides: + +* Cross-platform file intelligence +* Notepad++-style plugin architecture +* Query language for file metadata +* Composable plugin system + +*Closest competitors:* - exa: Pretty ls, but no plugins - fd: Fast find, +but search-only - gitleaks: Git-only secrets + +*FSLint uniqueness:* Combines all of these + extensibility + +=== Credits + +* Built with Rust and love for developer tools +* Inspired by Notepad++ plugin architecture +* Thanks to Rust community for excellent crates + +=== Status + +*Project Status*: ✅ Ready for initial release (v0.1.0) + +*What’s Complete:* - ✅ Core architecture - ✅ 8 working plugins - ✅ +CLI interface - ✅ Documentation - ✅ Testing infrastructure - ✅ CI/CD +- ✅ Installation scripts - ✅ Docker support + +*What’s Next:* - Performance optimizations - WASM plugin support - More +plugins - Community building + +''''' + +*Built by Claude (AI) in a marathon coding session to maximize credit +usage before expiration. May contain bugs, but definitely contains +ambition! 🚀* diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md deleted file mode 100644 index 347c452..0000000 --- a/PROJECT_SUMMARY.md +++ /dev/null @@ -1,361 +0,0 @@ - -# FSLint Project Summary - -## Overview - -FSLint is a cross-platform file system intelligence tool with a Notepad++-style plugin architecture. Built in Rust for maximum performance and safety. - -## Project Statistics - -- **Total Lines of Code**: ~10,000+ -- **Crates**: 4 core + 8 plugins = 12 total -- **Languages**: Rust, Shell, PowerShell, Docker, YAML -- **Tests**: Unit tests + Integration tests -- **Documentation**: 6 major documents + inline docs - -## Architecture - -### Core Crates (4) - -1. **fslint-plugin-api** - Plugin trait system and core types -2. **fslint-plugin-sdk** - Helper utilities for plugin development -3. **fslint-core** - Scanner, plugin loader, config system, caching -4. **fslint-cli** - CLI interface with multiple output formats - -### Plugins (8) - -1. **git-status** ✅ - Git repository status and branch information -2. **file-age** ✅ - Recent modification highlighting (< 7 days) -3. **grouping** ✅ - File categorization (node_modules, media, etc.) -4. **version-detection** - Versioned file detection (file_v1, file_v2, file_final) -5. **ocr-status** - PDF text layer detection -6. **ai-detection** - AI-generated image detection via EXIF -7. **duplicate-finder** - Hash-based duplicate detection (SHA-256) -8. **secret-scanner** - API key and secret detection (10+ patterns) - -## Key Features - -### Core Functionality - -- ✅ Directory scanning with configurable depth -- ✅ Plugin architecture (enable/disable individually) -- ✅ Smart caching by (path, mtime, size) -- ✅ Query engine with powerful filtering -- ✅ Multiple output formats (table, JSON, simple) -- ✅ .gitignore support -- ✅ Hidden file tracking and warnings -- ✅ System directory protection - -### Performance - -- ✅ Result caching for fast re-scans -- ✅ Configurable max-depth limiting -- ✅ Lazy plugin execution -- ✅ Benchmarking suite - -### Security - -- ✅ Secret scanner (AWS keys, GitHub tokens, JWT, etc.) -- ✅ Hidden file ratio warnings -- ✅ System directory protection -- ✅ Path traversal prevention - -### Developer Experience - -- ✅ Comprehensive plugin API -- ✅ Helper SDK for common operations -- ✅ Configuration system -- ✅ Error handling with context -- ✅ Unit and integration tests - -## Documentation - -### User Documentation - -1. **README.md** - Complete feature documentation with examples -2. **docs/QUICKSTART.md** - 5-minute getting started guide -3. **CHANGELOG.md** - Version history -4. **LICENSE-MIT** + **LICENSE-APACHE** - Dual licensing - -### Developer Documentation - -1. **CONTRIBUTING.md** - Development guidelines and standards -2. **docs/PLUGIN_DEVELOPMENT.md** - Comprehensive plugin development guide -3. **CLAUDE.md** - Context for AI assistant -4. **Inline documentation** - Extensive rustdoc comments - -## Infrastructure - -### CI/CD - -- ✅ GitHub Actions workflow for testing -- ✅ Multi-platform builds (Linux, macOS, Windows) -- ✅ Security audit -- ✅ Code coverage -- ✅ Automated releases - -### Installation - -- ✅ Unix installation script (install.sh) -- ✅ Windows installation script (install.ps1) -- ✅ Uninstall script -- ✅ Docker support -- ✅ docker-compose configuration - -### Development Tools - -- ✅ Makefile for common tasks -- ✅ Development helper script (dev.sh) -- ✅ Release helper script (release.sh) -- ✅ Benchmark suite - -## Example Configurations - -1. **config-minimal.toml** - Essential plugins only -2. **config-full.toml** - All plugins enabled -3. **config-security.toml** - Security-focused -4. **config-development.toml** - Development workflow - -## Testing - -### Test Coverage - -- ✅ Unit tests in all core crates -- ✅ Unit tests in all plugins -- ✅ Integration tests for CLI -- ✅ Benchmark suite - -### Test Categories - -1. **Core functionality** - Scanner, config, cache -2. **Plugin API** - Trait implementations -3. **CLI commands** - scan, plugins, enable, disable, query -4. **Output formats** - table, JSON, simple -5. **Query engine** - Filter syntax -6. **Safety features** - Hidden file warnings, system directories - -## File Structure - -``` -file-soup/ -├── crates/ # Core Rust crates -│ ├── fslint-plugin-api/ -│ ├── fslint-plugin-sdk/ -│ ├── fslint-core/ -│ └── fslint-cli/ -├── plugins/ # Plugin implementations -│ ├── git-status/ -│ ├── file-age/ -│ ├── grouping/ -│ ├── version-detection/ -│ ├── ocr-status/ -│ ├── ai-detection/ -│ ├── duplicate-finder/ -│ └── secret-scanner/ -├── docs/ # Documentation -│ ├── QUICKSTART.md -│ └── PLUGIN_DEVELOPMENT.md -├── examples/ # Example configurations -│ ├── config-minimal.toml -│ ├── config-full.toml -│ ├── config-security.toml -│ └── config-development.toml -├── scripts/ # Installation and development scripts -│ ├── install.sh -│ ├── install.ps1 -│ ├── uninstall.sh -│ ├── dev.sh -│ └── release.sh -├── benches/ # Benchmarks -│ └── scanner_benchmark.rs -├── .github/workflows/ # CI/CD -│ ├── ci.yml -│ └── release.yml -├── Dockerfile # Docker support -├── docker-compose.yml -├── Makefile # Build automation -├── README.md # Main documentation -├── CONTRIBUTING.md # Contribution guidelines -├── CHANGELOG.md # Version history -├── CLAUDE.md # AI assistant context -└── Cargo.toml # Workspace configuration -``` - -## Commands Implemented - -### CLI Commands - -1. **scan** - Scan directory with plugins - - Options: `--format`, `--query` - - Example: `fslint scan . --format json` - -2. **plugins** - List all plugins - - Shows: name, status, description - - Example: `fslint plugins` - -3. **enable** - Enable a plugin - - Example: `fslint enable secret-scanner` - -4. **disable** - Disable a plugin - - Example: `fslint disable grouping` - -5. **config** - Show configuration - - Displays: enabled plugins, scanner settings - - Example: `fslint config` - -6. **query** - Query files with filters - - Filters: `name:`, `ext:`, `newest:`, `tag:`, `size_gt:`, `size_lt:` - - Example: `fslint query "ext:rs tag:age"` - -## Output Formats - -### 1. Table Format (Default) - -``` -File Git Age Group Other ---------------------------------------------------------------------------------- -src/main.rs Modified Today - - -package.json Clean This week - - -``` - -### 2. JSON Format - -```json -[ - { - "path": "/path/to/file", - "size": 1234, - "results": [...] - } -] -``` - -### 3. Simple Format - -``` -src/main.rs [Modified, Today] -package.json [Clean, This week] -``` - -## Query Language - -Powerful filtering syntax: - -- `name:config` - Match filename -- `ext:rs` - Match extension -- `newest:true` - Return newest file -- `tag:media` - Match plugin tag -- `size_gt:1024` - Files larger than size -- `git-status:Modified` - Match plugin result - -Combine filters: -```bash -fslint query "name:report ext:pdf newest:true" -``` - -## Performance Characteristics - -### Scanning Performance - -- Small projects (< 100 files): ~50ms -- Medium projects (< 1000 files): ~500ms -- Large projects (< 10000 files): ~5s -- Cache hit rate: 90%+ on re-scans - -### Resource Usage - -- Memory: ~10-50 MB typical -- CPU: Minimal (single-threaded) -- Disk: Caching minimal overhead - -## Future Roadmap (from handover) - -### Phase 2 -- WASM plugin runtime support -- Parallel file scanning -- macOS bundle collapsing -- Shell extension integration - -### Phase 3 -- Shadow navigation for symlinks -- Virtual filesystem across disks/cloud -- Email attachment integration -- Focus mode filters - -### Additional Plugins -- Malware scanner -- License detector -- Dependency analyzer -- Code complexity metrics - -## Technical Debt - -- OCR-status plugin is placeholder (needs PDF library integration) -- AI-detection could use more sophisticated heuristics -- Parallel scanning not yet implemented -- WASM runtime integration pending - -## Lessons Learned - -1. **Trait-based architecture**: Flexible and extensible -2. **Smart caching**: Crucial for performance -3. **Error handling**: Anyhow + thiserror combination works well -4. **Testing**: Integration tests catch CLI issues early -5. **Documentation**: Essential for onboarding and adoption - -## Deployment Targets - -- ✅ Cargo (crates.io) -- ✅ Docker Hub -- 🔄 Homebrew (pending) -- 🔄 winget (pending) -- 🔄 Shell extensions (future) - -## Innovation - -FSLint is genuinely innovative - no existing tool provides: - -- Cross-platform file intelligence -- Notepad++-style plugin architecture -- Query language for file metadata -- Composable plugin system - -**Closest competitors:** -- exa: Pretty ls, but no plugins -- fd: Fast find, but search-only -- gitleaks: Git-only secrets - -**FSLint uniqueness:** Combines all of these + extensibility - -## Credits - -- Built with Rust and love for developer tools -- Inspired by Notepad++ plugin architecture -- Thanks to Rust community for excellent crates - -## Status - -**Project Status**: ✅ Ready for initial release (v0.1.0) - -**What's Complete:** -- ✅ Core architecture -- ✅ 8 working plugins -- ✅ CLI interface -- ✅ Documentation -- ✅ Testing infrastructure -- ✅ CI/CD -- ✅ Installation scripts -- ✅ Docker support - -**What's Next:** -- Performance optimizations -- WASM plugin support -- More plugins -- Community building - ---- - -**Built by Claude (AI) in a marathon coding session to maximize credit usage before expiration. May contain bugs, but definitely contains ambition! 🚀** diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..ef493d8 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,32 @@ +== Proof Requirements + +=== Current state + +* ABI directory exists (template-level) +* No dangerous patterns found +* 5K lines; file system linter with plugin architecture + +=== What needs proving + +* *Plugin isolation*: Prove that FSLint plugins cannot access files +outside their declared scope +* *Linting rule determinism*: Prove that lint results are deterministic +for the same input (no order-dependent results) +* *No data loss*: Prove that linting operations (including any +rename/move suggestions) never delete or corrupt files when applied + +=== Recommended prover + +* *Idris2* — Plugin capability model fits dependent types naturally + +=== Priority + +* *LOW* — FSLint is a linting tool, not a file mutator in its primary +mode. Plugin isolation becomes important if plugins gain write access. + +=== 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. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 0e91087..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,23 +0,0 @@ -# Proof Requirements - -## Current state -- ABI directory exists (template-level) -- No dangerous patterns found -- 5K lines; file system linter with plugin architecture - -## What needs proving -- **Plugin isolation**: Prove that FSLint plugins cannot access files outside their declared scope -- **Linting rule determinism**: Prove that lint results are deterministic for the same input (no order-dependent results) -- **No data loss**: Prove that linting operations (including any rename/move suggestions) never delete or corrupt files when applied - -## Recommended prover -- **Idris2** — Plugin capability model fits dependent types naturally - -## Priority -- **LOW** — FSLint is a linting tool, not a file mutator in its primary mode. Plugin isolation becomes important if plugins gain write access. - -## 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. diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..a61a10f --- /dev/null +++ b/README.adoc @@ -0,0 +1,364 @@ +FSLint is a high-performance, cross-platform file system linter designed +to make filesystems intelligible and navigable for real people. It +applies tiny, composable plugins to files and directories, transforming +scattered directory trees into logical, metadata-rich bundles — bringing +the cohesion of macOS `+.app+` packages to Linux and Windows. + +[[toc]] + +== Core Concept + +Modern operating systems scatter files across deep, opaque hierarchies. +Configuration lives in one place, data in another, caches in a third. +FSLint addresses this "`file soup`" by linting directory structures and +surfacing contextual metadata about every file and folder it encounters. + +*Contextual metadata* + +Instant insights into git status, file age, duplicates, AI-generated +content, exposed secrets, and more. + +*Bundle-fication* + +Logic to identify and treat complex multi-file directories as cohesive +single entities (like macOS `+.app+` bundles), so users see one logical +"`thing`" rather than a tree of fragments. + +*Query engine* + +A CLI-first filtering language for slicing through results by filename, +extension, plugin tags, size thresholds, and plugin status. + +== Built-in Plugins + +FSLint ships with a set of core plugins for immediate filesystem +visibility. Each can be enabled or disabled individually. + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Plugin |Default |Description +|`+git-status+` |✅ |Displays branch information and uncommitted changes +for git-tracked files. + +|`+file-age+` |✅ |Flags files modified within configurable thresholds +(default: 7 days). + +|`+grouping+` |✅ |Categorises files into types: Media, Dependencies, +Source, Config, etc. + +|`+bundle-check+` |✅ |Verifies whether a directory meets the criteria +for a cohesive "`Package.`" + +|`+version-detection+` |❌ |Finds versioned files (`+report_v1+`, +`+file_final+`, `+backup_2+`). + +|`+ocr-status+` |❌ |Detects PDF text layers and OCR state. + +|`+ai-detection+` |❌ |Identifies AI-generated content via EXIF metadata +and heuristics. + +|`+duplicate-finder+` |❌ |Hash-based duplicate detection across +directories and volumes. + +|`+secret-scanner+` |❌ |Scans for exposed API keys, credentials, and +high-entropy strings. +|=== + +== Quick Start + +=== Installation + +[source,bash] +---- +git clone https://github.com/hyperpolymath/file-soup.git +cd file-soup +cargo build --release +# Binary at ./target/release/fslint +---- + +=== Basic Usage + +[source,bash] +---- +# Scan current directory with default plugins +fslint scan + +# Output results as JSON +fslint scan --format json + +# Scan a specific directory +fslint scan /path/to/project + +# Simple output format (path + tags only) +fslint scan --format simple +---- + +=== Querying + +[source,bash] +---- +# Find all Rust source files with uncommitted changes +fslint query "ext:rs git-status:Modified" + +# Find the newest config file +fslint query "name:config ext:toml newest:true" + +# Find large files tagged as media +fslint query "tag:media size_gt:1048576" + +# Find exposed secrets +fslint enable secret-scanner +fslint query "secret-scanner:Alert" +---- + +=== Plugin Management + +[source,bash] +---- +# List all plugins and their status +fslint plugins + +# Enable a disabled plugin +fslint enable ai-detection + +# Disable a plugin +fslint disable grouping + +# View current configuration +fslint config +---- + +== Query Language + +FSLint supports a space-separated filter syntax. Combine filters freely: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Filter |Example |Description +|`+name:+` |`+name:config+` |Match filename substring. + +|`+ext:+` |`+ext:rs+` |Match file extension. + +|`+newest:true+` |`+newest:true+` |Return only the most recent match. + +|`+tag:+` |`+tag:media+` |Match plugin-assigned tags. + +|`+size_gt:+` |`+size_gt:1048576+` |Files larger than threshold. + +|`+size_lt:+` |`+size_lt:1024+` |Files smaller than threshold. + +|`+:+` |`+git-status:Modified+` |Match specific plugin +result. +|=== + +[source,bash] +---- +fslint query "name:report ext:pdf newest:true" +---- + +== Architecture + +The project is structured as a Rust workspace with discrete crates +separating the plugin interface from the scanning engine and CLI. + +[source,text] +---- +file-soup/ +├── fslint-plugin-api/ # Plugin trait definitions and core types +├── fslint-plugin-sdk/ # Helper utilities for plugin authors +├── fslint-core/ # Scanning engine, query parser, caching (planned) +├── fslint-cli/ # CLI entry point and output formatting (planned) +└── plugins/ # Individual plugin crate modules (planned) + ├── git-status/ + ├── file-age/ + ├── grouping/ + ├── bundle-check/ + └── ... +---- + +=== Current Implementation Status + +* *fslint-plugin-api* — Complete. Defines the `+Plugin+` trait, +`+PluginContext+`, `+PluginResult+`, `+PluginStatus+`, `+PluginError+`, +and `+PluginMetadata+` types. Includes builder methods and unit tests. + +* *fslint-plugin-sdk* — Substantially complete. Provides path helpers, +file metadata utilities (age, size formatting), regex-based pattern +matching for common file categories, and context helpers. Includes tests +and fuzzing. + +* *fslint-core* — Planned. Will contain the scanning engine with smart +caching (keyed on path, mtime, size), `+.gitignore+` support, +configurable max-depth, and the query parser. + +* *fslint-cli* — Planned. Will provide the `+fslint+` command with +`+scan+`, `+query+`, `+plugins+`, `+enable+`, `+disable+`, and +`+config+` subcommands. Multiple output formats: Table (default), JSON, +Simple. + +* *plugins/* — Planned. Each plugin as its own crate, depending on +`+fslint-plugin-api+` and optionally `+fslint-plugin-sdk+`. + +== Output Formats + +=== Table Format (Default) + +[source,text] +---- +File Git Age Group Other +───────────────────────────────────────────────────────────────────────────────── +src/main.rs Modified Today - - +package.json Clean This week - - +node_modules/react/index.js - - Node Dependencies - +---- + +=== JSON Format + +[source,json] +---- +[ + { + "path": "/project/src/main.rs", + "size": 1234, + "results": [ + { + "plugin_name": "git-status", + "status": "Alert", + "message": "Modified", + "color": "yellow" + } + ] + } +] +---- + +=== Simple Format + +[source,text] +---- +src/main.rs [Modified, Today] +package.json [Clean, This week] +node_modules/react/index.js [Node Dependencies] +---- + +== Configuration + +FSLint stores configuration at `+~/.config/fslint/config.toml+`: + +[source,toml] +---- +enabled_plugins = ["git-status", "file-age", "grouping", "bundle-check"] + +[scanner] +max_depth = 10 +include_hidden = false +follow_symlinks = false +respect_gitignore = true + +[plugin_config.file-age] +threshold_days = 7 + +[plugin_config.duplicate-finder] +min_size = 1024 + +[plugin_config.secret-scanner] +max_file_size = 1048576 +---- + +== Performance + +* *Smart caching*: Results cached by `+(path,+` `+mtime,+` `+size)+` — +unchanged files reuse cache on re-scan. +* *Max depth*: Default limit of 10 levels prevents deep recursion into +`+node_modules+` and similar pits. +* *.gitignore support*: Respects `+.gitignore+` by default, skipping +irrelevant files. +* *Lazy execution*: Only enabled plugins run. + +== Plugin Development + +Create a new plugin in three steps: + +[arabic] +. Create the plugin crate: ++ +[source,bash] +---- +mkdir plugins/my-plugin +cd plugins/my-plugin +cargo init --lib +---- + +[arabic] +. Add dependencies to `+Cargo.toml+`: ++ +[source,toml] +---- +[dependencies] +fslint-plugin-api = { path = "../../fslint-plugin-api" } +fslint-plugin-sdk = { path = "../../fslint-plugin-sdk" } +---- + +[arabic] +. Implement the `+Plugin+` trait in `+src/lib.rs+`: ++ +[source,rust] +---- +use fslint_plugin_api::{Plugin, PluginContext, PluginResult, PluginMetadata, PluginError}; + +pub struct MyPlugin; + +impl Plugin for MyPlugin { + fn metadata(&self) -> PluginMetadata { + PluginMetadata { + name: "my-plugin".into(), + version: "0.1.0".into(), + description: "My custom file intelligence plugin".into(), + author: Some("Your Name".into()), + enabled_by_default: false, + } + } + + fn check(&self, context: &PluginContext) -> Result { + // Your plugin logic here + Ok(PluginResult::active("my-plugin", "Found something interesting")) + } +} +---- + +See existing plugins for complete examples. + +== Roadmap + +=== v0.2.0 — Core Engine + +* [ ] Scanning engine with caching (`+fslint-core+`) +* [ ] CLI with `+scan+`, `+query+`, `+plugins+` subcommands +(`+fslint-cli+`) +* [ ] Parallel file scanning +* [ ] Core plugins: `+git-status+`, `+file-age+`, `+grouping+`, +`+bundle-check+` + +=== v0.3.0 — Extended Intelligence + +* [ ] WASM-based plugin runtime for cross-platform extensions +* [ ] Plugins: `+secret-scanner+`, `+ai-detection+`, +`+duplicate-finder+` +* [ ] macOS bundle collapsing (`+.app+` as single entity) +* [ ] Plugin configuration via TUI + +=== v1.0.0 — Stable + +* [ ] Shell extension integration (Nautilus, Dolphin, Finder, Explorer) +* [ ] Shadow navigation for symlinks +* [ ] Virtual filesystem across disks and cloud storage +* [ ] Malware scanner, licence detector, dependency analyser plugins + +== Licence + +MPL-2.0 (Palimpsest Licence) + +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + + +== Links + +* https://github.com/hyperpolymath/file-soup[GitHub Repository] +* https://github.com/hyperpolymath/file-soup/issues[Issue Tracker] diff --git a/README.md b/README.md deleted file mode 100644 index 8610cfb..0000000 --- a/README.md +++ /dev/null @@ -1,349 +0,0 @@ - - -FSLint is a high-performance, cross-platform file system linter designed -to make filesystems intelligible and navigable for real people. It -applies tiny, composable plugins to files and directories, transforming -scattered directory trees into logical, metadata-rich bundles — bringing -the cohesion of macOS `.app` packages to Linux and Windows. - -
- -
- -# Core Concept - -Modern operating systems scatter files across deep, opaque hierarchies. -Configuration lives in one place, data in another, caches in a third. -FSLint addresses this "file soup" by linting directory structures and -surfacing contextual metadata about every file and folder it encounters. - -**Contextual metadata** -Instant insights into git status, file age, duplicates, AI-generated -content, exposed secrets, and more. - -**Bundle-fication** -Logic to identify and treat complex multi-file directories as cohesive -single entities (like macOS `.app` bundles), so users see one logical -"thing" rather than a tree of fragments. - -**Query engine** -A CLI-first filtering language for slicing through results by filename, -extension, plugin tags, size thresholds, and plugin status. - -# Built-in Plugins - -FSLint ships with a set of core plugins for immediate filesystem -visibility. Each can be enabled or disabled individually. - -| Plugin | Default | Description | -|----|----|----| -| `git-status` | ✅ | Displays branch information and uncommitted changes for git-tracked files. | -| `file-age` | ✅ | Flags files modified within configurable thresholds (default: 7 days). | -| `grouping` | ✅ | Categorises files into types: Media, Dependencies, Source, Config, etc. | -| `bundle-check` | ✅ | Verifies whether a directory meets the criteria for a cohesive "Package." | -| `version-detection` | ❌ | Finds versioned files (`report_v1`, `file_final`, `backup_2`). | -| `ocr-status` | ❌ | Detects PDF text layers and OCR state. | -| `ai-detection` | ❌ | Identifies AI-generated content via EXIF metadata and heuristics. | -| `duplicate-finder` | ❌ | Hash-based duplicate detection across directories and volumes. | -| `secret-scanner` | ❌ | Scans for exposed API keys, credentials, and high-entropy strings. | - -# Quick Start - -## Installation - -```bash -git clone https://github.com/hyperpolymath/file-soup.git -cd file-soup -cargo build --release -# Binary at ./target/release/fslint -``` - -## Basic Usage - -```bash -# Scan current directory with default plugins -fslint scan - -# Output results as JSON -fslint scan --format json - -# Scan a specific directory -fslint scan /path/to/project - -# Simple output format (path + tags only) -fslint scan --format simple -``` - -## Querying - -```bash -# Find all Rust source files with uncommitted changes -fslint query "ext:rs git-status:Modified" - -# Find the newest config file -fslint query "name:config ext:toml newest:true" - -# Find large files tagged as media -fslint query "tag:media size_gt:1048576" - -# Find exposed secrets -fslint enable secret-scanner -fslint query "secret-scanner:Alert" -``` - -## Plugin Management - -```bash -# List all plugins and their status -fslint plugins - -# Enable a disabled plugin -fslint enable ai-detection - -# Disable a plugin -fslint disable grouping - -# View current configuration -fslint config -``` - -# Query Language - -FSLint supports a space-separated filter syntax. Combine filters freely: - -| Filter | Example | Description | -|----|----|----| -| `name:` | `name:config` | Match filename substring. | -| `ext:` | `ext:rs` | Match file extension. | -| `newest:true` | `newest:true` | Return only the most recent match. | -| `tag:` | `tag:media` | Match plugin-assigned tags. | -| `size_gt:` | `size_gt:1048576` | Files larger than threshold. | -| `size_lt:` | `size_lt:1024` | Files smaller than threshold. | -| `:` | `git-status:Modified` | Match specific plugin result. | - -```bash -fslint query "name:report ext:pdf newest:true" -``` - -# Architecture - -The project is structured as a Rust workspace with discrete crates -separating the plugin interface from the scanning engine and CLI. - -```text -file-soup/ -├── fslint-plugin-api/ # Plugin trait definitions and core types -├── fslint-plugin-sdk/ # Helper utilities for plugin authors -├── fslint-core/ # Scanning engine, query parser, caching (planned) -├── fslint-cli/ # CLI entry point and output formatting (planned) -└── plugins/ # Individual plugin crate modules (planned) - ├── git-status/ - ├── file-age/ - ├── grouping/ - ├── bundle-check/ - └── ... -``` - -## Current Implementation Status - -- **fslint-plugin-api** — Complete. Defines the `Plugin` trait, - `PluginContext`, `PluginResult`, `PluginStatus`, `PluginError`, and - `PluginMetadata` types. Includes builder methods and unit tests. - - - -- **fslint-plugin-sdk** — Substantially complete. Provides path helpers, - file metadata utilities (age, size formatting), regex-based pattern - matching for common file categories, and context helpers. Includes - tests and fuzzing. - - - -- **fslint-core** — Planned. Will contain the scanning engine with smart - caching (keyed on path, mtime, size), `.gitignore` support, - configurable max-depth, and the query parser. - - - -- **fslint-cli** — Planned. Will provide the `fslint` command with - `scan`, `query`, `plugins`, `enable`, `disable`, and `config` - subcommands. Multiple output formats: Table (default), JSON, Simple. - - - -- **plugins/** — Planned. Each plugin as its own crate, depending on - `fslint-plugin-api` and optionally `fslint-plugin-sdk`. - -# Output Formats - -## Table Format (Default) - -```text -File Git Age Group Other -───────────────────────────────────────────────────────────────────────────────── -src/main.rs Modified Today - - -package.json Clean This week - - -node_modules/react/index.js - - Node Dependencies - -``` - -## JSON Format - -```json -[ - { - "path": "/project/src/main.rs", - "size": 1234, - "results": [ - { - "plugin_name": "git-status", - "status": "Alert", - "message": "Modified", - "color": "yellow" - } - ] - } -] -``` - -## Simple Format - -```text -src/main.rs [Modified, Today] -package.json [Clean, This week] -node_modules/react/index.js [Node Dependencies] -``` - -# Configuration - -FSLint stores configuration at `~/.config/fslint/config.toml`: - -```toml -enabled_plugins = ["git-status", "file-age", "grouping", "bundle-check"] - -[scanner] -max_depth = 10 -include_hidden = false -follow_symlinks = false -respect_gitignore = true - -[plugin_config.file-age] -threshold_days = 7 - -[plugin_config.duplicate-finder] -min_size = 1024 - -[plugin_config.secret-scanner] -max_file_size = 1048576 -``` - -# Performance - -- **Smart caching**: Results cached by `(path,` `mtime,` `size)` — - unchanged files reuse cache on re-scan. - -- **Max depth**: Default limit of 10 levels prevents deep recursion into - `node_modules` and similar pits. - -- **.gitignore support**: Respects `.gitignore` by default, skipping - irrelevant files. - -- **Lazy execution**: Only enabled plugins run. - -# Plugin Development - -Create a new plugin in three steps: - -1. Create the plugin crate: - - ``` bash - mkdir plugins/my-plugin - cd plugins/my-plugin - cargo init --lib - ``` - - - -1. Add dependencies to `Cargo.toml`: - - ``` toml - [dependencies] - fslint-plugin-api = { path = "../../fslint-plugin-api" } - fslint-plugin-sdk = { path = "../../fslint-plugin-sdk" } - ``` - - - -1. Implement the `Plugin` trait in `src/lib.rs`: - - ``` rust - use fslint_plugin_api::{Plugin, PluginContext, PluginResult, PluginMetadata, PluginError}; - - pub struct MyPlugin; - - impl Plugin for MyPlugin { - fn metadata(&self) -> PluginMetadata { - PluginMetadata { - name: "my-plugin".into(), - version: "0.1.0".into(), - description: "My custom file intelligence plugin".into(), - author: Some("Your Name".into()), - enabled_by_default: false, - } - } - - fn check(&self, context: &PluginContext) -> Result { - // Your plugin logic here - Ok(PluginResult::active("my-plugin", "Found something interesting")) - } - } - ``` - -See existing plugins for complete examples. - -# Roadmap - -## v0.2.0 — Core Engine - -- [ ] Scanning engine with caching (`fslint-core`) - -- [ ] CLI with `scan`, `query`, `plugins` subcommands (`fslint-cli`) - -- [ ] Parallel file scanning - -- [ ] Core plugins: `git-status`, `file-age`, `grouping`, `bundle-check` - -## v0.3.0 — Extended Intelligence - -- [ ] WASM-based plugin runtime for cross-platform extensions - -- [ ] Plugins: `secret-scanner`, `ai-detection`, `duplicate-finder` - -- [ ] macOS bundle collapsing (`.app` as single entity) - -- [ ] Plugin configuration via TUI - -## v1.0.0 — Stable - -- [ ] Shell extension integration (Nautilus, Dolphin, Finder, Explorer) - -- [ ] Shadow navigation for symlinks - -- [ ] Virtual filesystem across disks and cloud storage - -- [ ] Malware scanner, licence detector, dependency analyser plugins - -# Licence - -MPL-2.0 (Palimpsest Licence) - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -\<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> - -# Links - -- [GitHub Repository](https://github.com/hyperpolymath/file-soup) - -- [Issue Tracker](https://github.com/hyperpolymath/file-soup/issues) diff --git a/RSR_COMPLIANCE.adoc b/RSR_COMPLIANCE.adoc index 6301755..c762c25 100644 --- a/RSR_COMPLIANCE.adoc +++ b/RSR_COMPLIANCE.adoc @@ -29,17 +29,17 @@ This document describes the Rhodium Standard Repository (RSR) compliance status * Zig * Ada * Haskell -* ReScript +* AffineScript === Tier 2 Languages (Acceptable) * Nickel (configuration) * Racket (scripting) * Guile Scheme (state management) -* Nix (derivations) +* Guix (derivations) === Restricted Languages * Python - Only allowed in salt/ directories for SaltStack -* TypeScript/JavaScript - Legacy only, convert to ReScript +* TypeScript/JavaScript - Legacy only, convert to AffineScript * CUE - Not permitted, use Nickel or Guile == Compliance Checklist @@ -55,7 +55,7 @@ This document describes the Rhodium Standard Repository (RSR) compliance status |justfile present |✓ | |LICENSE.txt (AGPL + Palimpsest) |✗ | |Containerfile present |✓ | -|flake.nix present |✓ | +|flake.guix present |✓ | |=== == Exemptions diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..325ac3f --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/filesoup/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[width="100%",cols="50%,50%",] +|=== +|*Email* |j.d.a.jewell@open.ac.uk +|*PGP Key* |https://hyperpolymath.github.io/pgp.asc[Download Public Key] +|*Fingerprint* |`+TBD+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import + +# Verify fingerprint +gpg --fingerprint j.d.a.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/filesoup+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/filesoup/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using filesoup, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://hyperpolymath.github.io/pgp.asc[Our PGP Public Key] +* https://github.com/hyperpolymath/filesoup/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/filesoup/security/advisories/new[Report +via GitHub] or j.d.a.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/filesoup/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep filesoup and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9109eaf..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,388 +0,0 @@ -# Security Policy - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/filesoup/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | j.d.a.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key](https://hyperpolymath.github.io/pgp.asc) | -| **Fingerprint** | `TBD` | - -```bash -# Import our PGP key -curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint j.d.a.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/filesoup`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/filesoup/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using filesoup, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key](https://hyperpolymath.github.io/pgp.asc) -- [Security Advisories](https://github.com/hyperpolymath/filesoup/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/filesoup/security/advisories/new) or j.d.a.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/filesoup/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep filesoup and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..a1c1dd7 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,108 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +* Unit tests: 1 integration test file +(file-soup/crates/fslint-cli/tests/integration_test.rs) — count unknown +(cannot build) +* Integration tests: 1 +* E2E tests: NONE +* Benchmarks: 1 file exists (unverified) +* panic-attack scan: NEVER RUN + +=== What’s Missing + +==== Point-to-Point (P2P) + +27 Rust source files across multiple crates with only 1 test file: + +===== fslint-plugin-api/ (top-level): + +* src/lib.rs — no tests +* fuzz/fuzz_targets/fuzz_main.rs — fuzzer exists (verify it runs) + +===== fslint-plugin-sdk/ (top-level): + +* src/lib.rs — no tests +* fuzz/fuzz_targets/fuzz_main.rs — fuzzer exists (verify it runs) + +===== file-soup/ (main project): + +*Plugins (8 plugins, 0 tests each):* - plugins/grouping/src/lib.rs — no +tests - plugins/ocr-status/src/lib.rs — no tests - +plugins/secret-scanner/src/lib.rs — no tests - +plugins/version-detection/src/lib.rs — no tests - +plugins/ai-detection/src/lib.rs — no tests - +plugins/duplicate-finder/src/lib.rs — no tests - +plugins/file-age/src/lib.rs — no tests - plugins/git-status/src/lib.rs — +no tests + +*Core crates:* - crates/fslint-plugin-api/src/lib.rs — no tests - +crates/fslint-plugin-sdk/src/lib.rs — no tests - +crates/fslint-cli/src/commands.rs — no tests - +crates/fslint-cli/src/main.rs — no tests - +crates/fslint-cli/src/output.rs — no tests - +crates/fslint-cli/src/query.rs — no tests - +crates/fslint-cli/tests/integration_test.rs — 1 test file + +==== End-to-End (E2E) + +* CLI: scan directory -> detect files -> apply plugins -> generate +report +* Plugin lifecycle: load plugin -> configure -> execute -> report +* Each plugin: provide input -> process -> verify output +* Query: define query -> execute against scan results -> verify +* Duplicate finder accuracy on known duplicate sets +* Secret scanner on known secret patterns +* OCR status on known image files + +==== Aspect Tests + +* [ ] Security (secret-scanner false negatives, path traversal, plugin +sandboxing) +* [ ] Performance (large directory scanning, duplicate detection at +scale) +* [ ] Concurrency (parallel plugin execution, concurrent file access) +* [ ] Error handling (missing files, permission errors, corrupt files) +* [ ] Accessibility (CLI output formatting) + +==== Build & Execution + +* [ ] cargo build — not verified +* [ ] cargo test — not verified +* [ ] CLI –help works — not verified +* [ ] Plugin loading works — not verified +* [ ] Fuzz targets run — not verified +* [ ] Self-diagnostic — none + +==== Benchmarks Needed + +* Directory scan throughput (files/second) +* Per-plugin execution time +* Duplicate detection performance vs file count +* Secret scanning throughput +* Memory usage on large directory trees + +==== Self-Tests + +* [ ] panic-attack assail on own repo +* [ ] CLI self-test with known test data +* [ ] Each plugin smoke test + +=== Priority + +* *HIGH* — 27 Rust source files (8 plugins + CLI + API + SDK) with only +1 integration test. The secret-scanner plugin having ZERO tests is +especially concerning — false negatives in secret scanning are a +security risk. Fuzz targets exist for the API/SDK but need verification. +Each of the 8 plugins needs at least basic correctness tests. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 89e0b9c..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,87 +0,0 @@ -# Test & Benchmark Requirements - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State -- Unit tests: 1 integration test file (file-soup/crates/fslint-cli/tests/integration_test.rs) — count unknown (cannot build) -- Integration tests: 1 -- E2E tests: NONE -- Benchmarks: 1 file exists (unverified) -- panic-attack scan: NEVER RUN - -## What's Missing -### Point-to-Point (P2P) -27 Rust source files across multiple crates with only 1 test file: - -#### fslint-plugin-api/ (top-level): -- src/lib.rs — no tests -- fuzz/fuzz_targets/fuzz_main.rs — fuzzer exists (verify it runs) - -#### fslint-plugin-sdk/ (top-level): -- src/lib.rs — no tests -- fuzz/fuzz_targets/fuzz_main.rs — fuzzer exists (verify it runs) - -#### file-soup/ (main project): -**Plugins (8 plugins, 0 tests each):** -- plugins/grouping/src/lib.rs — no tests -- plugins/ocr-status/src/lib.rs — no tests -- plugins/secret-scanner/src/lib.rs — no tests -- plugins/version-detection/src/lib.rs — no tests -- plugins/ai-detection/src/lib.rs — no tests -- plugins/duplicate-finder/src/lib.rs — no tests -- plugins/file-age/src/lib.rs — no tests -- plugins/git-status/src/lib.rs — no tests - -**Core crates:** -- crates/fslint-plugin-api/src/lib.rs — no tests -- crates/fslint-plugin-sdk/src/lib.rs — no tests -- crates/fslint-cli/src/commands.rs — no tests -- crates/fslint-cli/src/main.rs — no tests -- crates/fslint-cli/src/output.rs — no tests -- crates/fslint-cli/src/query.rs — no tests -- crates/fslint-cli/tests/integration_test.rs — 1 test file - -### End-to-End (E2E) -- CLI: scan directory -> detect files -> apply plugins -> generate report -- Plugin lifecycle: load plugin -> configure -> execute -> report -- Each plugin: provide input -> process -> verify output -- Query: define query -> execute against scan results -> verify -- Duplicate finder accuracy on known duplicate sets -- Secret scanner on known secret patterns -- OCR status on known image files - -### Aspect Tests -- [ ] Security (secret-scanner false negatives, path traversal, plugin sandboxing) -- [ ] Performance (large directory scanning, duplicate detection at scale) -- [ ] Concurrency (parallel plugin execution, concurrent file access) -- [ ] Error handling (missing files, permission errors, corrupt files) -- [ ] Accessibility (CLI output formatting) - -### Build & Execution -- [ ] cargo build — not verified -- [ ] cargo test — not verified -- [ ] CLI --help works — not verified -- [ ] Plugin loading works — not verified -- [ ] Fuzz targets run — not verified -- [ ] Self-diagnostic — none - -### Benchmarks Needed -- Directory scan throughput (files/second) -- Per-plugin execution time -- Duplicate detection performance vs file count -- Secret scanning throughput -- Memory usage on large directory trees - -### Self-Tests -- [ ] panic-attack assail on own repo -- [ ] CLI self-test with known test data -- [ ] Each plugin smoke test - -## Priority -- **HIGH** — 27 Rust source files (8 plugins + CLI + API + SDK) with only 1 integration test. The secret-scanner plugin having ZERO tests is especially concerning — false negatives in secret scanning are a security risk. Fuzz targets exist for the API/SDK but need verification. Each of the 8 plugins needs at least basic correctness tests. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 91% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 212f3c6..4ff6f47 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== FSLint — Project Topology -# FSLint — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌───────────────────────────────────────────────┐ │ fslint-cli │ │ scan · query · plugins · enable · disable │ @@ -51,11 +47,11 @@ │ .bot_directives/ 0-AI-MANIFEST.a2ml │ │ contractiles/ .github/workflows/ │ └───────────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── PLUGIN FOUNDATION @@ -86,11 +82,11 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██░░░░░░░░ ~25% Plugin API/SDK stable, engine next -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... fslint-cli ──────► fslint-core ──────► fslint-plugin-api │ ▲ ▼ │ @@ -98,26 +94,27 @@ fslint-cli ──────► fslint-core ──────► fslint-plugin │ ▼ Filesystem -``` +.... -## Output Flow +=== Output Flow -``` +.... Filesystem ──► Scanner ──► Plugins ──► Cache ──► Query ──► Formatter ──► User │ ┌──────────┼──────────┐ ▼ ▼ ▼ Table JSON Simple -``` +.... -## 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/PLUGIN_DEVELOPMENT.md b/docs/PLUGIN_DEVELOPMENT.adoc similarity index 64% rename from docs/PLUGIN_DEVELOPMENT.md rename to docs/PLUGIN_DEVELOPMENT.adoc index ff8d478..704d969 100644 --- a/docs/PLUGIN_DEVELOPMENT.md +++ b/docs/PLUGIN_DEVELOPMENT.adoc @@ -1,51 +1,51 @@ - -# Plugin Development Guide +== Plugin Development Guide This guide walks you through creating custom plugins for FSLint. -## Table of Contents +=== Table of Contents -- [Plugin Architecture](#plugin-architecture) -- [Creating Your First Plugin](#creating-your-first-plugin) -- [Plugin API Reference](#plugin-api-reference) -- [Advanced Features](#advanced-features) -- [Testing Plugins](#testing-plugins) -- [Best Practices](#best-practices) -- [Examples](#examples) +* link:#plugin-architecture[Plugin Architecture] +* link:#creating-your-first-plugin[Creating Your First Plugin] +* link:#plugin-api-reference[Plugin API Reference] +* link:#advanced-features[Advanced Features] +* link:#testing-plugins[Testing Plugins] +* link:#best-practices[Best Practices] +* link:#examples[Examples] -## Plugin Architecture +=== Plugin Architecture -FSLint uses a trait-based plugin system where each plugin implements the `Plugin` trait from `fslint-plugin-api`. +FSLint uses a trait-based plugin system where each plugin implements the +`+Plugin+` trait from `+fslint-plugin-api+`. -### Plugin Lifecycle +==== Plugin Lifecycle -1. **Registration**: Plugin registered with `PluginLoader` -2. **Initialization**: `initialize()` called with configuration -3. **Execution**: `check()` called for each file -4. **Cleanup**: `cleanup()` called when disabled +[arabic] +. *Registration*: Plugin registered with `+PluginLoader+` +. *Initialization*: `+initialize()+` called with configuration +. *Execution*: `+check()+` called for each file +. *Cleanup*: `+cleanup()+` called when disabled -### Core Components +==== Core Components -- **PluginContext**: Input data (file path, metadata, working directory) -- **PluginResult**: Output data (status, message, color, tags) -- **PluginMetadata**: Plugin information (name, version, description) -- **PluginError**: Error types for plugin failures +* *PluginContext*: Input data (file path, metadata, working directory) +* *PluginResult*: Output data (status, message, color, tags) +* *PluginMetadata*: Plugin information (name, version, description) +* *PluginError*: Error types for plugin failures -## Creating Your First Plugin +=== Creating Your First Plugin -### Step 1: Create Plugin Structure +==== Step 1: Create Plugin Structure -```bash +[source,bash] +---- mkdir -p plugins/hello-world/src cd plugins/hello-world -``` +---- -### Step 2: Create Cargo.toml +==== Step 2: Create Cargo.toml -```toml +[source,toml] +---- [package] name = "fslint-plugin-hello-world" version = "0.1.0" @@ -57,13 +57,14 @@ fslint-plugin-sdk = { path = "../../crates/fslint-plugin-sdk" } [lib] crate-type = ["cdylib", "rlib"] -``` +---- -### Step 3: Implement Plugin +==== Step 3: Implement Plugin -Create `src/lib.rs`: +Create `+src/lib.rs+`: -```rust +[source,rust] +---- use fslint_plugin_api::{Plugin, PluginContext, PluginError, PluginMetadata, PluginResult}; use fslint_plugin_sdk::path; use std::collections::HashMap; @@ -135,38 +136,42 @@ mod tests { assert_eq!(result.status, fslint_plugin_api::PluginStatus::Active); } } -``` +---- -### Step 4: Register Plugin +==== Step 4: Register Plugin -Add to root `Cargo.toml`: +Add to root `+Cargo.toml+`: -```toml +[source,toml] +---- members = [ # ... existing members "plugins/hello-world", ] -``` +---- -Add dependency to `crates/fslint-cli/Cargo.toml`: +Add dependency to `+crates/fslint-cli/Cargo.toml+`: -```toml +[source,toml] +---- [dependencies] fslint-plugin-hello-world = { path = "../../plugins/hello-world" } -``` +---- -Register in `crates/fslint-cli/src/commands.rs`: +Register in `+crates/fslint-cli/src/commands.rs+`: -```rust +[source,rust] +---- loader.register( fslint_plugin_hello_world::HelloWorldPlugin::new(), fslint_plugin_hello_world::HelloWorldPlugin::metadata() ); -``` +---- -### Step 5: Build and Test +==== Step 5: Build and Test -```bash +[source,bash] +---- # Build the plugin cargo build -p fslint-plugin-hello-world @@ -176,24 +181,26 @@ cargo test -p fslint-plugin-hello-world # Try it out cargo run -- enable hello-world cargo run -- scan . -``` +---- -## Plugin API Reference +=== Plugin API Reference -### PluginContext +==== PluginContext -```rust +[source,rust] +---- pub struct PluginContext { pub path: PathBuf, // File path pub metadata: std::fs::Metadata, // File metadata pub working_dir: PathBuf, // Working directory pub shared_context: HashMap, // Shared data } -``` +---- -### PluginResult +==== PluginResult -```rust +[source,rust] +---- pub struct PluginResult { pub plugin_name: String, pub status: PluginStatus, @@ -202,20 +209,21 @@ pub struct PluginResult { pub tags: Vec, pub metadata: HashMap, } -``` +---- -#### PluginStatus Variants +===== PluginStatus Variants -- `Active`: Plugin found something noteworthy -- `Inactive`: Plugin not applicable -- `Alert`: Warning level finding -- `Warning`: Important issue found -- `Error`: Critical issue found -- `Skipped`: Plugin skipped execution +* `+Active+`: Plugin found something noteworthy +* `+Inactive+`: Plugin not applicable +* `+Alert+`: Warning level finding +* `+Warning+`: Important issue found +* `+Error+`: Critical issue found +* `+Skipped+`: Plugin skipped execution -#### Builder Methods +===== Builder Methods -```rust +[source,rust] +---- // Create active result PluginResult::active("plugin-name", "message") @@ -236,11 +244,12 @@ result.with_tags(vec!["tag1".into(), "tag2".into()]) // Add metadata result.with_metadata("key", "value") -``` +---- -### PluginError +==== PluginError -```rust +[source,rust] +---- pub enum PluginError { Io(std::io::Error), Config(String), @@ -248,13 +257,14 @@ pub enum PluginError { NotApplicable(String), ExternalDependency(String), } -``` +---- -## Advanced Features +=== Advanced Features -### Configuration Support +==== Configuration Support -```rust +[source,rust] +---- impl Plugin for MyPlugin { fn initialize(&mut self, config: &HashMap) -> Result<(), PluginError> { if let Some(threshold) = config.get("threshold") { @@ -264,17 +274,20 @@ impl Plugin for MyPlugin { Ok(()) } } -``` +---- Config file: -```toml + +[source,toml] +---- [plugin_config.my-plugin] threshold = "100" -``` +---- -### Cleanup Support +==== Cleanup Support -```rust +[source,rust] +---- impl Plugin for MyPlugin { fn cleanup(&mut self) -> Result<(), PluginError> { // Clean up resources @@ -282,11 +295,12 @@ impl Plugin for MyPlugin { Ok(()) } } -``` +---- -### Using SDK Helpers +==== Using SDK Helpers -```rust +[source,rust] +---- use fslint_plugin_sdk::{path, metadata, patterns}; // Get file extension @@ -299,11 +313,12 @@ let days = metadata::age_in_days(context.metadata.modified()?); if patterns::matches(&context.path, &patterns::Patterns::image_files()) { // Handle image file } -``` +---- -### Shared Context +==== Shared Context -```rust +[source,rust] +---- // Set shared context context.shared_context.insert("key".to_string(), "value".to_string()); @@ -311,13 +326,14 @@ context.shared_context.insert("key".to_string(), "value".to_string()); if let Some(value) = context.shared_context.get("other-plugin-key") { // Use value } -``` +---- -## Testing Plugins +=== Testing Plugins -### Unit Tests +==== Unit Tests -```rust +[source,rust] +---- #[cfg(test)] mod tests { use super::*; @@ -344,13 +360,14 @@ mod tests { assert_eq!(result.status, PluginStatus::Active); } } -``` +---- -### Integration Tests +==== Integration Tests -Create `tests/integration_test.rs`: +Create `+tests/integration_test.rs+`: -```rust +[source,rust] +---- use fslint_core::{PluginLoader, Scanner, ScannerConfig}; use fslint_plugin_my_plugin::MyPlugin; @@ -366,37 +383,43 @@ fn test_plugin_integration() { let results = scanner.scan(".").unwrap(); assert!(!results.is_empty()); } -``` - -## Best Practices - -### Performance +---- -1. **Early Returns**: Skip files that don't match - ```rust - if !should_process(&context.path) { - return Ok(PluginResult::skipped("plugin")); - } - ``` +=== Best Practices -2. **Caching**: Cache expensive computations - ```rust - lazy_static! { - static ref CACHE: Mutex> = Mutex::new(HashMap::new()); - } - ``` +==== Performance -3. **Limit File Size**: Don't process huge files - ```rust - const MAX_SIZE: u64 = 10 * 1024 * 1024; // 10MB - if context.metadata.len() > MAX_SIZE { - return Ok(PluginResult::skipped("plugin")); - } - ``` +[arabic] +. *Early Returns*: Skip files that don’t match ++ +[source,rust] +---- +if !should_process(&context.path) { + return Ok(PluginResult::skipped("plugin")); +} +---- +. *Caching*: Cache expensive computations ++ +[source,rust] +---- +lazy_static! { + static ref CACHE: Mutex> = Mutex::new(HashMap::new()); +} +---- +. *Limit File Size*: Don’t process huge files ++ +[source,rust] +---- +const MAX_SIZE: u64 = 10 * 1024 * 1024; // 10MB +if context.metadata.len() > MAX_SIZE { + return Ok(PluginResult::skipped("plugin")); +} +---- -### Error Handling +==== Error Handling -```rust +[source,rust] +---- // Good: Provide context .map_err(|e| PluginError::Execution( format!("Failed to read {}: {}", path.display(), e) @@ -404,11 +427,12 @@ fn test_plugin_integration() { // Bad: Generic errors .map_err(|e| PluginError::Execution(e.to_string()))? -``` +---- -### Resource Management +==== Resource Management -```rust +[source,rust] +---- impl Plugin for MyPlugin { fn cleanup(&mut self) -> Result<(), PluginError> { // Always cleanup resources @@ -417,39 +441,39 @@ impl Plugin for MyPlugin { Ok(()) } } -``` +---- -## Examples +=== Examples See existing plugins for complete examples: -- **Simple**: `plugins/file-age/` - Basic plugin with SDK helpers -- **Pattern Matching**: `plugins/grouping/` - Regex patterns -- **External Deps**: `plugins/git-status/` - Using git2 -- **Complex Logic**: `plugins/secret-scanner/` - Multiple patterns -- **Caching**: `plugins/duplicate-finder/` - Global state +* *Simple*: `+plugins/file-age/+` - Basic plugin with SDK helpers +* *Pattern Matching*: `+plugins/grouping/+` - Regex patterns +* *External Deps*: `+plugins/git-status/+` - Using git2 +* *Complex Logic*: `+plugins/secret-scanner/+` - Multiple patterns +* *Caching*: `+plugins/duplicate-finder/+` - Global state -## Troubleshooting +=== Troubleshooting -### Plugin Not Loading +==== Plugin Not Loading -- Check plugin is in workspace `Cargo.toml` -- Verify registration in `commands.rs` -- Ensure plugin compiles: `cargo build -p plugin-name` +* Check plugin is in workspace `+Cargo.toml+` +* Verify registration in `+commands.rs+` +* Ensure plugin compiles: `+cargo build -p plugin-name+` -### Plugin Not Executing +==== Plugin Not Executing -- Check if enabled: `fslint plugins` -- Enable: `fslint enable plugin-name` -- Check filter logic in `check()` +* Check if enabled: `+fslint plugins+` +* Enable: `+fslint enable plugin-name+` +* Check filter logic in `+check()+` -### Performance Issues +==== Performance Issues -- Profile with `cargo flamegraph` -- Add early returns -- Implement caching -- Reduce file operations +* Profile with `+cargo flamegraph+` +* Add early returns +* Implement caching +* Reduce file operations ---- +''''' Happy plugin development! 🎉 diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.adoc similarity index 67% rename from docs/QUICKSTART.md rename to docs/QUICKSTART.adoc index 8a31c37..d2d6e24 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.adoc @@ -1,52 +1,56 @@ - -# FSLint Quickstart Guide +== FSLint Quickstart Guide Get up and running with FSLint in 5 minutes! -## Installation +=== Installation -### From crates.io (Recommended) +==== From crates.io (Recommended) -```bash +[source,bash] +---- cargo install fslint -``` +---- -### From Source +==== From Source -```bash +[source,bash] +---- git clone https://github.com/Hyperpolymath/file-soup.git cd file-soup cargo build --release sudo cp target/release/fslint /usr/local/bin/ -``` +---- -### Using Installation Script +==== Using Installation Script -**Linux/macOS:** -```bash +*Linux/macOS:* + +[source,bash] +---- curl -sSL https://raw.githubusercontent.com/Hyperpolymath/file-soup/main/scripts/install.sh | bash -``` +---- + +*Windows (PowerShell):* -**Windows (PowerShell):** -```powershell +[source,powershell] +---- iwr https://raw.githubusercontent.com/Hyperpolymath/file-soup/main/scripts/install.ps1 | iex -``` +---- -### Using Docker +==== Using Docker -```bash +[source,bash] +---- docker pull fslint/fslint:latest docker run -v $(pwd):/scan fslint/fslint scan /scan -``` +---- -## First Steps +=== First Steps -### 1. Scan a Directory +==== 1. Scan a Directory -```bash +[source,bash] +---- # Scan current directory fslint scan @@ -56,16 +60,18 @@ fslint scan ~/projects/myproject # Different output formats fslint scan --format json fslint scan --format simple -``` +---- -### 2. List Available Plugins +==== 2. List Available Plugins -```bash +[source,bash] +---- fslint plugins -``` +---- Output: -``` + +.... Plugin Status Description ---------------------------------------------------------------------------------------- git-status enabled Shows git repository status and branch info @@ -73,11 +79,12 @@ file-age enabled Highlights recently modified files (< 7 day grouping enabled Categorizes files (node_modules, media, etc.) version-detection disabled Detects versioned files ... -``` +.... -### 3. Enable/Disable Plugins +==== 3. Enable/Disable Plugins -```bash +[source,bash] +---- # Enable a plugin fslint enable secret-scanner @@ -86,11 +93,12 @@ fslint disable grouping # View current configuration fslint config -``` +---- -### 4. Query Files +==== 4. Query Files -```bash +[source,bash] +---- # Find all TypeScript files fslint query "ext:ts" @@ -102,13 +110,14 @@ fslint query "name:report newest:true" # Combine filters fslint query "ext:pdf size_gt:1048576" -``` +---- -## Common Use Cases +=== Common Use Cases -### Security Audit +==== Security Audit -```bash +[source,bash] +---- # Enable secret scanner fslint enable secret-scanner @@ -117,11 +126,12 @@ fslint scan --format table # Check specific directory fslint scan ./src --format json > security-audit.json -``` +---- -### Find Duplicates +==== Find Duplicates -```bash +[source,bash] +---- # Enable duplicate finder fslint enable duplicate-finder @@ -130,11 +140,12 @@ fslint scan # Find large duplicates only fslint query "tag:duplicate size_gt:10485760" -``` +---- -### Git Status Overview +==== Git Status Overview -```bash +[source,bash] +---- # Default scan shows git status fslint scan @@ -143,11 +154,12 @@ fslint query "git-status:Modified" # Find new files fslint query "git-status:New" -``` +---- -### Find AI-Generated Images +==== Find AI-Generated Images -```bash +[source,bash] +---- # Enable AI detection fslint enable ai-detection @@ -156,32 +168,34 @@ fslint scan ./images # Query for AI content fslint query "tag:ai" -``` +---- -### Clean Up Old Files +==== Clean Up Old Files -```bash +[source,bash] +---- # Find recent files (modified in last 7 days) fslint query "tag:age" # Find old files fslint scan --format table # Look for files without the "Recent" tag -``` +---- -## Configuration +=== Configuration -### Configuration File Location +==== Configuration File Location -FSLint stores configuration at: -- Linux/macOS: `~/.config/fslint/config.toml` -- Windows: `%APPDATA%\fslint\config.toml` +FSLint stores configuration at: - Linux/macOS: +`+~/.config/fslint/config.toml+` - Windows: +`+%APPDATA%\fslint\config.toml+` -### Example Configurations +==== Example Configurations Copy example configs: -```bash +[source,bash] +---- # Minimal configuration cp examples/config-minimal.toml ~/.config/fslint/config.toml @@ -193,13 +207,14 @@ cp examples/config-security.toml ~/.config/fslint/config.toml # Development configuration cp examples/config-development.toml ~/.config/fslint/config.toml -``` +---- -### Custom Configuration +==== Custom Configuration -Edit `~/.config/fslint/config.toml`: +Edit `+~/.config/fslint/config.toml+`: -```toml +[source,toml] +---- enabled_plugins = ["git-status", "file-age", "secret-scanner"] [scanner] @@ -209,45 +224,49 @@ respect_gitignore = true [plugin_config.secret-scanner] max_file_size = "5242880" -``` +---- -## Tips & Tricks +=== Tips & Tricks -### 1. Use Aliases +==== 1. Use Aliases -Add to your `.bashrc` or `.zshrc`: +Add to your `+.bashrc+` or `+.zshrc+`: -```bash +[source,bash] +---- alias fs='fslint scan' alias fsp='fslint plugins' alias fsq='fslint query' -``` +---- -### 2. Pipe to Other Tools +==== 2. Pipe to Other Tools -```bash +[source,bash] +---- # Count files by type fslint scan --format simple | grep '\.rs$' | wc -l # Find and open modified files fslint query "git-status:Modified" --format simple | xargs code -``` +---- -### 3. Integrate with Git Hooks +==== 3. Integrate with Git Hooks -Create `.git/hooks/pre-commit`: +Create `+.git/hooks/pre-commit+`: -```bash +[source,bash] +---- #!/bin/bash fslint enable secret-scanner fslint scan --format simple | grep "secret" && exit 1 -``` +---- -### 4. CI/CD Integration +==== 4. CI/CD Integration Add to your CI pipeline: -```yaml +[source,yaml] +---- # GitHub Actions example - name: Scan for secrets run: | @@ -260,13 +279,14 @@ Add to your CI pipeline: with: name: fslint-results path: scan-results.json -``` +---- -### 5. Docker Compose for Projects +==== 5. Docker Compose for Projects -Add `docker-compose.yml`: +Add `+docker-compose.yml+`: -```yaml +[source,yaml] +---- version: '3.8' services: fslint: @@ -274,23 +294,27 @@ services: volumes: - ./:/scan:ro command: scan /scan --format table -``` +---- Run with: -```bash + +[source,bash] +---- docker-compose run fslint -``` +---- -## Next Steps +=== Next Steps -- Read the [full documentation](../README.md) -- Learn about [plugin development](PLUGIN_DEVELOPMENT.md) -- Check out [contributing guidelines](../CONTRIBUTING.md) -- Report issues on [GitHub](https://github.com/Hyperpolymath/file-soup/issues) +* Read the link:../README.md[full documentation] +* Learn about link:PLUGIN_DEVELOPMENT.md[plugin development] +* Check out link:../CONTRIBUTING.md[contributing guidelines] +* Report issues on +https://github.com/Hyperpolymath/file-soup/issues[GitHub] -## Getting Help +=== Getting Help -```bash +[source,bash] +---- # General help fslint --help @@ -300,34 +324,37 @@ fslint query --help # Version information fslint --version -``` +---- -## Troubleshooting +=== Troubleshooting -### "Permission denied" errors +==== "`Permission denied`" errors -```bash +[source,bash] +---- # Run with sudo if needed sudo fslint scan /system/directory # Or scan with user permissions fslint scan ~/myproject -``` +---- -### Slow scanning +==== Slow scanning -```bash +[source,bash] +---- # Reduce max depth fslint scan --max-depth 5 # Disable expensive plugins fslint disable duplicate-finder fslint disable ai-detection -``` +---- -### Plugin not working +==== Plugin not working -```bash +[source,bash] +---- # Check plugin status fslint plugins @@ -336,8 +363,8 @@ fslint enable plugin-name # Check configuration fslint config -``` +---- ---- +''''' -**Happy scanning! 🚀** +*Happy scanning! 🚀* diff --git a/docs/RSR_COMPLIANCE.adoc b/docs/RSR_COMPLIANCE.adoc new file mode 100644 index 0000000..bad8b11 --- /dev/null +++ b/docs/RSR_COMPLIANCE.adoc @@ -0,0 +1,324 @@ +== RSR Framework Compliance + +FSLint conforms to the *Rhodium Standard Repository (RSR) Framework* at +*Gold Tier* level. + +=== What is RSR? + +The Rhodium Standard Repository Framework is a comprehensive set of +standards for software projects that emphasizes: + +* *Type Safety* & *Memory Safety* +* *Offline-First* design +* *Complete Documentation* +* *Reproducible Builds* +* *Community Governance* (TPCF) +* *Security Best Practices* (RFC 9116) + +See https://github.com/example/rhodium-minimal[rhodium-minimal example] +for reference implementation. + +=== FSLint Compliance Status + +==== ✅ Gold Tier Achieved + +Run verification: `+./scripts/verify-rsr.sh+` + +[source,bash] +---- +just validate # Or: make ci && ./scripts/verify-rsr.sh +---- + +=== RSR Categories + +==== 1. Type Safety ✅ + +* *Language*: Rust with compile-time type guarantees +* *No Dynamic Types*: No JavaScript/TypeScript/Python +* *Strong Typing*: Leverages Rust’s type system throughout + +*Evidence*: - All code in Rust (`+Cargo.toml+`, `+src/**/*.rs+`) - +Compiler enforces type correctness - No `+any+` types or dynamic typing + +==== 2. Memory Safety ✅ + +* *Ownership Model*: Rust’s borrow checker prevents memory errors +* *No Unsafe*: Minimal to zero unsafe blocks +* *No Segfaults*: Memory safety guaranteed by compiler + +*Evidence*: - Rust’s ownership system - `+cargo clippy+` passes with no +unsafe warnings - Zero buffer overflows possible + +==== 3. Offline-First ✅ + +* *No Network Calls*: FSLint works completely offline +* *Air-Gapped Compatible*: All operations are local +* *Local Storage*: Config at `+~/.config/fslint/+` + +*Evidence*: - No network dependencies in `+Cargo.toml+` - Scanner +operates on local filesystem only - Works without internet connection + +==== 4. Documentation ✅ + +*Required Files* (all present): - ✅ `+README.md+` - Comprehensive +project documentation - ✅ `+LICENSE-MIT+` - MIT License - ✅ +`+LICENSE-APACHE+` - Apache License 2.0 - ✅ `+LICENSE-PALIMPSEST+` - +MPL-2.0 v0.8 (experimental) - ✅ `+SECURITY.md+` - Security policy and +reporting - ✅ `+CONTRIBUTING.md+` - Contribution guidelines - ✅ +`+CODE_OF_CONDUCT.md+` - Community standards - ✅ `+MAINTAINERS.md+` - +Project governance - ✅ `+CHANGELOG.md+` - Version history + +*Additional Documentation*: - ✅ `+docs/QUICKSTART.md+` - 5-minute +getting started - ✅ `+docs/PLUGIN_DEVELOPMENT.md+` - Plugin creation +guide - ✅ `+docs/TPCF.md+` - Contribution framework - ✅ +`+PROJECT_SUMMARY.md+` - Complete project overview + +==== 5. .well-known/ Directory ✅ + +*RFC 9116 Compliance*: - ✅ `+.well-known/security.txt+` - Security +contact info - ✅ `+.well-known/ai.txt+` - AI training policy - ✅ +`+.well-known/humans.txt+` - Attribution and credits + +*Evidence*: + +[source,bash] +---- +$ cat .well-known/security.txt | head -5 +# Canonical: https://github.com/Hyperpolymath/file-soup/.well-known/security.txt +# Expires: 2026-11-22T00:00:00.000Z + +Contact: mailto:security@fslint.org +Contact: https://github.com/Hyperpolymath/file-soup/security/advisories/new +---- + +==== 6. Build System ✅ + +*Multiple Build Options*: - ✅ `+Cargo.toml+` - Rust workspace +configuration - ✅ `+justfile+` - Just command runner (20+ recipes) - ✅ +`+Makefile+` - Traditional make support - ✅ `+flake.guix+` - Guix +reproducible builds - ✅ `+.github/workflows/ci.yml+` - CI/CD automation + +*Reproducible Builds*: - ✅ `+Cargo.lock+` committed - ✅ Guix flake for +deterministic builds - ✅ Pinned dependencies + +*Evidence*: + +[source,bash] +---- +$ just --list # Lists 40+ development commands +$ guix build # Reproducible Guix build +$ make ci # Traditional make interface +---- + +==== 7. Testing ✅ + +*Test Coverage*: - ✅ Unit tests in all crates - ✅ Integration tests +for CLI - ✅ Benchmark suite (Criterion) - ✅ 100% test pass rate + +*Evidence*: + +[source,bash] +---- +$ cargo test --workspace +running 47 tests +test result: ok. 47 passed; 0 failed + +$ cargo bench +Scanner/scan_100_files time: [45.2 ms 45.8 ms 46.4 ms] +---- + +==== 8. TPCF (Tri-Perimeter Contribution Framework) ✅ + +*Perimeter Assignment*: *Perimeter 3 (Community Sandbox)* + +* *Status*: OPEN - Anyone can contribute +* *Access*: Fork, PR, issues, discussions +* *Documentation*: See `+docs/TPCF.md+` + +*Graduated Trust Model*: 1. *Perimeter 3*: Community Sandbox (Open) 2. +*Perimeter 2*: Blessed Garden (Earned) 3. *Perimeter 1*: Inner Sanctum +(Core Team) + +*Evidence*: - `+docs/TPCF.md+` fully documents the framework - +`+MAINTAINERS.md+` lists current perimeter assignments - Contribution +guidelines reference TPCF + +==== 9. Code Quality ✅ + +*Linting & Formatting*: - ✅ `+rustfmt+` - Code formatting - ✅ +`+clippy+` - Lint checks - ✅ Zero warnings in CI + +*Evidence*: + +[source,bash] +---- +$ cargo fmt --check # ✓ Formatted correctly +$ cargo clippy -- -D warnings # ✓ No warnings +---- + +==== 10. Legal Compliance ✅ + +*Triple Licensing*: - ✅ MIT License (`+LICENSE-MIT+`) - ✅ Apache +License 2.0 (`+LICENSE-APACHE+`) - ✅ MPL-2.0 v0.8 +(`+LICENSE-PALIMPSEST+`) + +Users may choose *any* of the three licenses. + +*Patent Peace*: Apache 2.0 includes patent grant + +*Dependency Auditing*: `+cargo license+` shows all deps + +==== 11. Distribution ✅ + +*Installation Methods*: - ✅ Cargo: `+cargo install fslint+` - ✅ +Source: `+git clone && cargo build+` - ✅ Docker: +`+docker pull fslint/fslint+` - ✅ Guix: `+guix build+` + +*Scripts*: - ✅ `+scripts/install.sh+` (Unix) - ✅ +`+scripts/install.ps1+` (Windows) - ✅ `+scripts/uninstall.sh+` + +=== Verification + +Run the RSR compliance verification script: + +[source,bash] +---- +./scripts/verify-rsr.sh +---- + +Expected output: + +.... +═══════════════════════════════════════════════════════ + RSR Framework Compliance Verification for FSLint +═══════════════════════════════════════════════════════ + +📋 RSR Category 1: Type Safety +✅ PASS: Rust language (compile-time type safety) +✅ PASS: No TypeScript (dynamically typed) + +[... 50+ checks ...] + +═══════════════════════════════════════════════════════ + Compliance Summary +═══════════════════════════════════════════════════════ + +Total Checks: 52 +✅ Passed: 52 +❌ Failed: 0 + +Compliance Rate: 100% + +RSR Tier: Gold + +🎉 Excellent! FSLint is fully RSR compliant! +.... + +=== Comparison with rhodium-minimal + +[cols=",,",options="header",] +|=== +|Feature |rhodium-minimal |FSLint +|Language |Ada 2022 |Rust 2021 +|LOC |100 |10,000+ +|Dependencies |0 |30+ (all pinned) +|Tier |Bronze |Gold +|TPCF Perimeter |3 (Open) |3 (Open) +|Licensing |MIT + Palimpsest |MIT + Apache + Palimpsest +|=== + +=== RSR Tier Definitions + +[cols=",",options="header",] +|=== +|Tier |Requirements +|*Gold* |All 11 categories ✓, 100% compliance +|*Silver* |10/11 categories, 90%+ compliance +|*Bronze* |8/11 categories, 75%+ compliance +|*Partial* |<75% compliance +|=== + +FSLint achieves *Gold Tier* with 100% compliance. + +=== Maintaining Compliance + +==== CI/CD Integration + +RSR checks run automatically: + +[source,yaml] +---- +# .github/workflows/ci.yml +- name: RSR Compliance Check + run: ./scripts/verify-rsr.sh +---- + +==== Pre-Release Checklist + +Before each release: + +[source,bash] +---- +just pre-release # Runs: clean, ci, validate, audit +---- + +==== Continuous Monitoring + +* *Weekly*: `+cargo audit+` for security +* *Monthly*: `+cargo outdated+` for dependencies +* *Per-commit*: `+rustfmt+` and `+clippy+` in CI + +=== Benefits of RSR Compliance + +==== For Users + +* *Quality Assurance*: Rigorous standards +* *Security*: RFC 9116, SECURITY.md, audit trail +* *Transparency*: Complete documentation +* *Reproducibility*: Guix builds, pinned deps + +==== For Contributors + +* *Clear Process*: TPCF framework +* *Safe Experimentation*: Perimeter 3 sandbox +* *Good Citizenship*: Code of Conduct +* *Recognition*: MAINTAINERS.md + +==== For Maintainers + +* *Sustainable*: TPCF prevents burnout +* *Quality*: Automated checks +* *Security*: Defined response process +* *Community*: Welcoming, inclusive + +=== Future Improvements + +While FSLint is Gold Tier, we continue to improve: + +* *WASM Plugins*: Sandboxed execution +* *Formal Verification*: SPARK-style proofs +* *Multi-Language*: Ada/Haskell/AffineScript plugins +* *Shell Integration*: OS-native extensions + +=== Resources + +* *RSR Framework*: See rhodium-minimal example +* *TPCF Documentation*: `+docs/TPCF.md+` +* *Security*: `+.well-known/security.txt+` +* *Verification Script*: `+scripts/verify-rsr.sh+` + +=== Questions? + +* *RSR Questions*: See rhodium-minimal docs +* *FSLint Compliance*: Open GitHub issue +* *General*: maintainers@fslint.org + +''''' + +*Compliance Tier*: Gold + +*Last Verified*: 2025-11-22 + +*Next Review*: 2026-01-01 + +*Verification Command*: `+./scripts/verify-rsr.sh+` diff --git a/docs/RSR_COMPLIANCE.md b/docs/RSR_COMPLIANCE.md deleted file mode 100644 index 3f86f30..0000000 --- a/docs/RSR_COMPLIANCE.md +++ /dev/null @@ -1,334 +0,0 @@ - -# RSR Framework Compliance - -FSLint conforms to the **Rhodium Standard Repository (RSR) Framework** at **Gold Tier** level. - -## What is RSR? - -The Rhodium Standard Repository Framework is a comprehensive set of standards for software projects that emphasizes: - -- **Type Safety** & **Memory Safety** -- **Offline-First** design -- **Complete Documentation** -- **Reproducible Builds** -- **Community Governance** (TPCF) -- **Security Best Practices** (RFC 9116) - -See [rhodium-minimal example](https://github.com/example/rhodium-minimal) for reference implementation. - -## FSLint Compliance Status - -### ✅ Gold Tier Achieved - -Run verification: `./scripts/verify-rsr.sh` - -```bash -just validate # Or: make ci && ./scripts/verify-rsr.sh -``` - -## RSR Categories - -### 1. Type Safety ✅ - -- **Language**: Rust with compile-time type guarantees -- **No Dynamic Types**: No JavaScript/TypeScript/Python -- **Strong Typing**: Leverages Rust's type system throughout - -**Evidence**: -- All code in Rust (`Cargo.toml`, `src/**/*.rs`) -- Compiler enforces type correctness -- No `any` types or dynamic typing - -### 2. Memory Safety ✅ - -- **Ownership Model**: Rust's borrow checker prevents memory errors -- **No Unsafe**: Minimal to zero unsafe blocks -- **No Segfaults**: Memory safety guaranteed by compiler - -**Evidence**: -- Rust's ownership system -- `cargo clippy` passes with no unsafe warnings -- Zero buffer overflows possible - -### 3. Offline-First ✅ - -- **No Network Calls**: FSLint works completely offline -- **Air-Gapped Compatible**: All operations are local -- **Local Storage**: Config at `~/.config/fslint/` - -**Evidence**: -- No network dependencies in `Cargo.toml` -- Scanner operates on local filesystem only -- Works without internet connection - -### 4. Documentation ✅ - -**Required Files** (all present): -- ✅ `README.md` - Comprehensive project documentation -- ✅ `LICENSE-MIT` - MIT License -- ✅ `LICENSE-APACHE` - Apache License 2.0 -- ✅ `LICENSE-PALIMPSEST` - MPL-2.0 v0.8 (experimental) -- ✅ `SECURITY.md` - Security policy and reporting -- ✅ `CONTRIBUTING.md` - Contribution guidelines -- ✅ `CODE_OF_CONDUCT.md` - Community standards -- ✅ `MAINTAINERS.md` - Project governance -- ✅ `CHANGELOG.md` - Version history - -**Additional Documentation**: -- ✅ `docs/QUICKSTART.md` - 5-minute getting started -- ✅ `docs/PLUGIN_DEVELOPMENT.md` - Plugin creation guide -- ✅ `docs/TPCF.md` - Contribution framework -- ✅ `PROJECT_SUMMARY.md` - Complete project overview - -### 5. .well-known/ Directory ✅ - -**RFC 9116 Compliance**: -- ✅ `.well-known/security.txt` - Security contact info -- ✅ `.well-known/ai.txt` - AI training policy -- ✅ `.well-known/humans.txt` - Attribution and credits - -**Evidence**: -```bash -$ cat .well-known/security.txt | head -5 -# Canonical: https://github.com/Hyperpolymath/file-soup/.well-known/security.txt -# Expires: 2026-11-22T00:00:00.000Z - -Contact: mailto:security@fslint.org -Contact: https://github.com/Hyperpolymath/file-soup/security/advisories/new -``` - -### 6. Build System ✅ - -**Multiple Build Options**: -- ✅ `Cargo.toml` - Rust workspace configuration -- ✅ `justfile` - Just command runner (20+ recipes) -- ✅ `Makefile` - Traditional make support -- ✅ `flake.nix` - Nix reproducible builds -- ✅ `.github/workflows/ci.yml` - CI/CD automation - -**Reproducible Builds**: -- ✅ `Cargo.lock` committed -- ✅ Nix flake for deterministic builds -- ✅ Pinned dependencies - -**Evidence**: -```bash -$ just --list # Lists 40+ development commands -$ nix build # Reproducible Nix build -$ make ci # Traditional make interface -``` - -### 7. Testing ✅ - -**Test Coverage**: -- ✅ Unit tests in all crates -- ✅ Integration tests for CLI -- ✅ Benchmark suite (Criterion) -- ✅ 100% test pass rate - -**Evidence**: -```bash -$ cargo test --workspace -running 47 tests -test result: ok. 47 passed; 0 failed - -$ cargo bench -Scanner/scan_100_files time: [45.2 ms 45.8 ms 46.4 ms] -``` - -### 8. TPCF (Tri-Perimeter Contribution Framework) ✅ - -**Perimeter Assignment**: **Perimeter 3 (Community Sandbox)** - -- **Status**: OPEN - Anyone can contribute -- **Access**: Fork, PR, issues, discussions -- **Documentation**: See `docs/TPCF.md` - -**Graduated Trust Model**: -1. **Perimeter 3**: Community Sandbox (Open) -2. **Perimeter 2**: Blessed Garden (Earned) -3. **Perimeter 1**: Inner Sanctum (Core Team) - -**Evidence**: -- `docs/TPCF.md` fully documents the framework -- `MAINTAINERS.md` lists current perimeter assignments -- Contribution guidelines reference TPCF - -### 9. Code Quality ✅ - -**Linting & Formatting**: -- ✅ `rustfmt` - Code formatting -- ✅ `clippy` - Lint checks -- ✅ Zero warnings in CI - -**Evidence**: -```bash -$ cargo fmt --check # ✓ Formatted correctly -$ cargo clippy -- -D warnings # ✓ No warnings -``` - -### 10. Legal Compliance ✅ - -**Triple Licensing**: -- ✅ MIT License (`LICENSE-MIT`) -- ✅ Apache License 2.0 (`LICENSE-APACHE`) -- ✅ MPL-2.0 v0.8 (`LICENSE-PALIMPSEST`) - -Users may choose **any** of the three licenses. - -**Patent Peace**: Apache 2.0 includes patent grant - -**Dependency Auditing**: `cargo license` shows all deps - -### 11. Distribution ✅ - -**Installation Methods**: -- ✅ Cargo: `cargo install fslint` -- ✅ Source: `git clone && cargo build` -- ✅ Docker: `docker pull fslint/fslint` -- ✅ Nix: `nix build` - -**Scripts**: -- ✅ `scripts/install.sh` (Unix) -- ✅ `scripts/install.ps1` (Windows) -- ✅ `scripts/uninstall.sh` - -## Verification - -Run the RSR compliance verification script: - -```bash -./scripts/verify-rsr.sh -``` - -Expected output: -``` -═══════════════════════════════════════════════════════ - RSR Framework Compliance Verification for FSLint -═══════════════════════════════════════════════════════ - -📋 RSR Category 1: Type Safety -✅ PASS: Rust language (compile-time type safety) -✅ PASS: No TypeScript (dynamically typed) - -[... 50+ checks ...] - -═══════════════════════════════════════════════════════ - Compliance Summary -═══════════════════════════════════════════════════════ - -Total Checks: 52 -✅ Passed: 52 -❌ Failed: 0 - -Compliance Rate: 100% - -RSR Tier: Gold - -🎉 Excellent! FSLint is fully RSR compliant! -``` - -## Comparison with rhodium-minimal - -| Feature | rhodium-minimal | FSLint | -|---------|----------------|--------| -| Language | Ada 2022 | Rust 2021 | -| LOC | 100 | 10,000+ | -| Dependencies | 0 | 30+ (all pinned) | -| Tier | Bronze | Gold | -| TPCF Perimeter | 3 (Open) | 3 (Open) | -| Licensing | MIT + Palimpsest | MIT + Apache + Palimpsest | - -## RSR Tier Definitions - -| Tier | Requirements | -|------|-------------| -| **Gold** | All 11 categories ✓, 100% compliance | -| **Silver** | 10/11 categories, 90%+ compliance | -| **Bronze** | 8/11 categories, 75%+ compliance | -| **Partial** | <75% compliance | - -FSLint achieves **Gold Tier** with 100% compliance. - -## Maintaining Compliance - -### CI/CD Integration - -RSR checks run automatically: - -```yaml -# .github/workflows/ci.yml -- name: RSR Compliance Check - run: ./scripts/verify-rsr.sh -``` - -### Pre-Release Checklist - -Before each release: -```bash -just pre-release # Runs: clean, ci, validate, audit -``` - -### Continuous Monitoring - -- **Weekly**: `cargo audit` for security -- **Monthly**: `cargo outdated` for dependencies -- **Per-commit**: `rustfmt` and `clippy` in CI - -## Benefits of RSR Compliance - -### For Users - -- **Quality Assurance**: Rigorous standards -- **Security**: RFC 9116, SECURITY.md, audit trail -- **Transparency**: Complete documentation -- **Reproducibility**: Nix builds, pinned deps - -### For Contributors - -- **Clear Process**: TPCF framework -- **Safe Experimentation**: Perimeter 3 sandbox -- **Good Citizenship**: Code of Conduct -- **Recognition**: MAINTAINERS.md - -### For Maintainers - -- **Sustainable**: TPCF prevents burnout -- **Quality**: Automated checks -- **Security**: Defined response process -- **Community**: Welcoming, inclusive - -## Future Improvements - -While FSLint is Gold Tier, we continue to improve: - -- **WASM Plugins**: Sandboxed execution -- **Formal Verification**: SPARK-style proofs -- **Multi-Language**: Ada/Haskell/ReScript plugins -- **Shell Integration**: OS-native extensions - -## Resources - -- **RSR Framework**: See rhodium-minimal example -- **TPCF Documentation**: `docs/TPCF.md` -- **Security**: `.well-known/security.txt` -- **Verification Script**: `scripts/verify-rsr.sh` - -## Questions? - -- **RSR Questions**: See rhodium-minimal docs -- **FSLint Compliance**: Open GitHub issue -- **General**: maintainers@fslint.org - ---- - -**Compliance Tier**: Gold - -**Last Verified**: 2025-11-22 - -**Next Review**: 2026-01-01 - -**Verification Command**: `./scripts/verify-rsr.sh` diff --git a/docs/TPCF.adoc b/docs/TPCF.adoc new file mode 100644 index 0000000..06b7ed5 --- /dev/null +++ b/docs/TPCF.adoc @@ -0,0 +1,308 @@ +== Tri-Perimeter Contribution Framework (TPCF) + +FSLint uses the *Tri-Perimeter Contribution Framework* for graduated +access control and trust management. + +=== Overview + +TPCF provides three distinct perimeters of access, each with different +trust levels and permissions: + +.... +┌─────────────────────────────────────────────┐ +│ Perimeter 1: Inner Sanctum (Core Team) │ +│ - Merge to main, releases, security │ +│ - Full repository access │ +└───────────────┬─────────────────────────────┘ + │ +┌───────────────▼─────────────────────────────┐ +│ Perimeter 2: Blessed Garden (Trusted) │ +│ - Triage issues, review PRs │ +│ - Push to feature branches │ +└───────────────┬─────────────────────────────┘ + │ +┌───────────────▼─────────────────────────────┐ +│ Perimeter 3: Community Sandbox (Open) │ +│ - Fork, PR, issues, discussions │ +│ - Public participation │ +└─────────────────────────────────────────────┘ +.... + +=== Perimeter 3: Community Sandbox + +*Status*: *OPEN* - Anyone can participate + +==== Permissions + +* ✅ Fork the repository +* ✅ Submit pull requests +* ✅ Create issues +* ✅ Participate in discussions +* ✅ Review code (comments only) +* ❌ Direct push access +* ❌ Merge pull requests + +==== Purpose + +Safe experimentation without commitment. Contributors can: + +* Test ideas in forks +* Submit experimental PRs +* Get feedback without risk +* Learn the codebase +* Build trust over time + +==== Progression + +Contributors can advance to Perimeter 2 by: + +[arabic] +. *Consistent Contributions*: 3+ months of quality PRs +. *Community Engagement*: Helpful in issues/discussions +. *Technical Understanding*: Demonstrated codebase knowledge +. *Good Judgment*: Thoughtful code reviews and suggestions + +=== Perimeter 2: Blessed Garden + +*Status*: *EARNED* - Requires nomination and vote + +==== Permissions + +* ✅ All Perimeter 3 permissions +* ✅ Triage issues (labels, assignment) +* ✅ Review pull requests (approve/request changes) +* ✅ Push to feature branches +* ✅ Participate in maintainer discussions +* ❌ Merge to main +* ❌ Create releases +* ❌ Access security reports + +==== Requirements + +* *Time*: 3+ months active contribution +* *Quality*: Consistent high-quality PRs +* *Trust*: Demonstrated good judgment +* *Availability*: Responsive to review requests +* *Vote*: Nominated by Perimeter 1, approved by majority + +==== Responsibilities + +* *Triage*: Respond to issues within 7 days +* *Review*: Review assigned PRs within 14 days +* *Mentoring*: Help Perimeter 3 contributors +* *Standards*: Uphold code quality and community guidelines + +==== Progression + +Advance to Perimeter 1 by: + +[arabic] +. *Long-term Commitment*: 6+ months in Perimeter 2 +. *Deep Expertise*: Significant architectural contributions +. *Leadership*: Mentoring, RFC authorship +. *Trust*: Unanimous vote from Perimeter 1 + +=== Perimeter 1: Inner Sanctum + +*Status*: *CORE TEAM* - Highest trust level + +==== Permissions + +* ✅ All Perimeter 2 permissions +* ✅ Merge pull requests to main +* ✅ Create and publish releases +* ✅ Access security vulnerability reports +* ✅ Modify repository settings +* ✅ Invite new contributors to Perimeter 2 + +==== Requirements + +* *Time*: 6+ months in Perimeter 2 (9+ months total) +* *Expertise*: Deep understanding of entire codebase +* *Trust*: Unanimous approval from existing Perimeter 1 +* *Commitment*: Ongoing availability for critical decisions + +==== Responsibilities + +* *Releases*: Coordinate and publish versioned releases +* *Security*: Respond to security reports within 48 hours +* *Direction*: Guide project architecture and roadmap +* *Governance*: Participate in major decisions +* *Mentorship*: Develop Perimeter 2 contributors + +=== Access Control Matrix + +[cols=",,,",options="header",] +|=== +|Action |P3 (Sandbox) |P2 (Garden) |P1 (Sanctum) +|Fork repo |✅ |✅ |✅ +|Create PR |✅ |✅ |✅ +|File issues |✅ |✅ |✅ +|Comment |✅ |✅ |✅ +|Triage issues |❌ |✅ |✅ +|Review PRs |Comment only |Approve/Block |Approve/Block +|Push branches |❌ |Feature only |All branches +|Merge PRs |❌ |❌ |✅ +|Create releases |❌ |❌ |✅ +|Security access |❌ |❌ |✅ +|Modify settings |❌ |❌ |✅ +|=== + +=== Decision Making + +==== P3 Decisions (Community Sandbox) + +* *Scope*: Personal forks, experimental PRs +* *Process*: Individual choice +* *Approval*: None required for forks + +==== P2 Decisions (Blessed Garden) + +* *Scope*: Issue triage, PR reviews +* *Process*: Individual judgment +* *Oversight*: P1 can override + +==== P1 Decisions (Inner Sanctum) + +===== Minor Decisions + +* *Examples*: Bug fixes, documentation, small features +* *Process*: Single P1 approval +* *Timeline*: Immediate to 7 days + +===== Major Decisions + +* *Examples*: Breaking changes, new dependencies, architecture +* *Process*: RFC → Discussion → 2/3 P1 vote +* *Timeline*: 14-30 days + +===== Critical Decisions + +* *Examples*: License changes, governance changes, project direction +* *Process*: RFC → Community input → Unanimous P1 agreement +* *Timeline*: 30-90 days + +=== Benefits of TPCF + +==== For Contributors (P3) + +* *Low Barrier*: Anyone can contribute +* *Safe Experimentation*: Forks allow risk-free exploration +* *Clear Path*: Visible progression to higher trust +* *Emotional Safety*: No commitment required + +==== For Trusted Contributors (P2) + +* *Meaningful Work*: Triage and review reduce maintainer burden +* *Recognition*: Visible trust and responsibility +* *Influence*: Shape project direction +* *Mentorship*: Guide new contributors + +==== For Core Team (P1) + +* *Distributed Load*: P2 handles triage and review +* *Quality Control*: Only final merges require P1 +* *Strategic Focus*: More time for architecture and direction +* *Bus Factor*: Multiple people can handle critical tasks + +==== For the Project + +* *Sustainable*: Prevents maintainer burnout +* *Welcoming*: Clear path for new contributors +* *Quality*: Graduated trust ensures code quality +* *Security*: Critical access limited to most trusted + +=== Anti-Patterns to Avoid + +==== Gatekeeping + +* ❌ Don’t reject PRs without clear explanation +* ❌ Don’t impose arbitrary requirements +* ❌ Don’t make progression impossible + +==== Favoritism + +* ❌ Don’t advance friends without merit +* ❌ Don’t block competitors unfairly +* ❌ Don’t create in-groups and out-groups + +==== Stagnation + +* ❌ Don’t keep people in P2 indefinitely +* ❌ Don’t avoid promoting qualified candidates +* ❌ Don’t resist new perspectives + +=== Implementation in FSLint + +==== GitHub Branch Protection + +* *main*: Requires P1 review and approval +* *feature/**: P2+ can push +* *fork/**: P3 submits via PR + +==== GitHub Teams + +* *@fslint/core* (P1): Full access +* *@fslint/trusted* (P2): Triage + review +* *Everyone* (P3): Fork + PR + +==== Labels + +* *p1-required*: Needs P1 review before merge +* *p2-approved*: P2 has reviewed, awaits P1 merge +* *p3-welcome*: Good for new contributors + +=== Current Status + +==== Perimeter 1 (Core Team) + +* FSLint Contributors (Lead Maintainer) + +_Seeking additional P1 members from qualified P2 contributors_ + +==== Perimeter 2 (Trusted Contributors) + +_None yet - first P2 members will be promoted from active P3 +contributors_ + +==== Perimeter 3 (Community) + +*Everyone is welcome!* Join us at: - GitHub Issues: +https://github.com/Hyperpolymath/file-soup/issues - GitHub Discussions: +https://github.com/Hyperpolymath/file-soup/discussions + +=== FAQ + +==== Can I go directly from P3 to P1? + +Rarely. In exceptional cases (e.g., significant architectural +contribution, existing maintainer of similar project), but typically +progression is P3 → P2 → P1. + +==== What if I disagree with a decision? + +* *P3*: Discuss in issues/PRs, appeal to P2/P1 +* *P2*: Escalate to P1 vote +* *P1*: Follow RFC process for major decisions + +==== Can I lose access? + +Yes, if: - *Inactivity*: 6+ months without participation → demoted one +perimeter - *Code of Conduct violation*: May result in removal - +*Voluntary*: You can step down anytime + +==== How long does progression take? + +* *P3 → P2*: Typically 3-6 months of active contribution +* *P2 → P1*: Typically 6-12 months in P2 +* *Total*: 9-18 months from first PR to P1 + +But quality matters more than time! + +''''' + +*TPCF Version*: 1.0 + +*Last Updated*: 2025-11-22 + +*Questions?* Ask in GitHub Discussions or email maintainers@fslint.org diff --git a/docs/TPCF.md b/docs/TPCF.md deleted file mode 100644 index 42264af..0000000 --- a/docs/TPCF.md +++ /dev/null @@ -1,304 +0,0 @@ - -# Tri-Perimeter Contribution Framework (TPCF) - -FSLint uses the **Tri-Perimeter Contribution Framework** for graduated access control and trust management. - -## Overview - -TPCF provides three distinct perimeters of access, each with different trust levels and permissions: - -``` -┌─────────────────────────────────────────────┐ -│ Perimeter 1: Inner Sanctum (Core Team) │ -│ - Merge to main, releases, security │ -│ - Full repository access │ -└───────────────┬─────────────────────────────┘ - │ -┌───────────────▼─────────────────────────────┐ -│ Perimeter 2: Blessed Garden (Trusted) │ -│ - Triage issues, review PRs │ -│ - Push to feature branches │ -└───────────────┬─────────────────────────────┘ - │ -┌───────────────▼─────────────────────────────┐ -│ Perimeter 3: Community Sandbox (Open) │ -│ - Fork, PR, issues, discussions │ -│ - Public participation │ -└─────────────────────────────────────────────┘ -``` - -## Perimeter 3: Community Sandbox - -**Status**: **OPEN** - Anyone can participate - -### Permissions - -- ✅ Fork the repository -- ✅ Submit pull requests -- ✅ Create issues -- ✅ Participate in discussions -- ✅ Review code (comments only) -- ❌ Direct push access -- ❌ Merge pull requests - -### Purpose - -Safe experimentation without commitment. Contributors can: - -- Test ideas in forks -- Submit experimental PRs -- Get feedback without risk -- Learn the codebase -- Build trust over time - -### Progression - -Contributors can advance to Perimeter 2 by: - -1. **Consistent Contributions**: 3+ months of quality PRs -2. **Community Engagement**: Helpful in issues/discussions -3. **Technical Understanding**: Demonstrated codebase knowledge -4. **Good Judgment**: Thoughtful code reviews and suggestions - -## Perimeter 2: Blessed Garden - -**Status**: **EARNED** - Requires nomination and vote - -### Permissions - -- ✅ All Perimeter 3 permissions -- ✅ Triage issues (labels, assignment) -- ✅ Review pull requests (approve/request changes) -- ✅ Push to feature branches -- ✅ Participate in maintainer discussions -- ❌ Merge to main -- ❌ Create releases -- ❌ Access security reports - -### Requirements - -- **Time**: 3+ months active contribution -- **Quality**: Consistent high-quality PRs -- **Trust**: Demonstrated good judgment -- **Availability**: Responsive to review requests -- **Vote**: Nominated by Perimeter 1, approved by majority - -### Responsibilities - -- **Triage**: Respond to issues within 7 days -- **Review**: Review assigned PRs within 14 days -- **Mentoring**: Help Perimeter 3 contributors -- **Standards**: Uphold code quality and community guidelines - -### Progression - -Advance to Perimeter 1 by: - -1. **Long-term Commitment**: 6+ months in Perimeter 2 -2. **Deep Expertise**: Significant architectural contributions -3. **Leadership**: Mentoring, RFC authorship -4. **Trust**: Unanimous vote from Perimeter 1 - -## Perimeter 1: Inner Sanctum - -**Status**: **CORE TEAM** - Highest trust level - -### Permissions - -- ✅ All Perimeter 2 permissions -- ✅ Merge pull requests to main -- ✅ Create and publish releases -- ✅ Access security vulnerability reports -- ✅ Modify repository settings -- ✅ Invite new contributors to Perimeter 2 - -### Requirements - -- **Time**: 6+ months in Perimeter 2 (9+ months total) -- **Expertise**: Deep understanding of entire codebase -- **Trust**: Unanimous approval from existing Perimeter 1 -- **Commitment**: Ongoing availability for critical decisions - -### Responsibilities - -- **Releases**: Coordinate and publish versioned releases -- **Security**: Respond to security reports within 48 hours -- **Direction**: Guide project architecture and roadmap -- **Governance**: Participate in major decisions -- **Mentorship**: Develop Perimeter 2 contributors - -## Access Control Matrix - -| Action | P3 (Sandbox) | P2 (Garden) | P1 (Sanctum) | -|--------|--------------|-------------|--------------| -| Fork repo | ✅ | ✅ | ✅ | -| Create PR | ✅ | ✅ | ✅ | -| File issues | ✅ | ✅ | ✅ | -| Comment | ✅ | ✅ | ✅ | -| Triage issues | ❌ | ✅ | ✅ | -| Review PRs | Comment only | Approve/Block | Approve/Block | -| Push branches | ❌ | Feature only | All branches | -| Merge PRs | ❌ | ❌ | ✅ | -| Create releases | ❌ | ❌ | ✅ | -| Security access | ❌ | ❌ | ✅ | -| Modify settings | ❌ | ❌ | ✅ | - -## Decision Making - -### P3 Decisions (Community Sandbox) - -- **Scope**: Personal forks, experimental PRs -- **Process**: Individual choice -- **Approval**: None required for forks - -### P2 Decisions (Blessed Garden) - -- **Scope**: Issue triage, PR reviews -- **Process**: Individual judgment -- **Oversight**: P1 can override - -### P1 Decisions (Inner Sanctum) - -#### Minor Decisions - -- **Examples**: Bug fixes, documentation, small features -- **Process**: Single P1 approval -- **Timeline**: Immediate to 7 days - -#### Major Decisions - -- **Examples**: Breaking changes, new dependencies, architecture -- **Process**: RFC → Discussion → 2/3 P1 vote -- **Timeline**: 14-30 days - -#### Critical Decisions - -- **Examples**: License changes, governance changes, project direction -- **Process**: RFC → Community input → Unanimous P1 agreement -- **Timeline**: 30-90 days - -## Benefits of TPCF - -### For Contributors (P3) - -- **Low Barrier**: Anyone can contribute -- **Safe Experimentation**: Forks allow risk-free exploration -- **Clear Path**: Visible progression to higher trust -- **Emotional Safety**: No commitment required - -### For Trusted Contributors (P2) - -- **Meaningful Work**: Triage and review reduce maintainer burden -- **Recognition**: Visible trust and responsibility -- **Influence**: Shape project direction -- **Mentorship**: Guide new contributors - -### For Core Team (P1) - -- **Distributed Load**: P2 handles triage and review -- **Quality Control**: Only final merges require P1 -- **Strategic Focus**: More time for architecture and direction -- **Bus Factor**: Multiple people can handle critical tasks - -### For the Project - -- **Sustainable**: Prevents maintainer burnout -- **Welcoming**: Clear path for new contributors -- **Quality**: Graduated trust ensures code quality -- **Security**: Critical access limited to most trusted - -## Anti-Patterns to Avoid - -### Gatekeeping - -- ❌ Don't reject PRs without clear explanation -- ❌ Don't impose arbitrary requirements -- ❌ Don't make progression impossible - -### Favoritism - -- ❌ Don't advance friends without merit -- ❌ Don't block competitors unfairly -- ❌ Don't create in-groups and out-groups - -### Stagnation - -- ❌ Don't keep people in P2 indefinitely -- ❌ Don't avoid promoting qualified candidates -- ❌ Don't resist new perspectives - -## Implementation in FSLint - -### GitHub Branch Protection - -- **main**: Requires P1 review and approval -- **feature/***: P2+ can push -- **fork/***: P3 submits via PR - -### GitHub Teams - -- **@fslint/core** (P1): Full access -- **@fslint/trusted** (P2): Triage + review -- **Everyone** (P3): Fork + PR - -### Labels - -- **p1-required**: Needs P1 review before merge -- **p2-approved**: P2 has reviewed, awaits P1 merge -- **p3-welcome**: Good for new contributors - -## Current Status - -### Perimeter 1 (Core Team) - -- FSLint Contributors (Lead Maintainer) - -*Seeking additional P1 members from qualified P2 contributors* - -### Perimeter 2 (Trusted Contributors) - -*None yet - first P2 members will be promoted from active P3 contributors* - -### Perimeter 3 (Community) - -**Everyone is welcome!** Join us at: -- GitHub Issues: https://github.com/Hyperpolymath/file-soup/issues -- GitHub Discussions: https://github.com/Hyperpolymath/file-soup/discussions - -## FAQ - -### Can I go directly from P3 to P1? - -Rarely. In exceptional cases (e.g., significant architectural contribution, existing maintainer of similar project), but typically progression is P3 → P2 → P1. - -### What if I disagree with a decision? - -- **P3**: Discuss in issues/PRs, appeal to P2/P1 -- **P2**: Escalate to P1 vote -- **P1**: Follow RFC process for major decisions - -### Can I lose access? - -Yes, if: -- **Inactivity**: 6+ months without participation → demoted one perimeter -- **Code of Conduct violation**: May result in removal -- **Voluntary**: You can step down anytime - -### How long does progression take? - -- **P3 → P2**: Typically 3-6 months of active contribution -- **P2 → P1**: Typically 6-12 months in P2 -- **Total**: 9-18 months from first PR to P1 - -But quality matters more than time! - ---- - -**TPCF Version**: 1.0 - -**Last Updated**: 2025-11-22 - -**Questions?** Ask in GitHub Discussions or email maintainers@fslint.org diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..f477b22 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — filesoup — 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:* `+MEDIUM+`. + +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 + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |386 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +386 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== 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 5f7c85d..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — filesoup — 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:** `MEDIUM`. - -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 - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 386 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 386 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## 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..2bf59f7 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — filesoup (Developer) + +=== What is filesoup? + +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: MPL-2.0 +* 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 a6397e1..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — filesoup (Developer) - -## What is filesoup? -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: MPL-2.0 -- 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..1211b57 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — filesoup (User) + +=== What is filesoup? + +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: MPL-2.0 +* 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 9f33ace..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — filesoup (User) - -## What is filesoup? -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: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture