diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..b1d73e6 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,96 @@ +// Markdownlint-cli2 Configuration +// Documentation quality enforcement aligned with CLAUDE.md guidelines +// See: https://github.com/igorshubovych/markdownlint-cli2 + +{ + "config": { + "default": true, + + // Headings - enforce proper hierarchy + "MD001": false, // heading-increment (relaxed - allow flexibility) + "MD026": { "punctuation": ".,;:!?" }, // heading-punctuation + + // Lists - enforce consistency + "MD004": { "style": "consistent" }, // ul-style (consistent list markers) + "MD005": false, // inconsistent-indentation (relaxed) + "MD007": { "indent": 2 }, // ul-indent + "MD029": false, // ol-prefix (allow flexible list numbering) + "MD030": { "ul_single": 1, "ol_single": 1, "ul_multi": 1, "ol_multi": 1 }, + + // Code blocks - fenced only + "MD046": { "style": "fenced" }, // code-block-style + + // Formatting - strict whitespace + "MD009": true, // no-hard-tabs + "MD010": true, // hard-tabs + "MD011": true, // reversed-link-syntax + "MD018": true, // no-missing-space-atx + "MD019": true, // no-multiple-space-atx + "MD020": true, // no-missing-space-closed-atx + "MD021": true, // no-multiple-space-closed-atx + "MD023": true, // heading-starts-line + "MD027": true, // no-multiple-spaces-blockquote + "MD037": true, // no-space-in-emphasis + "MD039": true, // no-space-in-links + + // Trailing content + "MD012": false, // no-multiple-blanks (relaxed - allow formatting space) + "MD024": false, // no-duplicate-heading (too strict for docs) + "MD028": false, // no-blanks-blockquote (relaxed) + "MD047": true, // single-trailing-newline + + // Links and references + "MD034": true, // no-bare-urls (links must be formatted) + "MD040": true, // fenced-code-language (code blocks need language) + "MD042": true, // no-empty-links + + // HTML - allow for documentation formatting and images + "MD033": { "allowed_elements": ["br", "hr", "details", "summary", "p", "img"] }, + + // Line length - relaxed for technical documentation + "MD013": { + "line_length": 150, + "heading_line_length": 150, + "code_block_line_length": 150, + "code_blocks": true, + "tables": true, + "headers": true, + "headers_line_length": 150, + "strict": false, + "stern": false + }, + + // Images + "MD045": true, // image-alt-text + + // Disable rules that conflict with relaxed style + "MD003": false, // consistent-indentation + "MD041": false, // first-line-heading + "MD025": false, // single-h1 / multiple-top-level-headings + "MD022": false, // blanks-around-headings (flexible spacing) + "MD032": false, // blanks-around-lists (flexible spacing) + "MD035": false, // hr-style (consistent) + "MD036": false, // no-emphasis-as-heading + "MD044": false // proper-names + }, + + // Documentation patterns + "globs": [ + "docs/**/*.md", + "!docs/node_modules/**", + "!docs/build/**" + ], + + // Ignore build artifacts, external content, and operational directories + "ignores": [ + "node_modules/**", + "target/**", + ".git/**", + "build/**", + "dist/**", + ".coder/**", + ".claude/**", + ".wrks/**", + ".vale/**" + ] +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..af07e8c --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,128 @@ +# Pre-commit Framework Configuration +# Generated by dev-system/ci +# Configures git pre-commit hooks for Rust projects + +repos: + # ============================================================================ + # Rust Hooks (COMMENTED OUT - Not used in this repo) + # ============================================================================ + # - repo: local + # hooks: + # - id: rust-fmt + # name: Rust formatting (cargo +nightly fmt) + # entry: bash -c 'cargo +nightly fmt --all -- --check' + # language: system + # types: [rust] + # pass_filenames: false + # stages: [pre-commit] + # + # - id: rust-clippy + # name: Rust linting (cargo clippy) + # entry: bash -c 'cargo clippy --all-targets -- -D warnings' + # language: system + # types: [rust] + # pass_filenames: false + # stages: [pre-commit] + # + # - id: rust-test + # name: Rust tests + # entry: bash -c 'cargo test --workspace' + # language: system + # types: [rust] + # pass_filenames: false + # stages: [pre-push] + # + # - id: cargo-deny + # name: Cargo deny (licenses & advisories) + # entry: bash -c 'cargo deny check licenses advisories' + # language: system + # pass_filenames: false + # stages: [pre-push] + + # ============================================================================ + # Nushell Hooks (ACTIVE) + # ============================================================================ + - repo: local + hooks: + - id: nushell-check + name: Nushell validation (nu --ide-check) + entry: >- + bash -c 'for f in $(git diff --cached --name-only --diff-filter=ACM | grep "\.nu$"); do + echo "Checking: $f"; nu --ide-check 100 "$f" || exit 1; done' + language: system + types: [file] + files: \.nu$ + pass_filenames: false + stages: [pre-commit] + + # ============================================================================ + # Nickel Hooks (ACTIVE) + # ============================================================================ + - repo: local + hooks: + - id: nickel-typecheck + name: Nickel type checking + entry: >- + bash -c 'export NICKEL_IMPORT_PATH="../:."; for f in $(git diff --cached --name-only --diff-filter=ACM | grep "\.ncl$"); do + echo "Checking: $f"; nickel typecheck "$f" || exit 1; done' + language: system + types: [file] + files: \.ncl$ + pass_filenames: false + stages: [pre-commit] + + # ============================================================================ + # Bash Hooks (optional - enable if using Bash) + # ============================================================================ + # - repo: local + # hooks: + # - id: shellcheck + # name: Shellcheck (bash linting) + # entry: shellcheck + # language: system + # types: [shell] + # stages: [commit] + # + # - id: shfmt + # name: Shell script formatting + # entry: bash -c 'shfmt -i 2 -d' + # language: system + # types: [shell] + # stages: [commit] + + # ============================================================================ + # Markdown Hooks (ACTIVE) + # ============================================================================ + - repo: local + hooks: + - id: markdownlint + name: Markdown linting (markdownlint-cli2) + entry: markdownlint-cli2 + language: system + types: [markdown] + stages: [pre-commit] + + # ============================================================================ + # General Pre-commit Hooks + # ============================================================================ + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: check-added-large-files + args: ['--maxkb=1000'] + + - id: check-case-conflict + + - id: check-merge-conflict + + - id: check-toml + + # - id: check-yaml + # exclude: ^\.woodpecker/ + + - id: end-of-file-fixer + + - id: trailing-whitespace + exclude: \.md$ + + - id: mixed-line-ending diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..084ffa9 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,107 @@ +# Code of Conduct + +## Our Pledge + +We, as members, contributors, and leaders, pledge to make participation in our project and community a harassment-free experience for everyone, regardless of: + +- Age +- Body size +- Visible or invisible disability +- Ethnicity +- Sex characteristics +- Gender identity and expression +- Level of experience +- Education +- Socioeconomic status +- Nationality +- Personal appearance +- Race +- Caste +- Color +- Religion +- Sexual identity and orientation + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by mistakes +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery +- Trolling, insulting, or derogatory comments +- Personal or political attacks +- Public or private harassment +- Publishing others' private information (doxing) +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate corrective action in response to unacceptable behavior. + +Maintainers have the right and responsibility to: + +- Remove, edit, or reject comments, commits, code, and other contributions +- Ban contributors for behavior they deem inappropriate, threatening, or harmful + +## Scope + +This Code of Conduct applies to: + +- All community spaces (GitHub, forums, chat, events, etc.) +- Official project channels and representations +- Interactions between community members related to the project + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to project maintainers: + +- Email: [project contact] +- GitHub: Private security advisory +- Issues: Report with `conduct` label (public discussions only) + +All complaints will be reviewed and investigated promptly and fairly. + +### Enforcement Guidelines + +**1. Correction** + +- Community impact: Use of inappropriate language or unwelcoming behavior +- Action: Private written warning with explanation and clarity on impact +- Consequence: Warning and no further violations + +**2. Warning** + +- Community impact: Violation through single incident or series of actions +- Action: Written warning with severity consequences for continued behavior +- Consequence: Suspension from community interaction + +**3. Temporary Ban** + +- Community impact: Serious violation of standards +- Action: Temporary ban from community interaction +- Consequence: Revocation of ban after reflection period + +**4. Permanent Ban** + +- Community impact: Pattern of violating community standards +- Action: Permanent ban from community interaction + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1. + +For answers to common questions about this code of conduct, see the FAQ at . + +--- + +**Thank you for being part of our community!** + +We believe in creating a welcoming and inclusive space where everyone can contribute their best work. Together, we make this project better. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..dc40771 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,130 @@ +# Contributing to provisioning + +Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project. + +## Code of Conduct + +This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for details. + +## Getting Started + +### Prerequisites + +- Rust 1.70+ (if project uses Rust) +- NuShell (if project uses Nushell scripts) +- Git + +### Development Setup + +1. Fork the repository +2. Clone your fork: `git clone https://repo.jesusperez.pro/jesus/provisioning` +3. Add upstream: `git remote add upstream https://repo.jesusperez.pro/jesus/provisioning` +4. Create a branch: `git checkout -b feature/your-feature` + +## Development Workflow + +### Before You Code + +- Check existing issues and pull requests to avoid duplication +- Create an issue to discuss major changes before implementing +- Assign yourself to let others know you're working on it + +### Code Standards + +#### Rust + +- Run `cargo fmt --all` before committing +- All code must pass `cargo clippy -- -D warnings` +- Write tests for new functionality +- Maintain 100% documentation coverage for public APIs + +#### Nushell + +- Validate scripts with `nu --ide-check 100 script.nu` +- Follow consistent naming conventions +- Use type hints where applicable + +#### Nickel + +- Type check schemas with `nickel typecheck` +- Document schema fields with comments +- Test schema validation + +### Commit Guidelines + +- Write clear, descriptive commit messages +- Reference issues with `Fixes #123` or `Related to #123` +- Keep commits focused on a single concern +- Use imperative mood: "Add feature" not "Added feature" + +### Testing + +All changes must include tests: + +```bash +# Run all tests +cargo test --workspace + +# Run with coverage +cargo llvm-cov --all-features --lcov + +# Run locally before pushing +just ci-full +``` + +### Pull Request Process + +1. Update documentation for any changed functionality +2. Add tests for new code +3. Ensure all CI checks pass +4. Request review from maintainers +5. Be responsive to feedback and iterate quickly + +## Review Process + +- Maintainers will review your PR within 3-5 business days +- Feedback is constructive and meant to improve the code +- All discussions should be respectful and professional +- Once approved, maintainers will merge the PR + +## Reporting Bugs + +Found a bug? Please file an issue with: + +- **Title**: Clear, descriptive title +- **Description**: What happened and what you expected +- **Steps to reproduce**: Minimal reproducible example +- **Environment**: OS, Rust version, etc. +- **Screenshots**: If applicable + +## Suggesting Enhancements + +Have an idea? Please file an issue with: + +- **Title**: Clear feature title +- **Description**: What, why, and how +- **Use cases**: Real-world scenarios where this would help +- **Alternative approaches**: If you've considered any + +## Documentation + +- Keep README.md up to date +- Document public APIs with rustdoc comments +- Add examples for non-obvious functionality +- Update CHANGELOG.md with your changes + +## Release Process + +Maintainers handle releases following semantic versioning: + +- MAJOR: Breaking changes +- MINOR: New features (backward compatible) +- PATCH: Bug fixes + +## Questions? + +- Check existing documentation and issues +- Ask in discussions or open an issue +- Join our community channels + +Thank you for contributing!