@oddessentials/repo-standards 1.2.1 → 2.0.0

package/README.md

@@ -101,7 +101,7 @@ Each checklist item includes:
 The `version` field indicates schema compatibility:
 
 - `1` — Original schema
-- `2` — Adds `anyOfFiles` and `pinningNotes` fields (additive, non-breaking)
+- `2` — Adds `bazelHints`, `meta.bazelIntegration` for Bazel support, `anyOfFiles`, `pinningNotes`
 
 Consumers should ignore unknown fields for forward compatibility.
 
@@ -144,6 +144,84 @@ Required secrets:
 
 ---
 
+## Bazel Integration
+
+This framework supports Bazel as an **optional build executor** for quality checks.
+
+### Key Concepts
+
+- **Bazel is optional** — Stack-native commands (npm, cargo, etc.) remain the default
+- **Hints are advisory** — `bazelHints` are suggestions, not required execution paths
+- **Commands are illustrative** — Actual Bazel commands are repo-defined; examples show patterns only
+- **Detection is root-level** — Only `MODULE.bazel` / `WORKSPACE*` at repo root triggers Bazel mode
+
+### Detection Rules
+
+Repos are detected as Bazel-managed if the **repository root** contains:
+
+1. `MODULE.bazel` (bzlmod, preferred)
+2. `WORKSPACE.bazel` or `WORKSPACE` (legacy)
+
+Optional markers: `.bazelrc`, `.bazelversion`
+
+> Nested `BUILD.bazel` files (e.g., from vendored deps) do NOT trigger Bazel detection.
+
+### Bazel Commands (Not Assumed Targets)
+
+The `bazelHints.commands` field contains **actual commands to run**:
+
+| Check        | Stack-native           | Bazel Command                    |
+| ------------ | ---------------------- | -------------------------------- |
+| Lint         | `npm run lint`         | `bazel test //... --aspects=...` |
+| Format Check | `npm run format:check` | `bazel run //tools/format:check` |
+| Type Check   | `npm run typecheck`    | `bazel build //...`              |
+| Test         | `npm test`             | `bazel test //...`               |
+| Coverage     | `npm run coverage`     | `bazel coverage //...`           |
+
+> **Note**: Bazel commands shown are **illustrative patterns**. Actual targets (e.g., `//tools/lint:lint`, `//...:format_test`) are repo-defined and may not exist without explicit Bazel setup. `bazelHints` are advisory—consumers should prefer stack-native commands unless explicitly adopting Bazel.
+
+### Minimal `.bazelrc` for CI
+
+```bazelrc
+# .bazelrc
+build:ci --nokeep_going
+build:ci --test_output=errors
+```
+
+### Example GitHub Actions
+
+```yaml
+- uses: bazel-contrib/setup-bazel@0.14.0
+  with:
+    bazelisk-cache: true
+
+- run: bazel test //... --config=ci
+```
+
+### Example Azure DevOps
+
+```yaml
+- script: |
+    curl -Lo bazelisk https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64
+    chmod +x bazelisk && mv bazelisk /usr/local/bin/bazel
+  displayName: "Install Bazelisk"
+
+- script: bazel test //... --config=ci
+  displayName: "Run Bazel Tests"
+```
+
+> Remote cache is optional and not required for basic CI.
+
+### Opt-Out
+
+To disable Bazel hints for a repo that contains Bazel files but uses npm for quality checks:
+
+```json
+{ "meta": { "bazelIntegration": { "enabled": false } } }
+```
+
+---
+
 ## Generating Stack-Specific JSON
 
 The generator reads the master spec and produces filtered, deterministic outputs.

package/dist/config/standards.csharp-dotnet.azure-devops.json

@@ -35,6 +35,12 @@
         "id": "linting",
         "label": "Linting",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //... --aspects=@rules_dotnet//dotnet:analyzers.bzl%analyzer_aspect"
