Update Regal docs to v0.40.0 (#8538)

Add new rule docs, update adopters, and remove automated docs workflow
(broken due to hardening).

Signed-off-by: Charlie Egan <charlie_egan@apple.com>

.github/workflows/docs-update.yaml

@@ -1,128 +0,0 @@
-name: Update Regal Docs
-on:
-  workflow_dispatch: {}   # Allow for manual triggers
-  schedule:
-    - cron: '0 6 * * *'   # Daily at 6:00 UTC
-
-permissions:
-  contents: read
-
-jobs:
-  update-regal-docs:
-    name: Update Regal Documentation
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          token: ${{ secrets.GH_PUSH_TOKEN }} # zizmor: ignore[secrets-outside-env]
-          persist-credentials: false
-
-      - name: Get latest Regal release
-        id: latest
-        env:
-          GH_TOKEN: ${{ secrets.GH_PUSH_TOKEN }} # zizmor: ignore[secrets-outside-env]
-        run: |
-          LATEST_VERSION=$(gh api repos/open-policy-agent/regal/releases/latest --jq '.tag_name')
-          echo "version=$LATEST_VERSION" >> $GITHUB_OUTPUT
-          echo "Latest Regal version: $LATEST_VERSION"
-
-      - name: Get current version
-        id: current
-        run: |
-          CURRENT_VERSION=$(jq -r '.regal' docs/imported.json)
-          echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
-          echo "Current Regal version: $CURRENT_VERSION"
-
-      - name: Check if update needed
-        id: check
-        run: |
-          if [ "${STEPS_LATEST_OUTPUTS_VERSION}" = "${STEPS_CURRENT_OUTPUTS_VERSION}" ]; then
-            echo "Already at latest version, no update needed"
-            echo "needed=false" >> $GITHUB_OUTPUT
-          else
-            echo "Update needed: ${STEPS_CURRENT_OUTPUTS_VERSION} -> ${STEPS_LATEST_OUTPUTS_VERSION}"
-            echo "needed=true" >> $GITHUB_OUTPUT
-          fi
-        env:
-          STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }}
-          STEPS_CURRENT_OUTPUTS_VERSION: ${{ steps.current.outputs.version }}
-
-      - name: Check if branch already exists
-        if: steps.check.outputs.needed == 'true'
-        run: |
-          BRANCH_NAME="update-regal-${STEPS_LATEST_OUTPUTS_VERSION}"
-          if git ls-remote --exit-code --heads origin "$BRANCH_NAME" >/dev/null 2>&1; then
-            echo "::error::Branch '$BRANCH_NAME' already exists. A PR for this version may already be open."
-            exit 1
-          fi
-          echo "Branch '$BRANCH_NAME' does not exist, proceeding with update"
-        env:
-          STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }}
-
-      - name: Update imported.json
-        if: steps.check.outputs.needed == 'true'
-        run: |
-          jq --arg version "${STEPS_LATEST_OUTPUTS_VERSION}" '.regal = $version' docs/imported.json > docs/imported.json.tmp
-          mv docs/imported.json.tmp docs/imported.json
-        env:
-          STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }}
-
-      - name: Run import script
-        if: steps.check.outputs.needed == 'true'
-        run: |
-          cd docs
-          VERSION=${STEPS_LATEST_OUTPUTS_VERSION} ./bin/import-regal-docs.sh
-        env:
-          STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }}
-
-      - name: Check for changes
-        if: steps.check.outputs.needed == 'true'
-        id: changes
-        run: |
-          if git diff --quiet; then
-            echo "No changes detected after import"
-            echo "has_changes=false" >> $GITHUB_OUTPUT
-          else
-            echo "Changes detected"
-            echo "has_changes=true" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Configure git
-        if: steps.check.outputs.needed == 'true' && steps.changes.outputs.has_changes == 'true'
-        run: |
-          git config user.name "opa-docs-bot"
-          git config user.email "opa-docs-bot@openpolicyagent.org"
-
-      - name: Create branch and commit
-        if: steps.check.outputs.needed == 'true' && steps.changes.outputs.has_changes == 'true'
-        run: |
-          BRANCH_NAME="update-regal-${STEPS_LATEST_OUTPUTS_VERSION}"
-          git checkout -b "$BRANCH_NAME"
-          git add -A
-          git commit -s -m "docs: Update Regal docs to ${STEPS_LATEST_OUTPUTS_VERSION}"
-        env:
-          STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }}
-
-      - name: Push branch
-        if: steps.check.outputs.needed == 'true' && steps.changes.outputs.has_changes == 'true'
-        run: |
-          BRANCH_NAME="update-regal-${STEPS_LATEST_OUTPUTS_VERSION}"
-          git push origin "$BRANCH_NAME"
-        env:
-          STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }}
-
-      - name: Create pull request
-        if: steps.check.outputs.needed == 'true' && steps.changes.outputs.has_changes == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GH_PUSH_TOKEN }} # zizmor: ignore[secrets-outside-env]
-          STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }}
-        run: |
-          VERSION="${STEPS_LATEST_OUTPUTS_VERSION}"
-          gh pr create \
-            --title "docs: Update Regal docs to $VERSION" \
-            --body "$(cat <<EOF
-          This PR updates the Regal documentation to $VERSION.
-          EOF
-          )" \
-            --reviewer charlieegan3,anderseknert

