From f2e5703393333a89cb2556b00532e24842ed80a5 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:16:07 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 ++ ARCHITECTURE.md | 47 -- CHANGELOG.adoc | 120 ++++ CHANGELOG.md | 130 ---- CODE_OF_CONDUCT.adoc | 266 ++++++++ CODE_OF_CONDUCT.md | 244 ------- CONTRIBUTING.adoc | 3 + CONTRIBUTING.md | 3 - GOVERNANCE.adoc | 60 ++ GOVERNANCE.md | 60 -- MAINTAINERS.adoc | 237 +++++++ MAINTAINERS.md | 244 ------- README.adoc | 283 +++++++++ README.md | 316 ---------- SECURITY.adoc | 186 ++++++ SECURITY.md | 162 ----- TEST-NEEDS.adoc | 29 + TEST-NEEDS.md | 26 - TOPOLOGY.md => TOPOLOGY.adoc | 39 +- docs/{API.md => API.adoc} | 595 ++++++++++-------- docs/guides/contributor-onboarding.adoc | 366 +++++++++++ docs/guides/contributor-onboarding.md | 376 ----------- docs/guides/migration.adoc | 351 +++++++++++ docs/guides/migration.md | 324 ---------- .../{performance.md => performance.adoc} | 303 +++++---- ...uick-reference.md => quick-reference.adoc} | 230 ++++--- ...m-compilation.md => wasm-compilation.adoc} | 327 +++++----- docs/tech-debt-2026-05-26.adoc | 67 ++ docs/tech-debt-2026-05-26.md | 56 -- llm-warmup-dev.adoc | 19 + llm-warmup-dev.md | 16 - llm-warmup-user.adoc | 19 + llm-warmup-user.md | 16 - ...ASYFORK_SETUP.md => GREASYFORK_SETUP.adoc} | 193 +++--- .../{UPLOAD_GUIDE.md => UPLOAD_GUIDE.adoc} | 265 ++++---- 35 files changed, 3106 insertions(+), 2920 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 MAINTAINERS.adoc delete mode 100644 MAINTAINERS.md create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (89%) rename docs/{API.md => API.adoc} (50%) create mode 100644 docs/guides/contributor-onboarding.adoc delete mode 100644 docs/guides/contributor-onboarding.md create mode 100644 docs/guides/migration.adoc delete mode 100644 docs/guides/migration.md rename docs/guides/{performance.md => performance.adoc} (52%) rename docs/guides/{quick-reference.md => quick-reference.adoc} (54%) rename docs/guides/{wasm-compilation.md => wasm-compilation.adoc} (61%) create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md rename scripts/{GREASYFORK_SETUP.md => GREASYFORK_SETUP.adoc} (56%) rename scripts/{UPLOAD_GUIDE.md => UPLOAD_GUIDE.adoc} (66%) 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! ✨