+            ],
+            "notes": "Use rules_dotnet analyzer aspects for Roslyn-based linting in Bazel."
+          },
           "exampleConfigFiles": [
             ".editorconfig",
             "Directory.Build.props"
@@ -66,6 +72,12 @@
         "id": "unit-test-runner",
         "label": "Unit Test Runner",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel test //..."
+            ],
+            "notes": "Use rules_dotnet to define test targets for xUnit/NUnit/MSTest projects."
+          },
           "exampleConfigFiles": [
             "*.Tests.csproj"
           ],
@@ -160,6 +172,12 @@
         "id": "unit-test-reporter",
         "label": "Unit Test Reporter / Coverage",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel coverage //..."
+            ],
+            "notes": "Use rules_dotnet with coverage instrumentation enabled."
+          },
           "exampleConfigFiles": [
             "*.csproj"
           ],
@@ -181,6 +199,13 @@
         "id": "ci-quality-gates",
         "label": "CI Quality Gates",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //...",
+              "bazel test //..."
+            ],
+            "notes": "Bazel handles all analysis, testing, and packaging via defined targets."
+          },
           "exampleConfigFiles": [
             ".github/workflows/*",
             "azure-pipelines.yml"
@@ -200,6 +225,12 @@
         "id": "code-formatter",
         "label": "Code Formatter",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel run //tools/format:dotnet_format -- --verify-no-changes"
+            ],
+            "notes": "Wrap dotnet format as a Bazel run target."
+          },
           "exampleConfigFiles": [
             ".editorconfig"
           ],
@@ -240,6 +271,12 @@
         "id": "type-checking",
         "label": "Type Checking",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //..."
+            ],
+            "notes": "C# type errors surface during bazel build with rules_dotnet. No separate typecheck step needed."
+          },
           "exampleConfigFiles": [
             ".editorconfig",
             "Directory.Build.props",
@@ -530,6 +567,43 @@
     "azure-devops"
   ],
   "meta": {
+    "bazelIntegration": {
+      "advisoryNotice": "bazelHints are suggestions, not required execution paths. Consumers should prefer stack-native commands unless explicitly adopting Bazel.",
+      "ciContract": {
+        "configFlag": "--config=ci (define in .bazelrc)",
+        "deterministicFlags": [
+          "--nokeep_going",
+          "--test_output=errors"
+        ],
+        "remoteCache": "Optional; not required for CI",
+        "versionPinning": "Use .bazelversion file for Bazelisk"
+      },
+      "description": "Bazel build executor support for quality checks. All hints are ADVISORY—stack-native commands remain the default execution path.",
+      "detectionRules": {
+        "notes": "Detection uses repo-root markers only. Nested BUILD files do not trigger Bazel mode.",
+        "optionalMarkers": [
+          ".bazelrc",
+          ".bazelversion"
+        ],
+        "rootMarkers": [
+          "MODULE.bazel",
+          "WORKSPACE.bazel",
+          "WORKSPACE"
+        ]
+      },
+      "optOut": {
+        "configPath": "meta.bazelIntegration.enabled",
+        "description": "Set meta.bazelIntegration.enabled = false in repo config to disable Bazel hints"
+      },
+      "targetConventions": {
+        "build": "bazel build //...",
+        "coverage": "bazel coverage //...",
+        "description": "Recommended target naming (not assumed to exist). These are illustrative patterns; actual targets are repo-defined.",
+        "format": "bazel run //tools/format:check",
+        "lint": "//tools/lint:lint or bazel test //... with lint aspects",
+        "test": "bazel test //..."
+      }
+    },
     "complexityChecks": {
       "description": "When supported by the stack, run cyclomatic complexity or similar metrics in CI as a warning-only check initially.",
       "enabledByDefault": true

package/dist/config/standards.csharp-dotnet.github-actions.json

@@ -35,6 +35,12 @@
         "id": "linting",
         "label": "Linting",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //... --aspects=@rules_dotnet//dotnet:analyzers.bzl%analyzer_aspect"
+            ],
+            "notes": "Use rules_dotnet analyzer aspects for Roslyn-based linting in Bazel."
+          },
           "exampleConfigFiles": [
             ".editorconfig",
             "Directory.Build.props"
@@ -66,6 +72,12 @@
         "id": "unit-test-runner",
         "label": "Unit Test Runner",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel test //..."
+            ],
+            "notes": "Use rules_dotnet to define test targets for xUnit/NUnit/MSTest projects."
+          },
           "exampleConfigFiles": [
             "*.Tests.csproj"
           ],