docs/imported.json

@@ -1,3 +1,3 @@
 {
-  "regal": "foobar"
+  "regal": "v0.40.0"
 }

docs/projects/regal/adopters.md

@@ -44,8 +44,9 @@ Public open source projects integrating Regal for linting in their CI/CD pipelin
 Projects and products that integrate Regal into their offerings.
 
 <!-- cspell:disable -->
+- [Code Rabbit](https://docs.coderabbit.ai/tools/regal)
 - [Dependency Management Data](https://gitlab.com/tanna.dev/dependency-management-data)
-- [Enterprise OPA](https://github.com/styrainc/enterprise-opa)
+- [EOPA](https://github.com/open-policy-agent/eopa)
 - [The Rego Playground](https://play.openpolicyagent.org)
 - [Trunk Check](https://trunk.io/)
 - [reviewdog/action-regal](https://github.com/reviewdog/action-regal)
@@ -83,7 +84,6 @@ Some companies and organizations using Regal.
 - [Red Hat](https://www.redhat.com)
 - [Spacelift](https://www.spacelift.io)
 - [Stacklok](https://stacklok.com)
-- [Styra](https://www.styra.com)
 - [UNIwise](https://uniwise.eu/)
 - [VodafoneZiggo](https://www.vodafoneziggo.nl)
 <!-- cspell:enable-->

docs/projects/regal/cicd.md

@@ -28,8 +28,8 @@ jobs:
   lint-rego:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
-    - uses: open-policy-agent/setup-regal@v1
+    - uses: open-policy-agent/setup-regal@v2
       with:
         # For production workflows, use a specific version, like v0.22.0
         version: latest

docs/projects/regal/configuration/capabilities.md

@@ -52,18 +52,18 @@ capabilities:
     version: v0.58.0
   minus:
     builtins:
-    # exclude rules that depend on the http.send built-in function
+      # exclude rules that depend on the http.send built-in function
-    - name: http.send
+      - name: http.send
   plus:
     builtins:
-    # make Regal aware of a custom "ldap.query" function
+      # make Regal aware of a custom "ldap.query" function
-    - name: ldap.query
+      - name: ldap.query
-      type: function
+        type: function
-      decl:
+        decl:
-        args:
+          args:
-        - type: string
+            - type: string
-      result:
+        result:
-        type: object
+          type: object
 ```
 
 ## Loading Capabilities from URLs
@@ -82,10 +82,10 @@ capabilities:
 
 Regal includes capabilities files for the following engines:
 
-| Engine | Website                                                         | Description          |
+| Engine | Website                                                      | Description       |
-| ------ | --------------------------------------------------------------- | -------------------- |
+| ------ | ------------------------------------------------------------ | ----------------- |
-| `opa`  | [OPA website](https://www.openpolicyagent.org/)                 | Open Policy Agent    |
+| `opa`  | [OPA website](https://www.openpolicyagent.org/)              | Open Policy Agent |
-| `eopa` | [Enterprise OPA website](https://www.styra.com/enterprise-opa/) | Styra Enterprise OPA |
+| `eopa` | [EOPA repository](https://github.com/open-policy-agent/eopa) | EOPA              |
-| `rq`   | [rq website](https://git.sr.ht/~charles/rq)                     | Rego Query (`rq`)    |
+| `rq`   | [rq website](https://git.sr.ht/~charles/rq)                  | Rego Query (`rq`) |
 
 **`rq` support note**: `rq` scripts must include `package` statements to be compatible with Regal.

docs/projects/regal/rules/bugs/import-shadows-rule.md

@@ -5,18 +5,20 @@
 **Category**: Bugs
 
 **Avoid**
+
 ```rego
 package policy
 
 import data.resources
 
-# 'resources' shadowed by import 
+# 'resources' shadowed by import
 resources contains resource if {
     # ...
 }
 ```
 
 **Prefer**
+
 ```rego
 package policy
 
@@ -56,3 +58,7 @@ rules:
       # one of "error", "warning", "ignore"
       level: error
 ```
+
+## Related Resources
+
+- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/bugs/import-shadows-rule/import_shadows_rule.rego)

docs/projects/regal/rules/bugs/invalid-regexp.md

@@ -0,0 +1,46 @@
+# invalid-regexp
+
+**Summary**: Invalid regular expression
+
+**Category**: Bugs
+
+**Avoid**
+
+```rego
+package policy
+
+invalid if regex.match(`[abc`, input.text)
+```
+
+**Prefer**
+
+```rego
+package policy
+
+valid if regex.match(`[abc]`, input.text)
+```
+
+## Rationale
+
+An invalid regular expression typically fails silently (i.e. the result is undefined) at runtime when OPA evaluates the
+function call, or with a runtime error if the `show-builtin-errors` option is enabled. While hopefully caught by unit
+tests, tracking down a typo in a regular expression is still time consuming. This rule instead analyzes any regular
+expressions found in a policy as you author it (using OPA's own `regex.is_valid` function) and reports invalid patterns
+directly.
+
+## Configuration Options
+
+This linter rule provides the following configuration options:
+
+```yaml
+rules:
+  bugs:
+    invalid-regexp:
+      # one of "error", "warning", "ignore"
+      level: error
+```
+
+## Related Resources
+
+- OPA Docs: [Regex Functions](https://www.openpolicyagent.org/docs/latest/policy-reference/#regex-functions)
+- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/bugs/invalid-regexp/invalid_regexp.rego)

docs/projects/regal/rules/bugs/redundant-loop-count.md

@@ -5,6 +5,7 @@
 **Category**: Bugs
 
 **Avoid**
+
 ```rego
 package policy
 
@@ -17,6 +18,7 @@ allow if {
 ```
 
 **Prefer**
+
 ```rego
 package policy
 
@@ -80,3 +82,7 @@ rules:
       # one of "error", "warning", "ignore"
       level: error
 ```
+
+## Related Resources
+
+- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/bugs/redundant-loop-count/redundant_loop_count.rego)

docs/projects/regal/rules/custom/naming-convention.md

@@ -32,18 +32,27 @@ rules:
       # one of "error", "warning", "ignore"
       level: error
       conventions:
-          # allow only "private" rules and functions, i.e. those starting with
+        # allow only "private" rules and functions, i.e. those starting with
-          # underscore, or rules named "deny" or "allow"
+        # underscore, or rules named "deny" or "allow"
-        - pattern: '^_[a-z]+$|^deny$|^allow$'
+        - pattern: "^_[a-z]+$|^deny$|^allow$"
           # one of "package", "rule", "function", "variable"
           targets:
             - rule
             - function
         # any number of naming rules may be added
         # package names must start with "acmecorp" or "system"
-        - pattern: '^acmecorp|^system'
+        - pattern: "^acmecorp|^system"
           targets:
             - package
+        # a list of names may be provided in addition to a pattern
+        # if both a pattern and a list of names are provided, identifiers
+        # must match either the pattern or one of the names in the list
+        - names:
+            - i
+            - j
+            - k
+          targets:
+            - var
 ```
 
 **Note:** In order to avoid characters accidentally getting escaped, always use single quotes to encode your regex

docs/projects/regal/rules/idiomatic/superfluous-object-get.md

@@ -0,0 +1,47 @@
+# superfluous-object-get
+
+**Summary**: Superfluous `object.get` call
+
+**Category**: Idiomatic
+
+**Avoid**
+
+```rego
+package policy
+
+allow if {
+    object.get(input, ["path", "to", "value"], "default") == "expected"
+}
+```
+
+**Prefer**
+
+```rego
+package policy
+
+allow if {
+    input.path.to.value == "expected"
+}
+```
+
+## Rationale
+
+The `object.get` function is sometimes used to guard against undefined references halting evaluation. Immediately
+comparing the result of the call to a constant value that isn't the same as the default is however superfluous, as
+the expression will evaluate the same without using `object.get`. In such cases the call can simply be removed.
+
+## Configuration Options
+
+This linter rule provides the following configuration options:
+
+```yaml
+rules:
+  idiomatic:
+    superfluous-object-get:
+      # one of "error", "warning", "ignore"
+      level: error
+```
+
+## Related Resources
+
+- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/idiomatic/superfluous-object-get/superfluous_object_get.rego)

docs/projects/regal/rules/imports/confusing-alias.md

@@ -5,6 +5,7 @@
 **Category**: Imports
 
 **Avoid**
+
 ```rego
 package policy
 
@@ -14,6 +15,7 @@ import data.resources.users as employees
 ```
 
 **Prefer**
+
 ```rego
 package policy
 
@@ -50,3 +52,7 @@ rules:
       # one of "error", "warning", "ignore"
       level: error
 ```
+
+## Related Resources
+
+- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/imports/confusing-alias/confusing_alias.rego)

docs/projects/regal/rules/imports/pointless-import.md

@@ -5,6 +5,7 @@
 **Category**: Imports
 
 **Avoid**
+
 ```rego
 package policy
 
@@ -20,6 +21,7 @@ rule if {
 ```
 
 **Prefer**
+
 ```rego
 package policy
 ```
@@ -40,3 +42,7 @@ rules:
       # one of "error", "warning", "ignore"
       level: error
 ```
+
+## Related Resources
+
+- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/imports/pointless-import/pointless_import.rego)