Add common project files

Signed-off-by: Wiktor Kwapisiewicz <wiktor@metacode.biz>

Author: wiktor-k

.clippy.toml

@@ -0,0 +1 @@
+doc-valid-idents = ["OpenPGP"]

.config/git_allowed_signers

@@ -0,0 +1 @@
+wiktor@metacode.biz ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDQv2RJtGurpNLWyiGz9sSuX8agzV98gHW2ZG/7vFkIQrPlaYsd/OH1z7BZNeCHs5vcoq6c2Eh5s6a0vcH4n181TKfjgpbq4t7OFNygWBJplXIZvIlsY//UCxfp5ZdKWJfrYUu/0HeEv5r/7ZcpwF/omC97aM0ipmAeQ8QEGLfgGW427ATa/r2SFwK/4h0C+BTUnMj/YC/4KI/MPWA6x7RdAw+RbVjZd4kT2ZPXcUdruSqDQ4vSP/b8gERv1IjWUn+HHteRJgR2SwNmsuuT/Ko3FRFfXxXPV2yMEvUY2+DoU781VhZJl0aqpW5bIhlK5VE5rGvmMuE5S7XwYDM9V0Wl

.config/nextest.toml

@@ -0,0 +1,2 @@
+[profile.ci.junit]
+path = "junit.xml"

.gitattributes

@@ -0,0 +1 @@
+* text eol=lf

.github/workflows/just.yml

