feat: add github annotations reporter

docs/usage.md

@@ -384,6 +384,36 @@ json_output = "deptry_report.txt"
 deptry . --json-output deptry_report.txt
 ```
 
+#### GitHub Reporter
+When enabled with the `--github-output` flag, deptry prints GitHub Actions annotations for detected dependency issues.
+
+Annotations follow this format:
+```shell
+::error file=<file>,line=<line>,col=<column>,title=<error_code>::<error message>
+```
+By default, violations are annotated as errors. To report specific violation codes as warnings instead, use the `--github-warning-errors` option. For example, to treat violations with code `DEP001` as warnings:
+```shell
+deptry . --github-output --github-warning-errors DEP001
+```
+When a violation's error code is included in the warning list, the annotation uses the `warning` severity.
+
+- Type: `bool` (for `github_output`), `list[str]` (for `github_warning_errors`)
+- Default: `False` (for `github_output`), `[]` (for `github_warning_errors`)
+- `pyproject.toml` option names: `github_output`, `github_warning_errors`
+- CLI option names: `--github-output`, `--github-warning-errors`
+
+- `pyproject.toml` example:
+```toml
+[tool.deptry]
+github_output = true
+github_warning_errors = ["DEP001"]
+```
+
+- CLI example:
+```shell
+deptry . --github-output --github-warning-errors DEP001
+```
+
 #### Package module name map
 
 Deptry will automatically detect top level modules names that belong to a

python/deptry/cli.py

@@ -217,6 +217,21 @@ def display_deptry_version(ctx: click.Context, _param: click.Parameter, value: b
     help="""If specified, a summary of the dependency issues found will be written to the output location specified. e.g. `deptry . -o deptry.json`""",
     show_default=True,
 )
+@click.option(
+    "--github-output",
+    "-go",
+    is_flag=True,
+    help="""If specified, dependency issues found will be written in the format of github annotation. e.g. `deptry . -o deptry.json`""",
+)
+@click.option(
+    "--github-warning-errors",
+    "-gwe",
+    type=COMMA_SEPARATED_TUPLE,
+    help="""A comma-separated list of error codes that should be printed as warnings.
+    If not specified, all violations will be reported as errors.""",
+    default=(),
+    show_default=False,
+)
 @click.option(
     "--package-module-name-map",
     "-pmnm",
@@ -254,6 +269,8 @@ def cli(
     requirements_files_dev: tuple[str, ...],
     known_first_party: tuple[str, ...],
     json_output: str,
+    github_output: bool,
+    github_warning_errors: tuple[str, ...],
     package_module_name_map: MutableMapping[str, tuple[str, ...]],
     pep621_dev_dependency_groups: tuple[str, ...],
     experimental_namespace_package: bool,
@@ -287,6 +304,8 @@ def cli(
         requirements_files_dev=requirements_files_dev,
         known_first_party=known_first_party,
         json_output=json_output,
+        github_output=github_output,
+        github_warning_errors=list(github_warning_errors),
         package_module_name_map=package_module_name_map,
         pep621_dev_dependency_groups=pep621_dev_dependency_groups,
         experimental_namespace_package=experimental_namespace_package,

python/deptry/core.py

@@ -11,7 +11,7 @@
 from deptry.imports.extract import get_imported_modules_from_list_of_files
 from deptry.module import ModuleBuilder, ModuleLocations
 from deptry.python_file_finder import get_all_python_files_in
-from deptry.reporters import JSONReporter, TextReporter
+from deptry.reporters import GithubReporter, JSONReporter, TextReporter
 from deptry.stdlibs import STDLIBS_PYTHON
 from deptry.violations.finder import find_violations
 
@@ -42,6 +42,8 @@
     package_module_name_map: Mapping[str, tuple[str, ...]]
     pep621_dev_dependency_groups: tuple[str, ...]
     experimental_namespace_package: bool
+    github_output: bool
+    github_warning_errors: list[str]
 
     def run(self) -> None:
         self._log_config()
@@ -89,6 +91,9 @@
         if self.json_output:
             JSONReporter(violations, self.json_output).report()
 
+        if self.github_output:
+            GithubReporter(violations, warning_ids=self.github_warning_errors).report()
+
         self._exit(violations)
 
     def _find_python_files(self) -> list[Path]:

python/deptry/reporters/__init__.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
+from deptry.reporters.github import GithubReporter
 from deptry.reporters.json import JSONReporter
 from deptry.reporters.text import TextReporter
 
-__all__ = ("JSONReporter", "TextReporter")
+__all__ = ("GithubReporter", "JSONReporter", "TextReporter")

python/deptry/reporters/github.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from deptry.reporters.base import Reporter
+
+if TYPE_CHECKING:
+    from deptry.violations import Violation
+
+
+@dataclass
+class GithubReporter(Reporter):
+    warning_ids: list[str] = field(default_factory=list)  # list of error codes to print as warnings
+
+    def report(self) -> None:
+        self._log_and_exit()
+
+    def _log_and_exit(self) -> None:
+        self._log_violations(self.violations)
+
+    def _log_violations(self, violations: list[Violation]) -> None:
+        for violation in violations:
+            self._print_github_annotation(violation)
+
+    def _print_github_annotation(self, violation: Violation) -> None:
+        annotation_severity = "warning" if violation.error_code in self.warning_ids else "error"
+        file_name = violation.location.file
+        if violation.location.line is not None and violation.location.column is not None:
+            ret = _build_workflow_command(
+                annotation_severity,
+                str(file_name),
+                violation.location.line,
+                column=violation.location.column,
+                title=violation.error_code,
+                message=violation.get_error_message(),
+            )
+            print(ret)  # noqa: T201
+
+
+def _build_workflow_command(
+    command_name: str,
+    file: str,
+    line: int,
+    end_line: int | None = None,
+    column: int | None = None,
+    end_column: int | None = None,
+    title: str | None = None,
+    message: str | None = None,
+) -> str:
+    """Build a command to annotate a workflow."""
+    result = f"::{command_name} "
+
+    entries = [
+        ("file", file),
+        ("line", line),
+        ("endLine", end_line),
+        ("col", column),
+        ("endColumn", end_column),
+        ("title", title),
+    ]
+
+    result = result + ",".join(f"{k}={v}" for k, v in entries if v is not None)
+
+    if message is not None:
+        result = result + "::" + _escape(message)
+
+    return result
+
+
+def _escape(s: str) -> str:
+    return s.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")

tests/unit/reporters/test_github.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import io
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+from deptry.imports.location import Location
+from deptry.module import Module
+from deptry.reporters.github import GithubReporter, _build_workflow_command, _escape
+from deptry.violations import DEP001MissingDependencyViolation
+
+if TYPE_CHECKING:
+    from deptry.violations import Violation
+
+# Extract violation instance as a parameter
+violation_instance = DEP001MissingDependencyViolation(
+    Module("foo", package="foo-package"), Location(Path("foo.py"), 1, 2)
+)
+
+expected_warning = _build_workflow_command(
+    "warning",
+    "foo.py",
+    1,
+    column=2,
+    title="DEP001",
+    message="'foo' imported but missing from the dependency definitions",
+)
+
+expected_error = _build_workflow_command(
+    "error", "foo.py", 1, column=2, title="DEP001", message="'foo' imported but missing from the dependency definitions"
+)
+
+
+@pytest.mark.parametrize(
+    ("violation", "warning_ids", "expected"),
+    [
+        (violation_instance, ["DEP001"], expected_warning),
+        (violation_instance, [], expected_error),
+    ],
+)
+def test_github_annotation(
+    monkeypatch: pytest.MonkeyPatch, violation: Violation, warning_ids: list[str], expected: str
+) -> None:
+    reporter = GithubReporter(violations=[violation], warning_ids=warning_ids)
+
+    captured_output = io.StringIO()
+    monkeypatch.setattr(sys, "stdout", captured_output)
+
+    reporter.report()
+    output = captured_output.getvalue().strip()
+    assert output == expected
+
+
+def test_build_workflow_command_escaping() -> None:
+    # Directly test _build_workflow_command with characters needing escape.
+    message = "Error % occurred\r\nNew line"
+    escaped_message = _escape(message)
+    command = _build_workflow_command("warning", "file.py", 10, column=2, title="TEST", message=message)
+    assert "::warning file=file.py,line=10,col=2,title=TEST::" in command
+    assert escaped_message in command

tests/unit/test_core.py

@@ -129,6 +129,8 @@ def test__get_local_modules(
                 pep621_dev_dependency_groups=(),
                 using_default_requirements_files=True,
                 experimental_namespace_package=experimental_namespace_package,
+                github_output=False,
+                github_warning_errors=[],
             )._get_local_modules()
             == expected
         )