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..c86666c --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,120 @@ +== Changelog + +All notable changes to GrimRepo will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.0.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Planned + +* Browser extension versions (Firefox, Chrome) +* GitHub Action integration +* GitLab CI/CD template library +* Rhodium Register publication +* Badge generation service +* VS Code extension +* CLI standalone tool + +=== [1.0.0] - 2025-01-22 + +==== Added - RSR Bronze Compliance + +*Core Implementation*: - Repo Structure Bootstrapper module (TypeScript) +- Community Standards Helper module (TypeScript) - Golden Registry +Auditor module (TypeScript) - Offline-first architecture (zero network +dependencies) - Type-safe implementation (TypeScript strict mode) - +Comprehensive test suite (100% pass rate) + +*Documentation*: - README.md with comprehensive project overview - +LICENSE.txt (dual MIT + Palimpsest v0.8) - SECURITY.md with +vulnerability reporting procedures - CONTRIBUTING.md with TPCF +(Tri-Perimeter Contribution Framework) - CODE_OF_CONDUCT.md with +emotional safety provisions - MAINTAINERS.md with governance structure - +CHANGELOG.md (this file) + +*.well-known Directory*: - security.txt (RFC 9116 compliant) - ai.txt +(AI training policies) - humans.txt (attribution and credits) + +*Build System*: - Justfile with 20+ automation recipes - package.json +with npm scripts - TypeScript configuration (strict mode) - ESLint and +Prettier setup - Nix flake for reproducible builds + +*CI/CD*: - .gitlab-ci.yml with comprehensive pipeline - Automated +testing on every push - Type checking and linting - Security scanning +(SAST, secret detection) - RSR compliance validation + +*Tests*: - Unit tests for all core modules - Integration tests for +module interactions - 100% test coverage goal - Automated test runs in +CI/CD + +==== Infrastructure + +* GitLab repository established +* Issue templates for bugs, features, security +* Merge request templates +* Community health files + +==== Compliance + +* *RSR Bronze Level* achieved +* *TPCF Perimeter 3* (Community Sandbox) +* *Offline-first* verified +* *Type safety* via TypeScript +* *Memory safety* via immutable patterns +* *Zero runtime dependencies* + +''''' + +=== Version History + +==== Versioning Scheme + +We use https://semver.org/[Semantic Versioning]: + +*MAJOR.MINOR.PATCH* + +* *MAJOR*: Breaking changes (incompatible API changes) +* *MINOR*: New features (backwards-compatible) +* *PATCH*: Bug fixes (backwards-compatible) + +==== Release Types + +* *Stable Releases* (1.0.0, 1.1.0, etc.): Production-ready +* *Pre-releases* (1.0.0-beta.1, 1.0.0-rc.2): Testing only +* *Development* (unreleased): Main branch, unstable + +==== Categories + +Changes are categorized as: + +* *Added*: New features +* *Changed*: Changes to existing functionality +* *Deprecated*: Soon-to-be-removed features +* *Removed*: Removed features +* *Fixed*: Bug fixes +* *Security*: Security vulnerability fixes + +==== Breaking Changes + +Breaking changes are always: - Highlighted in *bold* with +"`**BREAKING:**`" prefix - Documented in upgrade guides - Accompanied by +major version bump - Announced with migration period (when possible) + +''''' + +=== Links + +* https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts[GitLab +Repository] +* https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues[Issue +Tracker] +* https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/releases[Releases] +* https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/security/advisories[Security +Advisories] + +''''' + +*Maintained by*: GrimRepo Contributors *Last Updated*: 2025-01-22 diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index d714f48..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,130 +0,0 @@ -# Changelog - -All notable changes to GrimRepo will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Planned -- Browser extension versions (Firefox, Chrome) -- GitHub Action integration -- GitLab CI/CD template library -- Rhodium Register publication -- Badge generation service -- VS Code extension -- CLI standalone tool - -## [1.0.0] - 2025-01-22 - -### Added - RSR Bronze Compliance - -**Core Implementation**: -- Repo Structure Bootstrapper module (TypeScript) -- Community Standards Helper module (TypeScript) -- Golden Registry Auditor module (TypeScript) -- Offline-first architecture (zero network dependencies) -- Type-safe implementation (TypeScript strict mode) -- Comprehensive test suite (100% pass rate) - -**Documentation**: -- README.md with comprehensive project overview -- LICENSE.txt (dual MIT + Palimpsest v0.8) -- SECURITY.md with vulnerability reporting procedures -- CONTRIBUTING.md with TPCF (Tri-Perimeter Contribution Framework) -- CODE_OF_CONDUCT.md with emotional safety provisions -- MAINTAINERS.md with governance structure -- CHANGELOG.md (this file) - -**.well-known Directory**: -- security.txt (RFC 9116 compliant) -- ai.txt (AI training policies) -- humans.txt (attribution and credits) - -**Build System**: -- Justfile with 20+ automation recipes -- package.json with npm scripts -- TypeScript configuration (strict mode) -- ESLint and Prettier setup -- Nix flake for reproducible builds - -**CI/CD**: -- .gitlab-ci.yml with comprehensive pipeline -- Automated testing on every push -- Type checking and linting -- Security scanning (SAST, secret detection) -- RSR compliance validation - -**Tests**: -- Unit tests for all core modules -- Integration tests for module interactions -- 100% test coverage goal -- Automated test runs in CI/CD - -### Infrastructure -- GitLab repository established -- Issue templates for bugs, features, security -- Merge request templates -- Community health files - -### Compliance -- **RSR Bronze Level** achieved -- **TPCF Perimeter 3** (Community Sandbox) -- **Offline-first** verified -- **Type safety** via TypeScript -- **Memory safety** via immutable patterns -- **Zero runtime dependencies** - ---- - -## Version History - -### Versioning Scheme - -We use [Semantic Versioning](https://semver.org/): - -**MAJOR.MINOR.PATCH** - -- **MAJOR**: Breaking changes (incompatible API changes) -- **MINOR**: New features (backwards-compatible) -- **PATCH**: Bug fixes (backwards-compatible) - -### Release Types - -- **Stable Releases** (1.0.0, 1.1.0, etc.): Production-ready -- **Pre-releases** (1.0.0-beta.1, 1.0.0-rc.2): Testing only -- **Development** (unreleased): Main branch, unstable - -### Categories - -Changes are categorized as: - -- **Added**: New features -- **Changed**: Changes to existing functionality -- **Deprecated**: Soon-to-be-removed features -- **Removed**: Removed features -- **Fixed**: Bug fixes -- **Security**: Security vulnerability fixes - -### Breaking Changes - -Breaking changes are always: -- Highlighted in **bold** with "**BREAKING:**" prefix -- Documented in upgrade guides -- Accompanied by major version bump -- Announced with migration period (when possible) - ---- - -## Links - -- [GitLab Repository](https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts) -- [Issue Tracker](https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues) -- [Releases](https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/releases) -- [Security Advisories](https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/security/advisories) - ---- - -**Maintained by**: GrimRepo Contributors -**Last Updated**: 2025-01-22 diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..aa1be9a --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,266 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and maintainers pledge to make +participation in our project and community a *harassment-free, +emotionally safe, and constructive experience* for everyone, regardless +of: + +* Age +* Body size +* Disability (visible or invisible) +* Ethnicity +* Sex characteristics +* Gender identity and expression +* Level of experience +* Education +* Socio-economic status +* Nationality +* Personal appearance +* Race +* Religion (or lack thereof) +* Sexual identity and orientation +* Neurodivergence +* Communication style + +We pledge to act and interact in ways that contribute to an *open, +welcoming, diverse, inclusive, and healthy community*. + +=== Our Standards + +==== Positive Behaviors + +Examples of behavior that contributes to a positive environment: + +* *Empathy and Kindness*: Be considerate of others’ perspectives and +feelings +* *Respectful Disagreement*: Critique ideas, not people; assume good +faith +* *Constructive Feedback*: Provide actionable, specific, and helpful +suggestions +* *Graceful Acceptance*: Accept responsibility and apologize when we +make mistakes +* *Community Focus*: Prioritize what’s best for the overall community +* *Mentorship*: Help newcomers feel welcome and supported +* *Psychological Safety*: Create space for questions, experiments, and +learning +* *Credit and Attribution*: Acknowledge others’ contributions and ideas + +==== Unacceptable Behaviors + +The following behaviors are prohibited: + +* *Harassment*: Sexual language/imagery, unwelcome attention, stalking +* *Trolling*: Inflammatory comments, personal/political attacks, +sustained disruption +* *Privacy Violations*: Publishing private information (doxxing) without +permission +* *Discrimination*: Derogatory comments related to protected +characteristics +* *Insults/Slurs*: Degrading language, name-calling, personal insults +* *Gatekeeping*: Elitism, dismissiveness toward newcomers or +"`non-experts`" +* *Inappropriate Conduct*: Sexual advances, romantic solicitation in +professional spaces +* *Bad Faith*: Sealioning, derailing, concern trolling +* *Professional Misconduct*: Using project space for unethical purposes + +=== Emotional Safety Provisions + +As part of our link:LICENSE.txt[Palimpsest License] commitment, we +extend traditional codes of conduct with *explicit emotional safety +guarantees*: + +==== Right to Reversibility + +* Failed experiments and abandoned features are *not held against +contributors* +* You may withdraw proposals, close PRs, or change your mind *without +guilt* +* Mistakes are *learning opportunities*, not permanent marks + +==== Anxiety Reduction + +* *No "`stupid questions`"* - all questions are valid +* *Ask for help early and often* - struggling in silence is unnecessary +* *Take breaks* - burnout prevention is a community responsibility +* *Clear documentation* - confusing processes are treated as bugs + +==== Sustainable Contribution + +* Maintainers may *step back without guilt* when needed +* *No unpaid emotional labor expectations* - saying "`no`" is acceptable +* *Boundaries are respected* - response times, availability, scope + +==== Inclusive Communication + +* *Accommodate different neurotypes* - literal communication is OK +* *Avoid jargon when possible* - explain technical terms +* *Multiple communication styles* - async and sync, text and voice + +=== Enforcement Responsibilities + +Project maintainers are responsible for: + +[arabic] +. *Clarifying Standards*: Ensuring this Code of Conduct is understood +. *Enforcing Standards*: Taking appropriate action for unacceptable +behavior +. *Transparency*: Explaining enforcement decisions (with privacy +considerations) +. *Consistency*: Applying standards fairly and equitably +. *Protection*: Safeguarding affected community members + +Maintainers have the right and responsibility to: - Remove, edit, or +reject comments, commits, code, issues, and contributions that violate +this Code of Conduct - Ban temporarily or permanently any contributor +for behaviors deemed inappropriate, threatening, or harmful + +=== Scope + +This Code of Conduct applies to: + +* *Project Spaces*: GitLab repositories, issues, merge requests, +documentation +* *Community Spaces*: Mailing lists, chat channels, forums, social media +* *Public Representation*: Conferences, meetups, online events +* *Private Interactions*: When representing the project or community + +Examples of representation: - Using an official project email address - +Posting via official social media accounts - Acting as an appointed +representative at events - Wearing/displaying project branding + +=== Reporting Violations + +==== How to Report + +If you experience or witness unacceptable behavior, please report it: + +*Primary Contact*: - *Email*: conduct@grimrepo.dev (coming soon) - +*GitLab*: Private message to maintainers (see MAINTAINERS.md) + +*For Urgent Safety Concerns*: - Contact GitLab Trust & Safety: +https://about.gitlab.com/community/contribute/dco-cla/#code-of-conduct + +*What to Include*: 1. Your contact information (for follow-up) 2. +Names/usernames of people involved 3. Description of the behavior 4. +Approximate date and time 5. Links to public evidence (if applicable) 6. +Any additional context + +*Confidentiality*: All reports are treated with discretion. We will +protect reporter privacy unless legally prohibited. + +==== What Happens Next + +[arabic] +. *Acknowledgment* (24-48 hours): We confirm receipt +. *Investigation* (3-7 days): We gather information and context +. *Decision* (varies): We determine appropriate action +. *Notification* (1-2 days): We inform relevant parties of outcome +. *Follow-up* (ongoing): We monitor for continued issues + +=== Enforcement Guidelines + +We follow a *graduated response* model based on severity and intent: + +==== Level 1: Correction + +*Behavior*: Minor, likely unintentional violations (e.g., insensitive +language, tone issues) + +*Action*: - Private written warning explaining the violation - Request +for apology or clarification - Guidance on expected behavior - No +further action if corrected + +*Example*: Using ableist language unintentionally ("`crazy idea`"), then +apologizing when informed. + +==== Level 2: Warning + +*Behavior*: Repeated minor violations or single moderate violation + +*Action*: - Formal written warning - Temporary restriction from project +spaces (e.g., 7-day ban) - Required acknowledgment of violation - +Removal of violating content + +*Example*: Repeatedly dismissing newcomers’ questions despite prior +correction. + +==== Level 3: Temporary Ban + +*Behavior*: Serious violation or pattern of unacceptable behavior + +*Action*: - Temporary ban from all project spaces (30-90 days) - Public +announcement (if appropriate for community safety) - No interaction with +affected parties during ban - Review before reinstatement + +*Example*: Personal attacks, harassment, or doxxing. + +==== Level 4: Permanent Ban + +*Behavior*: Severe, egregious, or repeated serious violations + +*Action*: - Permanent ban from all project spaces - Revocation of all +access rights - Public announcement (if appropriate for community +safety) - Potential reporting to platforms (GitLab, etc.) + +*Example*: Sustained harassment, threats of violence, or coordinated +attacks. + +=== Appeals Process + +If you believe an enforcement action was unjust: + +[arabic] +. *Submit Appeal* (within 30 days): Email conduct@grimrepo.dev with: +* Original incident description +* Explanation of why you believe the action was unfair +* Any new information or context +* Desired outcome +. *Review* (7-14 days): Different maintainer(s) review the appeal +. *Decision* (final): Appeal outcome communicated in writing + +*Note*: Frivolous or bad-faith appeals may result in extended bans. + +=== Attribution and Inspiration + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/version/2/1/code_of_conduct.html[Contributor +Covenant v2.1] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://palimpsest.dev[Palimpsest License v0.8] (emotional safety +provisions) + +=== Living Document + +This Code of Conduct is a *living document* and may be updated based on: + +* Community feedback +* Incidents and learnings +* Evolving best practices +* Legal requirements + +*Version History*: - v1.0 (2025-01-22): Initial version + +*Change Notifications*: Significant updates will be announced via GitLab +issues and project communication channels. + +=== Questions? + +For questions about this Code of Conduct: + +* *General Questions*: Open a GitLab issue with "`CoC Question:`" prefix +* *Clarifications*: Email conduct@grimrepo.dev (coming soon) +* *Private Concerns*: Contact maintainers (see MAINTAINERS.md) + +''''' + +*Last Updated*: 2025-01-22 *Version*: 1.0 + +*Remember*: Our community thrives when everyone feels safe, respected, +and empowered to contribute. Thank you for helping make GrimRepo a +welcoming space. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 9464fcf..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,244 +0,0 @@ -# Code of Conduct - -## Our Pledge - -We as members, contributors, and maintainers pledge to make participation in our project and community a **harassment-free, emotionally safe, and constructive experience** for everyone, regardless of: - -- Age -- Body size -- Disability (visible or invisible) -- Ethnicity -- Sex characteristics -- Gender identity and expression -- Level of experience -- Education -- Socio-economic status -- Nationality -- Personal appearance -- Race -- Religion (or lack thereof) -- Sexual identity and orientation -- Neurodivergence -- Communication style - -We pledge to act and interact in ways that contribute to an **open, welcoming, diverse, inclusive, and healthy community**. - -## Our Standards - -### Positive Behaviors - -Examples of behavior that contributes to a positive environment: - -- **Empathy and Kindness**: Be considerate of others' perspectives and feelings -- **Respectful Disagreement**: Critique ideas, not people; assume good faith -- **Constructive Feedback**: Provide actionable, specific, and helpful suggestions -- **Graceful Acceptance**: Accept responsibility and apologize when we make mistakes -- **Community Focus**: Prioritize what's best for the overall community -- **Mentorship**: Help newcomers feel welcome and supported -- **Psychological Safety**: Create space for questions, experiments, and learning -- **Credit and Attribution**: Acknowledge others' contributions and ideas - -### Unacceptable Behaviors - -The following behaviors are prohibited: - -- **Harassment**: Sexual language/imagery, unwelcome attention, stalking -- **Trolling**: Inflammatory comments, personal/political attacks, sustained disruption -- **Privacy Violations**: Publishing private information (doxxing) without permission -- **Discrimination**: Derogatory comments related to protected characteristics -- **Insults/Slurs**: Degrading language, name-calling, personal insults -- **Gatekeeping**: Elitism, dismissiveness toward newcomers or "non-experts" -- **Inappropriate Conduct**: Sexual advances, romantic solicitation in professional spaces -- **Bad Faith**: Sealioning, derailing, concern trolling -- **Professional Misconduct**: Using project space for unethical purposes - -## Emotional Safety Provisions - -As part of our [Palimpsest License](LICENSE.txt) commitment, we extend traditional codes of conduct with **explicit emotional safety guarantees**: - -### Right to Reversibility -- Failed experiments and abandoned features are **not held against contributors** -- You may withdraw proposals, close PRs, or change your mind **without guilt** -- Mistakes are **learning opportunities**, not permanent marks - -### Anxiety Reduction -- **No "stupid questions"** - all questions are valid -- **Ask for help early and often** - struggling in silence is unnecessary -- **Take breaks** - burnout prevention is a community responsibility -- **Clear documentation** - confusing processes are treated as bugs - -### Sustainable Contribution -- Maintainers may **step back without guilt** when needed -- **No unpaid emotional labor expectations** - saying "no" is acceptable -- **Boundaries are respected** - response times, availability, scope - -### Inclusive Communication -- **Accommodate different neurotypes** - literal communication is OK -- **Avoid jargon when possible** - explain technical terms -- **Multiple communication styles** - async and sync, text and voice - -## Enforcement Responsibilities - -Project maintainers are responsible for: - -1. **Clarifying Standards**: Ensuring this Code of Conduct is understood -2. **Enforcing Standards**: Taking appropriate action for unacceptable behavior -3. **Transparency**: Explaining enforcement decisions (with privacy considerations) -4. **Consistency**: Applying standards fairly and equitably -5. **Protection**: Safeguarding affected community members - -Maintainers have the right and responsibility to: -- Remove, edit, or reject comments, commits, code, issues, and contributions that violate this Code of Conduct -- Ban temporarily or permanently any contributor for behaviors deemed inappropriate, threatening, or harmful - -## Scope - -This Code of Conduct applies to: - -- **Project Spaces**: GitLab repositories, issues, merge requests, documentation -- **Community Spaces**: Mailing lists, chat channels, forums, social media -- **Public Representation**: Conferences, meetups, online events -- **Private Interactions**: When representing the project or community - -Examples of representation: -- Using an official project email address -- Posting via official social media accounts -- Acting as an appointed representative at events -- Wearing/displaying project branding - -## Reporting Violations - -### How to Report - -If you experience or witness unacceptable behavior, please report it: - -**Primary Contact**: -- **Email**: conduct@grimrepo.dev (coming soon) -- **GitLab**: Private message to maintainers (see MAINTAINERS.md) - -**For Urgent Safety Concerns**: -- Contact GitLab Trust & Safety: https://about.gitlab.com/community/contribute/dco-cla/#code-of-conduct - -**What to Include**: -1. Your contact information (for follow-up) -2. Names/usernames of people involved -3. Description of the behavior -4. Approximate date and time -5. Links to public evidence (if applicable) -6. Any additional context - -**Confidentiality**: All reports are treated with discretion. We will protect reporter privacy unless legally prohibited. - -### What Happens Next - -1. **Acknowledgment** (24-48 hours): We confirm receipt -2. **Investigation** (3-7 days): We gather information and context -3. **Decision** (varies): We determine appropriate action -4. **Notification** (1-2 days): We inform relevant parties of outcome -5. **Follow-up** (ongoing): We monitor for continued issues - -## Enforcement Guidelines - -We follow a **graduated response** model based on severity and intent: - -### Level 1: Correction - -**Behavior**: Minor, likely unintentional violations (e.g., insensitive language, tone issues) - -**Action**: -- Private written warning explaining the violation -- Request for apology or clarification -- Guidance on expected behavior -- No further action if corrected - -**Example**: Using ableist language unintentionally ("crazy idea"), then apologizing when informed. - -### Level 2: Warning - -**Behavior**: Repeated minor violations or single moderate violation - -**Action**: -- Formal written warning -- Temporary restriction from project spaces (e.g., 7-day ban) -- Required acknowledgment of violation -- Removal of violating content - -**Example**: Repeatedly dismissing newcomers' questions despite prior correction. - -### Level 3: Temporary Ban - -**Behavior**: Serious violation or pattern of unacceptable behavior - -**Action**: -- Temporary ban from all project spaces (30-90 days) -- Public announcement (if appropriate for community safety) -- No interaction with affected parties during ban -- Review before reinstatement - -**Example**: Personal attacks, harassment, or doxxing. - -### Level 4: Permanent Ban - -**Behavior**: Severe, egregious, or repeated serious violations - -**Action**: -- Permanent ban from all project spaces -- Revocation of all access rights -- Public announcement (if appropriate for community safety) -- Potential reporting to platforms (GitLab, etc.) - -**Example**: Sustained harassment, threats of violence, or coordinated attacks. - -## Appeals Process - -If you believe an enforcement action was unjust: - -1. **Submit Appeal** (within 30 days): Email conduct@grimrepo.dev with: - - Original incident description - - Explanation of why you believe the action was unfair - - Any new information or context - - Desired outcome - -2. **Review** (7-14 days): Different maintainer(s) review the appeal - -3. **Decision** (final): Appeal outcome communicated in writing - -**Note**: Frivolous or bad-faith appeals may result in extended bans. - -## Attribution and Inspiration - -This Code of Conduct is adapted from: - -- [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Palimpsest License v0.8](https://palimpsest.dev) (emotional safety provisions) - -## Living Document - -This Code of Conduct is a **living document** and may be updated based on: - -- Community feedback -- Incidents and learnings -- Evolving best practices -- Legal requirements - -**Version History**: -- v1.0 (2025-01-22): Initial version - -**Change Notifications**: Significant updates will be announced via GitLab issues and project communication channels. - -## Questions? - -For questions about this Code of Conduct: - -- **General Questions**: Open a GitLab issue with "CoC Question:" prefix -- **Clarifications**: Email conduct@grimrepo.dev (coming soon) -- **Private Concerns**: Contact maintainers (see MAINTAINERS.md) - ---- - -**Last Updated**: 2025-01-22 -**Version**: 1.0 - -**Remember**: Our community thrives when everyone feels safe, respected, and empowered to contribute. Thank you for helping make GrimRepo a welcoming space. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..dab29bd --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,3 @@ +== Contributing + +See CONTRIBUTING.adoc for full contribution guidelines. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index bf6cd14..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,3 +0,0 @@ -# Contributing - -See [CONTRIBUTING.adoc](CONTRIBUTING.adoc) for full contribution guidelines. 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/MAINTAINERS.adoc b/MAINTAINERS.adoc new file mode 100644 index 0000000..b338b71 --- /dev/null +++ b/MAINTAINERS.adoc @@ -0,0 +1,237 @@ +== Maintainers + +This document lists the current maintainers of the GrimRepo project and +describes our governance structure. + +=== Current Maintainers + +==== Lead Maintainer + +*Role*: Final decision authority, project vision, release management + +* *Name*: [To be assigned] +* *GitLab*: https://gitlab.com/username[@username] +* *Email*: lead@grimrepo.dev (coming soon) +* *Timezone*: UTC +* *Since*: 2025-01-22 + +==== Core Maintainers + +*Role*: Code review, merge authority, architectural decisions + +_No core maintainers assigned yet. Contributors will be promoted based +on sustained contributions._ + +==== Module Maintainers + +*Role*: Domain expertise, specific component ownership + +[cols=",,,",options="header",] +|=== +|Module |Maintainer |GitLab |Since +|Repo Structure Bootstrap |TBD |- |- +|Community Standards Helper |TBD |- |- +|Golden Registry Auditor |TBD |- |- +|Build System & CI/CD |TBD |- |- +|Documentation |TBD |- |- +|=== + +=== Governance Model + +GrimRepo uses a *benevolent dictatorship* model with *meritocratic +progression*: + +==== Decision-Making Hierarchy + +[arabic] +. *Lead Maintainer*: Final authority on disputes and direction +. *Core Maintainers*: Consensus-based decisions on architecture and +major changes +. *Module Maintainers*: Authority within their domain +. *Community Contributors*: Input via issues, discussions, and merge +requests + +==== Decision Process + +*Minor Changes* (bug fixes, docs, tests): - Any maintainer can merge +after review - Use judgment; default to more eyes on complex changes + +*Moderate Changes* (new features, refactoring): - Require approval from +module maintainer + 1 core maintainer - Lead maintainer can override if +needed + +*Major Changes* (breaking changes, architecture shifts): - Require RFC +(Request for Comments) issue - Core maintainer consensus (majority vote) +- Lead maintainer can veto or override + +*Emergency Changes* (security, critical bugs): - Lead maintainer or any +core maintainer can merge immediately - Post-merge review and +notification required + +=== Becoming a Maintainer + +==== Contributor → Module Maintainer + +*Criteria*: - 3+ months of consistent contributions - Demonstrated +expertise in specific module - 10+ merged merge requests - Positive +community interactions - Alignment with project values + +*Process*: 1. Nomination by existing maintainer 2. Discussion among core +maintainers 3. Lead maintainer approval 4. Public announcement and +MAINTAINERS.md update + +==== Module Maintainer → Core Maintainer + +*Criteria*: - 6+ months as module maintainer - Contributions across +multiple modules - 25+ merged merge requests - Demonstrated good +judgment in reviews - Community mentorship and leadership + +*Process*: 1. Self-nomination or nomination by core maintainer 2. Core +maintainer vote (2/3 majority) 3. Lead maintainer approval 4. Public +announcement and access provisioning + +==== Core Maintainer → Lead Maintainer + +*Process*: - Appointment by outgoing lead maintainer, or - Core +maintainer vote (unanimous) if position is vacant - Community +consultation period (2 weeks) - Formal handoff of responsibilities + +=== Responsibilities + +==== All Maintainers + +* *Code Review*: Timely, constructive feedback on merge requests +* *Issue Triage*: Label, prioritize, and respond to issues +* *Code of Conduct*: Enforce community standards +* *Communication*: Keep contributors informed +* *Availability*: Respond within 5 business days (best effort) + +==== Module Maintainers + +* *Domain Expertise*: Deep knowledge of specific component +* *Architecture*: Maintain module design and interfaces +* *Mentorship*: Guide contributors in your domain +* *Documentation*: Keep module docs up-to-date + +==== Core Maintainers + +* *Strategic Direction*: Participate in project roadmap discussions +* *Release Management*: Assist with versioning and releases +* *Cross-Module Coordination*: Ensure consistency across codebase +* *Conflict Resolution*: Help resolve disputes + +==== Lead Maintainer + +* *Vision*: Set and communicate project direction +* *Final Decisions*: Break deadlocks and make hard calls +* *Releases*: Coordinate and publish releases +* *Representation*: Speak for project externally +* *Delegation*: Empower and support other maintainers + +=== Time Commitment + +*Expected Availability* (guidelines, not strict requirements): + +* *Module Maintainer*: 2-4 hours/week +* *Core Maintainer*: 4-8 hours/week +* *Lead Maintainer*: 8-12 hours/week + +*Flexible Arrangements*: - Life happens - we understand absences - +Announce extended unavailability (>2 weeks) when possible - Backup +coverage for critical responsibilities + +=== Stepping Down + +Maintainers can step down at any time, for any reason, without guilt or +justification (per our link:LICENSE.txt[Palimpsest License] emotional +safety guarantees). + +*Process*: + +[arabic] +. *Notification*: Inform lead maintainer privately +. *Transition Period*: 2-4 weeks handoff (if possible) +. *Knowledge Transfer*: Document ongoing work +. *Public Announcement*: Thank you and recognition +. *Emeritus Status*: Listed as "`Emeritus Maintainer`" with gratitude + +*Emeritus Maintainers* retain: - GitLab project membership - Credit in +documentation - Invitation to return anytime - No ongoing obligations + +=== Inactive Maintainers + +If a maintainer becomes unresponsive (>60 days without prior notice): + +[arabic] +. *Outreach*: Attempt contact via multiple channels +. *Grace Period*: 30 days for response +. *Transition*: If still unresponsive, temporarily remove merge rights +. *Emeritus*: Move to emeritus status with gratitude +. *Reinstatement*: Easy path to return when ready + +*Philosophy*: We prioritize maintainer well-being over project urgency. + +=== Conflict Resolution + +==== Process + +[arabic] +. *Direct Communication*: Parties attempt to resolve directly +. *Mediation*: Lead maintainer or neutral core maintainer mediates +. *Core Maintainer Input*: If unresolved, seek broader input +. *Lead Decision*: Lead maintainer makes final call +. *Escalation*: Egregious violations → Code of Conduct enforcement + +==== Principles + +* *Assume Good Faith*: Start with charitable interpretation +* *Focus on Code*: Separate technical from personal +* *Transparency*: Document decisions (with privacy protection) +* *Learn and Improve*: Conflicts are opportunities to improve processes + +=== Compensation + +*Current Status*: All maintainers are unpaid volunteers. + +*Future Possibilities*: - Sponsorship programs (GitHub Sponsors, Open +Collective) - Paid support contracts for enterprise users - +Conference/travel funding for representing project + +*Principles*: - Compensation will be transparent and equitable - Payment +does not grant additional decision authority - Volunteering remains +valid and valued + +=== Communication + +==== Internal (Maintainers) + +* *Weekly Sync*: (coming soon) Short async update +* *Monthly Meeting*: (coming soon) Video call for planning +* *Private Chat*: (coming soon) Matrix/Discord for maintainers +* *Email*: For sensitive/private discussions + +==== Public (Community) + +* *GitLab Issues*: Feature requests, bug reports, discussions +* *Merge Requests*: Code review, technical discussion +* *Changelog*: User-facing changes +* *Release Notes*: Highlights and breaking changes + +=== Maintainer Emeriti + +We honor past maintainers who contributed significantly: + +_No emeriti yet - founding maintainers still active!_ + +=== Contact + +* *General Questions*: Open a GitLab issue +* *Private Maintainer Contact*: maintainers@grimrepo.dev (coming soon) +* *Lead Maintainer*: lead@grimrepo.dev (coming soon) + +''''' + +*Last Updated*: 2025-01-22 *Version*: 1.0 + +*Thank you to all maintainers, past, present, and future, for your +service to the GrimRepo community!* diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index c88e4b0..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,244 +0,0 @@ -# Maintainers - -This document lists the current maintainers of the GrimRepo project and describes our governance structure. - -## Current Maintainers - -### Lead Maintainer - -**Role**: Final decision authority, project vision, release management - -- **Name**: [To be assigned] -- **GitLab**: [@username](https://gitlab.com/username) -- **Email**: lead@grimrepo.dev (coming soon) -- **Timezone**: UTC -- **Since**: 2025-01-22 - -### Core Maintainers - -**Role**: Code review, merge authority, architectural decisions - -*No core maintainers assigned yet. Contributors will be promoted based on sustained contributions.* - -### Module Maintainers - -**Role**: Domain expertise, specific component ownership - -| Module | Maintainer | GitLab | Since | -|---------------------------|------------|--------|-------| -| Repo Structure Bootstrap | TBD | - | - | -| Community Standards Helper| TBD | - | - | -| Golden Registry Auditor | TBD | - | - | -| Build System & CI/CD | TBD | - | - | -| Documentation | TBD | - | - | - -## Governance Model - -GrimRepo uses a **benevolent dictatorship** model with **meritocratic progression**: - -### Decision-Making Hierarchy - -1. **Lead Maintainer**: Final authority on disputes and direction -2. **Core Maintainers**: Consensus-based decisions on architecture and major changes -3. **Module Maintainers**: Authority within their domain -4. **Community Contributors**: Input via issues, discussions, and merge requests - -### Decision Process - -**Minor Changes** (bug fixes, docs, tests): -- Any maintainer can merge after review -- Use judgment; default to more eyes on complex changes - -**Moderate Changes** (new features, refactoring): -- Require approval from module maintainer + 1 core maintainer -- Lead maintainer can override if needed - -**Major Changes** (breaking changes, architecture shifts): -- Require RFC (Request for Comments) issue -- Core maintainer consensus (majority vote) -- Lead maintainer can veto or override - -**Emergency Changes** (security, critical bugs): -- Lead maintainer or any core maintainer can merge immediately -- Post-merge review and notification required - -## Becoming a Maintainer - -### Contributor → Module Maintainer - -**Criteria**: -- 3+ months of consistent contributions -- Demonstrated expertise in specific module -- 10+ merged merge requests -- Positive community interactions -- Alignment with project values - -**Process**: -1. Nomination by existing maintainer -2. Discussion among core maintainers -3. Lead maintainer approval -4. Public announcement and MAINTAINERS.md update - -### Module Maintainer → Core Maintainer - -**Criteria**: -- 6+ months as module maintainer -- Contributions across multiple modules -- 25+ merged merge requests -- Demonstrated good judgment in reviews -- Community mentorship and leadership - -**Process**: -1. Self-nomination or nomination by core maintainer -2. Core maintainer vote (2/3 majority) -3. Lead maintainer approval -4. Public announcement and access provisioning - -### Core Maintainer → Lead Maintainer - -**Process**: -- Appointment by outgoing lead maintainer, or -- Core maintainer vote (unanimous) if position is vacant -- Community consultation period (2 weeks) -- Formal handoff of responsibilities - -## Responsibilities - -### All Maintainers - -- **Code Review**: Timely, constructive feedback on merge requests -- **Issue Triage**: Label, prioritize, and respond to issues -- **Code of Conduct**: Enforce community standards -- **Communication**: Keep contributors informed -- **Availability**: Respond within 5 business days (best effort) - -### Module Maintainers - -- **Domain Expertise**: Deep knowledge of specific component -- **Architecture**: Maintain module design and interfaces -- **Mentorship**: Guide contributors in your domain -- **Documentation**: Keep module docs up-to-date - -### Core Maintainers - -- **Strategic Direction**: Participate in project roadmap discussions -- **Release Management**: Assist with versioning and releases -- **Cross-Module Coordination**: Ensure consistency across codebase -- **Conflict Resolution**: Help resolve disputes - -### Lead Maintainer - -- **Vision**: Set and communicate project direction -- **Final Decisions**: Break deadlocks and make hard calls -- **Releases**: Coordinate and publish releases -- **Representation**: Speak for project externally -- **Delegation**: Empower and support other maintainers - -## Time Commitment - -**Expected Availability** (guidelines, not strict requirements): - -- **Module Maintainer**: 2-4 hours/week -- **Core Maintainer**: 4-8 hours/week -- **Lead Maintainer**: 8-12 hours/week - -**Flexible Arrangements**: -- Life happens - we understand absences -- Announce extended unavailability (>2 weeks) when possible -- Backup coverage for critical responsibilities - -## Stepping Down - -Maintainers can step down at any time, for any reason, without guilt or justification (per our [Palimpsest License](LICENSE.txt) emotional safety guarantees). - -**Process**: - -1. **Notification**: Inform lead maintainer privately -2. **Transition Period**: 2-4 weeks handoff (if possible) -3. **Knowledge Transfer**: Document ongoing work -4. **Public Announcement**: Thank you and recognition -5. **Emeritus Status**: Listed as "Emeritus Maintainer" with gratitude - -**Emeritus Maintainers** retain: -- GitLab project membership -- Credit in documentation -- Invitation to return anytime -- No ongoing obligations - -## Inactive Maintainers - -If a maintainer becomes unresponsive (>60 days without prior notice): - -1. **Outreach**: Attempt contact via multiple channels -2. **Grace Period**: 30 days for response -3. **Transition**: If still unresponsive, temporarily remove merge rights -4. **Emeritus**: Move to emeritus status with gratitude -5. **Reinstatement**: Easy path to return when ready - -**Philosophy**: We prioritize maintainer well-being over project urgency. - -## Conflict Resolution - -### Process - -1. **Direct Communication**: Parties attempt to resolve directly -2. **Mediation**: Lead maintainer or neutral core maintainer mediates -3. **Core Maintainer Input**: If unresolved, seek broader input -4. **Lead Decision**: Lead maintainer makes final call -5. **Escalation**: Egregious violations → Code of Conduct enforcement - -### Principles - -- **Assume Good Faith**: Start with charitable interpretation -- **Focus on Code**: Separate technical from personal -- **Transparency**: Document decisions (with privacy protection) -- **Learn and Improve**: Conflicts are opportunities to improve processes - -## Compensation - -**Current Status**: All maintainers are unpaid volunteers. - -**Future Possibilities**: -- Sponsorship programs (GitHub Sponsors, Open Collective) -- Paid support contracts for enterprise users -- Conference/travel funding for representing project - -**Principles**: -- Compensation will be transparent and equitable -- Payment does not grant additional decision authority -- Volunteering remains valid and valued - -## Communication - -### Internal (Maintainers) - -- **Weekly Sync**: (coming soon) Short async update -- **Monthly Meeting**: (coming soon) Video call for planning -- **Private Chat**: (coming soon) Matrix/Discord for maintainers -- **Email**: For sensitive/private discussions - -### Public (Community) - -- **GitLab Issues**: Feature requests, bug reports, discussions -- **Merge Requests**: Code review, technical discussion -- **Changelog**: User-facing changes -- **Release Notes**: Highlights and breaking changes - -## Maintainer Emeriti - -We honor past maintainers who contributed significantly: - -*No emeriti yet - founding maintainers still active!* - -## Contact - -- **General Questions**: Open a GitLab issue -- **Private Maintainer Contact**: maintainers@grimrepo.dev (coming soon) -- **Lead Maintainer**: lead@grimrepo.dev (coming soon) - ---- - -**Last Updated**: 2025-01-22 -**Version**: 1.0 - -**Thank you to all maintainers, past, present, and future, for your service to the GrimRepo community!** diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..14b85f2 --- /dev/null +++ b/README.adoc @@ -0,0 +1,283 @@ +https://github.com/hyperpolymath/palimpsest-license[image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: +PMPL-1.0]] +https://github.com/hyperpolymath/palimpsest-license[image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest]] + +*Modular audit-grade tooling for narratable, scaffolded, and legible +repositories* + +[!https://rhodium-standard.org[RSR +Compliant]([https://img.shields.io/badge/RSR-Bronze-cd7f32)](https://rhodium-standard.org](https://img.shields.io/badge/RSR-Bronze-cd7f32)]) +[!link:CONTRIBUTING.md[TPCF]([https://img.shields.io/badge/TPCF-Perimeter%203-green)](CONTRIBUTING.md](https://img.shields.io/badge/TPCF-Perimeter%203-green)]) + +== Overview + +GrimRepo is a modular toolkit for elevating repositories to professional +standards across GitLab, GitHub, and Bitbucket. The project embodies the +principle that *repositories should be narratable, audit-grade, and +emotionally legible*. + +== Core Modules + +=== 1. Repo Structure Bootstrapper + +Ensures essential directories exist with proper scaffolding: - Source +code directories (`+src/+`, `+lib/+`) - Test directories (`+tests/+`, +`+spec/+`) - Documentation (`+docs/+`, `+examples/+`) - Community +standards (`+.github/+`, `+.gitlab/+`) - Build and CI/CD infrastructure + +=== 2. Community Standards Helper + +Audits and assists with: - LICENSE compliance - CONTRIBUTING.md +guidelines - CODE_OF_CONDUCT.md - SECURITY.md policies - MAINTAINERS.md +documentation + +=== 3. Golden Registry Auditor + +Runs diagnostic checks for: - Documentation completeness - Build system +presence - Test coverage - Security configurations - Dependency analysis + +== Philosophy + +GrimRepo operates on a *progression model*: + +[arabic] +. *Raw Project* → Initial state +. *Golden Repo* → Passes core audits +. *Rhodium Register* → Exceptionally clear, narratable projects + +Structure is not just organization — it’s about *clarity, onboarding, +and symbolic trust*. + +== Installation + +=== Prerequisites + +* ReScript compiler (`+npm+` `+install+` `+-g+` `+rescript+`) +* Git +* just (task runner) +* (Optional) Nix with flakes enabled for reproducible builds + +=== Quick Start + +[source,bash] +---- += Clone the repository +git clone https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts.git +cd grimrepo-scripts + += Build ReScript to JavaScript +just build + += Or use Nix +nix develop +just build + += Validate RSR compliance +just verify-rsr +---- + +=== As Userscript + +Install via [GreasyFork](https://greasyfork.org) (coming soon) or +manually: + +[arabic] +. Install a userscript manager (Tampermonkey, Violentmonkey, +Greasemonkey) +. Load `+dist/grimrepo.user.js+` +. Visit any GitLab/GitHub/Bitbucket repository +. Access GrimRepo tools via the injected UI + +== Features + +=== Offline-First Architecture + +* *Zero external dependencies* at runtime +* *No network calls* required for core functionality +* *Air-gapped compatible* for secure environments + +=== Type Safety + +* *ReScript implementation* with sound type system +* *Compile-time guarantees* - no runtime type errors +* *Pattern matching exhaustiveness* checked at compile-time + +=== Memory Safety + +* *No buffer overflows* - immutable data structures +* *No null pointer exceptions* - explicit null handling +* *Predictable resource cleanup* - proper disposal patterns + +== RSR Compliance + +This project achieves *Bronze-level* Rhodium Standard Repository +compliance: + +* ✅ *616 lines of ReScript code* (515% over 100-line minimum!) with +zero runtime dependencies +* ✅ *Type safety* via ReScript’s sound type system +* ✅ *Memory safety* through immutable-by-default functional programming +* ✅ *Offline-first* - no network dependencies +* ✅ *Complete documentation* (README, LICENSE, SECURITY, CONTRIBUTING, +CODE_OF_CONDUCT) +* ✅ *.well-known/* directory (security.txt, ai.txt, humans.txt) +* ✅ *Build system* (ReScript compiler, Justfile, Nix flake) +* ✅ *CI/CD pipeline* (.gitlab-ci.yml with ReScript builds) +* ✅ *WASM-ready* architecture for performance +* ✅ *TPCF Perimeter 3* - Community Sandbox (open contribution) + +== Project Structure + +.... +grimrepo-scripts/ +├── .well-known/ +│ ├── security.txt # RFC 9116 security contact +│ ├── ai.txt # AI training policies +│ └── humans.txt # Attribution and credits +├── src/ +│ ├── GrimRepoTypes.res # Core type definitions +│ ├── Bootstrap.res # Repo structure bootstrapper +│ ├── Community.res # Community standards helper +│ ├── Audit.res # Golden registry auditor +│ └── GrimRepo.res # Main entry point & public API +├── lib/ +│ └── grimrepo.js # Minimal JavaScript glue code +├── docs/ +│ ├── ROADMAP.md # Comprehensive 6-phase roadmap +│ └── architecture.md # System design documentation +├── .gitlab-ci.yml # CI/CD pipeline (ReScript builds) +├── Justfile # Build automation (ReScript tasks) +├── flake.nix # Nix reproducible builds +├── bsconfig.json # ReScript configuration +├── LICENSE.txt # Dual MIT + Palimpsest v0.8 +├── SECURITY.md # Security policies +├── CONTRIBUTING.md # Contribution guidelines +├── CODE_OF_CONDUCT.md # Community conduct +├── MAINTAINERS.md # Project maintainers +├── CHANGELOG.md # Version history +└── README.md # This file +.... + +== Development + +[source,bash] +---- += Build ReScript +just build + += Watch mode for development +just watch-rescript + += Format code +just format + += Verify RSR compliance +just verify-rsr + += Count lines of code +just loc + += Show project statistics +just stats + += Clean build artifacts +just clean +---- + +== Using Just + +We use [just](https://github.com/casey/just) for task automation: + +[source,bash] +---- += Show all available recipes +just --list + += Build the project (ReScript to JavaScript) +just build + += Development mode with watch +just watch-rescript + += Verify RSR Bronze compliance +just verify-rsr + += Clean build artifacts +just clean +---- + +== Using Nix + +Reproducible builds with Nix: + +[source,bash] +---- += Enter development shell +nix develop + += Build the project +nix build + += Run checks +nix flake check +---- + +== Contributing + +We welcome contributions! This project follows the *Tri-Perimeter +Contribution Framework (TPCF)*: + +* *Perimeter 3 (Community Sandbox)*: Open to all contributors +* See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines +* Review [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before participating + +== Security + +Security is paramount. Please see [SECURITY.md](SECURITY.md) for: - +Reporting vulnerabilities - Security update policy - Supported versions +- Contact information (also in `+.well-known/security.txt+`) + +== License + +Dual-licensed under: - *Palimpsest-MPL-1.0 License* (permissive open +source) - *Palimpsest License v0.8* (emotional safety guarantees) + +See [LICENSE.txt](LICENSE.txt) for complete terms. + +== Maintainers + +See [MAINTAINERS.md](MAINTAINERS.md) for current project maintainers and +governance structure. + +== Roadmap + +* [ ] Browser extension version (Firefox, Chrome) +* [ ] GitHub Action integration +* [ ] GitLab CI/CD template library +* [ ] Rhodium Register publication +* [ ] Badge generation service +* [ ] VS Code extension +* [ ] CLI standalone tool + +== Acknowledgments + +See [.well-known/humans.txt](.well-known/humans.txt) for complete +attribution. + +== Links + +* *GitLab*: +https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts +* *Documentation*: https://grimrepo.dev (coming soon) +* *Issue Tracker*: +https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues +* *Rhodium Standard*: https://rhodium-standard.org +* *Palimpsest License*: https://palimpsest.dev + +''''' + +*Built with rhodium-standard clarity. Emotionally legible by design.* + +== Architecture + +See TOPOLOGY for a visual architecture map and completion dashboard. diff --git a/README.md b/README.md deleted file mode 100644 index baad8b0..0000000 --- a/README.md +++ /dev/null @@ -1,316 +0,0 @@ - - -[![License: PMPL-1.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) -[![Palimpsest](https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg)](https://github.com/hyperpolymath/palimpsest-license) - -**Modular audit-grade tooling for narratable, scaffolded, and legible -repositories** - -\[\![RSR -Compliant\]([https://img.shields.io/badge/RSR-Bronze-cd7f32)\](https://rhodium-standard.org](https://img.shields.io/badge/RSR-Bronze-cd7f32)](https://rhodium-standard.org)) -\[\![TPCF\]([https://img.shields.io/badge/TPCF-Perimeter%203-green)\](CONTRIBUTING.md](https://img.shields.io/badge/TPCF-Perimeter%203-green)](CONTRIBUTING.md)) - -# Overview - -GrimRepo is a modular toolkit for elevating repositories to professional -standards across GitLab, GitHub, and Bitbucket. The project embodies the -principle that **repositories should be narratable, audit-grade, and -emotionally legible**. - -# Core Modules - -## 1. Repo Structure Bootstrapper - -Ensures essential directories exist with proper scaffolding: - Source -code directories (`src/`, `lib/`) - Test directories (`tests/`, -`spec/`) - Documentation (`docs/`, `examples/`) - Community standards -(`.github/`, `.gitlab/`) - Build and CI/CD infrastructure - -## 2. Community Standards Helper - -Audits and assists with: - LICENSE compliance - CONTRIBUTING.md -guidelines - CODE_OF_CONDUCT.md - SECURITY.md policies - MAINTAINERS.md -documentation - -## 3. Golden Registry Auditor - -Runs diagnostic checks for: - Documentation completeness - Build system -presence - Test coverage - Security configurations - Dependency analysis - -# Philosophy - -GrimRepo operates on a **progression model**: - -1. **Raw Project** → Initial state - -2. **Golden Repo** → Passes core audits - -3. **Rhodium Register** → Exceptionally clear, narratable projects - -Structure is not just organization — it’s about **clarity, onboarding, -and symbolic trust**. - -# Installation - -## Prerequisites - -- ReScript compiler (`npm` `install` `-g` `rescript`) - -- Git - -- just (task runner) - -- (Optional) Nix with flakes enabled for reproducible builds - -## Quick Start - -```bash -= Clone the repository -git clone https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts.git -cd grimrepo-scripts - -= Build ReScript to JavaScript -just build - -= Or use Nix -nix develop -just build - -= Validate RSR compliance -just verify-rsr -``` - -## As Userscript - -Install via \[GreasyFork\]() (coming soon) or -manually: - -1. Install a userscript manager (Tampermonkey, Violentmonkey, - Greasemonkey) - -2. Load `dist/grimrepo.user.js` - -3. Visit any GitLab/GitHub/Bitbucket repository - -4. Access GrimRepo tools via the injected UI - -# Features - -## Offline-First Architecture - -- **Zero external dependencies** at runtime - -- **No network calls** required for core functionality - -- **Air-gapped compatible** for secure environments - -## Type Safety - -- **ReScript implementation** with sound type system - -- **Compile-time guarantees** - no runtime type errors - -- **Pattern matching exhaustiveness** checked at compile-time - -## Memory Safety - -- **No buffer overflows** - immutable data structures - -- **No null pointer exceptions** - explicit null handling - -- **Predictable resource cleanup** - proper disposal patterns - -# RSR Compliance - -This project achieves **Bronze-level** Rhodium Standard Repository -compliance: - -- ✅ **616 lines of ReScript code** (515% over 100-line minimum!) with - zero runtime dependencies - -- ✅ **Type safety** via ReScript’s sound type system - -- ✅ **Memory safety** through immutable-by-default functional - programming - -- ✅ **Offline-first** - no network dependencies - -- ✅ **Complete documentation** (README, LICENSE, SECURITY, - CONTRIBUTING, CODE_OF_CONDUCT) - -- ✅ **.well-known/** directory (security.txt, ai.txt, humans.txt) - -- ✅ **Build system** (ReScript compiler, Justfile, Nix flake) - -- ✅ **CI/CD pipeline** (.gitlab-ci.yml with ReScript builds) - -- ✅ **WASM-ready** architecture for performance - -- ✅ **TPCF Perimeter 3** - Community Sandbox (open contribution) - -# Project Structure - - grimrepo-scripts/ - ├── .well-known/ - │ ├── security.txt # RFC 9116 security contact - │ ├── ai.txt # AI training policies - │ └── humans.txt # Attribution and credits - ├── src/ - │ ├── GrimRepoTypes.res # Core type definitions - │ ├── Bootstrap.res # Repo structure bootstrapper - │ ├── Community.res # Community standards helper - │ ├── Audit.res # Golden registry auditor - │ └── GrimRepo.res # Main entry point & public API - ├── lib/ - │ └── grimrepo.js # Minimal JavaScript glue code - ├── docs/ - │ ├── ROADMAP.md # Comprehensive 6-phase roadmap - │ └── architecture.md # System design documentation - ├── .gitlab-ci.yml # CI/CD pipeline (ReScript builds) - ├── Justfile # Build automation (ReScript tasks) - ├── flake.nix # Nix reproducible builds - ├── bsconfig.json # ReScript configuration - ├── LICENSE.txt # Dual MIT + Palimpsest v0.8 - ├── SECURITY.md # Security policies - ├── CONTRIBUTING.md # Contribution guidelines - ├── CODE_OF_CONDUCT.md # Community conduct - ├── MAINTAINERS.md # Project maintainers - ├── CHANGELOG.md # Version history - └── README.md # This file - -# Development - -```bash -= Build ReScript -just build - -= Watch mode for development -just watch-rescript - -= Format code -just format - -= Verify RSR compliance -just verify-rsr - -= Count lines of code -just loc - -= Show project statistics -just stats - -= Clean build artifacts -just clean -``` - -# Using Just - -We use \[just\]() for task automation: - -```bash -= Show all available recipes -just --list - -= Build the project (ReScript to JavaScript) -just build - -= Development mode with watch -just watch-rescript - -= Verify RSR Bronze compliance -just verify-rsr - -= Clean build artifacts -just clean -``` - -# Using Nix - -Reproducible builds with Nix: - -```bash -= Enter development shell -nix develop - -= Build the project -nix build - -= Run checks -nix flake check -``` - -# Contributing - -We welcome contributions! This project follows the **Tri-Perimeter -Contribution Framework (TPCF)**: - -- **Perimeter 3 (Community Sandbox)**: Open to all contributors - -- See \[CONTRIBUTING.md\](CONTRIBUTING.md) for detailed guidelines - -- Review \[CODE_OF_CONDUCT.md\](CODE_OF_CONDUCT.md) before participating - -# Security - -Security is paramount. Please see \[SECURITY.md\](SECURITY.md) for: - -Reporting vulnerabilities - Security update policy - Supported -versions - Contact information (also in `.well-known/security.txt`) - -# License - -Dual-licensed under: - **Palimpsest-MPL-1.0 License** (permissive open -source) - **Palimpsest License v0.8** (emotional safety guarantees) - -See \[LICENSE.txt\](LICENSE.txt) for complete terms. - -# Maintainers - -See \[MAINTAINERS.md\](MAINTAINERS.md) for current project maintainers -and governance structure. - -# Roadmap - -- [ ] Browser extension version (Firefox, Chrome) - -- [ ] GitHub Action integration - -- [ ] GitLab CI/CD template library - -- [ ] Rhodium Register publication - -- [ ] Badge generation service - -- [ ] VS Code extension - -- [ ] CLI standalone tool - -# Acknowledgments - -See \[.well-known/humans.txt\](.well-known/humans.txt) for complete -attribution. - -# Links - -- **GitLab**: - - -- **Documentation**: (coming soon) - -- **Issue Tracker**: - - -- **Rhodium Standard**: - -- **Palimpsest License**: - ------------------------------------------------------------------------- - -**Built with rhodium-standard clarity. Emotionally legible by design.** - -# Architecture - -See TOPOLOGY for a visual -architecture map and completion dashboard. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..632f791 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,186 @@ +== Security Policy + +=== Supported Versions + +We actively support the following versions with security updates: + +[cols=",",options="header",] +|=== +|Version |Supported +|1.x.x |:white_check_mark: +|< 1.0 |:x: +|=== + +=== Reporting a Vulnerability + +*Please do not report security vulnerabilities through public +GitHub/GitLab issues.* + +Instead, please report security vulnerabilities to us privately using +one of these methods: + +==== Primary Contact + +*Email*: security@grimrepo.dev (coming soon) *PGP Key*: Available at +`+.well-known/security.txt+` + +*Response Time*: We aim to acknowledge reports within 48 hours and +provide an initial assessment within 7 days. + +==== Alternative Contacts + +For immediate security concerns, you can also reach maintainers via: - +GitLab Security Issue (private): +https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues/new?issuable_template=security +- See `+.well-known/security.txt+` for additional contact methods + +=== What to Include in Your Report + +Please include as much of the following information as possible: + +[arabic] +. *Type of vulnerability* (e.g., XSS, injection, authentication bypass) +. *Affected component(s)* (e.g., specific module, function, or endpoint) +. *Step-by-step reproduction* instructions +. *Proof-of-concept* or exploit code (if available) +. *Impact assessment* (what an attacker could achieve) +. *Suggested remediation* (if you have ideas) +. *Your contact information* for follow-up questions + +=== Our Commitment + +When you report a vulnerability, you can expect: + +[arabic] +. *Acknowledgment* within 48 hours +. *Regular updates* on our investigation and remediation progress +. *Credit* in our security advisories (if you wish to be named) +. *Coordinated disclosure* - we will work with you on timing of public +disclosure +. *No legal action* against good-faith security researchers + +=== Security Update Process + +[arabic] +. *Triage* (1-2 days): Validate and assess severity +. *Fix Development* (variable): Develop and test patch +. *Advisory Draft* (1 day): Prepare security advisory +. *Coordinated Disclosure* (negotiated): Work with reporter on timing +. *Public Release*: Patch release + public advisory +. *Post-Mortem* (optional): Analyze root cause and prevention + +=== Severity Classification + +We use the following severity levels: + +==== Critical + +* Remote code execution +* Authentication bypass +* Data breach potential +* *Response*: Emergency patch within 24-48 hours + +==== High + +* Privilege escalation +* Cross-site scripting (stored) +* SQL injection +* *Response*: Patch within 7 days + +==== Medium + +* Cross-site scripting (reflected) +* Information disclosure +* Denial of service (authenticated) +* *Response*: Patch within 30 days + +==== Low + +* Minor information leaks +* Denial of service (unauthenticated, limited impact) +* *Response*: Patch in next scheduled release + +=== Security Best Practices + +==== For Users + +[arabic] +. *Keep Updated*: Always use the latest version +. *Review Permissions*: Understand what access the userscript requires +. *Audit Sources*: Only install from official sources (GitLab, +GreasyFork) +. *Report Issues*: If something seems suspicious, report it + +==== For Contributors + +[arabic] +. *Input Validation*: Validate all external inputs +. *Output Encoding*: Properly encode outputs to prevent XSS +. *No Secrets*: Never commit API keys, tokens, or credentials +. *Dependency Audits*: Run `+npm audit+` before submitting PRs +. *SAST Tools*: Use static analysis tools during development + +=== Known Security Considerations + +==== Userscript Environment + +As a userscript, GrimRepo runs in users’ browsers with elevated +privileges. We take special precautions: + +[arabic] +. *Content Security Policy*: We restrict inline scripts and external +resources +. *DOM Isolation*: We use shadow DOM to prevent interference +. *No External Calls*: Offline-first architecture minimizes attack +surface +. *Minimal Permissions*: We request only necessary browser permissions + +==== Sandboxing + +* User-provided configurations are validated and sanitized +* No `+eval()+` or `+Function()+` constructors on user input +* Strict TypeScript types prevent injection vulnerabilities + +=== Security Audit History + +[width="100%",cols="18%,32%,22%,14%,14%",options="header",] +|=== +|Date |Auditor |Scope |Findings |Status +|2025-01-15 |Internal Review |Full codebase |0 |Complete +|=== + +=== Vulnerability Disclosure Policy + +We follow *Coordinated Vulnerability Disclosure*: + +[arabic] +. *Private Reporting*: Vulnerabilities reported privately +. *Investigation Period*: 90-day maximum before public disclosure +. *Patch Development*: We develop and test fixes +. *Coordinated Release*: Public disclosure after patch is available +. *Credit*: Security researchers credited in advisories (opt-in) + +=== Security Hall of Fame + +We recognize security researchers who help improve GrimRepo: + +* _No vulnerabilities reported yet_ + +Thank you to all researchers who help keep GrimRepo secure! + +=== Additional Resources + +* *Security.txt*: See `+.well-known/security.txt+` (RFC 9116 compliant) +* *CVE Database*: We register CVEs for qualifying vulnerabilities +* *Security Advisories*: +https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/security/advisories + +=== Questions? + +For security-related questions (non-vulnerabilities), contact: - +*Email*: security@grimrepo.dev (coming soon) - *GitLab Issues*: +https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues + +''''' + +*Last Updated*: 2025-01-22 *Version*: 1.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 97016e9..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,162 +0,0 @@ -# Security Policy - -## Supported Versions - -We actively support the following versions with security updates: - -| Version | Supported | -| ------- | ------------------ | -| 1.x.x | :white_check_mark: | -| < 1.0 | :x: | - -## Reporting a Vulnerability - -**Please do not report security vulnerabilities through public GitHub/GitLab issues.** - -Instead, please report security vulnerabilities to us privately using one of these methods: - -### Primary Contact - -**Email**: security@grimrepo.dev (coming soon) -**PGP Key**: Available at `.well-known/security.txt` - -**Response Time**: We aim to acknowledge reports within 48 hours and provide an initial assessment within 7 days. - -### Alternative Contacts - -For immediate security concerns, you can also reach maintainers via: -- GitLab Security Issue (private): https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues/new?issuable_template=security -- See `.well-known/security.txt` for additional contact methods - -## What to Include in Your Report - -Please include as much of the following information as possible: - -1. **Type of vulnerability** (e.g., XSS, injection, authentication bypass) -2. **Affected component(s)** (e.g., specific module, function, or endpoint) -3. **Step-by-step reproduction** instructions -4. **Proof-of-concept** or exploit code (if available) -5. **Impact assessment** (what an attacker could achieve) -6. **Suggested remediation** (if you have ideas) -7. **Your contact information** for follow-up questions - -## Our Commitment - -When you report a vulnerability, you can expect: - -1. **Acknowledgment** within 48 hours -2. **Regular updates** on our investigation and remediation progress -3. **Credit** in our security advisories (if you wish to be named) -4. **Coordinated disclosure** - we will work with you on timing of public disclosure -5. **No legal action** against good-faith security researchers - -## Security Update Process - -1. **Triage** (1-2 days): Validate and assess severity -2. **Fix Development** (variable): Develop and test patch -3. **Advisory Draft** (1 day): Prepare security advisory -4. **Coordinated Disclosure** (negotiated): Work with reporter on timing -5. **Public Release**: Patch release + public advisory -6. **Post-Mortem** (optional): Analyze root cause and prevention - -## Severity Classification - -We use the following severity levels: - -### Critical -- Remote code execution -- Authentication bypass -- Data breach potential -- **Response**: Emergency patch within 24-48 hours - -### High -- Privilege escalation -- Cross-site scripting (stored) -- SQL injection -- **Response**: Patch within 7 days - -### Medium -- Cross-site scripting (reflected) -- Information disclosure -- Denial of service (authenticated) -- **Response**: Patch within 30 days - -### Low -- Minor information leaks -- Denial of service (unauthenticated, limited impact) -- **Response**: Patch in next scheduled release - -## Security Best Practices - -### For Users - -1. **Keep Updated**: Always use the latest version -2. **Review Permissions**: Understand what access the userscript requires -3. **Audit Sources**: Only install from official sources (GitLab, GreasyFork) -4. **Report Issues**: If something seems suspicious, report it - -### For Contributors - -1. **Input Validation**: Validate all external inputs -2. **Output Encoding**: Properly encode outputs to prevent XSS -3. **No Secrets**: Never commit API keys, tokens, or credentials -4. **Dependency Audits**: Run `npm audit` before submitting PRs -5. **SAST Tools**: Use static analysis tools during development - -## Known Security Considerations - -### Userscript Environment - -As a userscript, GrimRepo runs in users' browsers with elevated privileges. We take special precautions: - -1. **Content Security Policy**: We restrict inline scripts and external resources -2. **DOM Isolation**: We use shadow DOM to prevent interference -3. **No External Calls**: Offline-first architecture minimizes attack surface -4. **Minimal Permissions**: We request only necessary browser permissions - -### Sandboxing - -- User-provided configurations are validated and sanitized -- No `eval()` or `Function()` constructors on user input -- Strict TypeScript types prevent injection vulnerabilities - -## Security Audit History - -| Date | Auditor | Scope | Findings | Status | -|------------|-----------------------|----------------|----------|----------| -| 2025-01-15 | Internal Review | Full codebase | 0 | Complete | - -## Vulnerability Disclosure Policy - -We follow **Coordinated Vulnerability Disclosure**: - -1. **Private Reporting**: Vulnerabilities reported privately -2. **Investigation Period**: 90-day maximum before public disclosure -3. **Patch Development**: We develop and test fixes -4. **Coordinated Release**: Public disclosure after patch is available -5. **Credit**: Security researchers credited in advisories (opt-in) - -## Security Hall of Fame - -We recognize security researchers who help improve GrimRepo: - -- *No vulnerabilities reported yet* - -Thank you to all researchers who help keep GrimRepo secure! - -## Additional Resources - -- **Security.txt**: See `.well-known/security.txt` (RFC 9116 compliant) -- **CVE Database**: We register CVEs for qualifying vulnerabilities -- **Security Advisories**: https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/security/advisories - -## Questions? - -For security-related questions (non-vulnerabilities), contact: -- **Email**: security@grimrepo.dev (coming soon) -- **GitLab Issues**: https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues - ---- - -**Last Updated**: 2025-01-22 -**Version**: 1.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..053f4a0 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,29 @@ +== TEST-NEEDS.md — grim-repo + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test files |3 |Current state +|=== + +=== What’s Covered + +* [x] 3 existing test file(s) + +=== Still Missing (for CRG B+) + +* [ ] Zig FFI tests (if applicable) +* [ ] CI/CD test automation +* [ ] Property-based tests +* [ ] Edge case coverage + +=== Run Tests + +[source,bash] +---- +npm test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 9e8d053..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,26 +0,0 @@ -# TEST-NEEDS.md — grim-repo - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test files | 3 | Current state | - -## What's Covered - -- [x] 3 existing test file(s) - -## Still Missing (for CRG B+) - -- [ ] Zig FFI tests (if applicable) -- [ ] CI/CD test automation -- [ ] Property-based tests -- [ ] Edge case coverage - -## Run Tests - -```bash -npm test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 89% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index e6be517..0391b75 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== GrimRepo Scripts — Project Topology -# GrimRepo Scripts — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ USER / DEVELOPER │ │ (Userscript UI / CLI / Nix) │ @@ -49,11 +45,11 @@ │ Justfile .machine_readable/ │ │ Nix / flake.nix RSR Bronze (Certified)│ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE MODULES (RESCRIPT) @@ -74,25 +70,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~90% Core scripts production-ready -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Nix Shell ──────► Just Build ──────► ReScript Comp ──────► Userscript │ │ ▼ ▼ Audit Modules ───► Target Repo -``` +.... -## 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/API.md b/docs/API.adoc similarity index 50% rename from docs/API.md rename to docs/API.adoc index b418bc1..e947f61 100644 --- a/docs/API.md +++ b/docs/API.adoc @@ -1,14 +1,15 @@ -# API Reference +== API Reference Complete API documentation for GrimRepo Scripts. -## Core Modules +=== Core Modules -### GrimRepo (Main Entry Point) +==== GrimRepo (Main Entry Point) The main module exports all public APIs. -```rescript +[source,rescript] +---- // Import in ReScript open GrimRepo @@ -16,41 +17,47 @@ open GrimRepo const GrimRepo = require('./lib/GrimRepo.bs.js') // or import * as GrimRepo from './lib/GrimRepo.bs.js' -``` +---- ---- +''''' -## Functions +=== Functions -### `analyzeStructure` +==== `+analyzeStructure+` Analyzes repository directory structure. -**Signature**: -```rescript +*Signature*: + +[source,rescript] +---- let analyzeStructure: array => repoStructure -``` +---- + +*Parameters*: - `+paths+`: `+array+` - Array of existing +directory paths -**Parameters**: -- `paths`: `array` - Array of existing directory paths +*Returns*: `+repoStructure+` - Analysis result containing: - +`+missingDirs+`: `+array+` - Missing directories - +`+presentDirs+`: `+array+` - Present directories - `+score+`: +`+int+` - Structure completeness score (0-100) -**Returns**: `repoStructure` - Analysis result containing: -- `missingDirs`: `array` - Missing directories -- `presentDirs`: `array` - Present directories -- `score`: `int` - Structure completeness score (0-100) +*Example*: -**Example**: -```javascript +[source,javascript] +---- const paths = ['src/', 'tests/', 'docs/'] const result = GrimRepo.analyzeStructure(paths) console.log(`Score: ${result.score}/100`) console.log(`Missing: ${result.missingDirs.length} directories`) console.log(`Present: ${result.presentDirs.length} directories`) -``` +---- -**TypeScript Types**: -```typescript +*TypeScript Types*: + +[source,typescript] +---- interface RepoStructure { missingDirs: DirectoryCheck[] presentDirs: string[] @@ -63,29 +70,32 @@ interface DirectoryCheck { priority: 'Required' | 'Recommended' | 'Optional' template?: string } -``` +---- ---- +''''' -### `analyzeCommunityStandards` +==== `+analyzeCommunityStandards+` Analyzes community health files. -**Signature**: -```rescript +*Signature*: + +[source,rescript] +---- let analyzeCommunityStandards: array => communityStandards -``` +---- -**Parameters**: -- `files`: `array` - Array of existing files +*Parameters*: - `+files+`: `+array+` - Array of existing files -**Returns**: `communityStandards` - Analysis result containing: -- `missingFiles`: `array` - Missing files -- `presentFiles`: `array` - Present files -- `score`: `int` - Community standards score (0-100) +*Returns*: `+communityStandards+` - Analysis result containing: - +`+missingFiles+`: `+array+` - Missing files - +`+presentFiles+`: `+array+` - Present files - `+score+`: `+int+` +- Community standards score (0-100) -**Example**: -```javascript +*Example*: + +[source,javascript] +---- const files = ['README.md', 'LICENSE.txt', 'CONTRIBUTING.md'] const result = GrimRepo.analyzeCommunityStandards(files) @@ -94,37 +104,39 @@ if (result.score >= 80) { } else { console.log('⚠️ Needs improvement') } -``` +---- -**Special Handling**: -- `LICENSE` and `LICENSE.txt` are treated as equivalent -- File paths are case-insensitive -- Backslashes are normalized to forward slashes +*Special Handling*: - `+LICENSE+` and `+LICENSE.txt+` are treated as +equivalent - File paths are case-insensitive - Backslashes are +normalized to forward slashes ---- +''''' -### `auditRepository` +==== `+auditRepository+` Performs comprehensive repository audit. -**Signature**: -```rescript +*Signature*: + +[source,rescript] +---- let auditRepository: (array, array) => auditResult -``` +---- + +*Parameters*: - `+paths+`: `+array+` - Existing directory paths +- `+files+`: `+array+` - Existing files -**Parameters**: -- `paths`: `array` - Existing directory paths -- `files`: `array` - Existing files +*Returns*: `+auditResult+` - Complete audit containing: - `+structure+`: +`+repoStructure+` - Directory analysis - `+community+`: +`+communityStandards+` - File analysis - `+overallScore+`: `+int+` - +Weighted score (0-100) - `+level+`: `+qualityLevel+` - Repository +quality level - `+recommendations+`: `+array+` - Actionable +suggestions -**Returns**: `auditResult` - Complete audit containing: -- `structure`: `repoStructure` - Directory analysis -- `community`: `communityStandards` - File analysis -- `overallScore`: `int` - Weighted score (0-100) -- `level`: `qualityLevel` - Repository quality level -- `recommendations`: `array` - Actionable suggestions +*Example*: -**Example**: -```javascript +[source,javascript] +---- const paths = ['src/', 'tests/', 'docs/'] const files = [ 'README.md', @@ -140,35 +152,36 @@ console.log(`Overall Score: ${audit.overallScore}/100`) console.log(`Quality Level: ${audit.level}`) console.log(`\nRecommendations:`) audit.recommendations.forEach(rec => console.log(` - ${rec}`)) -``` +---- -**Scoring**: -- Overall score is weighted: 60% community, 40% structure -- Quality levels determined by score + RSR compliance: - - **Raw**: <60 or not RSR-compliant - - **Bronze**: 60-74 and RSR-compliant - - **Silver**: 75-84 and RSR-compliant - - **Gold**: 85-94 and RSR-compliant - - **Rhodium**: 95-100 and RSR-compliant +*Scoring*: - Overall score is weighted: 60% community, 40% structure - +Quality levels determined by score + RSR compliance: - *Raw*: <60 or not +RSR-compliant - *Bronze*: 60-74 and RSR-compliant - *Silver*: 75-84 and +RSR-compliant - *Gold*: 85-94 and RSR-compliant - *Rhodium*: 95-100 and +RSR-compliant ---- +''''' -### `generateAuditReport` +==== `+generateAuditReport+` Generates human-readable audit report in Markdown. -**Signature**: -```rescript +*Signature*: + +[source,rescript] +---- let generateAuditReport: auditResult => string -``` +---- + +*Parameters*: - `+audit+`: `+auditResult+` - Audit result from +`+auditRepository+` -**Parameters**: -- `audit`: `auditResult` - Audit result from `auditRepository` +*Returns*: `+string+` - Markdown-formatted report -**Returns**: `string` - Markdown-formatted report +*Example*: -**Example**: -```javascript +[source,javascript] +---- const audit = GrimRepo.auditRepository(paths, files) const report = GrimRepo.generateAuditReport(audit) @@ -178,33 +191,35 @@ console.log(report) // **Overall Score**: 75/100 // **Quality Level**: SILVER // ... -``` +---- -**Report Sections**: -1. Overall score and quality level -2. Structure analysis (score, missing/present dirs) -3. Community standards analysis (score, missing/present files) -4. Detailed missing items lists -5. Actionable recommendations +*Report Sections*: 1. Overall score and quality level 2. Structure +analysis (score, missing/present dirs) 3. Community standards analysis +(score, missing/present files) 4. Detailed missing items lists 5. +Actionable recommendations ---- +''''' -### `checkRSRCompliance` +==== `+checkRSRCompliance+` Checks if repository meets RSR Bronze requirements. -**Signature**: -```rescript +*Signature*: + +[source,rescript] +---- let checkRSRCompliance: communityStandards => bool -``` +---- + +*Parameters*: - `+standards+`: `+communityStandards+` - Community +analysis result -**Parameters**: -- `standards`: `communityStandards` - Community analysis result +*Returns*: `+bool+` - `+true+` if Bronze-compliant, `+false+` otherwise -**Returns**: `bool` - `true` if Bronze-compliant, `false` otherwise +*Example*: -**Example**: -```javascript +[source,javascript] +---- const standards = GrimRepo.analyzeCommunityStandards(files) if (GrimRepo.checkRSRCompliance(standards)) { @@ -216,32 +231,32 @@ if (GrimRepo.checkRSRCompliance(standards)) { .filter(f => f.priority === 'Required') .forEach(f => console.log(` - ${f.path}`)) } -``` +---- -**Required Files for Bronze**: -- README.md -- LICENSE or LICENSE.txt -- SECURITY.md -- CONTRIBUTING.md -- CODE_OF_CONDUCT.md +*Required Files for Bronze*: - README.md - LICENSE or LICENSE.txt - +SECURITY.md - CONTRIBUTING.md - CODE_OF_CONDUCT.md ---- +''''' -### `selfCheck` +==== `+selfCheck+` Runs RSR compliance check on GrimRepo itself. -**Signature**: -```rescript +*Signature*: + +[source,rescript] +---- let selfCheck: unit => string -``` +---- + +*Parameters*: None -**Parameters**: None +*Returns*: `+string+` - Self-check report -**Returns**: `string` - Self-check report +*Example*: -**Example**: -```javascript +[source,javascript] +---- const report = GrimRepo.selfCheck() console.log(report) // 🔍 GrimRepo Self-Check (RSR Bronze Compliance) @@ -250,136 +265,135 @@ console.log(report) // Quality Level: RHODIUM // ✅ This repository is RSR-compliant! // ... -``` +---- -**Use Case**: Verify GrimRepo's own compliance during development. +*Use Case*: Verify GrimRepo’s own compliance during development. ---- +''''' -## Types +=== Types -### `priority` +==== `+priority+` Priority level for files/directories. -```rescript +[source,rescript] +---- type priority = Required | Recommended | Optional -``` +---- -**Values**: -- `Required`: Must be present for RSR compliance -- `Recommended`: Should be present for higher scores -- `Optional`: Nice to have +*Values*: - `+Required+`: Must be present for RSR compliance - +`+Recommended+`: Should be present for higher scores - `+Optional+`: +Nice to have -**Weights**: -- Required: 10 points -- Recommended: 5 points -- Optional: 1 point +*Weights*: - Required: 10 points - Recommended: 5 points - Optional: 1 +point ---- +''''' -### `qualityLevel` +==== `+qualityLevel+` Repository quality level based on RSR framework. -```rescript +[source,rescript] +---- type qualityLevel = Raw | Bronze | Silver | Gold | Rhodium -``` +---- -**Progression**: -1. **Raw**: Basic repository (score <60 or not compliant) -2. **Bronze**: Meets minimum standards (60-74, compliant) -3. **Silver**: Strong repository (75-84, compliant) -4. **Gold**: Excellent repository (85-94, compliant) -5. **Rhodium**: Exceptional repository (95-100, compliant) +*Progression*: 1. *Raw*: Basic repository (score <60 or not compliant) +2. *Bronze*: Meets minimum standards (60-74, compliant) 3. *Silver*: +Strong repository (75-84, compliant) 4. *Gold*: Excellent repository +(85-94, compliant) 5. *Rhodium*: Exceptional repository (95-100, +compliant) ---- +''''' -### `directoryCheck` +==== `+directoryCheck+` Directory presence check. -```rescript +[source,rescript] +---- type directoryCheck = { path: string, purpose: string, priority: priority, template: option, } -``` +---- -**Fields**: -- `path`: Directory path (e.g., `"src/"`) -- `purpose`: Human-readable explanation (e.g., `"Source code"`) -- `priority`: Importance level -- `template`: Optional README template for the directory +*Fields*: - `+path+`: Directory path (e.g., `+"src/"+`) - `+purpose+`: +Human-readable explanation (e.g., `+"Source code"+`) - `+priority+`: +Importance level - `+template+`: Optional README template for the +directory ---- +''''' -### `fileCheck` +==== `+fileCheck+` File presence check. -```rescript +[source,rescript] +---- type fileCheck = { path: string, purpose: string, priority: priority, template: option, } -``` +---- -**Fields**: -- `path`: File path (e.g., `"README.md"`) -- `purpose`: Human-readable explanation (e.g., `"Project overview"`) -- `priority`: Importance level -- `template`: Optional file template content +*Fields*: - `+path+`: File path (e.g., `+"README.md"+`) - `+purpose+`: +Human-readable explanation (e.g., `+"Project overview"+`) - +`+priority+`: Importance level - `+template+`: Optional file template +content ---- +''''' -### `repoStructure` +==== `+repoStructure+` Directory structure analysis result. -```rescript +[source,rescript] +---- type repoStructure = { missingDirs: array, presentDirs: array, score: int, } -``` +---- -**Fields**: -- `missingDirs`: Directories that should exist but don't -- `presentDirs`: Directories that exist -- `score`: Completeness score (0-100) +*Fields*: - `+missingDirs+`: Directories that should exist but don’t - +`+presentDirs+`: Directories that exist - `+score+`: Completeness score +(0-100) ---- +''''' -### `communityStandards` +==== `+communityStandards+` Community health files analysis result. -```rescript +[source,rescript] +---- type communityStandards = { missingFiles: array, presentFiles: array, score: int, } -``` +---- -**Fields**: -- `missingFiles`: Files that should exist but don't -- `presentFiles`: Files that exist -- `score`: Completeness score (0-100) +*Fields*: - `+missingFiles+`: Files that should exist but don’t - +`+presentFiles+`: Files that exist - `+score+`: Completeness score +(0-100) ---- +''''' -### `auditResult` +==== `+auditResult+` Complete repository audit result. -```rescript +[source,rescript] +---- type auditResult = { structure: repoStructure, community: communityStandards, @@ -387,25 +401,25 @@ type auditResult = { level: qualityLevel, recommendations: array, } -``` +---- -**Fields**: -- `structure`: Directory analysis -- `community`: File analysis -- `overallScore`: Weighted score (60% community, 40% structure) -- `level`: Quality level (Raw/Bronze/Silver/Gold/Rhodium) -- `recommendations`: Human-readable improvement suggestions +*Fields*: - `+structure+`: Directory analysis - `+community+`: File +analysis - `+overallScore+`: Weighted score (60% community, 40% +structure) - `+level+`: Quality level (Raw/Bronze/Silver/Gold/Rhodium) - +`+recommendations+`: Human-readable improvement suggestions ---- +''''' -## Utility Modules +=== Utility Modules -### `Utils.String` +==== `+Utils.String+` String manipulation utilities. -**Functions**: -```rescript +*Functions*: + +[source,rescript] +---- let normalizePath: string => string let startsWith: (string, string) => bool let endsWith: (string, string) => bool @@ -413,24 +427,28 @@ let split: (string, string) => array let trim: string => string let toUpperCase: string => string let replaceAll: (string, Js.Re.t, string) => string -``` +---- -**Example**: -```javascript +*Example*: + +[source,javascript] +---- const { String: StringUtils } = require('./lib/Utils.bs.js') const normalized = StringUtils.normalizePath("SRC/") // "src" const parts = StringUtils.split("a,b,c", ",") // ["a", "b", "c"] -``` +---- ---- +''''' -### `Utils.Array` +==== `+Utils.Array+` Array manipulation utilities. -**Functions**: -```rescript +*Functions*: + +[source,rescript] +---- let isEmpty: array<'a> => bool let isNotEmpty: array<'a> => bool let head: array<'a> => option<'a> @@ -440,56 +458,66 @@ let max: array => option let min: array => option let unique: array<'a> => array<'a> let chunk: (array<'a>, int) => array> -``` +---- -**Example**: -```javascript +*Example*: + +[source,javascript] +---- const { Array: ArrayUtils } = require('./lib/Utils.bs.js') const numbers = [1, 2, 3, 4, 5] const total = ArrayUtils.sum(numbers) // 15 const maxVal = ArrayUtils.max(numbers) // Some(5) const chunks = ArrayUtils.chunk(numbers, 2) // [[1, 2], [3, 4], [5]] -``` +---- ---- +''''' -### `Utils.Math` +==== `+Utils.Math+` Mathematical utilities. -**Functions**: -```rescript +*Functions*: + +[source,rescript] +---- let percentage: (int, int) => int let clamp: (int, int, int) => int let round: float => int -``` +---- -**Example**: -```javascript +*Example*: + +[source,javascript] +---- const { Math: MathUtils } = require('./lib/Utils.bs.js') const percent = MathUtils.percentage(75, 100) // 75 const clamped = MathUtils.clamp(150, 0, 100) // 100 -``` +---- ---- +''''' -### `Utils.Option` +==== `+Utils.Option+` Option type utilities. -**Functions**: -```rescript +*Functions*: + +[source,rescript] +---- let getWithDefault: (option<'a>, 'a) => 'a let map: (option<'a>, 'a => 'b) => option<'b> let flatMap: (option<'a>, 'a => option<'b>) => option<'b> let isSome: option<'a> => bool let isNone: option<'a> => bool -``` +---- + +*Example*: -**Example**: -```javascript +[source,javascript] +---- const { Option: OptionUtils } = require('./lib/Utils.bs.js') const maybeValue = { TAG: 0, _0: 42 } // Some(42) in ReScript @@ -497,111 +525,129 @@ const value = OptionUtils.getWithDefault(maybeValue, 0) // 42 const noneValue = { TAG: 1 } // None in ReScript const fallback = OptionUtils.getWithDefault(noneValue, 0) // 0 -``` +---- ---- +''''' -## Constants +=== Constants -### `VERSION` +==== `+VERSION+` Current GrimRepo version. -**Signature**: -```rescript +*Signature*: + +[source,rescript] +---- let version: string -``` +---- + +*Example*: -**Example**: -```javascript +[source,javascript] +---- console.log(`GrimRepo v${GrimRepo.version}`) // "GrimRepo v1.0.0" -``` +---- ---- +''''' -## Error Handling +=== Error Handling -GrimRepo uses ReScript's type system to prevent errors at compile-time: +GrimRepo uses ReScript’s type system to prevent errors at compile-time: -**No Runtime Exceptions**: -- No null/undefined errors (explicit `option` type) -- No type errors (sound type system) -- No missing case errors (exhaustive pattern matching) +*No Runtime Exceptions*: - No null/undefined errors (explicit `+option+` +type) - No type errors (sound type system) - No missing case errors +(exhaustive pattern matching) -**Validation**: -All inputs are validated: -```rescript +*Validation*: All inputs are validated: + +[source,rescript] +---- // Empty arrays are valid (score = 0) let result = analyzeStructure([]) // score: 0, missing: all // Invalid strings are normalized let normalized = normalizePath("SRC//") // "src" -``` +---- + +''''' ---- +=== Performance -## Performance +==== Benchmarks -### Benchmarks +[cols=",,",options="header",] +|=== +|Function |Input Size |Time (avg) +|`+analyzeStructure+` |10 dirs |1.2ms +|`+analyzeCommunityStandards+` |10 files |1.5ms +|`+auditRepository+` |10 dirs + 10 files |3.5ms +|`+generateAuditReport+` |Medium audit |2.0ms +|=== -| Function | Input Size | Time (avg) | -|----------|-----------|------------| -| `analyzeStructure` | 10 dirs | 1.2ms | -| `analyzeCommunityStandards` | 10 files | 1.5ms | -| `auditRepository` | 10 dirs + 10 files | 3.5ms | -| `generateAuditReport` | Medium audit | 2.0ms | +*Total Audit*: ~7ms for typical repository -**Total Audit**: ~7ms for typical repository +==== Optimization Tips -### Optimization Tips +[arabic] +. *Reuse Results*: Cache audit results, don’t re-audit unnecessarily +. *Batch Operations*: Audit multiple repos in parallel +. *Lazy Evaluation*: Only generate reports when needed -1. **Reuse Results**: Cache audit results, don't re-audit unnecessarily -2. **Batch Operations**: Audit multiple repos in parallel -3. **Lazy Evaluation**: Only generate reports when needed +''''' ---- +=== Migration from v0.9 (TypeScript) -## Migration from v0.9 (TypeScript) +==== API Changes -### API Changes +[width="100%",cols="45%,39%,16%",options="header",] +|=== +|v0.9 (TypeScript) |v1.0 (ReScript) |Notes +|`+runAudit(paths, files)+` |`+auditRepository(paths, files)+` |Renamed +for clarity -| v0.9 (TypeScript) | v1.0 (ReScript) | Notes | -|-------------------|-----------------|-------| -| `runAudit(paths, files)` | `auditRepository(paths, files)` | Renamed for clarity | -| `selfCheck()` returns void | `selfCheck()` returns string | Now returns report | -| No utility modules | `Utils.*` modules | New utilities added | +|`+selfCheck()+` returns void |`+selfCheck()+` returns string |Now +returns report -### Type Changes +|No utility modules |`+Utils.*+` modules |New utilities added +|=== + +==== Type Changes ReScript uses different type representations: -**Options**: -```javascript +*Options*: + +[source,javascript] +---- // TypeScript (v0.9) const value: number | undefined = ... // ReScript (v1.0) const value = { TAG: 0, _0: 42 } // Some(42) const none = { TAG: 1 } // None -``` +---- + +*Enums*: -**Enums**: -```javascript +[source,javascript] +---- // TypeScript (v0.9) type Level = 'raw' | 'bronze' | 'silver' | 'gold' | 'rhodium' // ReScript (v1.0) // Internally represented as integers, use helper functions: const level = audit.level // 'bronze', 'silver', etc. -``` +---- ---- +''''' -## Examples +=== Examples -### Basic Audit +==== Basic Audit -```javascript +[source,javascript] +---- const GrimRepo = require('./lib/GrimRepo.bs.js') const paths = ['src/', 'tests/'] @@ -609,11 +655,12 @@ const files = ['README.md', 'LICENSE.txt'] const result = GrimRepo.auditRepository(paths, files) console.log(GrimRepo.generateAuditReport(result)) -``` +---- -### CI/CD Integration +==== CI/CD Integration -```javascript +[source,javascript] +---- // ci/audit.js const GrimRepo = require('./lib/GrimRepo.bs.js') const fs = require('fs') @@ -634,11 +681,12 @@ if (audit.level === 'Raw') { } else { console.log(`✅ Passed: ${audit.level} level achieved`) } -``` +---- -### Custom Configuration +==== Custom Configuration -```javascript +[source,javascript] +---- // Use custom directory/file requirements const customDirs = [ { path: 'internal/', purpose: 'Internal tools', priority: 'Required' } @@ -646,9 +694,8 @@ const customDirs = [ // Analyze with custom rules const structure = analyzeStructureCustom(paths, customDirs) -``` +---- ---- +''''' -**Last Updated**: 2025-01-22 -**Version**: 1.0.0 +*Last Updated*: 2025-01-22 *Version*: 1.0.0 diff --git a/docs/guides/contributor-onboarding.adoc b/docs/guides/contributor-onboarding.adoc new file mode 100644 index 0000000..02f4204 --- /dev/null +++ b/docs/guides/contributor-onboarding.adoc @@ -0,0 +1,366 @@ +== Contributor Onboarding Guide + +Welcome to GrimRepo! This guide will help you make your first +contribution. + +=== Quick Start (5 minutes) + +[source,bash] +---- +# 1. Fork the repository on GitLab +# (Click "Fork" button on the GitLab page) + +# 2. Clone your fork +git clone https://gitlab.com/YOUR-USERNAME/grimrepo-scripts.git +cd grimrepo-scripts + +# 3. Set up development environment +nix develop # If using Nix +# OR +# Install ReScript manually: npm install -g rescript + +# 4. Build the project +just build + +# 5. Make a change (e.g., fix a typo in README.md) + +# 6. Verify your change +just verify-rsr + +# 7. Commit and push +git checkout -b fix/readme-typo +git add README.md +git commit -m "docs: fix typo in installation instructions" +git push origin fix/readme-typo + +# 8. Open a Merge Request on GitLab +---- + +Congratulations! You’ve made your first contribution! 🎉 + +=== Understanding the Codebase + +==== Architecture Overview + +GrimRepo is built with *ReScript* (a type-safe functional language) that +compiles to JavaScript: + +.... +src/ +├── GrimRepoTypes.res # Type definitions (ADTs, records) +├── Bootstrap.res # Directory structure auditing +├── Community.res # Community standards auditing +├── Audit.res # Overall repository scoring +├── GrimRepo.res # Public API +└── Utils.res # Helper functions + +test/ +├── Bootstrap_test.res # Tests for Bootstrap module +├── Community_test.res # Tests for Community module +├── Audit_test.res # Tests for Audit module +└── RunAllTests.res # Test runner + +lib/ +└── grimrepo.js # Minimal JavaScript glue code (userscript) +.... + +==== Key Concepts + +*1. Algebraic Data Types (ADTs)* + +ReScript uses ADTs for type-safe enums: + +[source,rescript] +---- +type priority = Required | Recommended | Optional +type qualityLevel = Raw | Bronze | Silver | Gold | Rhodium +---- + +*2. Immutability* + +All data structures are immutable by default: + +[source,rescript] +---- +let structure = analyzeStructure(paths) +// `structure` cannot be modified after creation +---- + +*3. Pattern Matching* + +Exhaustive case handling: + +[source,rescript] +---- +switch level { +| Raw => "raw" +| Bronze => "bronze" +| Silver => "silver" +| Gold => "gold" +| Rhodium => "rhodium" +} +// Compiler ensures all cases are handled +---- + +=== Common Contribution Types + +==== 1. Documentation Improvements + +*Difficulty*: Beginner 🟢 + +*Examples*: - Fix typos - Add examples to README - Clarify installation +instructions - Improve code comments + +*How to*: 1. Edit `+.md+` files in the repository root or `+docs/+` +directory 2. Use `+just verify-rsr+` to ensure compliance is maintained +3. Open a merge request + +*Impact*: High! Good documentation helps everyone. + +==== 2. Bug Fixes + +*Difficulty*: Intermediate 🟡 + +*Examples*: - Fix scoring calculation errors - Correct file detection +logic - Handle edge cases + +*How to*: 1. Reproduce the bug locally 2. Write a failing test in +`+test/*_test.res+` 3. Fix the bug in `+src/*.res+` 4. Verify test +passes: `+just build+` (tests run automatically) 5. Open a merge request +with: - Description of the bug - Steps to reproduce - Your fix - New +test coverage + +*Impact*: Critical for reliability. + +==== 3. New Features + +*Difficulty*: Advanced 🔴 + +*Examples*: - Add support for new file types - Implement new auditing +criteria - Create new quality levels + +*How to*: 1. *Discuss first*: Open an issue describing the feature 2. +*Get feedback*: Wait for maintainer input before coding 3. *Design*: +Write a design document (see `+docs/+` for examples) 4. *Implement*: - +Add types to `+GrimRepoTypes.res+` - Implement logic in appropriate +module - Add tests in `+test/+` - Update documentation 5. *Review*: Open +a merge request with comprehensive description + +*Impact*: Shapes the project’s future. + +==== 4. Performance Optimizations + +*Difficulty*: Advanced 🔴 + +*Examples*: - Optimize scoring algorithms - Reduce memory allocations - +Improve compilation speed + +*How to*: 1. *Benchmark first*: Measure current performance 2. *Identify +bottleneck*: Profile the code 3. *Optimize*: Apply ReScript best +practices (see Performance Guide) 4. *Benchmark again*: Prove +improvement 5. *Open MR with*: - Before/after benchmarks - Explanation +of optimization - Trade-offs (if any) + +*Impact*: Makes GrimRepo faster for everyone. + +=== Development Workflow + +==== Branch Naming + +Use descriptive branch names: + +.... +feat/add-wasm-compilation +fix/scoring-calculation-bug +docs/improve-readme +refactor/simplify-audit-logic +chore/update-dependencies +.... + +==== Commit Messages + +Follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +feat: add WASM compilation support +fix: correct LICENSE file detection +docs: add migration guide from npm init +refactor: simplify scoring algorithm +chore: update ReScript to v11.0 +.... + +*Types*: - `+feat+`: New feature - `+fix+`: Bug fix - `+docs+`: +Documentation only - `+style+`: Formatting (no logic change) - +`+refactor+`: Code restructuring - `+perf+`: Performance improvement - +`+test+`: Adding or updating tests - `+chore+`: Maintenance +(dependencies, build, etc.) + +==== Code Style + +*ReScript Conventions*: + +[arabic] +. *Module names*: PascalCase (`+Bootstrap+`, `+Community+`) +. *Function names*: camelCase (`+analyzeStructure+`, +`+checkRSRCompliance+`) +. *Type names*: camelCase (`+directoryCheck+`, `+auditResult+`) +. *Constants*: camelCase (`+standardDirectories+`) + +*Formatting*: + +[source,bash] +---- +just format # Auto-formats all ReScript code +---- + +*Best Practices*: - Prefer immutability - Use pattern matching over +if/else - Keep functions small and focused - Document public APIs with +comments - Write tests for all new logic + +==== Testing + +*Running Tests*: + +[source,bash] +---- +just build # Tests run during compilation +---- + +*Writing Tests*: + +Add tests to `+test/*_test.res+`: + +[source,rescript] +---- +// Test helper +let assertEqual = (actual, expected, testName) => { + if actual == expected { + Js.log(`✓ ${testName}`) + } else { + Js.log(`✗ ${testName}: expected ${expected}, got ${actual}`) + } +} + +// Test case +let runTests = () => { + Js.log("\n🧪 Running My Tests\n") + + let result = myFunction(input) + assertEqual(result, expectedOutput, "should return expected output") + + Js.log("\n✅ My tests complete\n") +} + +runTests() +---- + +*Test Coverage*: - Aim for 100% coverage of new code - Include edge +cases (empty inputs, boundary values) - Test error handling + +==== Code Review + +*As a Contributor*: 1. *Self-review*: Read your own code before +requesting review 2. *Test locally*: Ensure `+just verify-rsr+` passes +3. *Address feedback*: Respond to reviewer comments promptly 4. *Be +patient*: Maintainers are volunteers + +*As a Reviewer*: 1. *Be constructive*: Suggest improvements, don’t just +criticize 2. *Explain why*: Help contributors learn 3. *Approve +generously*: Perfect is the enemy of good 4. *Thank contributors*: +Appreciate their time + +=== Emotional Safety + +Per our link:../../LICENSE.txt[Palimpsest License], we prioritize +emotional safety: + +==== Right to Reversibility + +* *Experiments are OK*: If your PR doesn’t work out, no problem! +* *Abandon freely*: Close a PR without guilt if you lose interest +* *No permanent marks*: Failed attempts don’t count against you + +==== Anxiety Reduction + +* *Ask questions*: There are no "`stupid questions`" +* *Request help*: "`I’m stuck`" is a valid comment +* *Take breaks*: Contributing should be enjoyable, not stressful + +==== Constructive Critique + +* *Code reviews focus on code*, not the person +* *Disagreement is welcome*, personal attacks are not +* *We assume good faith* in all interactions + +=== Resources + +==== Learning ReScript + +* https://rescript-lang.org/docs/manual/latest/introduction[ReScript +Documentation] +* https://rescript-lang.org/try[ReScript by Example] +* https://rescript-lang.org/docs/manual/latest/pattern-matching-destructuring[Pattern +Matching Guide] + +==== GrimRepo Internals + +* link:../architecture.md[Architecture Documentation] +* link:../ROADMAP.md[ROADMAP] +* link:migration.md[Migration Guide] + +==== Communication + +* *Issues*: Ask questions, report bugs, propose features +* *Merge Requests*: Submit code changes +* *Discussions*: (coming soon) Long-form conversations + +=== Advanced Topics + +==== WASM Compilation + +(Future feature - documentation coming) + +GrimRepo is designed to compile to WebAssembly for performance: + +[source,bash] +---- +# (Not yet implemented) +just build-wasm +---- + +This will enable near-native performance in the browser. + +==== Nix Development + +For reproducible builds: + +[source,bash] +---- +# Enter Nix shell with all dependencies +nix develop + +# All tools are now available: +# - rescript +# - just +# - git +# - dune (for future WASM compilation) + +# Build normally +just build +---- + +=== Next Steps + +After your first contribution: + +[arabic] +. *Introduce yourself* in an issue (tell us about your background!) +. *Pick a second issue* (labeled `+good-first-issue+` or +`+help-wanted+`) +. *Help others* (review someone else’s MR) +. *Propose a feature* (share your ideas!) + +''''' + +*Thank you for contributing to GrimRepo!* Every contribution, no matter +how small, makes the project better. 🎉 diff --git a/docs/guides/contributor-onboarding.md b/docs/guides/contributor-onboarding.md deleted file mode 100644 index 1453e67..0000000 --- a/docs/guides/contributor-onboarding.md +++ /dev/null @@ -1,376 +0,0 @@ -# Contributor Onboarding Guide - -Welcome to GrimRepo! This guide will help you make your first contribution. - -## Quick Start (5 minutes) - -```bash -# 1. Fork the repository on GitLab -# (Click "Fork" button on the GitLab page) - -# 2. Clone your fork -git clone https://gitlab.com/YOUR-USERNAME/grimrepo-scripts.git -cd grimrepo-scripts - -# 3. Set up development environment -nix develop # If using Nix -# OR -# Install ReScript manually: npm install -g rescript - -# 4. Build the project -just build - -# 5. Make a change (e.g., fix a typo in README.md) - -# 6. Verify your change -just verify-rsr - -# 7. Commit and push -git checkout -b fix/readme-typo -git add README.md -git commit -m "docs: fix typo in installation instructions" -git push origin fix/readme-typo - -# 8. Open a Merge Request on GitLab -``` - -Congratulations! You've made your first contribution! 🎉 - -## Understanding the Codebase - -### Architecture Overview - -GrimRepo is built with **ReScript** (a type-safe functional language) that compiles to JavaScript: - -``` -src/ -├── GrimRepoTypes.res # Type definitions (ADTs, records) -├── Bootstrap.res # Directory structure auditing -├── Community.res # Community standards auditing -├── Audit.res # Overall repository scoring -├── GrimRepo.res # Public API -└── Utils.res # Helper functions - -test/ -├── Bootstrap_test.res # Tests for Bootstrap module -├── Community_test.res # Tests for Community module -├── Audit_test.res # Tests for Audit module -└── RunAllTests.res # Test runner - -lib/ -└── grimrepo.js # Minimal JavaScript glue code (userscript) -``` - -### Key Concepts - -**1. Algebraic Data Types (ADTs)** - -ReScript uses ADTs for type-safe enums: - -```rescript -type priority = Required | Recommended | Optional -type qualityLevel = Raw | Bronze | Silver | Gold | Rhodium -``` - -**2. Immutability** - -All data structures are immutable by default: - -```rescript -let structure = analyzeStructure(paths) -// `structure` cannot be modified after creation -``` - -**3. Pattern Matching** - -Exhaustive case handling: - -```rescript -switch level { -| Raw => "raw" -| Bronze => "bronze" -| Silver => "silver" -| Gold => "gold" -| Rhodium => "rhodium" -} -// Compiler ensures all cases are handled -``` - -## Common Contribution Types - -### 1. Documentation Improvements - -**Difficulty**: Beginner 🟢 - -**Examples**: -- Fix typos -- Add examples to README -- Clarify installation instructions -- Improve code comments - -**How to**: -1. Edit `.md` files in the repository root or `docs/` directory -2. Use `just verify-rsr` to ensure compliance is maintained -3. Open a merge request - -**Impact**: High! Good documentation helps everyone. - -### 2. Bug Fixes - -**Difficulty**: Intermediate 🟡 - -**Examples**: -- Fix scoring calculation errors -- Correct file detection logic -- Handle edge cases - -**How to**: -1. Reproduce the bug locally -2. Write a failing test in `test/*_test.res` -3. Fix the bug in `src/*.res` -4. Verify test passes: `just build` (tests run automatically) -5. Open a merge request with: - - Description of the bug - - Steps to reproduce - - Your fix - - New test coverage - -**Impact**: Critical for reliability. - -### 3. New Features - -**Difficulty**: Advanced 🔴 - -**Examples**: -- Add support for new file types -- Implement new auditing criteria -- Create new quality levels - -**How to**: -1. **Discuss first**: Open an issue describing the feature -2. **Get feedback**: Wait for maintainer input before coding -3. **Design**: Write a design document (see `docs/` for examples) -4. **Implement**: - - Add types to `GrimRepoTypes.res` - - Implement logic in appropriate module - - Add tests in `test/` - - Update documentation -5. **Review**: Open a merge request with comprehensive description - -**Impact**: Shapes the project's future. - -### 4. Performance Optimizations - -**Difficulty**: Advanced 🔴 - -**Examples**: -- Optimize scoring algorithms -- Reduce memory allocations -- Improve compilation speed - -**How to**: -1. **Benchmark first**: Measure current performance -2. **Identify bottleneck**: Profile the code -3. **Optimize**: Apply ReScript best practices (see Performance Guide) -4. **Benchmark again**: Prove improvement -5. **Open MR with**: - - Before/after benchmarks - - Explanation of optimization - - Trade-offs (if any) - -**Impact**: Makes GrimRepo faster for everyone. - -## Development Workflow - -### Branch Naming - -Use descriptive branch names: - -``` -feat/add-wasm-compilation -fix/scoring-calculation-bug -docs/improve-readme -refactor/simplify-audit-logic -chore/update-dependencies -``` - -### Commit Messages - -Follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -feat: add WASM compilation support -fix: correct LICENSE file detection -docs: add migration guide from npm init -refactor: simplify scoring algorithm -chore: update ReScript to v11.0 -``` - -**Types**: -- `feat`: New feature -- `fix`: Bug fix -- `docs`: Documentation only -- `style`: Formatting (no logic change) -- `refactor`: Code restructuring -- `perf`: Performance improvement -- `test`: Adding or updating tests -- `chore`: Maintenance (dependencies, build, etc.) - -### Code Style - -**ReScript Conventions**: - -1. **Module names**: PascalCase (`Bootstrap`, `Community`) -2. **Function names**: camelCase (`analyzeStructure`, `checkRSRCompliance`) -3. **Type names**: camelCase (`directoryCheck`, `auditResult`) -4. **Constants**: camelCase (`standardDirectories`) - -**Formatting**: -```bash -just format # Auto-formats all ReScript code -``` - -**Best Practices**: -- Prefer immutability -- Use pattern matching over if/else -- Keep functions small and focused -- Document public APIs with comments -- Write tests for all new logic - -### Testing - -**Running Tests**: -```bash -just build # Tests run during compilation -``` - -**Writing Tests**: - -Add tests to `test/*_test.res`: - -```rescript -// Test helper -let assertEqual = (actual, expected, testName) => { - if actual == expected { - Js.log(`✓ ${testName}`) - } else { - Js.log(`✗ ${testName}: expected ${expected}, got ${actual}`) - } -} - -// Test case -let runTests = () => { - Js.log("\n🧪 Running My Tests\n") - - let result = myFunction(input) - assertEqual(result, expectedOutput, "should return expected output") - - Js.log("\n✅ My tests complete\n") -} - -runTests() -``` - -**Test Coverage**: -- Aim for 100% coverage of new code -- Include edge cases (empty inputs, boundary values) -- Test error handling - -### Code Review - -**As a Contributor**: -1. **Self-review**: Read your own code before requesting review -2. **Test locally**: Ensure `just verify-rsr` passes -3. **Address feedback**: Respond to reviewer comments promptly -4. **Be patient**: Maintainers are volunteers - -**As a Reviewer**: -1. **Be constructive**: Suggest improvements, don't just criticize -2. **Explain why**: Help contributors learn -3. **Approve generously**: Perfect is the enemy of good -4. **Thank contributors**: Appreciate their time - -## Emotional Safety - -Per our [Palimpsest License](../../LICENSE.txt), we prioritize emotional safety: - -### Right to Reversibility -- **Experiments are OK**: If your PR doesn't work out, no problem! -- **Abandon freely**: Close a PR without guilt if you lose interest -- **No permanent marks**: Failed attempts don't count against you - -### Anxiety Reduction -- **Ask questions**: There are no "stupid questions" -- **Request help**: "I'm stuck" is a valid comment -- **Take breaks**: Contributing should be enjoyable, not stressful - -### Constructive Critique -- **Code reviews focus on code**, not the person -- **Disagreement is welcome**, personal attacks are not -- **We assume good faith** in all interactions - -## Resources - -### Learning ReScript - -- [ReScript Documentation](https://rescript-lang.org/docs/manual/latest/introduction) -- [ReScript by Example](https://rescript-lang.org/try) -- [Pattern Matching Guide](https://rescript-lang.org/docs/manual/latest/pattern-matching-destructuring) - -### GrimRepo Internals - -- [Architecture Documentation](../architecture.md) -- [ROADMAP](../ROADMAP.md) -- [Migration Guide](migration.md) - -### Communication - -- **Issues**: Ask questions, report bugs, propose features -- **Merge Requests**: Submit code changes -- **Discussions**: (coming soon) Long-form conversations - -## Advanced Topics - -### WASM Compilation - -(Future feature - documentation coming) - -GrimRepo is designed to compile to WebAssembly for performance: - -```bash -# (Not yet implemented) -just build-wasm -``` - -This will enable near-native performance in the browser. - -### Nix Development - -For reproducible builds: - -```bash -# Enter Nix shell with all dependencies -nix develop - -# All tools are now available: -# - rescript -# - just -# - git -# - dune (for future WASM compilation) - -# Build normally -just build -``` - -## Next Steps - -After your first contribution: - -1. **Introduce yourself** in an issue (tell us about your background!) -2. **Pick a second issue** (labeled `good-first-issue` or `help-wanted`) -3. **Help others** (review someone else's MR) -4. **Propose a feature** (share your ideas!) - ---- - -**Thank you for contributing to GrimRepo!** Every contribution, no matter how small, makes the project better. 🎉 diff --git a/docs/guides/migration.adoc b/docs/guides/migration.adoc new file mode 100644 index 0000000..6c0c7ee --- /dev/null +++ b/docs/guides/migration.adoc @@ -0,0 +1,351 @@ +== Migration Guide + +Migrating to GrimRepo from other repository scaffolding and auditing +tools. + +=== From npm/yarn init + +If you’re currently using `+npm init+` or `+yarn init+`: + +==== What GrimRepo Adds + +[cols=",,",options="header",] +|=== +|Feature |npm/yarn init |GrimRepo +|Package files |✅ package.json |✅ All community standards +|License |⚠️ Single choice |✅ Dual MIT + Palimpsest +|README |⚠️ Basic template |✅ Comprehensive guide +|Security |❌ None |✅ SECURITY.md, .well-known/security.txt +|Conduct |❌ None |✅ CODE_OF_CONDUCT.md +|Contribution |❌ None |✅ CONTRIBUTING.md with TPCF +|Maintainer |❌ None |✅ MAINTAINERS.md with governance +|Changelog |❌ None |✅ CHANGELOG.md (semver) +|AI Policy |❌ None |✅ .well-known/ai.txt +|Attribution |❌ None |✅ .well-known/humans.txt +|=== + +==== Migration Steps + +[source,bash] +---- +# 1. Add GrimRepo to your existing project +cd your-project + +# 2. Run GrimRepo audit +# (Once userscript is published) + +# 3. Review missing files +# GrimRepo will identify gaps + +# 4. Generate missing files +# Use GrimRepo's scaffolding tools + +# 5. Validate RSR compliance +just verify-rsr +---- + +=== From cookiecutter/yeoman + +If you’re using template generators like cookiecutter or yeoman: + +==== Advantages of GrimRepo + +[arabic] +. *No upfront templates* - GrimRepo audits your existing structure +. *Incremental adoption* - Add files as needed, not all at once +. *Cross-platform* - Works on GitLab, GitHub, Bitbucket +. *Offline-first* - No network calls, faster execution +. *Type-safe* - ReScript ensures correctness + +==== Migration Steps + +[source,bash] +---- +# 1. Keep your existing structure +# (GrimRepo doesn't force rewrites) + +# 2. Run GrimRepo audit to see what's missing +just build +node -e "const { selfCheck } = require('./lib/index.js'); selfCheck();" + +# 3. Add recommended files incrementally +# Start with: +# - LICENSE.txt (dual MIT + Palimpsest) +# - SECURITY.md +# - CONTRIBUTING.md + +# 4. Achieve Bronze level RSR +# Then progress to Silver, Gold, Rhodium +---- + +=== From GitHub’s "`community health files`" + +GitHub provides default community health files, but GrimRepo goes +further: + +==== What GrimRepo Adds + +[width="100%",cols="26%,47%,27%",options="header",] +|=== +|Feature |GitHub Defaults |GrimRepo +|LICENSE |✅ Templates |✅ Dual licensing (MIT + Palimpsest) + +|CODE_OF_CONDUCT |✅ Contributor Covenant |✅ Palimpsest-aligned +(emotional safety) + +|CONTRIBUTING |✅ Basic |✅ TPCF governance model + +|SECURITY |✅ Basic |✅ Comprehensive policies + .well-known/ + +|MAINTAINERS |❌ None |✅ Governance structure + +|CHANGELOG |❌ None |✅ Semantic versioning + +|.well-known/ |❌ None |✅ RFC 9116 security.txt, ai.txt, humans.txt + +|Auditing |❌ None |✅ Automated RSR scoring +|=== + +==== Migration Steps + +[source,bash] +---- +# 1. GrimRepo works alongside GitHub defaults +# Keep your .github/ISSUE_TEMPLATE/, etc. + +# 2. Add GrimRepo-specific files: +# - LICENSE.txt (replace LICENSE if needed) +# - MAINTAINERS.md +# - CHANGELOG.md +# - .well-known/security.txt +# - .well-known/ai.txt +# - .well-known/humans.txt + +# 3. Enhance existing files: +# - CODE_OF_CONDUCT.md → Add Palimpsest provisions +# - CONTRIBUTING.md → Add TPCF model +# - SECURITY.md → Add .well-known/ cross-reference + +# 4. Validate +just verify-rsr +---- + +=== From repolinter/repo-linter + +If you’re using repolinter or similar linting tools: + +==== Key Differences + +[width="100%",cols="27%,40%,33%",options="header",] +|=== +|Aspect |repolinter |GrimRepo +|Approach |Linter (enforces rules) |Auditor (suggests improvements) +|Philosophy |Pass/fail |Progressive levels (Raw → Rhodium) +|Emotional Safety |❌ None |✅ Palimpsest License provisions +|Offline-first |⚠️ Some network calls |✅ Zero network dependencies +|Type Safety |⚠️ JavaScript |✅ ReScript (sound types) +|Performance |⚠️ Good |✅ WASM-ready (near-native) +|=== + +==== Migration Steps + +[source,bash] +---- +# 1. Run both tools side-by-side initially +# Keep repolinter for CI/CD enforcement +# Use GrimRepo for audit insights + +# 2. Compare recommendations +# repolinter is stricter (pass/fail) +# GrimRepo is gentler (progressive levels) + +# 3. Gradually replace repolinter rules with GrimRepo +# Start with Bronze level requirements +# Enforce Silver/Gold for mature projects + +# 4. Automate with GitLab CI/CD +# GrimRepo's .gitlab-ci.yml validates RSR compliance +---- + +=== From ossf/scorecard + +OpenSSF Scorecard focuses on security, GrimRepo adds emotional safety +and narratability: + +==== Complementary Strengths + +Use both! GrimRepo complements OpenSSF Scorecard: + +[width="100%",cols="22%,51%,27%",options="header",] +|=== +|Aspect |OpenSSF Scorecard |GrimRepo +|Security |✅ Comprehensive |✅ .well-known/security.txt, SECURITY.md +|Code Review |✅ Enforced |⚠️ Recommended (TPCF) +|Dependencies |✅ Up-to-date checks |⚠️ Manual audit +|Emotional Safety |❌ None |✅ Palimpsest License, CoC +|Narratability |❌ None |✅ Core principle +|Community |⚠️ Basic |✅ TPCF governance +|=== + +==== Migration Steps + +[source,bash] +---- +# 1. Keep OpenSSF Scorecard for security metrics +# 2. Add GrimRepo for community health +# 3. Aim for high scores on both: +# - OpenSSF: 8+ score +# - GrimRepo: Gold/Rhodium level + +# 4. Cross-reference in documentation +# README.md: +# [![OpenSSF Scorecard](...)](#) +# [![RSR Compliant](...)](#) +---- + +=== From manual setup + +If you’ve been manually creating files: + +==== GrimRepo Advantages + +[arabic] +. *Consistency* - Standardized templates across projects +. *Completeness* - Never forget a file +. *Progressive* - Achieve Bronze, then level up +. *Validation* - `+just verify-rsr+` ensures compliance + +==== Migration Steps + +[source,bash] +---- +# 1. Inventory existing files +ls -la *.md .well-known/ + +# 2. Run GrimRepo audit +just build +# Check what's missing + +# 3. Add missing files using GrimRepo templates +# (Once scaffolding tools are built) + +# 4. Standardize across repositories +# Use GrimRepo for all projects +---- + +=== Best Practices + +==== Incremental Adoption + +Don’t try to go from Raw to Rhodium overnight: + +[arabic] +. *Week 1: Bronze* - Add required files (LICENSE, README, SECURITY, +CONTRIBUTING, CODE_OF_CONDUCT) +. *Week 2: Silver* - Add .well-known directory, MAINTAINERS, CHANGELOG +. *Month 2: Gold* - Enhance documentation, add examples, improve tests +. *Month 6: Rhodium* - Polish everything, submit to Rhodium Register + +==== Prioritization + +Focus on high-impact files first: + +*Priority 1 (Legal & Safety)*: - LICENSE.txt - SECURITY.md - +CODE_OF_CONDUCT.md + +*Priority 2 (Contribution)*: - CONTRIBUTING.md - README.md + +*Priority 3 (Maintenance)*: - MAINTAINERS.md - CHANGELOG.md + +*Priority 4 (Metadata)*: - .well-known/security.txt - .well-known/ai.txt +- .well-known/humans.txt + +==== Automation + +Integrate GrimRepo into your workflow: + +*Git Hooks*: + +[source,bash] +---- +# .git/hooks/pre-commit +#!/bin/bash +just verify-rsr || echo "Warning: RSR compliance degraded" +---- + +*CI/CD*: + +[source,yaml] +---- +# .gitlab-ci.yml +rsr-compliance: + script: + - just verify-rsr + allow_failure: false # Enforce Bronze minimum +---- + +*Pre-release Checklist*: + +[source,bash] +---- +# Before tagging a release: +1. Update CHANGELOG.md +2. Run: just verify-rsr +3. Ensure Bronze+ level +4. Tag release +---- + +=== Common Pitfalls + +==== 1. Boilerplate Fatigue + +*Problem*: Copying templates without customization + +*Solution*: GrimRepo’s templates are starting points. Customize: - +README.md: Describe YOUR project - CONTRIBUTING.md: Reflect YOUR +workflow - CODE_OF_CONDUCT.md: Adapt to YOUR community + +==== 2. License Confusion + +*Problem*: Mixing incompatible licenses + +*Solution*: GrimRepo’s dual MIT + Palimpsest is designed for +compatibility: - MIT: Permissive open source - Palimpsest: Adds +emotional safety (non-exclusive) + +Both licenses apply simultaneously (not "`either-or`"). + +==== 3. Ignoring .well-known/ + +*Problem*: Treating .well-known/ as optional + +*Solution*: `+.well-known/+` is RFC-compliant metadata: - security.txt: +Industry standard (RFC 9116) - ai.txt: Emerging standard for AI training +policies - humans.txt: Attribution (https://humanstxt.org) + +These files make your repository machine-readable and discoverable. + +==== 4. Perfectionism Paralysis + +*Problem*: Waiting for "`perfect`" documentation before publishing + +*Solution*: GrimRepo’s progressive levels allow: - Bronze: Good enough +to ship - Silver/Gold/Rhodium: Iterative improvements + +Ship Bronze, improve over time. + +=== Next Steps + +After migrating to GrimRepo: + +[arabic] +. *Share Your Journey* - Blog about achieving RSR compliance +. *Contribute Templates* - Help others with organization-specific +examples +. *Submit to Rhodium Register* - Showcase exemplary repositories +. *Mentor Others* - Guide projects from Raw to Bronze+ + +''''' + +*Questions?* Open an issue: +https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues diff --git a/docs/guides/migration.md b/docs/guides/migration.md deleted file mode 100644 index 704d306..0000000 --- a/docs/guides/migration.md +++ /dev/null @@ -1,324 +0,0 @@ -# Migration Guide - -Migrating to GrimRepo from other repository scaffolding and auditing tools. - -## From npm/yarn init - -If you're currently using `npm init` or `yarn init`: - -### What GrimRepo Adds - -| Feature | npm/yarn init | GrimRepo | -|---------|---------------|----------| -| Package files | ✅ package.json | ✅ All community standards | -| License | ⚠️ Single choice | ✅ Dual MIT + Palimpsest | -| README | ⚠️ Basic template | ✅ Comprehensive guide | -| Security | ❌ None | ✅ SECURITY.md, .well-known/security.txt | -| Conduct | ❌ None | ✅ CODE_OF_CONDUCT.md | -| Contribution | ❌ None | ✅ CONTRIBUTING.md with TPCF | -| Maintainer | ❌ None | ✅ MAINTAINERS.md with governance | -| Changelog | ❌ None | ✅ CHANGELOG.md (semver) | -| AI Policy | ❌ None | ✅ .well-known/ai.txt | -| Attribution | ❌ None | ✅ .well-known/humans.txt | - -### Migration Steps - -```bash -# 1. Add GrimRepo to your existing project -cd your-project - -# 2. Run GrimRepo audit -# (Once userscript is published) - -# 3. Review missing files -# GrimRepo will identify gaps - -# 4. Generate missing files -# Use GrimRepo's scaffolding tools - -# 5. Validate RSR compliance -just verify-rsr -``` - -## From cookiecutter/yeoman - -If you're using template generators like cookiecutter or yeoman: - -### Advantages of GrimRepo - -1. **No upfront templates** - GrimRepo audits your existing structure -2. **Incremental adoption** - Add files as needed, not all at once -3. **Cross-platform** - Works on GitLab, GitHub, Bitbucket -4. **Offline-first** - No network calls, faster execution -5. **Type-safe** - ReScript ensures correctness - -### Migration Steps - -```bash -# 1. Keep your existing structure -# (GrimRepo doesn't force rewrites) - -# 2. Run GrimRepo audit to see what's missing -just build -node -e "const { selfCheck } = require('./lib/index.js'); selfCheck();" - -# 3. Add recommended files incrementally -# Start with: -# - LICENSE.txt (dual MIT + Palimpsest) -# - SECURITY.md -# - CONTRIBUTING.md - -# 4. Achieve Bronze level RSR -# Then progress to Silver, Gold, Rhodium -``` - -## From GitHub's "community health files" - -GitHub provides default community health files, but GrimRepo goes further: - -### What GrimRepo Adds - -| Feature | GitHub Defaults | GrimRepo | -|---------|-----------------|----------| -| LICENSE | ✅ Templates | ✅ Dual licensing (MIT + Palimpsest) | -| CODE_OF_CONDUCT | ✅ Contributor Covenant | ✅ Palimpsest-aligned (emotional safety) | -| CONTRIBUTING | ✅ Basic | ✅ TPCF governance model | -| SECURITY | ✅ Basic | ✅ Comprehensive policies + .well-known/ | -| MAINTAINERS | ❌ None | ✅ Governance structure | -| CHANGELOG | ❌ None | ✅ Semantic versioning | -| .well-known/ | ❌ None | ✅ RFC 9116 security.txt, ai.txt, humans.txt | -| Auditing | ❌ None | ✅ Automated RSR scoring | - -### Migration Steps - -```bash -# 1. GrimRepo works alongside GitHub defaults -# Keep your .github/ISSUE_TEMPLATE/, etc. - -# 2. Add GrimRepo-specific files: -# - LICENSE.txt (replace LICENSE if needed) -# - MAINTAINERS.md -# - CHANGELOG.md -# - .well-known/security.txt -# - .well-known/ai.txt -# - .well-known/humans.txt - -# 3. Enhance existing files: -# - CODE_OF_CONDUCT.md → Add Palimpsest provisions -# - CONTRIBUTING.md → Add TPCF model -# - SECURITY.md → Add .well-known/ cross-reference - -# 4. Validate -just verify-rsr -``` - -## From repolinter/repo-linter - -If you're using repolinter or similar linting tools: - -### Key Differences - -| Aspect | repolinter | GrimRepo | -|--------|------------|----------| -| Approach | Linter (enforces rules) | Auditor (suggests improvements) | -| Philosophy | Pass/fail | Progressive levels (Raw → Rhodium) | -| Emotional Safety | ❌ None | ✅ Palimpsest License provisions | -| Offline-first | ⚠️ Some network calls | ✅ Zero network dependencies | -| Type Safety | ⚠️ JavaScript | ✅ ReScript (sound types) | -| Performance | ⚠️ Good | ✅ WASM-ready (near-native) | - -### Migration Steps - -```bash -# 1. Run both tools side-by-side initially -# Keep repolinter for CI/CD enforcement -# Use GrimRepo for audit insights - -# 2. Compare recommendations -# repolinter is stricter (pass/fail) -# GrimRepo is gentler (progressive levels) - -# 3. Gradually replace repolinter rules with GrimRepo -# Start with Bronze level requirements -# Enforce Silver/Gold for mature projects - -# 4. Automate with GitLab CI/CD -# GrimRepo's .gitlab-ci.yml validates RSR compliance -``` - -## From ossf/scorecard - -OpenSSF Scorecard focuses on security, GrimRepo adds emotional safety and narratability: - -### Complementary Strengths - -Use both! GrimRepo complements OpenSSF Scorecard: - -| Aspect | OpenSSF Scorecard | GrimRepo | -|--------|-------------------|----------| -| Security | ✅ Comprehensive | ✅ .well-known/security.txt, SECURITY.md | -| Code Review | ✅ Enforced | ⚠️ Recommended (TPCF) | -| Dependencies | ✅ Up-to-date checks | ⚠️ Manual audit | -| Emotional Safety | ❌ None | ✅ Palimpsest License, CoC | -| Narratability | ❌ None | ✅ Core principle | -| Community | ⚠️ Basic | ✅ TPCF governance | - -### Migration Steps - -```bash -# 1. Keep OpenSSF Scorecard for security metrics -# 2. Add GrimRepo for community health -# 3. Aim for high scores on both: -# - OpenSSF: 8+ score -# - GrimRepo: Gold/Rhodium level - -# 4. Cross-reference in documentation -# README.md: -# [![OpenSSF Scorecard](...)](#) -# [![RSR Compliant](...)](#) -``` - -## From manual setup - -If you've been manually creating files: - -### GrimRepo Advantages - -1. **Consistency** - Standardized templates across projects -2. **Completeness** - Never forget a file -3. **Progressive** - Achieve Bronze, then level up -4. **Validation** - `just verify-rsr` ensures compliance - -### Migration Steps - -```bash -# 1. Inventory existing files -ls -la *.md .well-known/ - -# 2. Run GrimRepo audit -just build -# Check what's missing - -# 3. Add missing files using GrimRepo templates -# (Once scaffolding tools are built) - -# 4. Standardize across repositories -# Use GrimRepo for all projects -``` - -## Best Practices - -### Incremental Adoption - -Don't try to go from Raw to Rhodium overnight: - -1. **Week 1: Bronze** - Add required files (LICENSE, README, SECURITY, CONTRIBUTING, CODE_OF_CONDUCT) -2. **Week 2: Silver** - Add .well-known directory, MAINTAINERS, CHANGELOG -3. **Month 2: Gold** - Enhance documentation, add examples, improve tests -4. **Month 6: Rhodium** - Polish everything, submit to Rhodium Register - -### Prioritization - -Focus on high-impact files first: - -**Priority 1 (Legal & Safety)**: -- LICENSE.txt -- SECURITY.md -- CODE_OF_CONDUCT.md - -**Priority 2 (Contribution)**: -- CONTRIBUTING.md -- README.md - -**Priority 3 (Maintenance)**: -- MAINTAINERS.md -- CHANGELOG.md - -**Priority 4 (Metadata)**: -- .well-known/security.txt -- .well-known/ai.txt -- .well-known/humans.txt - -### Automation - -Integrate GrimRepo into your workflow: - -**Git Hooks**: -```bash -# .git/hooks/pre-commit -#!/bin/bash -just verify-rsr || echo "Warning: RSR compliance degraded" -``` - -**CI/CD**: -```yaml -# .gitlab-ci.yml -rsr-compliance: - script: - - just verify-rsr - allow_failure: false # Enforce Bronze minimum -``` - -**Pre-release Checklist**: -```bash -# Before tagging a release: -1. Update CHANGELOG.md -2. Run: just verify-rsr -3. Ensure Bronze+ level -4. Tag release -``` - -## Common Pitfalls - -### 1. Boilerplate Fatigue - -**Problem**: Copying templates without customization - -**Solution**: GrimRepo's templates are starting points. Customize: -- README.md: Describe YOUR project -- CONTRIBUTING.md: Reflect YOUR workflow -- CODE_OF_CONDUCT.md: Adapt to YOUR community - -### 2. License Confusion - -**Problem**: Mixing incompatible licenses - -**Solution**: GrimRepo's dual MIT + Palimpsest is designed for compatibility: -- MIT: Permissive open source -- Palimpsest: Adds emotional safety (non-exclusive) - -Both licenses apply simultaneously (not "either-or"). - -### 3. Ignoring .well-known/ - -**Problem**: Treating .well-known/ as optional - -**Solution**: `.well-known/` is RFC-compliant metadata: -- security.txt: Industry standard (RFC 9116) -- ai.txt: Emerging standard for AI training policies -- humans.txt: Attribution (https://humanstxt.org) - -These files make your repository machine-readable and discoverable. - -### 4. Perfectionism Paralysis - -**Problem**: Waiting for "perfect" documentation before publishing - -**Solution**: GrimRepo's progressive levels allow: -- Bronze: Good enough to ship -- Silver/Gold/Rhodium: Iterative improvements - -Ship Bronze, improve over time. - -## Next Steps - -After migrating to GrimRepo: - -1. **Share Your Journey** - Blog about achieving RSR compliance -2. **Contribute Templates** - Help others with organization-specific examples -3. **Submit to Rhodium Register** - Showcase exemplary repositories -4. **Mentor Others** - Guide projects from Raw to Bronze+ - ---- - -**Questions?** Open an issue: https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues diff --git a/docs/guides/performance.md b/docs/guides/performance.adoc similarity index 52% rename from docs/guides/performance.md rename to docs/guides/performance.adoc index a339b79..461209d 100644 --- a/docs/guides/performance.md +++ b/docs/guides/performance.adoc @@ -1,43 +1,49 @@ -# Performance Guide +== Performance Guide Optimizing GrimRepo for speed and efficiency. -## Benchmarks +=== Benchmarks -### ReScript vs TypeScript +==== ReScript vs TypeScript -GrimRepo's migration from TypeScript to ReScript provides significant performance benefits: +GrimRepo’s migration from TypeScript to ReScript provides significant +performance benefits: -| Metric | TypeScript (v0.9) | ReScript (v1.0) | Improvement | -|--------|-------------------|-----------------|-------------| -| Compilation Time | 2.3s | 0.8s | **65% faster** | -| Bundle Size | 45 KB | 28 KB | **38% smaller** | -| Runtime (audit) | 12ms | 7ms | **42% faster** | -| Memory Usage | 8.2 MB | 5.1 MB | **38% less** | -| Cold Start | 45ms | 22ms | **51% faster** | +[cols=",,,",options="header",] +|=== +|Metric |TypeScript (v0.9) |ReScript (v1.0) |Improvement +|Compilation Time |2.3s |0.8s |*65% faster* +|Bundle Size |45 KB |28 KB |*38% smaller* +|Runtime (audit) |12ms |7ms |*42% faster* +|Memory Usage |8.2 MB |5.1 MB |*38% less* +|Cold Start |45ms |22ms |*51% faster* +|=== -*Benchmarks run on: Node.js 20, Ubuntu 22.04, Intel i7-10700K* +_Benchmarks run on: Node.js 20, Ubuntu 22.04, Intel i7-10700K_ -### Audit Performance +==== Audit Performance Time to audit repositories of varying sizes: -| Repository Size | Files | Directories | Audit Time | -|-----------------|-------|-------------|------------| -| Small (Demo) | 10 | 5 | **3ms** | -| Medium (Library) | 50 | 15 | **8ms** | -| Large (Framework) | 200 | 40 | **18ms** | -| Huge (Monorepo) | 1000 | 150 | **67ms** | +[cols=",,,",options="header",] +|=== +|Repository Size |Files |Directories |Audit Time +|Small (Demo) |10 |5 |*3ms* +|Medium (Library) |50 |15 |*8ms* +|Large (Framework) |200 |40 |*18ms* +|Huge (Monorepo) |1000 |150 |*67ms* +|=== -**Goal**: <100ms for any repository (✅ Achieved) +*Goal*: <100ms for any repository (✅ Achieved) -## Optimization Techniques +=== Optimization Techniques -### 1. Immutability Benefits +==== 1. Immutability Benefits -ReScript's immutable-by-default design enables compiler optimizations: +ReScript’s immutable-by-default design enables compiler optimizations: -```rescript +[source,rescript] +---- // Immutable data structures allow structural sharing let paths1 = ["src/", "tests/"] let paths2 = Belt.Array.concat(paths1, ["docs/"]) @@ -48,15 +54,16 @@ let analyzeStructure = (paths) => { // No side effects → compiler can inline, memoize, parallelize ... } -``` +---- -**Benefit**: 20-30% faster execution vs mutable approaches +*Benefit*: 20-30% faster execution vs mutable approaches -### 2. Pattern Matching Compilation +==== 2. Pattern Matching Compilation ReScript compiles pattern matching to efficient jump tables: -```rescript +[source,rescript] +---- // This code: let levelToString = (level) => switch level { @@ -70,15 +77,16 @@ let levelToString = (level) => // Compiles to something like: // const levelToString = (level) => LOOKUP_TABLE[level] // (O(1) lookup instead of O(n) if/else chain) -``` +---- -**Benefit**: Constant-time case handling +*Benefit*: Constant-time case handling -### 3. Belt.Array Optimizations +==== 3. Belt.Array Optimizations Belt.Array functions are heavily optimized: -```rescript +[source,rescript] +---- // Efficient reduction (single pass) let sum = Belt.Array.reduce(numbers, 0, (acc, x) => acc + x) @@ -88,29 +96,31 @@ let result = paths ->Belt.Array.keep(isValid) ->Belt.Array.length // Compiler fuses into single loop -``` +---- -**Benefit**: 40-50% faster than naive JavaScript loops +*Benefit*: 40-50% faster than naive JavaScript loops -### 4. Dead Code Elimination +==== 4. Dead Code Elimination -ReScript's tree-shaking removes unused code: +ReScript’s tree-shaking removes unused code: -```rescript +[source,rescript] +---- // If you only import `analyzeStructure`: import { analyzeStructure } from './GrimRepo.res' // Only that function's code is included in the bundle // (not the entire module) -``` +---- -**Benefit**: 38% smaller bundle size +*Benefit*: 38% smaller bundle size -## Profiling +=== Profiling -### Benchmarking Audit Performance +==== Benchmarking Audit Performance -```rescript +[source,rescript] +---- // Add to src/GrimRepo.res for benchmarking @genType let benchmarkAudit = (paths: array, files: array): float => { @@ -119,10 +129,12 @@ let benchmarkAudit = (paths: array, files: array): float => { let end = Js.Date.now() end -. start // Returns milliseconds } -``` +---- Usage: -```javascript + +[source,javascript] +---- const { benchmarkAudit } = require('./lib/GrimRepo.bs.js') const paths = ['src/', 'tests/', 'docs/'] @@ -130,27 +142,31 @@ const files = ['README.md', 'LICENSE.txt'] const ms = benchmarkAudit(paths, files) console.log(`Audit took ${ms}ms`) -``` +---- + +==== Profiling with Chrome DevTools -### Profiling with Chrome DevTools +[arabic] +. *Run in browser*: -1. **Run in browser**: -```html +[source,html] +---- -``` - -2. **Open DevTools** → Performance tab → View flame graph +---- -3. **Identify bottlenecks** (functions taking >10% of time) +[arabic, start=2] +. *Open DevTools* → Performance tab → View flame graph +. *Identify bottlenecks* (functions taking >10% of time) -### Memory Profiling +==== Memory Profiling -```javascript +[source,javascript] +---- // Before audit const before = process.memoryUsage().heapUsed @@ -161,55 +177,56 @@ const result = GrimRepo.runAudit(paths, files) const after = process.memoryUsage().heapUsed const used = (after - before) / 1024 / 1024 // MB console.log(`Memory used: ${used.toFixed(2)} MB`) -``` +---- -## WASM Compilation (Future) +=== WASM Compilation (Future) -### Expected Performance Gains +==== Expected Performance Gains When GrimRepo compiles to WebAssembly: -| Metric | JavaScript | WASM (projected) | Improvement | -|--------|------------|------------------|-------------| -| Audit Time | 7ms | **2ms** | **71% faster** | -| Memory | 5.1 MB | **3.2 MB** | **37% less** | -| Bundle Size | 28 KB | **18 KB** | **36% smaller** | -| Startup | 22ms | **8ms** | **64% faster** | +[cols=",,,",options="header",] +|=== +|Metric |JavaScript |WASM (projected) |Improvement +|Audit Time |7ms |*2ms* |*71% faster* +|Memory |5.1 MB |*3.2 MB* |*37% less* +|Bundle Size |28 KB |*18 KB* |*36% smaller* +|Startup |22ms |*8ms* |*64% faster* +|=== -### WASM Compilation Path +==== WASM Compilation Path -```bash +[source,bash] +---- # (Future feature - not yet implemented) just build-wasm # Generates: # lib/grimrepo.wasm (WebAssembly binary) # lib/grimrepo_wasm.js (JavaScript loader) -``` +---- -**Benefits**: -- Near-native performance (C/Rust speed) -- Smaller bundle (binary format) -- Faster parsing (pre-compiled) -- Consistent performance across browsers +*Benefits*: - Near-native performance (C/Rust speed) - Smaller bundle +(binary format) - Faster parsing (pre-compiled) - Consistent performance +across browsers -### WASM Limitations +==== WASM Limitations -- **Cannot access DOM directly** (JS glue code required) -- **Slightly larger initial download** (WASM runtime overhead) -- **Browser support** (IE11 doesn't support WASM) +* *Cannot access DOM directly* (JS glue code required) +* *Slightly larger initial download* (WASM runtime overhead) +* *Browser support* (IE11 doesn’t support WASM) -**Solution**: Hybrid approach -- Core logic in WASM (auditing, scoring) -- UI/DOM in JavaScript (userscript wrapper) +*Solution*: Hybrid approach - Core logic in WASM (auditing, scoring) - +UI/DOM in JavaScript (userscript wrapper) -## Best Practices +=== Best Practices -### For Contributors +==== For Contributors -**1. Avoid Unnecessary Allocations** +*1. Avoid Unnecessary Allocations* -```rescript +[source,rescript] +---- // Bad: Creates intermediate array let result = paths ->Belt.Array.map(normalize) @@ -217,11 +234,12 @@ let result = paths // Good: Single pass with composition let result = paths->Belt.Array.map(path => validate(normalize(path))) -``` +---- -**2. Use Tail Recursion** +*2. Use Tail Recursion* -```rescript +[source,rescript] +---- // Bad: Stack overflow for large inputs let rec sum = (arr) => switch arr { @@ -238,21 +256,23 @@ let sum = (arr) => { } go(arr, 0) } -``` +---- -**3. Prefer Belt.Array over Js.Array** +*3. Prefer Belt.Array over Js.Array* -```rescript +[source,rescript] +---- // Slower: Js.Array (minimal optimizations) let doubled = Js.Array2.map(numbers, x => x * 2) // Faster: Belt.Array (heavily optimized) let doubled = Belt.Array.map(numbers, x => x * 2) -``` +---- -**4. Avoid String Concatenation in Loops** +*4. Avoid String Concatenation in Loops* -```rescript +[source,rescript] +---- // Bad: O(n²) due to string immutability let rec buildString = (items) => switch items { @@ -263,13 +283,14 @@ let rec buildString = (items) => // Good: O(n) using array join let buildString = (items) => items->Js.Array2.joinWith("\n") -``` +---- -### For Users +==== For Users -**1. Cache Audit Results** +*1. Cache Audit Results* -```javascript +[source,javascript] +---- // Don't audit the same repo repeatedly const cache = new Map() @@ -282,11 +303,12 @@ function auditWithCache(paths, files) { cache.set(key, result) return result } -``` +---- -**2. Lazy Load on User Action** +*2. Lazy Load on User Action* -```javascript +[source,javascript] +---- // Don't audit immediately on page load window.addEventListener('load', () => { // Wait for user to click "Run Audit" button @@ -295,11 +317,12 @@ window.addEventListener('load', () => { displayResults(result) }) }) -``` +---- -**3. Throttle Audits** +*3. Throttle Audits* -```javascript +[source,javascript] +---- // Debounce audits when user is typing/editing let timeout function auditWithDebounce(paths, files) { @@ -309,15 +332,16 @@ function auditWithDebounce(paths, files) { updateUI(result) }, 500) // Wait 500ms after user stops typing } -``` +---- -## Performance Monitoring +=== Performance Monitoring -### Production Metrics +==== Production Metrics Track performance in production: -```javascript +[source,javascript] +---- // Send metrics to analytics function trackAuditPerformance(duration, score) { // Example: Google Analytics @@ -333,58 +357,67 @@ function trackAuditPerformance(duration, score) { body: JSON.stringify({ duration, score }) }) } -``` +---- -### Alerting on Regressions +==== Alerting on Regressions Set up alerts if performance degrades: -```javascript +[source,javascript] +---- const THRESHOLD_MS = 100 // Alert if audit takes >100ms if (duration > THRESHOLD_MS) { console.warn(`Slow audit: ${duration}ms (threshold: ${THRESHOLD_MS}ms)`) // Send alert to monitoring system } -``` +---- -## Comparison with Other Tools +=== Comparison with Other Tools -### GrimRepo vs repolinter +==== GrimRepo vs repolinter -| Tool | Language | Audit Time | Memory | Bundle Size | -|------|----------|------------|--------|-------------| -| **GrimRepo** | ReScript | **7ms** | **5.1 MB** | **28 KB** | -| repolinter | JavaScript | 45ms | 18 MB | 120 KB | +[cols=",,,,",options="header",] +|=== +|Tool |Language |Audit Time |Memory |Bundle Size +|*GrimRepo* |ReScript |*7ms* |*5.1 MB* |*28 KB* +|repolinter |JavaScript |45ms |18 MB |120 KB +|=== -**Winner**: GrimRepo is **6.4x faster**, uses **72% less memory**, and is **77% smaller**. +*Winner*: GrimRepo is *6.4x faster*, uses *72% less memory*, and is *77% +smaller*. -### GrimRepo vs ossf/scorecard +==== GrimRepo vs ossf/scorecard -| Tool | Language | Audit Time | Network Calls | -|------|----------|------------|---------------| -| **GrimRepo** | ReScript | **7ms** | **0** (offline) | -| ossf/scorecard | Go | 2,300ms | 15+ (API calls) | +[cols=",,,",options="header",] +|=== +|Tool |Language |Audit Time |Network Calls +|*GrimRepo* |ReScript |*7ms* |*0* (offline) +|ossf/scorecard |Go |2,300ms |15+ (API calls) +|=== -**Note**: Different use cases (GrimRepo: structure, ossf: security), but GrimRepo is **330x faster** for basic auditing. +*Note*: Different use cases (GrimRepo: structure, ossf: security), but +GrimRepo is *330x faster* for basic auditing. -## Future Optimizations +=== Future Optimizations -### Planned Improvements +==== Planned Improvements -1. **WASM Compilation** (Q2 2025) - 71% faster audits -2. **Parallel Auditing** (Q3 2025) - Multi-threaded for large repos -3. **Incremental Audits** (Q4 2025) - Only re-audit changed files -4. **Caching Layer** (Q4 2025) - Persist results across sessions +[arabic] +. *WASM Compilation* (Q2 2025) - 71% faster audits +. *Parallel Auditing* (Q3 2025) - Multi-threaded for large repos +. *Incremental Audits* (Q4 2025) - Only re-audit changed files +. *Caching Layer* (Q4 2025) - Persist results across sessions -### Research Areas +==== Research Areas -- **SIMD Instructions** - Vectorized string operations -- **Just-In-Time Compilation** - Runtime optimization -- **Graph-Based Auditing** - Dependency-aware scoring +* *SIMD Instructions* - Vectorized string operations +* *Just-In-Time Compilation* - Runtime optimization +* *Graph-Based Auditing* - Dependency-aware scoring ---- +''''' -**Takeaway**: GrimRepo is already fast (7ms audits), but we're continually optimizing for even better performance. Contributions welcome! +*Takeaway*: GrimRepo is already fast (7ms audits), but we’re continually +optimizing for even better performance. Contributions welcome! -**Last Updated**: 2025-01-22 +*Last Updated*: 2025-01-22 diff --git a/docs/guides/quick-reference.md b/docs/guides/quick-reference.adoc similarity index 54% rename from docs/guides/quick-reference.md rename to docs/guides/quick-reference.adoc index 5991d9c..068afe8 100644 --- a/docs/guides/quick-reference.md +++ b/docs/guides/quick-reference.adoc @@ -1,12 +1,13 @@ -# Quick Reference Guide +== Quick Reference Guide Essential commands and concepts for daily use of GrimRepo. -## Commands Cheat Sheet +=== Commands Cheat Sheet -### Build & Development +==== Build & Development -```bash +[source,bash] +---- # Build ReScript to JavaScript just build @@ -21,11 +22,12 @@ just clean # Show all available commands just --list -``` +---- -### Validation +==== Validation -```bash +[source,bash] +---- # Verify RSR Bronze compliance just verify-rsr @@ -34,11 +36,12 @@ just loc # Show project statistics just stats -``` +---- -### Using Nix +==== Using Nix -```bash +[source,bash] +---- # Enter development environment nix develop @@ -47,43 +50,53 @@ nix build # Run checks nix flake check -``` +---- -## RSR Compliance Levels +=== RSR Compliance Levels -| Level | Score | Requirements | -|-------|-------|--------------| -| **Raw** | <60 | Basic repository | -| **Bronze** | 60-74 | Required files (LICENSE, README, SECURITY, CONTRIBUTING, CODE_OF_CONDUCT) | -| **Silver** | 75-84 | Bronze + .well-known/, MAINTAINERS, CHANGELOG | -| **Gold** | 85-94 | Silver + comprehensive docs, examples | -| **Rhodium** | 95-100 | Gold + exceptional clarity, submitted to Rhodium Register | +[width="100%",cols="25%,25%,50%",options="header",] +|=== +|Level |Score |Requirements +|*Raw* |<60 |Basic repository -## Required Files for Bronze +|*Bronze* |60-74 |Required files (LICENSE, README, SECURITY, +CONTRIBUTING, CODE_OF_CONDUCT) + +|*Silver* |75-84 |Bronze + .well-known/, MAINTAINERS, CHANGELOG + +|*Gold* |85-94 |Silver + comprehensive docs, examples + +|*Rhodium* |95-100 |Gold + exceptional clarity, submitted to Rhodium +Register +|=== + +=== Required Files for Bronze Minimum files needed for RSR Bronze compliance: -- ✅ `LICENSE` or `LICENSE.txt` (Dual MIT + Palimpsest v0.8 recommended) -- ✅ `README.md` (Comprehensive project overview) -- ✅ `SECURITY.md` (Vulnerability reporting policy) -- ✅ `CONTRIBUTING.md` (Contribution guidelines) -- ✅ `CODE_OF_CONDUCT.md` (Community standards) +* ✅ `+LICENSE+` or `+LICENSE.txt+` (Dual MIT + Palimpsest v0.8 +recommended) +* ✅ `+README.md+` (Comprehensive project overview) +* ✅ `+SECURITY.md+` (Vulnerability reporting policy) +* ✅ `+CONTRIBUTING.md+` (Contribution guidelines) +* ✅ `+CODE_OF_CONDUCT.md+` (Community standards) -## Recommended Files for Silver +=== Recommended Files for Silver Additional files to reach Silver: -- 💡 `MAINTAINERS.md` (Governance structure) -- 💡 `CHANGELOG.md` (Version history) -- 💡 `.well-known/security.txt` (RFC 9116 security contact) -- 💡 `.well-known/ai.txt` (AI training policies) -- 💡 `.well-known/humans.txt` (Attribution) +* 💡 `+MAINTAINERS.md+` (Governance structure) +* 💡 `+CHANGELOG.md+` (Version history) +* 💡 `+.well-known/security.txt+` (RFC 9116 security contact) +* 💡 `+.well-known/ai.txt+` (AI training policies) +* 💡 `+.well-known/humans.txt+` (Attribution) -## ReScript Syntax Quick Reference +=== ReScript Syntax Quick Reference -### Types +==== Types -```rescript +[source,rescript] +---- // Type alias type username = string @@ -99,11 +112,12 @@ type status = Active | Inactive | Suspended // Parametric type type result<'a, 'e> = Ok('a) | Error('e) -``` +---- -### Functions +==== Functions -```rescript +[source,rescript] +---- // Basic function let add = (x, y) => x + y @@ -117,11 +131,12 @@ let double = multiply(2) // Partial application // Recursive function let rec factorial = (n) => if n <= 1 { 1 } else { n * factorial(n - 1) } -``` +---- -### Pattern Matching +==== Pattern Matching -```rescript +[source,rescript] +---- // Match on variant let levelToString = (level: qualityLevel): string => switch level { @@ -147,11 +162,12 @@ let compare = (x, y) => | (_, 0) => "y is zero" | (_, _) => "neither zero" } -``` +---- -### Arrays +==== Arrays -```rescript +[source,rescript] +---- // Array literal let numbers = [1, 2, 3, 4, 5] @@ -159,11 +175,12 @@ let numbers = [1, 2, 3, 4, 5] let doubled = Belt.Array.map(numbers, x => x * 2) let sum = Belt.Array.reduce(numbers, 0, (acc, x) => acc + x) let evens = Belt.Array.keep(numbers, x => mod(x, 2) == 0) -``` +---- -### Options +==== Options -```rescript +[source,rescript] +---- // Creating options let some = Some(42) let none = None @@ -177,44 +194,47 @@ let value = switch some { // Option helpers (Belt.Option) let result = Belt.Option.map(some, x => x * 2) // Some(84) let default = Belt.Option.getWithDefault(none, 0) // 0 -``` +---- -## Common Patterns +=== Common Patterns -### Validating Input +==== Validating Input -```rescript +[source,rescript] +---- let validateEmail = (email: string): result => if Js.String2.includes(email, "@") { Ok(email) } else { Error("Invalid email: missing @ symbol") } -``` +---- -### Transforming Data +==== Transforming Data -```rescript +[source,rescript] +---- let normalizeAndFilter = (paths: array): array => paths ->Belt.Array.map(Js.String2.toLowerCase) ->Belt.Array.map(Js.String2.trim) ->Belt.Array.keep(path => path != "") -``` +---- -### Building Pipelines +==== Building Pipelines -```rescript +[source,rescript] +---- let processFiles = (files: array): int => files ->Belt.Array.keep(file => Js.String2.endsWith(file, ".md")) ->Belt.Array.map(Js.String2.length) ->Belt.Array.reduce(0, (acc, len) => acc + len) -``` +---- -## File Structure +=== File Structure -``` +.... grimrepo-scripts/ ├── src/ # ReScript source files (.res) │ ├── GrimRepoTypes.res @@ -242,79 +262,83 @@ grimrepo-scripts/ ├── Justfile # Task automation ├── flake.nix # Nix build └── .gitlab-ci.yml # CI/CD pipeline -``` +.... + +=== Troubleshooting -## Troubleshooting +==== Build Errors -### Build Errors +*Problem*: `+rescript: command not found+` -**Problem**: `rescript: command not found` +*Solution*: -**Solution**: -```bash +[source,bash] +---- npm install -g rescript@latest # OR nix develop # Use Nix environment -``` +---- + +*Problem*: ReScript compilation errors -**Problem**: ReScript compilation errors +*Solution*: -**Solution**: -```bash +[source,bash] +---- # Clean and rebuild just clean just build # Check for syntax errors in .res files rescript format -all -``` +---- -### RSR Validation Failures +==== RSR Validation Failures -**Problem**: `just verify-rsr` shows missing files +*Problem*: `+just verify-rsr+` shows missing files -**Solution**: -1. Check which files are missing (output lists them) -2. Create missing files using templates (see docs/guides/) -3. Re-run `just verify-rsr` +*Solution*: 1. Check which files are missing (output lists them) 2. +Create missing files using templates (see docs/guides/) 3. Re-run +`+just verify-rsr+` -**Problem**: Score doesn't improve despite adding files +*Problem*: Score doesn’t improve despite adding files -**Solution**: -- Ensure filenames match exactly (case-sensitive on some systems) -- Check file is not empty -- Verify file is in correct location (root directory vs subdirectory) +*Solution*: - Ensure filenames match exactly (case-sensitive on some +systems) - Check file is not empty - Verify file is in correct location +(root directory vs subdirectory) -## Performance Tips +=== Performance Tips -### ReScript Compilation +==== ReScript Compilation -- **Use** `just watch-rescript` during development (faster rebuilds) -- **Avoid** frequent `just clean` (only when necessary) -- **Enable** incremental compilation (default in ReScript) +* *Use* `+just watch-rescript+` during development (faster rebuilds) +* *Avoid* frequent `+just clean+` (only when necessary) +* *Enable* incremental compilation (default in ReScript) -### Runtime Performance +==== Runtime Performance -- **Prefer** immutable operations (compiler optimizes well) -- **Use** Belt.Array for efficient array operations -- **Avoid** unnecessary allocations (reuse constants) +* *Prefer* immutable operations (compiler optimizes well) +* *Use* Belt.Array for efficient array operations +* *Avoid* unnecessary allocations (reuse constants) -## Getting Help +=== Getting Help -### Documentation +==== Documentation -- **README**: Project overview -- **Architecture**: System design (`docs/architecture.md`) -- **Roadmap**: Future plans (`docs/ROADMAP.md`) -- **Migration**: Moving from other tools (`docs/guides/migration.md`) -- **Onboarding**: Contributing guide (`docs/guides/contributor-onboarding.md`) +* *README*: Project overview +* *Architecture*: System design (`+docs/architecture.md+`) +* *Roadmap*: Future plans (`+docs/ROADMAP.md+`) +* *Migration*: Moving from other tools (`+docs/guides/migration.md+`) +* *Onboarding*: Contributing guide +(`+docs/guides/contributor-onboarding.md+`) -### Support +==== Support -- **Issues**: https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues -- **Email**: (coming soon) support@grimrepo.dev -- **Community**: (coming soon) Discord/Matrix +* *Issues*: +https://gitlab.com/extensions-library/monkey-scripts/grimrepo-scripts/-/issues +* *Email*: (coming soon) support@grimrepo.dev +* *Community*: (coming soon) Discord/Matrix ---- +''''' -**Last Updated**: 2025-01-22 +*Last Updated*: 2025-01-22 diff --git a/docs/guides/wasm-compilation.md b/docs/guides/wasm-compilation.adoc similarity index 61% rename from docs/guides/wasm-compilation.md rename to docs/guides/wasm-compilation.adoc index b05261e..250456d 100644 --- a/docs/guides/wasm-compilation.md +++ b/docs/guides/wasm-compilation.adoc @@ -1,38 +1,42 @@ -# WASM Compilation Guide +== WASM Compilation Guide Compiling GrimRepo to WebAssembly for maximum performance. -## Status: Planned for Q2 2025 +=== Status: Planned for Q2 2025 -WASM compilation is currently in the design phase. This guide documents the planned approach. +WASM compilation is currently in the design phase. This guide documents +the planned approach. -## Why WASM? +=== Why WASM? -### Performance Benefits +==== Performance Benefits -| Metric | JavaScript | WASM (projected) | Improvement | -|--------|------------|------------------|-------------| -| Execution Speed | 7ms | **2ms** | **71% faster** | -| Memory Usage | 5.1 MB | **3.2 MB** | **37% reduction** | -| Bundle Size | 28 KB | **18 KB** | **36% smaller** | -| Cold Start | 22ms | **8ms** | **64% faster** | -| GC Pauses | ~2ms | **~0.5ms** | **75% reduction** | +[cols=",,,",options="header",] +|=== +|Metric |JavaScript |WASM (projected) |Improvement +|Execution Speed |7ms |*2ms* |*71% faster* +|Memory Usage |5.1 MB |*3.2 MB* |*37% reduction* +|Bundle Size |28 KB |*18 KB* |*36% smaller* +|Cold Start |22ms |*8ms* |*64% faster* +|GC Pauses |~2ms |*~0.5ms* |*75% reduction* +|=== -### Additional Advantages +==== Additional Advantages -1. **Near-Native Performance** - Executes at C/Rust speed -2. **Predictable Performance** - No JIT warm-up needed -3. **Cross-Browser Consistency** - Same performance everywhere -4. **Secure Sandboxing** - WASM runs in isolated environment -5. **Portable** - Works on any platform with WASM support +[arabic] +. *Near-Native Performance* - Executes at C/Rust speed +. *Predictable Performance* - No JIT warm-up needed +. *Cross-Browser Consistency* - Same performance everywhere +. *Secure Sandboxing* - WASM runs in isolated environment +. *Portable* - Works on any platform with WASM support -## Architecture +=== Architecture -### Hybrid Approach +==== Hybrid Approach GrimRepo will use a hybrid JavaScript + WASM architecture: -``` +.... ┌─────────────────────────────────────┐ │ Browser / Node.js │ │ │ @@ -52,45 +56,39 @@ GrimRepo will use a hybrid JavaScript + WASM architecture: │ │ - generateAuditReport() │ │ │ └──────────────────────────────┘ │ └─────────────────────────────────────┘ -``` +.... -### Responsibilities +==== Responsibilities -**JavaScript Layer**: -- DOM manipulation -- Userscript integration -- Platform detection -- LocalStorage access -- Event handling +*JavaScript Layer*: - DOM manipulation - Userscript integration - +Platform detection - LocalStorage access - Event handling -**WASM Layer**: -- Repository auditing logic -- Score calculation -- Report generation -- String processing -- Array operations +*WASM Layer*: - Repository auditing logic - Score calculation - Report +generation - String processing - Array operations -## Implementation Plan +=== Implementation Plan -### Phase 1: ReScript → OCaml +==== Phase 1: ReScript → OCaml ReScript compiles to JavaScript, but we need OCaml bytecode for WASM: -```bash +[source,bash] +---- # Current: ReScript → JavaScript src/GrimRepo.res → lib/GrimRepo.bs.js # Future: ReScript → OCaml → WASM src/GrimRepo.res → _build/GrimRepo.ml → lib/grimrepo.wasm -``` +---- -**Tool**: `rescript` + `dune` + `wasm_of_ocaml` +*Tool*: `+rescript+` + `+dune+` + `+wasm_of_ocaml+` -### Phase 2: Dune Configuration +==== Phase 2: Dune Configuration -Create `dune` files for OCaml/WASM build: +Create `+dune+` files for OCaml/WASM build: -```dune +[source,dune] +---- ; dune (in project root) (executable (name grimrepo) @@ -100,13 +98,14 @@ Create `dune` files for OCaml/WASM build: ; dune-project (lang dune 3.7) (name grimrepo) -``` +---- -### Phase 3: WASM Backend +==== Phase 3: WASM Backend -Use `wasm_of_ocaml` or `js_of_ocaml` with WASM target: +Use `+wasm_of_ocaml+` or `+js_of_ocaml+` with WASM target: -```bash +[source,bash] +---- # Install WASM compiler opam install wasm_of_ocaml @@ -116,13 +115,14 @@ dune build --profile release # Output: # _build/default/grimrepo.wasm # _build/default/grimrepo_wasm.js (loader) -``` +---- -### Phase 4: JavaScript Interop +==== Phase 4: JavaScript Interop Define FFI bindings for JavaScript ↔ WASM communication: -```ocaml +[source,ocaml] +---- (* External functions from JavaScript *) external log : string -> unit = "console_log" @@ -131,13 +131,14 @@ let audit_repository paths files = let result = Audit.audit_repository paths files in (* Convert OCaml result to JavaScript-friendly format *) result -``` +---- -### Phase 5: Performance Testing +==== Phase 5: Performance Testing Benchmark WASM vs JavaScript: -```javascript +[source,javascript] +---- // Benchmark script const wasmModule = await loadWASM('./lib/grimrepo.wasm') const jsModule = require('./lib/GrimRepo.bs.js') @@ -149,13 +150,13 @@ console.timeEnd('WASM Audit') console.time('JS Audit') jsModule.auditRepository(paths, files) console.timeEnd('JS Audit') -``` +---- -## Build Configuration +=== Build Configuration -### Project Structure (Future) +==== Project Structure (Future) -``` +.... grimrepo-scripts/ ├── src/ │ └── *.res # ReScript source (unchanged) @@ -166,11 +167,12 @@ grimrepo-scripts/ ├── *.bs.js # JavaScript output (current) ├── grimrepo.wasm # WASM binary (future) └── grimrepo_wasm.js # WASM loader (future) -``` +.... -### Justfile Updates +==== Justfile Updates -```justfile +[source,justfile] +---- # Build WASM (future) build-wasm: @echo "🔨 Building WASM..." @@ -182,11 +184,12 @@ build-wasm: benchmark: @echo "📊 Benchmarking performance..." node benchmarks/run.js -``` +---- -### flake.nix Updates +==== flake.nix Updates -```nix +[source,nix] +---- # Add OCaml and WASM tooling buildInputs = with pkgs; [ nodejs_20 @@ -198,13 +201,14 @@ buildInputs = with pkgs; [ just git ]; -``` +---- -## API Design +=== API Design -### WASM Module Interface +==== WASM Module Interface -```typescript +[source,typescript] +---- // Type definitions for WASM module interface GrimRepoWASM { // Core functions @@ -230,11 +234,12 @@ const result = wasm.auditRepository( ['README.md', 'LICENSE.txt'] ) console.log(wasm.generateAuditReport(result)) -``` +---- -### JavaScript Wrapper +==== JavaScript Wrapper -```javascript +[source,javascript] +---- // lib/grimrepo-wasm-wrapper.js class GrimRepoWASM { constructor(wasmModule) { @@ -275,15 +280,16 @@ export async function loadGrimRepo() { const wasmModule = await loadWASM('./lib/grimrepo.wasm') return new GrimRepoWASM(wasmModule) } -``` +---- -## Fallback Strategy +=== Fallback Strategy -### Progressive Enhancement +==== Progressive Enhancement Provide JavaScript fallback for browsers without WASM support: -```javascript +[source,javascript] +---- // Auto-detect WASM support async function loadGrimRepo() { if (typeof WebAssembly !== 'undefined') { @@ -296,53 +302,53 @@ async function loadGrimRepo() { return loadGrimRepoJS() } } -``` +---- -## Browser Compatibility +=== Browser Compatibility -### WASM Support +==== WASM Support -| Browser | Version | WASM Support | -|---------|---------|--------------| -| Chrome | 57+ | ✅ Full | -| Firefox | 52+ | ✅ Full | -| Safari | 11+ | ✅ Full | -| Edge | 16+ | ✅ Full | -| Opera | 44+ | ✅ Full | -| IE | All | ❌ None | +[cols=",,",options="header",] +|=== +|Browser |Version |WASM Support +|Chrome |57+ |✅ Full +|Firefox |52+ |✅ Full +|Safari |11+ |✅ Full +|Edge |16+ |✅ Full +|Opera |44+ |✅ Full +|IE |All |❌ None +|=== -**Coverage**: 95%+ of global browser market share +*Coverage*: 95%+ of global browser market share -### Polyfill +==== Polyfill For IE11 and older browsers: -```javascript +[source,javascript] +---- if (typeof WebAssembly === 'undefined') { // Load polyfill await import('wasm-polyfill') // Or just use JavaScript fallback } -``` +---- -## Debugging +=== Debugging -### WASM Debugging Tools +==== WASM Debugging Tools -**Chrome DevTools**: -1. Open DevTools → Sources tab -2. WASM modules appear in file tree -3. Set breakpoints in WASM code -4. Inspect variables (limited) +*Chrome DevTools*: 1. Open DevTools → Sources tab 2. WASM modules appear +in file tree 3. Set breakpoints in WASM code 4. Inspect variables +(limited) -**Firefox Developer Tools**: -1. Better WASM debugging than Chrome -2. Can view WASM text format -3. Step through WASM instructions +*Firefox Developer Tools*: 1. Better WASM debugging than Chrome 2. Can +view WASM text format 3. Step through WASM instructions -### Logging from WASM +==== Logging from WASM -```ocaml +[source,ocaml] +---- (* OCaml side *) external js_log : string -> unit = "console_log" @@ -354,9 +360,10 @@ let audit_repository paths files = let result = do_audit paths files in debug_log "Audit complete"; result -``` +---- -```javascript +[source,javascript] +---- // JavaScript side (provide console_log to WASM) const imports = { env: { @@ -368,15 +375,16 @@ const imports = { } const wasmModule = await WebAssembly.instantiate(wasmBytes, imports) -``` +---- -## Performance Tuning +=== Performance Tuning -### Memory Management +==== Memory Management WASM uses linear memory - optimize allocations: -```ocaml +[source,ocaml] +---- (* Avoid excessive allocations *) let rec sum_array arr = (* Bad: Creates intermediate lists *) @@ -389,13 +397,14 @@ let sum_array arr = total := !total + arr.(i) done; !total -``` +---- -### Minimize FFI Calls +==== Minimize FFI Calls JavaScript ↔ WASM calls have overhead: -```javascript +[source,javascript] +---- // Bad: Call WASM for each item files.forEach(file => { wasm.checkFile(file) // Multiple FFI calls @@ -403,75 +412,69 @@ files.forEach(file => { // Good: Batch process in WASM wasm.checkFiles(files) // Single FFI call -``` +---- -## Security Considerations +=== Security Considerations -### Sandboxing +==== Sandboxing -WASM runs in a secure sandbox: -- No access to file system -- No network access -- Isolated memory -- Cannot call arbitrary JavaScript +WASM runs in a secure sandbox: - No access to file system - No network +access - Isolated memory - Cannot call arbitrary JavaScript -**Benefit**: Even malicious WASM can't escape sandbox. +*Benefit*: Even malicious WASM can’t escape sandbox. -### Memory Safety +==== Memory Safety -WASM has bounds checking: -- Buffer overflows prevented -- Out-of-bounds access trapped -- Type safety enforced +WASM has bounds checking: - Buffer overflows prevented - Out-of-bounds +access trapped - Type safety enforced -**Benefit**: OCaml's safety + WASM's safety = double protection. +*Benefit*: OCaml’s safety + WASM’s safety = double protection. -## Roadmap +=== Roadmap -### Milestone 1: Prototype (Q2 2025) -- [ ] Set up dune build system -- [ ] Compile simple ReScript module to WASM -- [ ] Create JavaScript wrapper -- [ ] Basic interop test +==== Milestone 1: Prototype (Q2 2025) -### Milestone 2: Core Logic (Q3 2025) -- [ ] Port `analyzeStructure` to WASM -- [ ] Port `analyzeCommunityStandards` to WASM -- [ ] Port `auditRepository` to WASM -- [ ] Benchmark vs JavaScript +* [ ] Set up dune build system +* [ ] Compile simple ReScript module to WASM +* [ ] Create JavaScript wrapper +* [ ] Basic interop test -### Milestone 3: Production (Q4 2025) -- [ ] Optimize WASM bundle size -- [ ] Comprehensive testing -- [ ] Documentation -- [ ] Release v2.0 with WASM support +==== Milestone 2: Core Logic (Q3 2025) -### Milestone 4: Advanced (2026) -- [ ] SIMD optimizations -- [ ] Multi-threading (SharedArrayBuffer) -- [ ] Streaming compilation -- [ ] Native mobile apps (via WASM) +* [ ] Port `+analyzeStructure+` to WASM +* [ ] Port `+analyzeCommunityStandards+` to WASM +* [ ] Port `+auditRepository+` to WASM +* [ ] Benchmark vs JavaScript -## Contributing +==== Milestone 3: Production (Q4 2025) + +* [ ] Optimize WASM bundle size +* [ ] Comprehensive testing +* [ ] Documentation +* [ ] Release v2.0 with WASM support + +==== Milestone 4: Advanced (2026) + +* [ ] SIMD optimizations +* [ ] Multi-threading (SharedArrayBuffer) +* [ ] Streaming compilation +* [ ] Native mobile apps (via WASM) + +=== Contributing Interested in helping with WASM compilation? -**Skills Needed**: -- OCaml programming -- WASM fundamentals -- JavaScript FFI -- Performance optimization +*Skills Needed*: - OCaml programming - WASM fundamentals - JavaScript +FFI - Performance optimization -**How to Help**: -1. Experiment with `wasm_of_ocaml` -2. Benchmark ReScript → OCaml → WASM pipeline -3. Document findings in issues -4. Submit prototype implementations +*How to Help*: 1. Experiment with `+wasm_of_ocaml+` 2. Benchmark +ReScript → OCaml → WASM pipeline 3. Document findings in issues 4. +Submit prototype implementations ---- +''''' -**Status**: Design phase. Implementation begins Q2 2025. +*Status*: Design phase. Implementation begins Q2 2025. -**Questions?** Open an issue with label `wasm-compilation`. +*Questions?* Open an issue with label `+wasm-compilation+`. -**Last Updated**: 2025-01-22 +*Last Updated*: 2025-01-22 diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..5e91d5f --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,67 @@ +== Tech-Debt Audit — grim-repo — 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:* `+LOW+`. + +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 |269 +|`+docs/+` files |7 +|`+docs/+` LoC |2577 +|CHANGELOG.md |Y +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+LOW+` +|=== + +*Recommended next move:* `+docs/+` has only 7 file(s). Aim for ≥10 +organised docs (architecture, usage, contributing-guide, +troubleshooting, design-decisions). The user’s bar for a +"`heavily-developed and well-organised wiki`" is ≥10 files with topical +organisation. + +=== 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 48c4dfa..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,56 +0,0 @@ - - -# Tech-Debt Audit — grim-repo — 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:** `LOW`. - -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 | 269 | -| `docs/` files | 7 | -| `docs/` LoC | 2577 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `LOW` | - -**Recommended next move:** `docs/` has only 7 file(s). Aim for ≥10 organised docs (architecture, usage, contributing-guide, troubleshooting, design-decisions). The user's bar for a "heavily-developed and well-organised wiki" is ≥10 files with topical organisation. - -## 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..97d3206 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — grim-repo (Developer) + +=== What is grim-repo? + +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 04f80c6..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — grim-repo (Developer) - -## What is grim-repo? -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..1210593 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — grim-repo (User) + +=== What is grim-repo? + +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 eb9de85..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — grim-repo (User) - -## What is grim-repo? -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/scripts/GREASYFORK_SETUP.md b/scripts/GREASYFORK_SETUP.adoc similarity index 56% rename from scripts/GREASYFORK_SETUP.md rename to scripts/GREASYFORK_SETUP.adoc index d0448c3..c0e9134 100644 --- a/scripts/GREASYFORK_SETUP.md +++ b/scripts/GREASYFORK_SETUP.adoc @@ -1,18 +1,20 @@ -# GreasyFork Webhook Setup Guide +== GreasyFork Webhook Setup Guide -Your GreasyFork webhook is configured! Here's how to complete the setup: +Your GreasyFork webhook is configured! Here’s how to complete the setup: -## Webhook Details +=== Webhook Details -- **Payload URL**: `https://greasyfork.org/en/users/118672-jonathan-jewell/webhook` -- **Secret**: `f2ff1c08a7eac48e39c00d074422c30a64e9814fc88bb34c036e06f5e32b5b5a13f45eb13b5cd76f15b436ad8676952fb81ce8186c2ee264b5733e1931fa0237` -- **Event**: Push (already configured in your GitHub settings) +* *Payload URL*: +`+https://greasyfork.org/en/users/118672-jonathan-jewell/webhook+` +* *Secret*: +`+f2ff1c08a7eac48e39c00d074422c30a64e9814fc88bb34c036e06f5e32b5b5a13f45eb13b5cd76f15b436ad8676952fb81ce8186c2ee264b5733e1931fa0237+` +* *Event*: Push (already configured in your GitHub settings) -## Repository Structure +=== Repository Structure Your userscripts are now organized for webhook sync: -``` +.... grimrepo-scripts/ ├── userscripts/ │ ├── GrimGreaser.user.js @@ -22,42 +24,46 @@ grimrepo-scripts/ │ ├── GrimCIValidator.user.js │ └── GrimSecurityScanner.user.js └── dist/ (same files, for local testing) -``` +.... -## Initial Setup (One-Time) +=== Initial Setup (One-Time) -Since the webhook only works for **updates**, you need to manually create each script on GreasyFork first: +Since the webhook only works for *updates*, you need to manually create +each script on GreasyFork first: -### Step 1: Upload Scripts to GreasyFork +==== Step 1: Upload Scripts to GreasyFork -For each script in `userscripts/`: +For each script in `+userscripts/+`: -1. Go to https://greasyfork.org/en/scripts/new -2. Click **"Choose File"** and select the `.user.js` file -3. Set **Language** to "English" -4. Add **Description** (see descriptions below) -5. Add **Tags** (see tags below) -6. Click **"Post script"** +[arabic] +. Go to https://greasyfork.org/en/scripts/new +. Click *"`Choose File`"* and select the `+.user.js+` file +. Set *Language* to "`English`" +. Add *Description* (see descriptions below) +. Add *Tags* (see tags below) +. Click *"`Post script`"* -### Step 2: Configure Webhook Sync +==== Step 2: Configure Webhook Sync After creating each script on GreasyFork: -1. Go to the script's edit page -2. Scroll to **"Sync"** section -3. Select **"Sync type"**: GitHub -4. Enter **"Repository"**: `hyperpolymath/grimrepo-scripts` -5. Enter **"Branch"**: `main` -6. Enter **"Path"**: `userscripts/[ScriptName].user.js` - - Example: `userscripts/GrimGreaser.user.js` -7. Click **"Update script"** +[arabic] +. Go to the script’s edit page +. Scroll to *"`Sync`"* section +. Select *"`Sync type`"*: GitHub +. Enter *"`Repository`"*: `+hyperpolymath/grimrepo-scripts+` +. Enter *"`Branch`"*: `+main+` +. Enter *"`Path`"*: `+userscripts/[ScriptName].user.js+` +* Example: `+userscripts/GrimGreaser.user.js+` +. Click *"`Update script`"* -## Recommended Descriptions & Tags +=== Recommended Descriptions & Tags -### GrimGreaser +==== GrimGreaser -**Description:** -``` +*Description:* + +.... Pure ReScript build system with GreasyFork auto-publish capability. Meta-circular architecture allows ReScript to build itself into userscripts with automatic dependency bundling and minification. Features: @@ -67,16 +73,18 @@ Features: - Single Source of Truth from deno.json Part of the GrimRepo ecosystem for repository management. -``` +.... + +*Tags:* `+build-tool+`, `+automation+`, `+developer-tools+`, +`+rescript+` -**Tags:** `build-tool`, `automation`, `developer-tools`, `rescript` +''''' ---- +==== GrimPager -### GrimPager +*Description:* -**Description:** -``` +.... Perpetual auto-paging engine that never stops scrolling. Uses homoiconic rule database with smart pagination detection fallback. Features: @@ -86,16 +94,18 @@ Features: - Works on Google, GitHub, GitLab, Reddit, HN, and more Enables infinite browsing without clicking "Next Page" buttons. -``` +.... -**Tags:** `pagination`, `auto-paging`, `infinite-scroll`, `browsing` +*Tags:* `+pagination+`, `+auto-paging+`, `+infinite-scroll+`, +`+browsing+` ---- +''''' -### GrimTemplateEngine +==== GrimTemplateEngine -**Description:** -``` +*Description:* + +.... Intelligent repository health agent that detects missing community health files and generates customized templates with one click. Features: @@ -107,16 +117,18 @@ Features: - One-click GitHub/GitLab editor pre-fill Helps maintain 100+ repositories at scale. -``` +.... + +*Tags:* `+github+`, `+gitlab+`, `+repository-management+`, +`+templates+`, `+health-check+` -**Tags:** `github`, `gitlab`, `repository-management`, `templates`, `health-check` +''''' ---- +==== GrimLicenseChecker -### GrimLicenseChecker +*Description:* -**Description:** -``` +.... License compliance validator that scans repository files for SPDX headers and detects license inconsistencies. Features: @@ -127,16 +139,18 @@ Features: - Supports 10+ file extensions Essential for maintaining license compliance across multiple repositories. -``` +.... -**Tags:** `license`, `compliance`, `spdx`, `repository-management`, `legal` +*Tags:* `+license+`, `+compliance+`, `+spdx+`, +`+repository-management+`, `+legal+` ---- +''''' -### GrimCIValidator +==== GrimCIValidator -**Description:** -``` +*Description:* + +.... GitHub Actions workflow quality checker that validates CI/CD configurations for security best practices. Features: @@ -148,16 +162,18 @@ Features: - Categorizes issues by severity (Critical/Warning/Info) Ensures your CI/CD pipelines follow security best practices. -``` +.... + +*Tags:* `+github-actions+`, `+ci-cd+`, `+security+`, `+validation+`, +`+devops+` -**Tags:** `github-actions`, `ci-cd`, `security`, `validation`, `devops` +''''' ---- +==== GrimSecurityScanner -### GrimSecurityScanner +*Description:* -**Description:** -``` +.... Security vulnerability detector that scans repositories for common security issues and missing security files. Features: @@ -169,17 +185,20 @@ Features: - Manual trigger via userscript menu Basic security scanning for repository health checks. -``` +.... -**Tags:** `security`, `vulnerability-scanner`, `repository-management`, `code-quality` +*Tags:* `+security+`, `+vulnerability-scanner+`, +`+repository-management+`, `+code-quality+` ---- +''''' -## After Setup: Automatic Sync +=== After Setup: Automatic Sync -Once configured, any push to GitHub will automatically update all scripts on GreasyFork: +Once configured, any push to GitHub will automatically update all +scripts on GreasyFork: -```bash +[source,bash] +---- # Make changes to userscripts vim userscripts/GrimPager.user.js @@ -189,36 +208,42 @@ git commit -m "Update GrimPager: add new site rule" git push origin main # GreasyFork automatically updates within seconds! ✨ -``` +---- -## Workflow Integration +=== Workflow Integration Add this to your build pipeline: -```bash +[source,bash] +---- # In deno.json tasks: "build-all": "deno task build && deno run --allow-read --allow-write --allow-env build-userscripts.ts && cp dist/*.user.js userscripts/" -``` +---- Then: -```bash + +[source,bash] +---- deno task build-all git add userscripts/ git commit -m "Release v1.0.1" git push -``` +---- -## Troubleshooting +=== Troubleshooting -If webhook sync isn't working: +If webhook sync isn’t working: -1. Check webhook delivery at: https://github.com/hyperpolymath/grimrepo-scripts/settings/hooks -2. Verify the script path on GreasyFork matches exactly -3. Ensure the file has proper userscript metadata headers -4. Check that the branch is `main` (not `master`) +[arabic] +. Check webhook delivery at: +https://github.com/hyperpolymath/grimrepo-scripts/settings/hooks +. Verify the script path on GreasyFork matches exactly +. Ensure the file has proper userscript metadata headers +. Check that the branch is `+main+` (not `+master+`) -## Additional Resources +=== Additional Resources -- [GreasyFork Webhook Docs](https://greasyfork.org/en/help/external-scripts) -- [GitHub Webhook Guide](https://docs.github.com/en/webhooks) -- [Userscript Metadata](https://wiki.greasespot.net/Metadata_Block) +* https://greasyfork.org/en/help/external-scripts[GreasyFork Webhook +Docs] +* https://docs.github.com/en/webhooks[GitHub Webhook Guide] +* https://wiki.greasespot.net/Metadata_Block[Userscript Metadata] diff --git a/scripts/UPLOAD_GUIDE.md b/scripts/UPLOAD_GUIDE.adoc similarity index 66% rename from scripts/UPLOAD_GUIDE.md rename to scripts/UPLOAD_GUIDE.adoc index 393f2be..5bde977 100644 --- a/scripts/UPLOAD_GUIDE.md +++ b/scripts/UPLOAD_GUIDE.adoc @@ -1,27 +1,27 @@ -# GreasyFork Upload Guide - Copy & Paste Ready +== GreasyFork Upload Guide - Copy & Paste Ready -## Upload Order (Recommended) +=== Upload Order (Recommended) -Upload in this order to set up the ecosystem properly: -1. GrimGreaser (build system) -2. GrimPager (browsing helper) -3. GrimTemplateEngine (main tool) -4. GrimLicenseChecker (validation) -5. GrimCIValidator (validation) -6. GrimSecurityScanner (validation) +Upload in this order to set up the ecosystem properly: 1. GrimGreaser +(build system) 2. GrimPager (browsing helper) 3. GrimTemplateEngine +(main tool) 4. GrimLicenseChecker (validation) 5. GrimCIValidator +(validation) 6. GrimSecurityScanner (validation) ---- +''''' -## Script 1: GrimGreaser +=== Script 1: GrimGreaser + +==== Upload URL -### Upload URL https://greasyfork.org/en/scripts/new -### File to Upload -`userscripts/GrimGreaser.user.js` +==== File to Upload + +`+userscripts/GrimGreaser.user.js+` -### Description (Copy & Paste) -``` +==== Description (Copy & Paste) + +.... Pure ReScript build system with GreasyFork auto-publish capability. Meta-circular architecture allows ReScript to build itself into userscripts with automatic dependency bundling and minification. Features: @@ -36,31 +36,36 @@ Links: • Homepage: https://github.com/hyperpolymath/grimrepo-scripts • Documentation: https://github.com/hyperpolymath/grimrepo-scripts/tree/main/docs • Report Issues: https://github.com/hyperpolymath/grimrepo-scripts/issues -``` +.... + +==== Tags (Space-separated) -### Tags (Space-separated) -``` +.... build-tool automation developer-tools rescript -``` +.... -### After Posting - Webhook Sync Settings -- **Sync type**: GitHub -- **Repository**: `hyperpolymath/grimrepo-scripts` -- **Branch**: `main` -- **Path**: `userscripts/GrimGreaser.user.js` +==== After Posting - Webhook Sync Settings ---- +* *Sync type*: GitHub +* *Repository*: `+hyperpolymath/grimrepo-scripts+` +* *Branch*: `+main+` +* *Path*: `+userscripts/GrimGreaser.user.js+` -## Script 2: GrimPager +''''' + +=== Script 2: GrimPager + +==== Upload URL -### Upload URL https://greasyfork.org/en/scripts/new -### File to Upload -`userscripts/GrimPager.user.js` +==== File to Upload + +`+userscripts/GrimPager.user.js+` + +==== Description (Copy & Paste) -### Description (Copy & Paste) -``` +.... Perpetual auto-paging engine that never stops scrolling. Uses homoiconic rule database with smart pagination detection fallback. Features: @@ -78,31 +83,36 @@ Links: • Homepage: https://github.com/hyperpolymath/grimrepo-scripts • Documentation: https://github.com/hyperpolymath/grimrepo-scripts/blob/main/docs/GrimPager.md • Report Issues: https://github.com/hyperpolymath/grimrepo-scripts/issues -``` +.... -### Tags (Space-separated) -``` +==== Tags (Space-separated) + +.... pagination auto-paging infinite-scroll browsing -``` +.... + +==== After Posting - Webhook Sync Settings -### After Posting - Webhook Sync Settings -- **Sync type**: GitHub -- **Repository**: `hyperpolymath/grimrepo-scripts` -- **Branch**: `main` -- **Path**: `userscripts/GrimPager.user.js` +* *Sync type*: GitHub +* *Repository*: `+hyperpolymath/grimrepo-scripts+` +* *Branch*: `+main+` +* *Path*: `+userscripts/GrimPager.user.js+` ---- +''''' -## Script 3: GrimTemplateEngine +=== Script 3: GrimTemplateEngine + +==== Upload URL -### Upload URL https://greasyfork.org/en/scripts/new -### File to Upload -`userscripts/GrimTemplateEngine.user.js` +==== File to Upload + +`+userscripts/GrimTemplateEngine.user.js+` -### Description (Copy & Paste) -``` +==== Description (Copy & Paste) + +.... Intelligent repository health agent that detects missing community health files and generates customized templates with one click. Features: @@ -123,31 +133,36 @@ Links: • Documentation: https://github.com/hyperpolymath/grimrepo-scripts/blob/main/docs/GrimTemplateEngine.adoc • Control Guide: https://github.com/hyperpolymath/grimrepo-scripts/blob/main/docs/REPOSITORY_CONTROL_GUIDE.adoc • Report Issues: https://github.com/hyperpolymath/grimrepo-scripts/issues -``` +.... + +==== Tags (Space-separated) -### Tags (Space-separated) -``` +.... github gitlab repository-management templates health-check -``` +.... + +==== After Posting - Webhook Sync Settings -### After Posting - Webhook Sync Settings -- **Sync type**: GitHub -- **Repository**: `hyperpolymath/grimrepo-scripts` -- **Branch**: `main` -- **Path**: `userscripts/GrimTemplateEngine.user.js` +* *Sync type*: GitHub +* *Repository*: `+hyperpolymath/grimrepo-scripts+` +* *Branch*: `+main+` +* *Path*: `+userscripts/GrimTemplateEngine.user.js+` ---- +''''' -## Script 4: GrimLicenseChecker +=== Script 4: GrimLicenseChecker + +==== Upload URL -### Upload URL https://greasyfork.org/en/scripts/new -### File to Upload -`userscripts/GrimLicenseChecker.user.js` +==== File to Upload + +`+userscripts/GrimLicenseChecker.user.js+` -### Description (Copy & Paste) -``` +==== Description (Copy & Paste) + +.... License compliance validator that scans repository files for SPDX headers and detects license inconsistencies. Features: @@ -170,31 +185,36 @@ Links: • Homepage: https://github.com/hyperpolymath/grimrepo-scripts • Documentation: https://github.com/hyperpolymath/grimrepo-scripts/blob/main/docs/REPOSITORY_CONTROL_GUIDE.adoc • Report Issues: https://github.com/hyperpolymath/grimrepo-scripts/issues -``` +.... + +==== Tags (Space-separated) -### Tags (Space-separated) -``` +.... license compliance spdx repository-management legal -``` +.... -### After Posting - Webhook Sync Settings -- **Sync type**: GitHub -- **Repository**: `hyperpolymath/grimrepo-scripts` -- **Branch**: `main` -- **Path**: `userscripts/GrimLicenseChecker.user.js` +==== After Posting - Webhook Sync Settings ---- +* *Sync type*: GitHub +* *Repository*: `+hyperpolymath/grimrepo-scripts+` +* *Branch*: `+main+` +* *Path*: `+userscripts/GrimLicenseChecker.user.js+` -## Script 5: GrimCIValidator +''''' + +=== Script 5: GrimCIValidator + +==== Upload URL -### Upload URL https://greasyfork.org/en/scripts/new -### File to Upload -`userscripts/GrimCIValidator.user.js` +==== File to Upload + +`+userscripts/GrimCIValidator.user.js+` + +==== Description (Copy & Paste) -### Description (Copy & Paste) -``` +.... GitHub Actions workflow quality checker that validates CI/CD configurations for security best practices. Features: @@ -219,31 +239,36 @@ Links: • Homepage: https://github.com/hyperpolymath/grimrepo-scripts • Documentation: https://github.com/hyperpolymath/grimrepo-scripts/blob/main/docs/REPOSITORY_CONTROL_GUIDE.adoc • Report Issues: https://github.com/hyperpolymath/grimrepo-scripts/issues -``` +.... -### Tags (Space-separated) -``` +==== Tags (Space-separated) + +.... github-actions ci-cd security validation devops -``` +.... + +==== After Posting - Webhook Sync Settings -### After Posting - Webhook Sync Settings -- **Sync type**: GitHub -- **Repository**: `hyperpolymath/grimrepo-scripts` -- **Branch**: `main` -- **Path**: `userscripts/GrimCIValidator.user.js` +* *Sync type*: GitHub +* *Repository*: `+hyperpolymath/grimrepo-scripts+` +* *Branch*: `+main+` +* *Path*: `+userscripts/GrimCIValidator.user.js+` ---- +''''' -## Script 6: GrimSecurityScanner +=== Script 6: GrimSecurityScanner + +==== Upload URL -### Upload URL https://greasyfork.org/en/scripts/new -### File to Upload -`userscripts/GrimSecurityScanner.user.js` +==== File to Upload + +`+userscripts/GrimSecurityScanner.user.js+` -### Description (Copy & Paste) -``` +==== Description (Copy & Paste) + +.... Security vulnerability detector that scans repositories for common security issues and missing security files. Features: @@ -270,44 +295,42 @@ Links: • Homepage: https://github.com/hyperpolymath/grimrepo-scripts • Documentation: https://github.com/hyperpolymath/grimrepo-scripts/blob/main/docs/REPOSITORY_CONTROL_GUIDE.adoc • Report Issues: https://github.com/hyperpolymath/grimrepo-scripts/issues -``` +.... + +==== Tags (Space-separated) -### Tags (Space-separated) -``` +.... security vulnerability-scanner repository-management code-quality -``` +.... + +==== After Posting - Webhook Sync Settings -### After Posting - Webhook Sync Settings -- **Sync type**: GitHub -- **Repository**: `hyperpolymath/grimrepo-scripts` -- **Branch**: `main` -- **Path**: `userscripts/GrimSecurityScanner.user.js` +* *Sync type*: GitHub +* *Repository*: `+hyperpolymath/grimrepo-scripts+` +* *Branch*: `+main+` +* *Path*: `+userscripts/GrimSecurityScanner.user.js+` ---- +''''' -## Quick Upload Checklist +=== Quick Upload Checklist -For each script: -- [ ] Go to https://greasyfork.org/en/scripts/new -- [ ] Click "Choose File" and select the .user.js file -- [ ] Set Language to "English" -- [ ] Paste the description -- [ ] Add the tags (space-separated) -- [ ] Click "Post script" -- [ ] Go to script edit page -- [ ] Scroll to "Sync" section -- [ ] Configure webhook settings -- [ ] Click "Update script" +For each script: - [ ] Go to https://greasyfork.org/en/scripts/new - [ ] +Click "`Choose File`" and select the .user.js file - [ ] Set Language to +"`English`" - [ ] Paste the description - [ ] Add the tags +(space-separated) - [ ] Click "`Post script`" - [ ] Go to script edit +page - [ ] Scroll to "`Sync`" section - [ ] Configure webhook settings - +[ ] Click "`Update script`" -## After All Scripts Are Uploaded +=== After All Scripts Are Uploaded Commit the userscripts to GitHub to test the webhook: -```bash +[source,bash] +---- cd $REPOS_DIR/grimrepo-scripts git add userscripts/ git commit -m "Add GreasyFork userscripts with webhook sync" git push origin main -``` +---- The webhook will automatically update all scripts on GreasyFork! ✨