@@ -160,6 +172,12 @@
         "id": "unit-test-reporter",
         "label": "Unit Test Reporter / Coverage",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel coverage //..."
+            ],
+            "notes": "Use rules_dotnet with coverage instrumentation enabled."
+          },
           "exampleConfigFiles": [
             "*.csproj"
           ],
@@ -181,6 +199,13 @@
         "id": "ci-quality-gates",
         "label": "CI Quality Gates",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //...",
+              "bazel test //..."
+            ],
+            "notes": "Bazel handles all analysis, testing, and packaging via defined targets."
+          },
           "exampleConfigFiles": [
             ".github/workflows/*",
             "azure-pipelines.yml"
@@ -200,6 +225,12 @@
         "id": "code-formatter",
         "label": "Code Formatter",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel run //tools/format:dotnet_format -- --verify-no-changes"
+            ],
+            "notes": "Wrap dotnet format as a Bazel run target."
+          },
           "exampleConfigFiles": [
             ".editorconfig"
           ],
@@ -240,6 +271,12 @@
         "id": "type-checking",
         "label": "Type Checking",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //..."
+            ],
+            "notes": "C# type errors surface during bazel build with rules_dotnet. No separate typecheck step needed."
+          },
           "exampleConfigFiles": [
             ".editorconfig",
             "Directory.Build.props",
@@ -530,6 +567,43 @@
     "github-actions"
   ],
   "meta": {
+    "bazelIntegration": {
+      "advisoryNotice": "bazelHints are suggestions, not required execution paths. Consumers should prefer stack-native commands unless explicitly adopting Bazel.",
+      "ciContract": {
+        "configFlag": "--config=ci (define in .bazelrc)",
+        "deterministicFlags": [
+          "--nokeep_going",
+          "--test_output=errors"
+        ],
+        "remoteCache": "Optional; not required for CI",
+        "versionPinning": "Use .bazelversion file for Bazelisk"
+      },
+      "description": "Bazel build executor support for quality checks. All hints are ADVISORY—stack-native commands remain the default execution path.",
+      "detectionRules": {
+        "notes": "Detection uses repo-root markers only. Nested BUILD files do not trigger Bazel mode.",
+        "optionalMarkers": [
+          ".bazelrc",
+          ".bazelversion"
+        ],
+        "rootMarkers": [
+          "MODULE.bazel",
+          "WORKSPACE.bazel",
+          "WORKSPACE"
+        ]
+      },
+      "optOut": {
+        "configPath": "meta.bazelIntegration.enabled",
+        "description": "Set meta.bazelIntegration.enabled = false in repo config to disable Bazel hints"
+      },
+      "targetConventions": {
+        "build": "bazel build //...",
+        "coverage": "bazel coverage //...",
+        "description": "Recommended target naming (not assumed to exist). These are illustrative patterns; actual targets are repo-defined.",
+        "format": "bazel run //tools/format:check",
+        "lint": "//tools/lint:lint or bazel test //... with lint aspects",
+        "test": "bazel test //..."
+      }
+    },
     "complexityChecks": {
       "description": "When supported by the stack, run cyclomatic complexity or similar metrics in CI as a warning-only check initially.",
       "enabledByDefault": true

package/dist/config/standards.csharp-dotnet.json

@@ -41,6 +41,12 @@
         "id": "linting",
         "label": "Linting",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //... --aspects=@rules_dotnet//dotnet:analyzers.bzl%analyzer_aspect"
+            ],
+            "notes": "Use rules_dotnet analyzer aspects for Roslyn-based linting in Bazel."
+          },
           "exampleConfigFiles": [
             ".editorconfig",
             "Directory.Build.props"
@@ -75,6 +81,12 @@
         "id": "unit-test-runner",
         "label": "Unit Test Runner",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel test //..."
+            ],
+            "notes": "Use rules_dotnet to define test targets for xUnit/NUnit/MSTest projects."
+          },
           "exampleConfigFiles": [
             "*.Tests.csproj"
           ],
