fix: exclude standalone examples from mise run format

.mise/tasks/lint/example-poms.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+
+# [MISE] description="Verify standalone example POMs won't break spotless"
+
+"""Check that standalone example modules don't break 'mise run format'.
+
+Example modules are intentionally standalone (no <parent> from the project)
+so users can copy them. But they're included in the Maven reactor via the
+examples-and-integration-tests profile. If 'mise run format' doesn't
+exclude them, spotless:apply fails because the plugin isn't declared.
+
+This lint verifies that every standalone example POM is excluded from
+the format task in mise.toml.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[3]
+EXAMPLES_DIR = ROOT / "examples"
+
+
+def find_standalone_example_poms() -> list[Path]:
+    """Find example pom.xml files that don't inherit from the project parent."""
+    standalone = []
+    for pom in sorted(EXAMPLES_DIR.rglob("pom.xml")):
+        if "target" in pom.parts:
+            continue
+        text = pom.read_text(encoding="utf-8")
+        # Check if this POM has a <parent> with the project's groupId/artifactId
+        has_project_parent = bool(
+            re.search(
+                r"<parent>\s*<groupId>io\.prometheus</groupId>\s*"
+                r"<artifactId>client_java</artifactId>",
+                text,
+            )
+        )
+        if not has_project_parent:
+            standalone.append(pom)
+    return standalone
+
+
+def format_task_excludes_examples() -> bool:
+    """Check that the format task in mise.toml excludes standalone examples."""
+    mise_toml = ROOT / "mise.toml"
+    text = mise_toml.read_text(encoding="utf-8")
+    # Look for the format task run command
+    match = re.search(r'\[tasks\.format\].*?run\s*=\s*"([^"]*)"', text, re.DOTALL)
+    if not match:
+        return False
+    run_cmd = match.group(1)
+    # The command should deactivate the examples-and-integration-tests profile
+    return "!examples-and-integration-tests" in run_cmd
+
+
+def main() -> int:
+    standalone = find_standalone_example_poms()
+    if not standalone:
+        return 0
+
+    if format_task_excludes_examples():
+        return 0
+
+    print("ERROR: Standalone example POMs found but 'mise run format'")
+    print("does not exclude the examples-and-integration-tests profile.")
+    print()
+    print("Standalone example POMs (no project parent):")
+    for pom in standalone:
+        print(f"  {pom.relative_to(ROOT)}")
+    print()
+    print("Fix: ensure the format task in mise.toml deactivates the")
+    print("examples-and-integration-tests profile, e.g.:")
+    print("  -P '!examples-and-integration-tests'")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AGENTS.md

@@ -23,7 +23,6 @@ mise run test-all
 
 # Format code with Google Java Format
 mise run format
-# or directly: ./mvnw spotless:apply
 
 # Run a single test class
 ./mvnw test -Dtest=CounterTest \
@@ -143,6 +142,12 @@ mise run lint
 # or to autofix: mise run fix
 ```
 
+### Before Pushing
+
+**ALWAYS** run `mise run lint` before pushing to verify
+all lints pass. CI runs the same checks and will fail
+if any lint is violated.
+
 ## Testing
 
 - JUnit 5 (Jupiter) with `@Test` annotations

mise.toml

@@ -20,7 +20,9 @@ env.PROTO_GENERATION = "true"
 
 [tasks.format]
 description = "format source code"
-run = "./mvnw spotless:apply"
+# Use fully-qualified plugin goal and deactivate the examples-and-integration-tests
+# profile because standalone example modules don't inherit the spotless plugin.
+run = "./mvnw com.diffplug.spotless:spotless-maven-plugin:apply -P '!examples-and-integration-tests'"
 
 [tasks.clean]
 description = "clean all modules"
@@ -65,7 +67,7 @@ file = "https://raw.githubusercontent.com/grafana/flint/0ac131d7832bd8964f6ca9e5
 
 [tasks."lint"]
 description = "Run all lints"
-depends = ["lint:super-linter", "lint:links", "lint:bom", "lint:renovate-deps"]
+depends = ["lint:super-linter", "lint:links", "lint:bom", "lint:example-poms", "lint:renovate-deps"]
 
 [tasks.fix]
 description = "Auto-fix lint issues"