agentlint 2.2.1__tar.gz → 2.3.0__tar.gz

{agentlint-2.2.1 → agentlint-2.3.0}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v2.3.0 (2026-05-14) — CI Signal Polish
+
+This release applies real-world Codex and AgentLint dogfooding feedback. It
+keeps CI adoption safe by preserving INFO-as-non-blocking behavior while
+reducing repeated output and avoiding framework-convention false positives.
+
+### Changed
+
+- `no-unnecessary-async` is now FastAPI-aware and skips route handlers such as
+  `@router.get(...)` and `@app.post(...)` by default.
+- `agentlint ci --format text` now groups repeated findings by file, rule, and
+  severity while leaving JSON output unchanged.
+- Added per-rule `ignore_paths` as an accepted-pattern alias for documented
+  local conventions.
+- Documented `ignore_fastapi_routes`, per-rule `ignore_paths`, and `reason`
+  examples in the sample config and README.
+
+### Compatibility
+
+- INFO findings still do not fail CI by default.
+- Teams that want strict async-route checks can set
+  `rules.no-unnecessary-async.ignore_fastapi_routes: false`.
+- Existing `allow_paths` behavior is unchanged.
+
+---
+
 ## v2.2.1 (2026-05-10) — Install Experience Polish
 
 This release removes the last extra-step surprise from AgentChute setup.