@@ -181,6 +193,12 @@
         "id": "unit-test-reporter",
         "label": "Unit Test Reporter / Coverage",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel coverage //..."
+            ],
+            "notes": "Use rules_dotnet with coverage instrumentation enabled."
+          },
           "exampleConfigFiles": [
             "*.csproj"
           ],
@@ -205,6 +223,13 @@
         "id": "ci-quality-gates",
         "label": "CI Quality Gates",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //...",
+              "bazel test //..."
+            ],
+            "notes": "Bazel handles all analysis, testing, and packaging via defined targets."
+          },
           "exampleConfigFiles": [
             ".github/workflows/*",
             "azure-pipelines.yml"
@@ -227,6 +252,12 @@
         "id": "code-formatter",
         "label": "Code Formatter",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel run //tools/format:dotnet_format -- --verify-no-changes"
+            ],
+            "notes": "Wrap dotnet format as a Bazel run target."
+          },
           "exampleConfigFiles": [
             ".editorconfig"
           ],
@@ -273,6 +304,12 @@
         "id": "type-checking",
         "label": "Type Checking",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //..."
+            ],
+            "notes": "C# type errors surface during bazel build with rules_dotnet. No separate typecheck step needed."
+          },
           "exampleConfigFiles": [
             ".editorconfig",
             "Directory.Build.props",
@@ -599,6 +636,43 @@
     "github-actions"
   ],
   "meta": {
+    "bazelIntegration": {
+      "advisoryNotice": "bazelHints are suggestions, not required execution paths. Consumers should prefer stack-native commands unless explicitly adopting Bazel.",
+      "ciContract": {
+        "configFlag": "--config=ci (define in .bazelrc)",
+        "deterministicFlags": [
+          "--nokeep_going",
+          "--test_output=errors"
+        ],
+        "remoteCache": "Optional; not required for CI",
+        "versionPinning": "Use .bazelversion file for Bazelisk"
+      },
+      "description": "Bazel build executor support for quality checks. All hints are ADVISORY—stack-native commands remain the default execution path.",
+      "detectionRules": {
+        "notes": "Detection uses repo-root markers only. Nested BUILD files do not trigger Bazel mode.",
+        "optionalMarkers": [
+          ".bazelrc",
+          ".bazelversion"
+        ],
+        "rootMarkers": [
+          "MODULE.bazel",
+          "WORKSPACE.bazel",
+          "WORKSPACE"
+        ]
+      },
+      "optOut": {
+        "configPath": "meta.bazelIntegration.enabled",
+        "description": "Set meta.bazelIntegration.enabled = false in repo config to disable Bazel hints"
+      },
+      "targetConventions": {
+        "build": "bazel build //...",
+        "coverage": "bazel coverage //...",
+        "description": "Recommended target naming (not assumed to exist). These are illustrative patterns; actual targets are repo-defined.",
+        "format": "bazel run //tools/format:check",
+        "lint": "//tools/lint:lint or bazel test //... with lint aspects",
+        "test": "bazel test //..."
+      }
+    },
     "complexityChecks": {
       "description": "When supported by the stack, run cyclomatic complexity or similar metrics in CI as a warning-only check initially.",
       "enabledByDefault": true

package/dist/config/standards.go.azure-devops.json

@@ -35,6 +35,12 @@
         "id": "linting",
         "label": "Linting",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel test //... --@io_bazel_rules_go//go/config:nogo=@//:nogo"
+            ],
+            "notes": "Use nogo for static analysis via rules_go. Configure nogo target with desired analyzers."
+          },
           "exampleConfigFiles": [
             ".golangci.yml",
             ".golangci.yaml"
@@ -64,6 +70,12 @@
         "id": "unit-test-runner",
         "label": "Unit Test Runner",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel test //..."
+            ],
+            "notes": "rules_go go_test targets wrap 'go test' with Bazel's caching and hermeticity."
+          },
           "exampleConfigFiles": [
             "go.mod"
           ],
