flake8-agents 0.1.0__py3-none-any.whl

flake8_agents/__init__.py

@@ -0,0 +1,4 @@
+from flake8_agents._version_ import __commit_id__, __version__  # noqa: AGT300
+from flake8_agents.checker import FlakeAgentsChecker
+
+__all__ = ["FlakeAgentsChecker", "__commit_id__", "__version__"]

flake8_agents/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

flake8_agents/_version_.py

@@ -0,0 +1,35 @@
+from typing import Any
+
+__all__ = ["__commit_id__", "__version__"]
+
+__version__: str
+__commit_id__: str | None
+
+
+def __getattr__(name: str) -> Any:  # noqa: AGT105
+    match name:
+        case "__version__":
+            try:
+                # pyrefly: ignore[missing-import]
+                from flake8_agents._version import (  # noqa: PLC0415,AGT300
+                    __version__ as _version,
+                )
+            except ImportError:  # pragma: no cover
+                from importlib.metadata import version  # noqa: PLC0415
+
+                _version = version("flake8-agents")
+            globals()["__version__"] = _version
+            return _version
+        case "__commit_id__":
+            try:
+                # pyrefly: ignore[missing-import]
+                from flake8_agents._version import (  # noqa: PLC0415,AGT300
+                    __commit_id__ as _commit_id,
+                )
+            except ImportError:  # pragma: no cover
+                _commit_id = None
+            globals()["__commit_id__"] = _commit_id
+            return _commit_id
+
+    error_msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(error_msg)

flake8_agents/anti_pattern.py

@@ -0,0 +1,393 @@
+from __future__ import annotations
+
+import ast
+from collections import deque
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from typing_extensions import Self, override
+
+from flake8_agents._version_ import __version__  # noqa: AGT300
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+__all__ = ["AntiPatternChecker"]
+
+_DYNAMIC_BUILTIN_CODES: dict[str, DiagnosticCode]
+_MONKEYPATCH_NAME = "monkeypatch"
+_IMPORTLIB_MODULE = "importlib"
+_IMPORT_MODULE_NAME = "import_module"
+
+
+class DiagnosticCode(Enum):
+    GETATTR = "AGT200"
+    SETATTR = "AGT201"
+    VARS = "AGT202"
+    DUNDER_IMPORT = "AGT203"
+    IMPORT_MODULE = "AGT204"
+    ATTRIBUTE_SETATTR = "AGT205"
+    DUNDER_SETATTR = "AGT206"
+    DUNDER_NEW = "AGT207"
+    NAMESPACE_DICT_DIRECT_INDEX = "AGT208"
+    NAMESPACE_DICT_ALIAS_ASSIGNMENT = "AGT209"
+    NAMESPACE_DICT_ALIAS_INDEX = "AGT210"
+    DOTTED_IMPORT_ALIAS = "AGT211"
+
+
+_MESSAGES: dict[DiagnosticCode, str] = {
+    DiagnosticCode.GETATTR: "avoid dynamic getattr calls",
+    DiagnosticCode.SETATTR: "avoid dynamic setattr calls",
+    DiagnosticCode.VARS: "avoid dynamic vars calls",
+    DiagnosticCode.DUNDER_IMPORT: "avoid dynamic __import__ calls",
+    DiagnosticCode.IMPORT_MODULE: "avoid dynamic import_module calls",
+    DiagnosticCode.ATTRIBUTE_SETATTR: "avoid setattr-style mutation methods",
+    DiagnosticCode.DUNDER_SETATTR: "avoid dynamic __setattr__ calls",
+    DiagnosticCode.DUNDER_NEW: "avoid direct __new__ calls",
+    DiagnosticCode.NAMESPACE_DICT_DIRECT_INDEX: "avoid indexing raw __dict__",
+    DiagnosticCode.NAMESPACE_DICT_ALIAS_ASSIGNMENT: "avoid aliasing raw __dict__",
+    DiagnosticCode.NAMESPACE_DICT_ALIAS_INDEX: "avoid indexing raw __dict__ aliases",
+    DiagnosticCode.DOTTED_IMPORT_ALIAS: "avoid aliasing dotted module imports",
+}
+
+
+_DYNAMIC_BUILTIN_CODES = {
+    "getattr": DiagnosticCode.GETATTR,
+    "setattr": DiagnosticCode.SETATTR,
+    "vars": DiagnosticCode.VARS,
+    "__import__": DiagnosticCode.DUNDER_IMPORT,
+}
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    line_number: int
+    column_number: int
+    code: DiagnosticCode
+
+    @property
+    def message(self) -> str:
+        return f"{self.code.value} {_MESSAGES[self.code]}"
+
+
+@dataclass(frozen=True)
+class SourceContext:
+    tree: ast.AST
+
+    @classmethod
+    def build(cls, tree: ast.AST) -> Self:
+        return cls(tree=tree)
+
+
+class AntiPatternChecker:
+    """Flake8 checker for dynamic Python anti-patterns."""
+
+    name = "flake8-agents-anti-pattern"
+    version = __version__
+
+    def __init__(self, tree: ast.AST, filename: str, lines: Sequence[str]) -> None:
+        del filename, lines
+        self._context = SourceContext.build(tree)
+
+    def run(self) -> Iterator[tuple[int, int, str, type[AntiPatternChecker]]]:
+        """Yield flake8-compatible anti-pattern diagnostics for this file."""
+        diagnostics = _scan_context(self._context)
+        for diagnostic in diagnostics:
+            yield (
+                diagnostic.line_number,
+                diagnostic.column_number,
+                diagnostic.message,
+                type(self),
+            )
+
+
+def _scan_context(context: SourceContext) -> tuple[Diagnostic, ...]:
+    visitor = _AntiPatternVisitor(context)
+    visitor.visit(context.tree)
+    return tuple(visitor.diagnostics)
+
+
+class _AntiPatternVisitor(ast.NodeVisitor):
+    def __init__(self, context: SourceContext) -> None:
+        self._context = context
+        self._call_shadow_scopes: deque[set[str]] = deque([set()])
+        self._import_module_scopes: deque[set[str]] = deque([
+            {f"{_IMPORTLIB_MODULE}.{_IMPORT_MODULE_NAME}"}
+        ])
+        self._namespace_scopes: deque[dict[str, bool]] = deque([{}])
+        self.diagnostics: list[Diagnostic] = []
+
+    @override
+    def visit_Import(self, node: ast.Import) -> None:
+        for alias in node.names:
+            bound_name = alias.asname or alias.name.partition(".")[0]
+            if alias.name == _IMPORTLIB_MODULE:
+                self._unshadow_call(bound_name)
+                self._bind_import_module_name(f"{bound_name}.{_IMPORT_MODULE_NAME}")
+                self._bind_namespace_name(bound_name, is_alias=False)
+            else:
+                self._bind_name(bound_name, is_namespace_alias=False)
+            if alias.asname is not None and "." in alias.name:
+                self._record(node, DiagnosticCode.DOTTED_IMPORT_ALIAS)
+
+    @override
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        for alias in node.names:
+            bound_name = alias.asname or alias.name
+            if node.module == _IMPORTLIB_MODULE and alias.name == _IMPORT_MODULE_NAME:
+                self._unshadow_call(bound_name)
+                self._bind_import_module_name(bound_name)
+                self._bind_namespace_name(bound_name, is_alias=False)
+            else:
+                self._bind_name(bound_name, is_namespace_alias=False)
+
+    @override
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._bind_name(node.name, is_namespace_alias=False)
+        self._visit_function_scope(node)
+
+    @override
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._bind_name(node.name, is_namespace_alias=False)
+        self._visit_function_scope(node)
+
+    @override
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self._bind_name(node.name, is_namespace_alias=False)
+        self._call_shadow_scopes.append(set())
+        self._import_module_scopes.append(set())
+        self._namespace_scopes.append({})
+        self.generic_visit(node)
+        self._namespace_scopes.pop()
+        self._import_module_scopes.pop()
+        self._call_shadow_scopes.pop()
+
+    @override
+    def visit_Assign(self, node: ast.Assign) -> None:
+        self.visit(node.value)
+        is_namespace_alias = _is_namespace_dictionary(node.value)
+        for target in node.targets:
+            self.visit(target)
+            self._bind_assignment_target(target, is_namespace_alias=is_namespace_alias)
+        if is_namespace_alias:
+            self._record(node, DiagnosticCode.NAMESPACE_DICT_ALIAS_ASSIGNMENT)
+
+    @override
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        self.visit(node.annotation)
+        if node.value is not None:
+            self.visit(node.value)
+        is_namespace_alias = node.value is not None and _is_namespace_dictionary(
+            node.value
+        )
+        self.visit(node.target)
+        self._bind_assignment_target(node.target, is_namespace_alias=is_namespace_alias)
+        if is_namespace_alias and isinstance(node.target, ast.Name):
+            self._record(node, DiagnosticCode.NAMESPACE_DICT_ALIAS_ASSIGNMENT)
+
+    @override
+    def visit_AugAssign(self, node: ast.AugAssign) -> None:
+        self.visit(node.value)
+        self.visit(node.target)
+        self._bind_assignment_target(node.target, is_namespace_alias=False)
+
+    @override
+    def visit_For(self, node: ast.For) -> None:
+        self.visit(node.iter)
+        self._bind_assignment_target(node.target, is_namespace_alias=False)
+        for statement in node.body:
+            self.visit(statement)
+        for statement in node.orelse:
+            self.visit(statement)
+
+    @override
+    def visit_AsyncFor(self, node: ast.AsyncFor) -> None:
+        self.visit(node.iter)
+        self._bind_assignment_target(node.target, is_namespace_alias=False)
+        for statement in node.body:
+            self.visit(statement)
+        for statement in node.orelse:
+            self.visit(statement)
+
+    @override
+    def visit_With(self, node: ast.With) -> None:
+        for item in node.items:
+            self.visit(item.context_expr)
+            if item.optional_vars is not None:
+                self._bind_assignment_target(
+                    item.optional_vars, is_namespace_alias=False
+                )
+        for statement in node.body:
+            self.visit(statement)
+
+    @override
+    def visit_AsyncWith(self, node: ast.AsyncWith) -> None:
+        for item in node.items:
+            self.visit(item.context_expr)
+            if item.optional_vars is not None:
+                self._bind_assignment_target(
+                    item.optional_vars, is_namespace_alias=False
+                )
+        for statement in node.body:
+            self.visit(statement)
+
+    @override
+    def visit_Call(self, node: ast.Call) -> None:
+        category = self._call_category(node)
+        if category is not None:
+            self._record(node, category)
+        self.generic_visit(node)
+
+    @override
+    def visit_Subscript(self, node: ast.Subscript) -> None:
+        if _is_namespace_dictionary(node.value):
+            self._record(node, DiagnosticCode.NAMESPACE_DICT_DIRECT_INDEX)
+        elif isinstance(node.value, ast.Name) and self._is_active_namespace_alias(
+            node.value.id
+        ):
+            self._record(node, DiagnosticCode.NAMESPACE_DICT_ALIAS_INDEX)
+        self.generic_visit(node)
+
+    def _visit_function_scope(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> None:
+        argument_names = set(_iter_argument_names(node.args))
+        self._call_shadow_scopes.append(argument_names)
+        self._import_module_scopes.append(set())
+        self._namespace_scopes.append(dict.fromkeys(argument_names, False))
+        for statement in node.body:
+            self.visit(statement)
+        self._namespace_scopes.pop()
+        self._import_module_scopes.pop()
+        self._call_shadow_scopes.pop()
+
+    def _call_category(self, node: ast.Call) -> DiagnosticCode | None:
+        function = node.func
+        if isinstance(function, ast.Name):
+            return self._name_call_category(function.id)
+        if isinstance(function, ast.Attribute):
+            return self._attribute_call_category(function, node)
+        return None
+
+    def _name_call_category(self, name: str) -> DiagnosticCode | None:
+        if self._is_call_shadowed(name):
+            return None
+        if self._is_import_module_name(name):
+            return DiagnosticCode.IMPORT_MODULE
+        return _DYNAMIC_BUILTIN_CODES.get(name)
+
+    def _attribute_call_category(
+        self, function: ast.Attribute, node: ast.Call
+    ) -> DiagnosticCode | None:
+        if _is_shadowed_qualified_name(function, self._call_shadow_scopes):
+            return None
+        if self._is_import_module_name(_qualified_name(function)):
+            return DiagnosticCode.IMPORT_MODULE
+        if function.attr == "setattr" and not _is_monkeypatch_setattr(function):
+            return DiagnosticCode.ATTRIBUTE_SETATTR
+        if function.attr == "__setattr__":
+            return DiagnosticCode.DUNDER_SETATTR
+        if function.attr == "__new__" and not _is_object_new_call(node):
+            return DiagnosticCode.DUNDER_NEW
+        return None
+
+    def _bind_assignment_target(
+        self, target: ast.expr, *, is_namespace_alias: bool
+    ) -> None:
+        for name in _stored_names(target):
+            self._bind_name(name, is_namespace_alias=is_namespace_alias)
+
+    def _bind_name(self, name: str, *, is_namespace_alias: bool) -> None:
+        self._call_shadow_scopes[-1].add(name)
+        self._bind_namespace_name(name, is_alias=is_namespace_alias)
+
+    def _unshadow_call(self, name: str) -> None:
+        self._call_shadow_scopes[-1].discard(name)
+
+    def _bind_import_module_name(self, name: str) -> None:
+        self._import_module_scopes[-1].add(name)
+
+    def _bind_namespace_name(self, name: str, *, is_alias: bool) -> None:
+        self._namespace_scopes[-1][name] = is_alias
+
+    def _is_call_shadowed(self, name: str) -> bool:
+        return any(name in scope for scope in reversed(self._call_shadow_scopes))
+
+    def _is_import_module_name(self, name: str) -> bool:
+        return any(name in scope for scope in reversed(self._import_module_scopes))
+
+    def _is_active_namespace_alias(self, name: str) -> bool:
+        for scope in reversed(self._namespace_scopes):
+            if name in scope:
+                return scope[name]
+        return False
+
+    def _record(self, node: ast.expr | ast.stmt, code: DiagnosticCode) -> None:
+        self.diagnostics.append(
+            Diagnostic(
+                line_number=node.lineno, column_number=node.col_offset, code=code
+            )
+        )
+
+
+def _is_namespace_dictionary(node: ast.AST) -> bool:
+    return isinstance(node, ast.Attribute) and node.attr == "__dict__"
+
+
+def _is_monkeypatch_setattr(function: ast.Attribute) -> bool:
+    return (
+        function.attr == "setattr"
+        and isinstance(function.value, ast.Name)
+        and function.value.id == _MONKEYPATCH_NAME
+    )
+
+
+def _is_object_new_call(node: ast.Call) -> bool:
+    return (
+        isinstance(node.func, ast.Attribute)
+        and node.func.attr == "__new__"
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id == "object"
+    )
+
+
+def _qualified_name(node: ast.Attribute) -> str:
+    value = node.value
+    if isinstance(value, ast.Name):
+        return f"{value.id}.{node.attr}"
+    if isinstance(value, ast.Attribute):
+        return f"{_qualified_name(value)}.{node.attr}"
+    return node.attr
+
+
+def _is_shadowed_qualified_name(
+    node: ast.Attribute, shadow_scopes: Sequence[set[str]]
+) -> bool:
+    value = node.value
+    while isinstance(value, ast.Attribute):
+        value = value.value
+    if not isinstance(value, ast.Name):
+        return False
+    return any(value.id in scope for scope in reversed(shadow_scopes))
+
+
+def _iter_argument_names(arguments: ast.arguments) -> Iterator[str]:
+    yield from (arg.arg for arg in arguments.posonlyargs)
+    yield from (arg.arg for arg in arguments.args)
+    yield from (arg.arg for arg in arguments.kwonlyargs)
+    if arguments.vararg is not None:
+        yield arguments.vararg.arg
+    if arguments.kwarg is not None:
+        yield arguments.kwarg.arg
+
+
+def _stored_names(target: ast.expr) -> frozenset[str]:
+    if isinstance(target, ast.Name):
+        return frozenset({target.id})
+    if isinstance(target, (ast.Tuple, ast.List)):
+        names: set[str] = set()
+        for element in target.elts:
+            names.update(_stored_names(element))
+        return frozenset(names)
+    return frozenset()

flake8_agents/checker.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import re
+import tokenize
+from dataclasses import dataclass
+from itertools import chain
+from typing import TYPE_CHECKING, TypeAlias
+
+from flake8_agents._version_ import __version__  # noqa: AGT300
+from flake8_agents.anti_pattern import AntiPatternChecker
+from flake8_agents.import_boundary import ImportBoundaryChecker
+from flake8_agents.type_escape import TypeEscapeChecker
+
+if TYPE_CHECKING:
+    import ast
+    from collections.abc import Iterator, Sequence
+
+
+__all__ = ["FlakeAgentsChecker"]
+
+
+_OwnedCheckerType: TypeAlias = type[
+    AntiPatternChecker | ImportBoundaryChecker | TypeEscapeChecker
+]
+Flake8Result: TypeAlias = tuple[
+    int, int, str, _OwnedCheckerType | type["FlakeAgentsChecker"]
+]
+
+_NOQA_INLINE_RE = re.compile(
+    r"# noqa(?::[\s]?(?P<codes>([A-Z]+[0-9]*(?:[,\s]+)?)+))?", re.IGNORECASE
+)
+_AUDITED_AGT_NOQA_CODE_RE = re.compile(r"AGT[1-9][0-9]*\Z")
+_AGT_UNUSED_NOQA_CODE = "AGT001"
+_AGT_UNUSED_NOQA_MESSAGE = "unused AGT noqa suppression"
+
+
+@dataclass(frozen=True)
+class _RawDiagnostic:
+    line_number: int
+    column_number: int
+    message: str
+    checker_type: _OwnedCheckerType
+
+    @property
+    def code(self) -> str:
+        return self.message.split(maxsplit=1)[0]
+
+    def to_result(self) -> Flake8Result:
+        return (self.line_number, self.column_number, self.message, self.checker_type)
+
+
+@dataclass(frozen=True)
+class _NoqaSuppression:
+    line_number: int
+    column_number: int
+    codes: tuple[str, ...]
+    logical_line_numbers: frozenset[int]
+
+
+class FlakeAgentsChecker:
+    """Aggregate flake8 checker for repository AGT diagnostics."""
+
+    name = "flake8-agents"
+    version = __version__
+
+    def __init__(self, tree: ast.Module, filename: str, lines: Sequence[str]) -> None:
+        self._type_escape_checker = TypeEscapeChecker(
+            tree=tree, filename=filename, lines=lines
+        )
+        self._anti_pattern_checker = AntiPatternChecker(
+            tree=tree, filename=filename, lines=lines
+        )
+        self._import_boundary_checker = ImportBoundaryChecker(
+            tree=tree, filename=filename, lines=lines
+        )
+        self._lines = lines
+
+    def run(self) -> Iterator[Flake8Result]:
+        """Yield all flake8-compatible AGT diagnostics for this file."""
+        diagnostics = tuple(self._raw_diagnostics())
+        for diagnostic in diagnostics:
+            yield diagnostic.to_result()
+        yield from _unused_noqa_results(diagnostics, self._lines, type(self))
+
+    def _raw_diagnostics(self) -> Iterator[_RawDiagnostic]:
+        for line_number, column_number, message, checker_type in chain(
+            self._type_escape_checker.run(),
+            self._anti_pattern_checker.run(),
+            self._import_boundary_checker.run(),
+        ):
+            yield _RawDiagnostic(
+                line_number=line_number,
+                column_number=column_number,
+                message=message,
+                checker_type=checker_type,
+            )
+
+
+def _unused_noqa_results(
+    diagnostics: tuple[_RawDiagnostic, ...],
+    lines: Sequence[str],
+    checker_type: type[FlakeAgentsChecker],
+) -> Iterator[Flake8Result]:
+    diagnostic_codes_by_line = _diagnostic_codes_by_line(diagnostics)
+    for suppression in _explicit_agt_noqa_suppressions(lines):
+        unused_codes = tuple(
+            code
+            for code in suppression.codes
+            if not _suppression_matches_any_diagnostic(
+                code, suppression.logical_line_numbers, diagnostic_codes_by_line
+            )
+        )
+        if unused_codes:
+            yield (
+                suppression.line_number,
+                suppression.column_number,
+                _unused_noqa_message(unused_codes),
+                checker_type,
+            )
+
+
+def _diagnostic_codes_by_line(
+    diagnostics: tuple[_RawDiagnostic, ...],
+) -> dict[int, tuple[str, ...]]:
+    codes_by_line: dict[int, list[str]] = {}
+    for diagnostic in diagnostics:
+        codes_by_line.setdefault(diagnostic.line_number, []).append(diagnostic.code)
+    return {line_number: tuple(codes) for line_number, codes in codes_by_line.items()}
+
+
+def _explicit_agt_noqa_suppressions(
+    lines: Sequence[str],
+) -> tuple[_NoqaSuppression, ...]:
+    logical_lines_by_line = _logical_lines_by_line(lines)
+    return tuple(
+        suppression
+        for token in _tokens_from_lines(lines)
+        if token.type == tokenize.COMMENT
+        for suppression in _suppression_from_comment(
+            token, lines, logical_lines_by_line
+        )
+    )
+
+
+def _tokens_from_lines(lines: Sequence[str]) -> tuple[tokenize.TokenInfo, ...]:
+    line_index = 0
+
+    def readline() -> str:
+        nonlocal line_index
+        if line_index >= len(lines):
+            return ""
+        line = lines[line_index]
+        line_index += 1
+        return line
+
+    try:
+        return tuple(tokenize.generate_tokens(readline))
+    except tokenize.TokenError:
+        return ()
+
+
+def _logical_lines_by_line(lines: Sequence[str]) -> dict[int, frozenset[int]]:
+    logical_lines: dict[int, frozenset[int]] = {}
+    min_line = len(lines) + 2
+    max_line = -1
+    for token in _tokens_from_lines(lines):
+        if token.type in {tokenize.ENDMARKER, tokenize.DEDENT}:
+            continue
+        min_line = min(min_line, token.start[0])
+        max_line = max(max_line, token.end[0])
+        if token.type in {tokenize.NL, tokenize.NEWLINE}:
+            current_lines = frozenset(range(min_line, max_line + 1))
+            for line_number in current_lines:
+                logical_lines[line_number] = current_lines
+            min_line = len(lines) + 2
+            max_line = -1
+    return logical_lines
+
+
+def _suppression_from_comment(
+    token: tokenize.TokenInfo,
+    lines: Sequence[str],
+    logical_lines_by_line: dict[int, frozenset[int]],
+) -> tuple[_NoqaSuppression, ...]:
+    line_number, column_number = token.start
+    if line_number > len(lines):
+        return ()
+    if not lines[line_number - 1][:column_number].strip():
+        return ()
+    match = _NOQA_INLINE_RE.search(token.string)
+    if match is None:
+        return ()
+    codes_text = match.groupdict()["codes"]
+    if codes_text is None:
+        return ()
+    codes = tuple(
+        code
+        for code in re.split(r"[,\s]+", codes_text.upper())
+        if _AUDITED_AGT_NOQA_CODE_RE.fullmatch(code) is not None
+    )
+    if not codes:
+        return ()
+    return (
+        _NoqaSuppression(
+            line_number=line_number,
+            column_number=column_number + match.start(),
+            codes=codes,
+            logical_line_numbers=logical_lines_by_line.get(
+                line_number, frozenset({line_number})
+            ),
+        ),
+    )
+
+
+def _suppression_matches_any_diagnostic(
+    suppression_code: str,
+    logical_line_numbers: frozenset[int],
+    diagnostic_codes_by_line: dict[int, tuple[str, ...]],
+) -> bool:
+    return any(
+        diagnostic_code == suppression_code
+        or diagnostic_code.startswith(suppression_code)
+        for line_number in logical_line_numbers
+        for diagnostic_code in diagnostic_codes_by_line.get(line_number, ())
+    )
+
+
+def _unused_noqa_message(unused_codes: tuple[str, ...]) -> str:
+    return (
+        f"{_AGT_UNUSED_NOQA_CODE} {_AGT_UNUSED_NOQA_MESSAGE}: {', '.join(unused_codes)}"
+    )

flake8_agents/cli/__init__.py

@@ -0,0 +1,3 @@
+from flake8_agents.cli import module_size
+
+__all__ = ["module_size"]