@@ -0,0 +1,33 @@
+name: Check
+
+on: [pull_request]
+
+jobs:
+  generate-matrix:
+    name: Generate jobs
+    runs-on: ubuntu-latest
+    outputs:
+      jobs: ${{ steps.set-matrix.outputs.jobs }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: taiki-e/install-action@just
+      - run: node ./scripts/ci/create-github-checks.js
+        id: set-matrix
+
+  run-task:
+    name: ${{ matrix.jobs.doc }}
+    runs-on: ubuntu-latest
+    needs: [generate-matrix]
+    container:
+      image: archlinux
+    strategy:
+      fail-fast: false
+      max-parallel: 6
+      matrix: ${{fromJSON(needs.generate-matrix.outputs.jobs)}}
+
+    steps:
+      - uses: actions/checkout@v6
+      - run: pacman-key --init
+      - run: pacman -Sy --needed --noconfirm archlinux-keyring
+      - run: pacman -Syu --needed --noconfirm ${{ matrix.jobs.packages }}
+      - run: just --justfile ${{ matrix.jobs.file }} ${{ matrix.jobs.name }}

.justfile

@@ -0,0 +1,224 @@
+#!/usr/bin/env -S just --working-directory . --justfile
+
+clippy := "cargo clippy --quiet --workspace --no-deps --all-targets"
+clippy_args := "-D warnings"
+nextest_args := "--locked --workspace"
+udeps_args := "--quiet --workspace --all-features --all-targets"
+
+# Perform all checks
+[parallel]
+check: spell fmt doc lints deps unused-deps recipes test integration-test
+
+# Check spelling
+[group('ci')]
+[metadata('pacman', 'codespell')]
+spell:
+    codespell
+
+# Check source code formatting
+[group('ci')]
+[metadata('pacman', 'rustup')]
+fmt:
+    just --unstable --fmt --check
+    # We're using nightly to properly group imports, see .rustfmt.toml
+    rustup component add --toolchain nightly rustfmt
+    cargo +nightly fmt --quiet --all -- --check
+
+# Lint the source code
+[group('ci')]
+[metadata('gitlabci-job', '{"artifacts":{"when":"always","paths":["target/clippy"]}}')]
+[metadata('pacman', 'rust', 'python')]
+lints:
+    #!/usr/bin/bash
+    set -euo pipefail
+
+    if [ "${CI:-}" = "true" ]; then
+        ARGS=(--message-format=json)
+    else
+        ARGS=()
+    fi
+
+    mkdir -p target
+    {{ clippy }} "${ARGS[@]}" -- {{ clippy_args }} | tee target/clippy
+
+# Create lints report
+[metadata('gitlabci-job', '{"stage":"deploy","when":"always","artifacts":{"reports":{"codequality":"target/codeclimate.json"}}}')]
+[metadata('pacman', 'cargo-sonar', 'rust')]
+create-codeclimate:
+    # deny reports can be tested by adding a yanked dep e.g. `cargo add ed25519-dalek@0.9.0`
+    cargo codeclimate \
+        --clippy --clippy-path "target/clippy" \
+        --deny --deny-path "target/deny" \
+        --udeps --udeps-path "target/udeps" \
+        --codeclimate-path target/codeclimate.json
+
+# Check for issues with dependencies
+[group('ci')]
+[metadata('gitlabci-job', '{"artifacts":{"when":"always","paths":["target/deny"]}}')]
+[metadata('pacman', 'cargo-deny')]
+deps:
+    #!/usr/bin/bash
+    set -euo pipefail
+
+    if [ "${CI:-}" = "true" ]; then
+        ARGS=(--format json)
+    else
+        ARGS=()
+    fi
+
+    mkdir -p target
+    cargo deny "${ARGS[@]}" check -D advisory-not-detected -D license-not-encountered -D no-license-field 2>&1 | tee target/deny
+
+# Check for unused dependencies
+[group('ci')]
+[metadata('gitlabci-job', '{"artifacts":{"when":"always","paths":["target/udeps"]}}')]
+[metadata('pacman', 'cargo-machete', 'cargo-udeps', 'rust', 'python')]
+unused-deps:
+    #!/usr/bin/bash
+    set -euo pipefail
+
+    if [ "${CI:-}" = "true" ]; then
+        ARGS=(--output json)
+    else
+        ARGS=()
+    fi
+
+    mkdir -p target
+    cargo +nightly udeps {{ udeps_args }} "${ARGS[@]}" | tee target/udeps
+    cargo +nightly machete
+
+# Run unit tests
+[metadata('pacman', 'cargo-nextest')]
+test:
+    #!/usr/bin/bash
+    set -euxo pipefail
+
+    if [ "${CI:-}" = "true" ]; then
+        PROFILE=ci
+    else
+        PROFILE=default
+    fi
+
+    cargo +nightly nextest run {{ nextest_args }} --profile "$PROFILE"
+    cargo +nightly nextest run --no-default-features {{ nextest_args }} --profile "$PROFILE"
+
+# Run integration tests
+[metadata('pacman', 'git', 'jq', 'openssh', 'tangler', 'tree')]
+integration-test:
+    #!/usr/bin/bash
+    set -euo pipefail
+    cargo +nightly build --locked
+    target=$(cargo +nightly metadata --format-version 1 | jq --raw-output '.target_directory')
+    tangler sh < README.md | sed --quiet --regexp-extended 's/^\$ (.*)/\1/p' | PATH="$target/debug:$PATH" bash -euxo pipefail -
+
+# Report on all tests
+[group('ci')]
+[metadata('gitlabci-job', '{"coverage":"/Line coverage: ([0-9.]*)%/","artifacts":{"when":"always","reports":{"junit":"target/nextest/ci/junit.xml","metrics":"target/metrics.txt","coverage_report":{"coverage_format":"cobertura","path":"target/coverage.xml"}}}}')]
+[metadata('pacman', 'rust', 'cargo-llvm-cov', 'rustup', 'python')]
+report-test:
+    #!/usr/bin/bash
+    # enabling "x" here will garble text output that's parsed by GitLab for code coverage
+    set -euo pipefail
+
+    rustup component add --toolchain nightly llvm-tools-preview
+
+    # shellcheck disable=SC1090
+    source <(cargo +nightly llvm-cov show-env --export-prefix --doctests --branch)
+    cargo +nightly llvm-cov clean
+
+    just test integration-test
+
+    # explicitly use "target" (even if CARGO_TARGET_DIR is somewhere else) so that
+    # local tools (such as https://github.com/ryanluker/vscode-coverage-gutters) can find the file
+    cargo +nightly llvm-cov --quiet report --cobertura --output-path target/coverage.xml > /dev/null 2>&1
+
+    LINE_RATE=$(head target/coverage.xml | sed -nE 's/(.*coverage.*line-rate=")([^"]*)".*/\2/p')
+    LINE_PERCENT=$(echo "$LINE_RATE" | awk '{print $1 * 100}')
+    printf 'Line coverage: %s%%\n' "$LINE_PERCENT"
+
+    BRANCH_RATE=$(head target/coverage.xml | sed -nE 's/(.*coverage.*branch-rate=")([^"]*)".*/\2/p')
+    printf 'line_coverage_ratio %s\nbranch_coverage_ratio %s\n' "$LINE_RATE" "$BRANCH_RATE" > target/metrics.txt
+
+# Generate HTML report for the coverage
+coverage-html-report: report-test
+    #!/usr/bin/bash
+    set -euo pipefail
+    # shellcheck disable=SC1090
+    source <(cargo +nightly llvm-cov show-env --export-prefix)
+    cargo +nightly llvm-cov --quiet report --html > /dev/null 2>&1
+    printf "The coverage report is in file://%s/llvm-cov/html/index.html\n" "${CARGO_TARGET_DIR:-target}"
+
+# Build docs
+[group('ci')]
+[metadata('pacman', 'rust', 'python')]
+doc:
+    RUSTDOCFLAGS='-D warnings' cargo doc --quiet --no-deps --document-private-items
+
+# Check commit messages
+[metadata('pacman', 'codespell', 'git')]
+commits:
+    #!/usr/bin/env bash
+    set -Eeuo pipefail
+
+    # fetch default branch if it is set
+    if [[ -v CI_DEFAULT_BRANCH ]]; then
+        git fetch origin "$CI_DEFAULT_BRANCH"
+        refs="origin/$CI_DEFAULT_BRANCH"
+    else
+        refs="main"
+    fi
+
+    commits=$(git rev-list "${refs}..")
+    for commit in $commits; do
+      MSG="$(git show -s --format=%B "$commit")"
+      CODESPELL_RC="$(mktemp)"
+      git show "$commit:.codespellrc" > "$CODESPELL_RC"
+      if ! grep -q "Signed-off-by: " <<< "$MSG"; then
+        printf "⛔ Commit %s lacks \"Signed-off-by\" line.\n" "$commit"
+        printf "%s\n" \
+            "  Please use:" \
+            "    git rebase --signoff main && git push --force-with-lease" \
+            "  See https://developercertificate.org/ for more details."
+        exit 1;
+      elif ! codespell --config "$CODESPELL_RC" - <<< "$MSG"; then
+        printf "⛔ The spelling in commit %s needs improvement.\n" "$commit"
+        exit 1;
+      elif grep "WIP: " <<< "$MSG"; then
+        printf "⛔ Commit %s includes a 'WIP' marker which should be removed.\n" "$commit"
+        exit 1;
+      else
+        printf "✅ Commit %s is good.\n" "$commit"
+      fi
+    done
+
+# Lint justfile recipes
+[group('ci')]
+[metadata('pacman', 'nodejs', 'shellcheck')]
+recipes:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    T=$(mktemp -d)
+    node scripts/ci/export-shell.ts "$T"
+    for file in "$T"/*.sh; do
+        echo "Checking $file..."
+        shellcheck --shell bash "$file"
+    done
+
+# Fixes common issues. Files need to be git add'ed
+fix:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if ! git diff-files --quiet ; then
+        echo "Working tree has changes. Please stage them: git add ."
+        exit 1
+    fi
+
+    codespell --write-changes
+    just --unstable --fmt
+    # try to fix rustc issues
+    cargo fix --allow-staged
+    # try to fix clippy issues
+    cargo clippy --fix --allow-staged
+
+    # fmt must be last as clippy changes may break formatting
+    cargo +nightly fmt --all

.rustfmt.toml

@@ -0,0 +1,5 @@
+# CHECK https://github.com/rust-lang/rustfmt/issues/5083
+group_imports = "StdExternalCrate"
+# CHECK https://github.com/rust-lang/rustfmt/issues/3348
+format_code_in_doc_comments = true
+reorder_imports = true

CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing
+
+Thanks for taking the time to contribute to this project!
+
+All changes need to:
+
+- pass basic checks, including tests, formatting and lints,
+- be signed-off.
+
+## Basic checks
+
+We are using standard Rust ecosystem tools including `rustfmt` and `clippy` with one minor difference.
+Due to a couple of `rustfmt` features being available only in nightly (see the `.rustfmt.toml` file) nightly `rustfmt` is necessary.
+
+All of these details are captured in a `.justfile` and can be checked by running [`just`](https://just.systems/) (just version 1.42.0 is required due to support for extended attributes).
+
+To run all checks locally before sending them to CI you can set your git hooks directory:
+
+```sh
+git config core.hooksPath scripts/hooks/
+```
+
+## Developer Certificate of Origin
+
+The sign-off is a simple line at the end of the git commit message, which certifies that you wrote it or otherwise have the right to pass it on as a open-source patch.
+
+The rules are pretty simple: if you can [certify the below][DCO]:
+
+```
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```
+
+then you just add a line saying
+
+    Signed-off-by: Random J Developer <random@developer.example.org>
+
+using your name.
+
+If you set your `user.name` and `user.email`, you can sign your commit automatically with [`git commit --signoff`][GSO].
+
+To sign-off your last commit:
+
+    git commit --amend --signoff
+
+[DCO]: https://developercertificate.org
+[GSO]: https://git-scm.com/docs/git-commit#git-commit---signoff
+
+If you want to fix multiple commits use:
+
+    git rebase --signoff main
+
+To check if your commits are correctly signed-off locally use `just commits`.