@@ -157,6 +169,12 @@
         "id": "unit-test-reporter",
         "label": "Unit Test Reporter / Coverage",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel coverage //..."
+            ],
+            "notes": "rules_go supports coverage via bazel coverage. Use --combined_report=lcov for aggregated output."
+          },
           "exampleConfigFiles": [
             "go.mod"
           ],
@@ -178,6 +196,13 @@
         "id": "ci-quality-gates",
         "label": "CI Quality Gates",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //...",
+              "bazel test //..."
+            ],
+            "notes": "rules_go go_binary and go_test targets provide hermetic builds and tests."
+          },
           "exampleConfigFiles": [
             ".github/workflows/*",
             "azure-pipelines.yml"
@@ -197,6 +222,12 @@
         "id": "code-formatter",
         "label": "Code Formatter",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel run @go_sdk//:bin/gofmt -- -d ."
+            ],
+            "notes": "Run gofmt via the Bazel-managed Go SDK for hermetic formatting checks."
+          },
           "exampleConfigFiles": [],
           "exampleTools": [
             "gofmt",
@@ -238,6 +269,12 @@
         "id": "type-checking",
         "label": "Type Checking",
         "stack": {
+          "bazelHints": {
+            "commands": [
+              "bazel build //..."
+            ],
+            "notes": "Go type checking is inherent to compilation. bazel build with rules_go enforces type safety."
+          },
           "exampleConfigFiles": [
             "go.mod"
           ],
@@ -515,6 +552,43 @@
     "azure-devops"
   ],
   "meta": {
+    "bazelIntegration": {
+      "advisoryNotice": "bazelHints are suggestions, not required execution paths. Consumers should prefer stack-native commands unless explicitly adopting Bazel.",
+      "ciContract": {
+        "configFlag": "--config=ci (define in .bazelrc)",
+        "deterministicFlags": [
+          "--nokeep_going",
+          "--test_output=errors"
+        ],
+        "remoteCache": "Optional; not required for CI",
+        "versionPinning": "Use .bazelversion file for Bazelisk"
+      },
+      "description": "Bazel build executor support for quality checks. All hints are ADVISORY—stack-native commands remain the default execution path.",
+      "detectionRules": {
+        "notes": "Detection uses repo-root markers only. Nested BUILD files do not trigger Bazel mode.",
+        "optionalMarkers": [
+          ".bazelrc",
+          ".bazelversion"
+        ],
+        "rootMarkers": [
+          "MODULE.bazel",
+          "WORKSPACE.bazel",
+          "WORKSPACE"
+        ]
+      },
+      "optOut": {
+        "configPath": "meta.bazelIntegration.enabled",
+        "description": "Set meta.bazelIntegration.enabled = false in repo config to disable Bazel hints"
+      },
+      "targetConventions": {
+        "build": "bazel build //...",
+        "coverage": "bazel coverage //...",
+        "description": "Recommended target naming (not assumed to exist). These are illustrative patterns; actual targets are repo-defined.",
+        "format": "bazel run //tools/format:check",
+        "lint": "//tools/lint:lint or bazel test //... with lint aspects",
+        "test": "bazel test //..."
+      }
+    },
     "complexityChecks": {
       "description": "When supported by the stack, run cyclomatic complexity or similar metrics in CI as a warning-only check initially.",
       "enabledByDefault": true