{agentlint-2.2.1 → agentlint-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentlint
-Version: 2.2.1
+Version: 2.3.0
 Summary: Real-time quality guardrails for AI coding agents
 Project-URL: Homepage, https://github.com/mauhpr/agentlint
 Project-URL: Repository, https://github.com/mauhpr/agentlint
@@ -62,7 +62,7 @@ We don't have a mature answer to that yet. Nobody does. The **autopilot pack** i
 
 AgentLint ships with 76 rules across 8 packs and normalizes tool events across supported AI coding agents. The 23 **universal** rules and 7 **quality** rules work with any tech stack; 4 additional packs auto-activate based on your project files; the **security** pack is opt-in; and the **autopilot** pack is opt-in and experimental.
 
-**v2.2.1 highlights:** Install experience polish with `agentlint --version` and AgentChute sync support from the default `pip install agentlint` package. Previous: Public documentation cleanup, AgentChute-ready team sync, hybrid cloud feeds, privacy-safe event queueing, multi-platform adapter architecture, unified `AgentEvent` taxonomy, `NormalizedTool` cross-platform mappings, session summary dashboard, MCP server, global config defaults, warning suppression, auto-suppress, `diff_only` mode, and `auto-fix` mode.
+**v2.3.0 highlights:** Codex dogfooding polish with FastAPI-aware `no-unnecessary-async`, grouped text CI findings, and repo-local accepted patterns through per-rule `ignore_paths`. Previous: Install experience polish, `agentlint --version`, AgentChute sync support from the default `pip install agentlint` package, public documentation cleanup, AgentChute-ready team sync, hybrid cloud feeds, privacy-safe event queueing, multi-platform adapter architecture, unified `AgentEvent` taxonomy, `NormalizedTool` cross-platform mappings, session summary dashboard, MCP server, global config defaults, warning suppression, auto-suppress, `diff_only` mode, and `auto-fix` mode.
 
 | Rule | Severity | What it does |
 |------|----------|-------------|
@@ -116,7 +116,7 @@ AgentLint ships with 76 rules across 8 packs and normalizes tool events across s
 | `no-unsafe-shell` | ERROR | Blocks unsafe shell execution via subprocess or os module |
 | `no-dangerous-migration` | WARNING | Warns on risky Alembic migration operations |
 | `no-wildcard-import` | WARNING | Prevents `from module import *` |
-| `no-unnecessary-async` | INFO | Flags async functions that never use `await` |
+| `no-unnecessary-async` | INFO | Flags async functions that never use `await`; skips FastAPI route handlers by default |
 | `no-sql-injection` | ERROR | Blocks SQL via string interpolation (f-strings, `.format()`) |
 
 </details>
@@ -194,6 +194,16 @@ rules:
 
 </details>
 
+Per-rule accepted patterns can be documented locally:
+
+```yaml
+rules:
+  no-unnecessary-async:
+    ignore_paths:
+      - "app/api/*_routes.py"
+    reason: "FastAPI route consistency"
+```
+
 <details>
 <summary><strong>Autopilot pack</strong> (18 rules) — ⚠️ experimental, opt-in</summary>
 

{agentlint-2.2.1 → agentlint-2.3.0}/README.md

@@ -26,7 +26,7 @@ We don't have a mature answer to that yet. Nobody does. The **autopilot pack** i
 
 AgentLint ships with 76 rules across 8 packs and normalizes tool events across supported AI coding agents. The 23 **universal** rules and 7 **quality** rules work with any tech stack; 4 additional packs auto-activate based on your project files; the **security** pack is opt-in; and the **autopilot** pack is opt-in and experimental.
 
-**v2.2.1 highlights:** Install experience polish with `agentlint --version` and AgentChute sync support from the default `pip install agentlint` package. Previous: Public documentation cleanup, AgentChute-ready team sync, hybrid cloud feeds, privacy-safe event queueing, multi-platform adapter architecture, unified `AgentEvent` taxonomy, `NormalizedTool` cross-platform mappings, session summary dashboard, MCP server, global config defaults, warning suppression, auto-suppress, `diff_only` mode, and `auto-fix` mode.
+**v2.3.0 highlights:** Codex dogfooding polish with FastAPI-aware `no-unnecessary-async`, grouped text CI findings, and repo-local accepted patterns through per-rule `ignore_paths`. Previous: Install experience polish, `agentlint --version`, AgentChute sync support from the default `pip install agentlint` package, public documentation cleanup, AgentChute-ready team sync, hybrid cloud feeds, privacy-safe event queueing, multi-platform adapter architecture, unified `AgentEvent` taxonomy, `NormalizedTool` cross-platform mappings, session summary dashboard, MCP server, global config defaults, warning suppression, auto-suppress, `diff_only` mode, and `auto-fix` mode.
 
 | Rule | Severity | What it does |
 |------|----------|-------------|
@@ -80,7 +80,7 @@ AgentLint ships with 76 rules across 8 packs and normalizes tool events across s
 | `no-unsafe-shell` | ERROR | Blocks unsafe shell execution via subprocess or os module |
 | `no-dangerous-migration` | WARNING | Warns on risky Alembic migration operations |
 | `no-wildcard-import` | WARNING | Prevents `from module import *` |
-| `no-unnecessary-async` | INFO | Flags async functions that never use `await` |
+| `no-unnecessary-async` | INFO | Flags async functions that never use `await`; skips FastAPI route handlers by default |
 | `no-sql-injection` | ERROR | Blocks SQL via string interpolation (f-strings, `.format()`) |
 
 </details>
@@ -158,6 +158,16 @@ rules:
 
 </details>
 
+Per-rule accepted patterns can be documented locally:
+
+```yaml
+rules:
+  no-unnecessary-async:
+    ignore_paths:
+      - "app/api/*_routes.py"
+    reason: "FastAPI route consistency"
+```
+
 <details>
 <summary><strong>Autopilot pack</strong> (18 rules) — ⚠️ experimental, opt-in</summary>
 

{agentlint-2.2.1 → agentlint-2.3.0}/agentlint.yml.example

@@ -51,6 +51,11 @@ rules:
   # ── PostToolUse (warnings after the action) ─────────────
   # max-file-size:
   #   limit: 500                # Warn if file exceeds this many lines
+  # no-unnecessary-async:
+  #   ignore_fastapi_routes: true  # Default: don't flag FastAPI route handlers
+  #   ignore_paths:
+  #     - "app/api/*_routes.py"
+  #   reason: "FastAPI route consistency"
   # drift-detector:
   #   threshold: 10             # Warn after this many edits without tests
 

{agentlint-2.2.1 → agentlint-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentlint"
-version = "2.2.1"
+version = "2.3.0"
 description = "Real-time quality guardrails for AI coding agents"
 readme = "README.md"
 license = "MIT"

{agentlint-2.2.1 → agentlint-2.3.0}/src/agentlint/__init__.py

@@ -1,6 +1,6 @@
 """AgentLint - Real-time quality guardrails for AI coding agents."""
 
-__version__ = "2.2.1"
+__version__ = "2.3.0"
 
 from agentlint.core.models import (
     AgentEvent,

{agentlint-2.2.1 → agentlint-2.3.0}/src/agentlint/cli.py

@@ -488,12 +488,27 @@ def ci(diff: str | None, project_dir: str | None, output_format: str):
         if not all_violations:
             click.echo(f"Clean — {len(changed_files)} files scanned, {total_evaluated} rules evaluated.")
         else:
-            for v in all_violations:
-                sev = v.severity.value.upper()
-                loc = f"{v.file_path}" if v.file_path else "?"
-                click.echo(f"{loc}  [{v.rule_id}] {sev}  {v.message}")
-                if v.suggestion:
-                    click.echo(f"  → {v.suggestion}")
+            for group in _group_ci_violations(all_violations):
+                if len(group) == 1:
+                    v = group[0]
+                    sev = v.severity.value.upper()
+                    loc = f"{v.file_path}" if v.file_path else "?"
+                    click.echo(f"{loc}  [{v.rule_id}] {sev}  {v.message}")
+                    if v.suggestion:
+                        click.echo(f"  → {v.suggestion}")
+                    click.echo()
+                    continue
+
+                first = group[0]
+                sev = first.severity.value.upper()
+                loc = f"{first.file_path}" if first.file_path else "?"
+                click.echo(f"{loc}  [{first.rule_id}] {sev}  {len(group)} findings")
+                for v in group:
+                    line = f"line {v.line}: " if v.line is not None else ""
+                    click.echo(f"  - {line}{v.message}")
+                suggestions = sorted({v.suggestion for v in group if v.suggestion})
+                if len(suggestions) == 1:
+                    click.echo(f"  → {suggestions[0]}")
                 click.echo()
             click.echo(
                 f"{len(all_violations)} violation(s) "
@@ -504,6 +519,19 @@ def ci(diff: str | None, project_dir: str | None, output_format: str):
     sys.exit(1 if has_errors else 0)
 
 
+def _group_ci_violations(violations: list) -> list[list]:
+    """Group repeated text CI findings by file, rule, and severity."""
+    grouped: list[list] = []
+    index: dict[tuple, list] = {}
+    for violation in violations:
+        key = (violation.file_path, violation.rule_id, violation.severity.value)
+        if key not in index:
+            index[key] = []
+            grouped.append(index[key])
+        index[key].append(violation)
+    return grouped
+
+
 @main.command()
 @click.option("--project-dir", default=None, help="Project directory")
 @click.option(

{agentlint-2.2.1 → agentlint-2.3.0}/src/agentlint/engine.py

@@ -59,6 +59,15 @@ class Engine:
                     if any(fnmatch(context.file_path, p) or fnmatch(basename, p) for p in rule_allow):
                         continue
 
+                # Per-rule ignore_paths — accepted-pattern alias for allow_paths.
+                # Useful when teams want to document why a rule does not apply
+                # to a local convention without disabling the rule globally.
+                rule_ignore = get_rule_setting(context.config, rule.id, "ignore_paths", [])
+                if isinstance(rule_ignore, list) and rule_ignore:
+                    basename = os.path.basename(context.file_path)
+                    if any(fnmatch(context.file_path, p) or fnmatch(basename, p) for p in rule_ignore):
+                        continue
+
             result.rules_evaluated += 1
 
             try:

{agentlint-2.2.1 → agentlint-2.3.0}/src/agentlint/packs/python/no_unnecessary_async.py

@@ -9,6 +9,7 @@ _WRITE_TOOLS = {"Write", "Edit"}
 
 _ASYNC_DEF_RE = re.compile(r"^(\s*)async\s+def\s+(\w+)\s*\(", re.MULTILINE)
 _AWAIT_RE = re.compile(r"\bawait\b")
+_FASTAPI_ROUTE_METHODS = {"get", "post", "put", "patch", "delete", "options", "head", "trace", "websocket"}
 _SKIP_DECORATORS = {"property", "override", "abstractmethod"}
 _SKIP_BODIES = {"pass", "...", "raise NotImplementedError"}
 
@@ -45,6 +46,7 @@ class NoUnnecessaryAsync(Rule):
 
         ignore_decorators = set(context.config.get("ignore_decorators", []))
         all_skip_decorators = _SKIP_DECORATORS | ignore_decorators
+        ignore_fastapi_routes = context.config.get("ignore_fastapi_routes", True)
 
         violations: list[Violation] = []
         lines = content.splitlines()
@@ -57,9 +59,11 @@ class NoUnnecessaryAsync(Rule):
             # Check decorators above
             decorator_line = func_line - 1
             skip = False
+            decorators: list[str] = []
             while decorator_line >= 0:
                 dline = lines[decorator_line].strip()
                 if dline.startswith("@"):
+                    decorators.append(dline)
                     dec_name = dline[1:].split("(")[0].split(".")[-1]
                     if dec_name in all_skip_decorators:
                         skip = True
@@ -72,6 +76,8 @@ class NoUnnecessaryAsync(Rule):
 
             if skip:
                 continue
+            if ignore_fastapi_routes and _has_fastapi_route_decorator(decorators):
+                continue
 
             # Extract body lines
             body_lines = []
@@ -104,3 +110,20 @@ class NoUnnecessaryAsync(Rule):
                 )
 
         return violations
+
+
+def _has_fastapi_route_decorator(decorators: list[str]) -> bool:
+    """Return True for common FastAPI route decorators.
+
+    Async FastAPI handlers are a framework convention even when a handler
+    currently has no direct await; dependencies, middleware, or later
+    instrumentation often remain async.
+    """
+    for decorator in decorators:
+        target = decorator[1:].split("(", 1)[0]
+        parts = target.split(".")
+        if len(parts) >= 2 and parts[-1] in _FASTAPI_ROUTE_METHODS:
+            receiver = parts[-2].lower()
+            if receiver == "app" or receiver.endswith("router"):
+                return True
+    return False

{agentlint-2.2.1 → agentlint-2.3.0}/tests/packs/test_python_pre.py

@@ -8,6 +8,7 @@ from agentlint.packs.python.no_sql_injection import NoSqlInjection
 from agentlint.packs.python.no_bare_except import NoBareExcept
 from agentlint.packs.python.no_unsafe_shell import NoUnsafeShell
 from agentlint.packs.python.no_dangerous_migration import NoDangerousMigration
+from agentlint.packs.python.no_unnecessary_async import NoUnnecessaryAsync
 from agentlint.packs.python.no_wildcard_import import NoWildcardImport
 
 
@@ -612,6 +613,48 @@ class TestNoWildcardImport:
         assert len(violations) == 0
 
 
+# ---------------------------------------------------------------------------
+# NoUnnecessaryAsync
+# ---------------------------------------------------------------------------
+
+
+class TestNoUnnecessaryAsync:
+    rule = NoUnnecessaryAsync()
+
+    def test_detects_plain_async_without_await(self):
+        ctx = _ctx("Write", {
+            "file_path": "app/service.py",
+            "content": "async def compute():\n    return 1\n",
+        })
+        violations = self.rule.evaluate(ctx)
+        assert len(violations) == 1
+        assert violations[0].severity == Severity.INFO
+
+    def test_skips_fastapi_route_by_default(self):
+        ctx = _ctx("Write", {
+            "file_path": "app/api/routes.py",
+            "content": "@router.get('/health')\nasync def health():\n    return {'ok': True}\n",
+        })
+        violations = self.rule.evaluate(ctx)
+        assert violations == []
+
+    def test_skips_fastapi_app_route_by_default(self):
+        ctx = _ctx("Write", {
+            "file_path": "app/main.py",
+            "content": "@app.post('/items')\nasync def create_item():\n    return {'ok': True}\n",
+        })
+        violations = self.rule.evaluate(ctx)
+        assert violations == []
+
+    def test_fastapi_route_can_be_checked_when_configured(self):
+        ctx = _ctx("Write", {
+            "file_path": "app/api/routes.py",
+            "content": "@router.get('/health')\nasync def health():\n    return {'ok': True}\n",
+        }, config={"ignore_fastapi_routes": False})
+        violations = self.rule.evaluate(ctx)
+        assert len(violations) == 1
+
+
 # ---------------------------------------------------------------------------
 # Pack loader
 # ---------------------------------------------------------------------------

{agentlint-2.2.1 → agentlint-2.3.0}/tests/test_ci.py

@@ -8,6 +8,7 @@ import sys
 from click.testing import CliRunner
 
 from agentlint.cli import main
+from agentlint.models import Severity, Violation
 
 
 class TestCiCommand:
@@ -142,6 +143,25 @@ class TestCiCommand:
         assert "Clean" in result.output or "No changed" in result.output
 
 
+class TestCiTextGrouping:
+    def test_groups_repeated_rule_findings(self):
+        from agentlint.cli import _group_ci_violations
+
+        violations = [
+            Violation("no-unnecessary-async", "async def one() has no await expression", Severity.INFO, "app.py", 1),
+            Violation("no-unnecessary-async", "async def two() has no await expression", Severity.INFO, "app.py", 4),
+            Violation("max-file-size", "File has 600 lines", Severity.WARNING, "app.py"),
+        ]
+
+        groups = _group_ci_violations(violations)
+        assert len(groups) == 2
+        assert [v.message for v in groups[0]] == [
+            "async def one() has no await expression",
+            "async def two() has no await expression",
+        ]
+        assert groups[1][0].rule_id == "max-file-size"
+
+
 class TestGetDiffFiles:
     def test_diff_range_returns_files(self, tmp_path):
         from agentlint.utils.git import get_diff_files

{agentlint-2.2.1 → agentlint-2.3.0}/tests/test_cli.py

@@ -17,7 +17,7 @@ class TestMainCommand:
         result = runner.invoke(main, ["--version"])
 
         assert result.exit_code == 0
-        assert result.output.strip() == "agentlint 2.2.1"
+        assert result.output.strip() == "agentlint 2.3.0"
 
 
 class TestCheckCommand:

{agentlint-2.2.1 → agentlint-2.3.0}/tests/test_engine.py

@@ -592,6 +592,17 @@ class TestPerRuleAllowPaths:
         result = engine.evaluate(ctx)
         assert len(result.violations) == 0
 
+    def test_rule_ignore_paths_alias_skips_specific_rule(self) -> None:
+        ctx = self._make_context("/project/app/api/users_routes.py", config={
+            "always-warn": {
+                "ignore_paths": ["**/api/*_routes.py"],
+                "reason": "FastAPI route consistency",
+            },
+        })
+        engine = self._make_engine()
+        result = engine.evaluate(ctx)
+        assert len(result.violations) == 0
+
     def test_other_rules_still_fire(self) -> None:
         """Rule A has allow_paths, rule B does not — B should still fire."""
         ctx = self._make_context("/project/generated/out.py", config={

{agentlint-2.2.1 → agentlint-2.3.0}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "agentlint"
-version = "2.2.1"
+version = "2.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },