Add ARCHITECTURE doc and MD markdownlint

.github/workflows/actionlint.yaml

@@ -5,11 +5,8 @@ on:
   pull_request:
     types:
       - opened
-      - edited
       - reopened
       - synchronize
-    paths:
-      - '.github/workflows/**'
 
 permissions:
   contents: read
@@ -19,7 +16,24 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Detect if workflows changed
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    outputs:
+      workflows: ${{ steps.filter.outputs.workflows }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: |
+            workflows:
+              - '.github/workflows/**'
+
   run-actionlint:
+    needs: changes
+    if: ${{ needs.changes.outputs.workflows == 'true' }}
     env:
       GH_TOKEN: ${{ github.token }}
     runs-on: ubuntu-24.04

.github/workflows/ci-on-push.yaml

@@ -21,8 +21,37 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Detect if only docs changed - skip CI if so
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          # For pull_request_target, checkout the PR head to detect changes
+          ref: ${{ github.event.pull_request.head.sha }}
+          # Fetch enough history to compare with base
+          fetch-depth: 0
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          # For pull_request_target, explicitly specify base and ref
+          base: ${{ github.event.pull_request.base.sha }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          filters: |
+            code:
+              - '**/*.rs'
+              - '**/*.toml'
+              - '**/*.lock'
+              - 'Cargo.lock'
+              - '.cargo/**'
+
   nvrc-ci-on-push:
-    if: contains(github.event.pull_request.labels.*.name, 'ok-to-test')
+    needs: changes
+    # Only run on self-hosted runner if: 1) ok-to-test label present (security), 2) code changed (efficiency)
+    if: ${{ contains(github.event.pull_request.labels.*.name, 'ok-to-test') && needs.changes.outputs.code == 'true' }}
     permissions:
       contents: read
       packages: write

.github/workflows/coverage.yaml

@@ -5,7 +5,6 @@ on:
   pull_request:
     types:
       - opened
-      - edited
       - reopened
       - synchronize
 
@@ -16,8 +15,29 @@ concurrency:
 name: Code Coverage
 
 jobs:
+  # Detect if only docs changed - skip CI if so
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: |
+            code:
+              - '**/*.rs'
+              - '**/*.toml'
+              - '**/*.lock'
+              - 'Cargo.lock'
+              - '.cargo/**'
+
   coverage:
     name: Code coverage
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

.github/workflows/docs.yaml

@@ -0,0 +1,42 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**.md'
+      - 'docs/**'
+      - '.markdownlint.json'
+      - '.github/workflows/docs.yaml'
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+    paths:
+      - '**.md'
+      - 'docs/**'
+      - '.markdownlint.json'
+      - '.github/workflows/docs.yaml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  markdown-lint:
+    name: Markdown Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Lint Markdown files
+        uses: DavidAnson/markdownlint-cli2-action@07035fd053f7be764496c0f8d8f9f41f98305101 # v22.0.0
+        with:
+          globs: '**/*.md'

.github/workflows/shellcheck.yaml

@@ -6,7 +6,6 @@ on:
   pull_request:
     types:
       - opened
-      - edited
       - reopened
       - synchronize
 
@@ -18,14 +17,69 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Detect what files changed
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    outputs:
+      scripts: ${{ steps.filter.outputs.scripts }}
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: |
+            scripts:
+              - '**.sh'
+              - '**.bash'
+            code:
+              - '**/*.rs'
+              - '**/*.toml'
+              - '**/*.lock'
+              - '**/*.sh'
+              - '**/*.bash'
+              - '**/*.yaml'
+              - '**/*.yml'
+              - '**/*.json'
+
+  # Always check for scripts without .sh extension (catches bad additions)
+  extension-check:
+    name: Check .sh extension
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Check shell scripts have .sh extension
+        run: |
+          # Find files with shell shebang but without .sh extension
+          bad_scripts=$(find . -type f \
+            ! -path './.git/*' \
+            ! -path './vendor/*' \
+            ! -path './target/*' \
+            ! -name '*.sh' \
+            ! -name '*.bash' \
+            -exec sh -c 'head -1 "$1" 2>/dev/null | grep -qE "^#!.*(bash|sh)" && echo "$1"' _ {} \;)
+          if [ -n "$bad_scripts" ]; then
+            echo "::error::Shell scripts must have .sh or .bash extension:"
+            echo "$bad_scripts"
+            exit 1
+          fi
+          echo "All shell scripts have correct extensions"
+
   shellcheck:
+    needs: changes
+    if: ${{ needs.changes.outputs.scripts == 'true' }}
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout the code
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           fetch-depth: 0
           persist-credentials: false
+
       - name: Run ShellCheck
         uses: ludeeus/action-shellcheck@00b27aa7cb85167568cb48a3838b75f4265f2bca # master (2024-06-20)
         with:

.github/workflows/static-checks.yaml

@@ -5,7 +5,6 @@ on:
   pull_request:
     types:
       - opened
-      - edited
       - reopened
       - synchronize
   schedule:
@@ -17,9 +16,30 @@ concurrency:
 
 name: Static checks
 jobs:
+  # Detect if only docs changed - skip CI if so
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: |
+            code:
+              - '**/*.rs'
+              - '**/*.toml'
+              - '**/*.lock'
+              - 'Cargo.lock'
+              - '.cargo/**'
+
   # Run unit and integration tests
   test:
     name: cargo test
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' || github.event_name == 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -36,6 +56,8 @@ jobs:
   # Check code formatting against Rust style guidelines
   formatting:
     name: cargo fmt
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' || github.event_name == 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -53,6 +75,8 @@ jobs:
   # Lint for common mistakes and style issues
   linting:
     name: cargo clippy
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' || github.event_name == 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -70,6 +94,8 @@ jobs:
   # Check dependencies for known security vulnerabilities
   security:
     name: cargo audit
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' || github.event_name == 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -87,6 +113,8 @@ jobs:
   # Verify licenses, check for banned dependencies, and audit sources
   deny:
     name: cargo deny
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' || github.event_name == 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -104,6 +132,8 @@ jobs:
   # Detect unused dependencies in Cargo.toml
   unused-deps:
     name: cargo udeps
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' || github.event_name == 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -121,6 +151,8 @@ jobs:
   # Analyze binary size and identify largest functions
   bloat:
     name: cargo bloat
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' || github.event_name == 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -138,6 +170,8 @@ jobs:
   # Detect undefined behavior in unsafe code using Miri interpreter
   miri:
     name: cargo miri
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' || github.event_name == 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

.markdownlint.json

@@ -0,0 +1,8 @@
+{
+  "default": true,
+  "MD013": {
+    "line_length": 80,
+    "code_blocks": false,
+    "tables": false
+  }
+}