Skip to content

formatters

ruff_sync.formatters

Output formatters for CLI results.

LOGGER module-attribute 

LOGGER = getLogger(__name__)

ResultFormatter

Bases: Protocol

Protocol for output formatters.

Streaming formatters (Text, GitHub, JSON) implement note / info / success / error / warning / debug / diff and provide a no-op finalize.

Accumulating formatters (GitLab, SARIF) collect issues during the run and write their structured report in finalize. finalize is always called by the CLI in a try...finally block, so all formatters receive it unconditionally.

Source code in src/ruff_sync/formatters.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
class ResultFormatter(Protocol):
    """Protocol for output formatters.

    Streaming formatters (Text, GitHub, JSON) implement ``note`` / ``info`` /
    ``success`` / ``error`` / ``warning`` / ``debug`` / ``diff`` and provide a
    no-op ``finalize``.

    Accumulating formatters (GitLab, SARIF) collect issues during the run and
    write their structured report in ``finalize``.  ``finalize`` is always
    called by the CLI in a ``try...finally`` block, so all formatters receive
    it unconditionally.
    """

    def note(self, message: str) -> None:
        """Print a status note (unconditional)."""

    def info(self, message: str, logger: logging.Logger | None = None) -> None:
        """Print an informational message."""

    def success(self, message: str) -> None:
        """Print a success message."""

    def error(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Print an error message.

        Args:
            message: Human-readable description of the issue.
            file_path: Path to the file that contains the issue.
            logger: Optional logger to use instead of the module logger.
            check_name: Machine-readable rule ID (used by structured formatters).
            drift_key: Dotted TOML key that drifted, e.g. ``"lint.select"``.
                Used by structured formatters to build stable fingerprints.
        """

    def warning(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Print a warning message.

        Args:
            message: Human-readable description of the issue.
            file_path: Path to the file that contains the issue.
            logger: Optional logger to use instead of the module logger.
            check_name: Machine-readable rule ID (used by structured formatters).
            drift_key: Dotted TOML key that drifted, e.g. ``"lint.select"``.
                Used by structured formatters to build stable fingerprints.
        """

    def debug(self, message: str, logger: logging.Logger | None = None) -> None:
        """Print a debug message."""

    def diff(self, diff_text: str) -> None:
        """Print a unified diff between configurations.

        Note:
            Structured (accumulating) formatters intentionally ignore this
            method — diffs are not representable in JSON report schemas.
        """

    def finalize(self) -> None:
        """Finalize and flush all output.

        Streaming formatters (Text, GitHub, JSON) implement this as a no-op.
        Accumulating formatters (GitLab, SARIF) write their collected report
        here.  The CLI calls this unconditionally inside a ``try...finally``
        block so it is always executed, even when an exception occurred.
        """

note 

note(message)

Print a status note (unconditional).

Source code in src/ruff_sync/formatters.py 
33
34
def note(self, message: str) -> None:
    """Print a status note (unconditional)."""

info 

info(message, logger=None)

Print an informational message.

Source code in src/ruff_sync/formatters.py 
36
37
def info(self, message: str, logger: logging.Logger | None = None) -> None:
    """Print an informational message."""

success 

success(message)

Print a success message.

Source code in src/ruff_sync/formatters.py 
39
40
def success(self, message: str) -> None:
    """Print a success message."""

error 

error(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Print an error message.

Parameters:

Name Type Description Default
message str

Human-readable description of the issue.

 required
file_path Path | None

Path to the file that contains the issue.

 None
logger Logger | None

Optional logger to use instead of the module logger.

 None
check_name str

Machine-readable rule ID (used by structured formatters).

 _DEFAULT_CHECK_NAME
drift_key str | None

Dotted TOML key that drifted, e.g. "lint.select". Used by structured formatters to build stable fingerprints.

 None
Source code in src/ruff_sync/formatters.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def error(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Print an error message.

    Args:
        message: Human-readable description of the issue.
        file_path: Path to the file that contains the issue.
        logger: Optional logger to use instead of the module logger.
        check_name: Machine-readable rule ID (used by structured formatters).
        drift_key: Dotted TOML key that drifted, e.g. ``"lint.select"``.
            Used by structured formatters to build stable fingerprints.
    """

warning 

warning(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Print a warning message.

Parameters:

Name Type Description Default
message str

Human-readable description of the issue.

 required
file_path Path | None

Path to the file that contains the issue.

 None
logger Logger | None

Optional logger to use instead of the module logger.

 None
check_name str

Machine-readable rule ID (used by structured formatters).

 _DEFAULT_CHECK_NAME
drift_key str | None

Dotted TOML key that drifted, e.g. "lint.select". Used by structured formatters to build stable fingerprints.

 None
Source code in src/ruff_sync/formatters.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def warning(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Print a warning message.

    Args:
        message: Human-readable description of the issue.
        file_path: Path to the file that contains the issue.
        logger: Optional logger to use instead of the module logger.
        check_name: Machine-readable rule ID (used by structured formatters).
        drift_key: Dotted TOML key that drifted, e.g. ``"lint.select"``.
            Used by structured formatters to build stable fingerprints.
    """

debug 

debug(message, logger=None)

Print a debug message.

Source code in src/ruff_sync/formatters.py 
80
81
def debug(self, message: str, logger: logging.Logger | None = None) -> None:
    """Print a debug message."""

diff 

diff(diff_text)

Print a unified diff between configurations.

Note

Structured (accumulating) formatters intentionally ignore this method — diffs are not representable in JSON report schemas.

Source code in src/ruff_sync/formatters.py 
83
84
85
86
87
88
89
def diff(self, diff_text: str) -> None:
    """Print a unified diff between configurations.

    Note:
        Structured (accumulating) formatters intentionally ignore this
        method — diffs are not representable in JSON report schemas.
    """

finalize 

finalize()

Finalize and flush all output.

Streaming formatters (Text, GitHub, JSON) implement this as a no-op. Accumulating formatters (GitLab, SARIF) write their collected report here. The CLI calls this unconditionally inside a try...finally block so it is always executed, even when an exception occurred.

Source code in src/ruff_sync/formatters.py 
91
92
93
94
95
96
97
98
def finalize(self) -> None:
    """Finalize and flush all output.

    Streaming formatters (Text, GitHub, JSON) implement this as a no-op.
    Accumulating formatters (GitLab, SARIF) write their collected report
    here.  The CLI calls this unconditionally inside a ``try...finally``
    block so it is always executed, even when an exception occurred.
    """

TextFormatter

Standard text output formatter.

Delegates diagnostic messages (info, warning, error, debug) to the project logger to ensure they benefit from standard logging configuration (colors, streams). Primary command feedback (note, success) is printed to stdout.

Source code in src/ruff_sync/formatters.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
class TextFormatter:
    """Standard text output formatter.

    Delegates diagnostic messages (info, warning, error, debug) to the project
    logger to ensure they benefit from standard logging configuration (colors,
    streams).  Primary command feedback (note, success) is printed to stdout.
    """

    def note(self, message: str) -> None:
        """Print a status note to stdout."""
        print(message)

    def info(self, message: str, logger: logging.Logger | None = None) -> None:
        """Log an info message."""
        (logger or LOGGER).info(message)

    def success(self, message: str) -> None:
        """Print a success message to stdout."""
        print(message)

    def error(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Log an error message."""
        (logger or LOGGER).error(message)

    def warning(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Log a warning message."""
        (logger or LOGGER).warning(message)

    def debug(self, message: str, logger: logging.Logger | None = None) -> None:
        """Log a debug message."""
        (logger or LOGGER).debug(message)

    def diff(self, diff_text: str) -> None:
        """Print a unified diff directly to stdout."""
        print(diff_text, end="")

    def finalize(self) -> None:
        """No-op for streaming formatters."""

note 

note(message)

Print a status note to stdout.

Source code in src/ruff_sync/formatters.py 
109
110
111
def note(self, message: str) -> None:
    """Print a status note to stdout."""
    print(message)

info 

info(message, logger=None)

Log an info message.

Source code in src/ruff_sync/formatters.py 
113
114
115
def info(self, message: str, logger: logging.Logger | None = None) -> None:
    """Log an info message."""
    (logger or LOGGER).info(message)

success 

success(message)

Print a success message to stdout.

Source code in src/ruff_sync/formatters.py 
117
118
119
def success(self, message: str) -> None:
    """Print a success message to stdout."""
    print(message)

error 

error(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Log an error message.

Source code in src/ruff_sync/formatters.py 
121
122
123
124
125
126
127
128
129
130
def error(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Log an error message."""
    (logger or LOGGER).error(message)

warning 

warning(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Log a warning message.

Source code in src/ruff_sync/formatters.py 
132
133
134
135
136
137
138
139
140
141
def warning(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Log a warning message."""
    (logger or LOGGER).warning(message)

debug 

debug(message, logger=None)

Log a debug message.

Source code in src/ruff_sync/formatters.py 
143
144
145
def debug(self, message: str, logger: logging.Logger | None = None) -> None:
    """Log a debug message."""
    (logger or LOGGER).debug(message)

diff 

diff(diff_text)

Print a unified diff directly to stdout.

Source code in src/ruff_sync/formatters.py 
147
148
149
def diff(self, diff_text: str) -> None:
    """Print a unified diff directly to stdout."""
    print(diff_text, end="")

finalize 

finalize()

No-op for streaming formatters.

Source code in src/ruff_sync/formatters.py 
151
152
def finalize(self) -> None:
    """No-op for streaming formatters."""

GithubIssue

Bases: TypedDict

GitHub Action output issue.

Source code in src/ruff_sync/formatters.py 
155
156
157
158
159
160
161
class GithubIssue(TypedDict):
    """GitHub Action output issue."""

    level: Literal["error", "warning"]
    message: str
    file_path: pathlib.Path | None
    drift_key: str | None

level instance-attribute 

level

message instance-attribute 

message

file_path instance-attribute 

file_path

drift_key instance-attribute 

drift_key

GithubFormatter

GitHub Actions output formatter.

Emits ::error:: and ::warning:: workflow commands for inline annotations, and writes a Markdown report to GITHUB_STEP_SUMMARY.

Source code in src/ruff_sync/formatters.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
class GithubFormatter:
    """GitHub Actions output formatter.

    Emits ``::error::`` and ``::warning::`` workflow commands for inline
    annotations, and writes a Markdown report to ``GITHUB_STEP_SUMMARY``.
    """

    _DEFAULT_PATH: Final[pathlib.Path] = pathlib.Path(RuffConfigFileName.PYPROJECT_TOML)

    def __init__(self) -> None:
        """Initialise an empty issue list."""
        self._errors: list[GithubIssue] = []
        self._warnings: list[GithubIssue] = []

    @staticmethod
    def _escape(value: str, is_property: bool = False) -> str:
        r"""Escapes characters for GitHub Actions workflow commands.

        GitHub requires percent-encoding for '%', '\r', and '\n' in all
        messages.  Additionally, property values (like file and title) require
        escaping for ':' and ','.
        """
        escaped = value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
        if is_property:
            return escaped.replace(":", "%3A").replace(",", "%2C")
        return escaped

    @staticmethod
    def _strip_status_prefix(message: str) -> str:
        """Return the message without leading status emoji (e.g. ❌, ⚠️)."""
        return message.removeprefix("❌ ").removeprefix("⚠️ ")

    def note(self, message: str) -> None:
        """Print a status note (standard stdout)."""
        print(message)

    def info(self, message: str, logger: logging.Logger | None = None) -> None:
        """Print an info message (delegates to logger)."""
        (logger or LOGGER).info(message)

    def success(self, message: str) -> None:
        """Print a success message (standard stdout)."""
        print(message)

    def error(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Accumulate an error-level finding."""
        # Delegate standard log output to the logger to preserve context
        (logger or LOGGER).error(message)
        self._errors.append(
            {
                "level": "error",
                "message": message,
                "file_path": file_path,
                "drift_key": drift_key,
            }
        )

    def warning(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Accumulate a warning-level finding."""
        (logger or LOGGER).warning(message)
        self._warnings.append(
            {
                "level": "warning",
                "message": message,
                "file_path": file_path,
                "drift_key": drift_key,
            }
        )

    def debug(self, message: str, logger: logging.Logger | None = None) -> None:
        """Print a debug message as a GitHub Action debug annotation."""
        (logger or LOGGER).debug(message)
        escaped_msg = self._escape(message)
        print(f"::debug::{escaped_msg}")

    def diff(self, diff_text: str) -> None:
        """Print a unified diff in GitHub Actions logs (standard stdout)."""
        print(diff_text, end="")

    def finalize(self) -> None:
        """Finalize and emit all accumulated issues as GitHub workflow commands.

        If multiple issues exist for a single file/level, they are combined into
        a single multi-line annotation to reduce visual noise.

        A Markdown summary is also written to ``GITHUB_STEP_SUMMARY`` if the
        environment variable is set.
        """
        all_issues = self._errors + self._warnings

        # 1. Emit Inline Annotations
        self._emit_annotations()

        # 2. Write Step Summary
        self._write_summary(all_issues)

    def _emit_annotations(self) -> None:
        """Group and emit issues as GitHub Action workflow commands."""
        for level, issues in [("error", self._errors), ("warning", self._warnings)]:
            # Group by file path object
            by_file: dict[pathlib.Path, list[GithubIssue]] = {}
            for issue in issues:
                file_key = issue["file_path"] or self._DEFAULT_PATH
                by_file.setdefault(file_key, []).append(issue)

            for file_path, file_issues in by_file.items():
                if not file_issues:
                    continue

                title_prefix = "Error" if level == "error" else "Warning"
                title_val = self._escape(f"Ruff Sync {title_prefix}", is_property=True)
                file_val = self._escape(str(file_path), is_property=True)
                file_arg = f"file={file_val},line=1,"

                if len(file_issues) == 1:
                    issue = file_issues[0]
                    clean_msg = self._strip_status_prefix(issue["message"])
                    escaped_msg = self._escape(clean_msg)
                else:
                    # Combine into a single bulleted annotation
                    combined_msg = f"Multiple ruff-sync {level}s in {file_path}:"
                    for issue in file_issues:
                        clean_line = self._strip_status_prefix(issue["message"])
                        combined_msg += f"\n- {clean_line}"
                    escaped_msg = self._escape(combined_msg)

                print(f"::{level} {file_arg}title={title_val}::{escaped_msg}")

    def _write_summary(self, all_issues: list[GithubIssue]) -> None:
        """Write a Markdown report to the GitHub Step Summary file."""
        summary_file = os.environ.get("GITHUB_STEP_SUMMARY")
        if not summary_file or not all_issues:
            return

        summary_path = pathlib.Path(summary_file)
        try:
            with summary_path.open("a", encoding="utf-8") as f:
                f.write("### 🔄 Ruff-Sync Drift Report\n\n")
                f.write("| Severity | Key | Message | File |\n")
                f.write("| :--- | :--- | :--- | :--- |\n")
                for issue in all_issues:
                    severity = "❌ Error" if issue["level"] == "error" else "⚠️ Warning"
                    key = issue["drift_key"] or "-"
                    clean_msg = self._strip_status_prefix(issue["message"])
                    file_path = issue["file_path"] or self._DEFAULT_PATH
                    f.write(f"| {severity} | `{key}` | {clean_msg} | `{file_path.name}` |\n")
                f.write("\n")
        except OSError:
            LOGGER.exception(f"Failed to write to GITHUB_STEP_SUMMARY: {summary_file}")

__init__ 

__init__()

Initialise an empty issue list.

Source code in src/ruff_sync/formatters.py 
173
174
175
176
def __init__(self) -> None:
    """Initialise an empty issue list."""
    self._errors: list[GithubIssue] = []
    self._warnings: list[GithubIssue] = []

note 

note(message)

Print a status note (standard stdout).

Source code in src/ruff_sync/formatters.py 
196
197
198
def note(self, message: str) -> None:
    """Print a status note (standard stdout)."""
    print(message)

info 

info(message, logger=None)

Print an info message (delegates to logger).

Source code in src/ruff_sync/formatters.py 
200
201
202
def info(self, message: str, logger: logging.Logger | None = None) -> None:
    """Print an info message (delegates to logger)."""
    (logger or LOGGER).info(message)

success 

success(message)

Print a success message (standard stdout).

Source code in src/ruff_sync/formatters.py 
204
205
206
def success(self, message: str) -> None:
    """Print a success message (standard stdout)."""
    print(message)

error 

error(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Accumulate an error-level finding.

Source code in src/ruff_sync/formatters.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
def error(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Accumulate an error-level finding."""
    # Delegate standard log output to the logger to preserve context
    (logger or LOGGER).error(message)
    self._errors.append(
        {
            "level": "error",
            "message": message,
            "file_path": file_path,
            "drift_key": drift_key,
        }
    )

warning 

warning(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Accumulate a warning-level finding.

Source code in src/ruff_sync/formatters.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
def warning(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Accumulate a warning-level finding."""
    (logger or LOGGER).warning(message)
    self._warnings.append(
        {
            "level": "warning",
            "message": message,
            "file_path": file_path,
            "drift_key": drift_key,
        }
    )

debug 

debug(message, logger=None)

Print a debug message as a GitHub Action debug annotation.

Source code in src/ruff_sync/formatters.py 
247
248
249
250
251
def debug(self, message: str, logger: logging.Logger | None = None) -> None:
    """Print a debug message as a GitHub Action debug annotation."""
    (logger or LOGGER).debug(message)
    escaped_msg = self._escape(message)
    print(f"::debug::{escaped_msg}")

diff 

diff(diff_text)

Print a unified diff in GitHub Actions logs (standard stdout).

Source code in src/ruff_sync/formatters.py 
253
254
255
def diff(self, diff_text: str) -> None:
    """Print a unified diff in GitHub Actions logs (standard stdout)."""
    print(diff_text, end="")

finalize 

finalize()

Finalize and emit all accumulated issues as GitHub workflow commands.

If multiple issues exist for a single file/level, they are combined into a single multi-line annotation to reduce visual noise.

A Markdown summary is also written to GITHUB_STEP_SUMMARY if the environment variable is set.

Source code in src/ruff_sync/formatters.py 
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
def finalize(self) -> None:
    """Finalize and emit all accumulated issues as GitHub workflow commands.

    If multiple issues exist for a single file/level, they are combined into
    a single multi-line annotation to reduce visual noise.

    A Markdown summary is also written to ``GITHUB_STEP_SUMMARY`` if the
    environment variable is set.
    """
    all_issues = self._errors + self._warnings

    # 1. Emit Inline Annotations
    self._emit_annotations()

    # 2. Write Step Summary
    self._write_summary(all_issues)

JsonFormatter

JSON output formatter (newline-delimited JSON, one record per line).

Source code in src/ruff_sync/formatters.py 
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
class JsonFormatter:
    """JSON output formatter (newline-delimited JSON, one record per line)."""

    def note(self, message: str) -> None:
        """Print a status note as JSON."""
        print(json.dumps({"level": "note", "message": message}))

    def info(self, message: str, logger: logging.Logger | None = None) -> None:
        """Print an info message as JSON."""
        data = {"level": "info", "message": message}
        if logger:
            data["logger"] = logger.name
        print(json.dumps(data))

    def success(self, message: str) -> None:
        """Print a success message as JSON."""
        print(json.dumps({"level": "success", "message": message}))

    def error(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Print an error message as JSON."""
        data = {"level": "error", "message": message}
        if file_path:
            data["file"] = str(file_path)
        if logger:
            data["logger"] = logger.name
        if drift_key:
            data["drift_key"] = drift_key
        data["check_name"] = check_name
        print(json.dumps(data))

    def warning(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Print a warning message as JSON."""
        data = {"level": "warning", "message": message}
        if file_path:
            data["file"] = str(file_path)
        if logger:
            data["logger"] = logger.name
        if drift_key:
            data["drift_key"] = drift_key
        data["check_name"] = check_name
        print(json.dumps(data))

    def debug(self, message: str, logger: logging.Logger | None = None) -> None:
        """Print a debug message as JSON."""
        data = {"level": "debug", "message": message}
        if logger:
            data["logger"] = logger.name
        print(json.dumps(data))

    def diff(self, diff_text: str) -> None:
        """Print a unified diff as JSON."""
        # Strip trailing newline if any, as it's common in diff text
        print(json.dumps({"level": "diff", "message": diff_text.strip()}))

    def finalize(self) -> None:
        """No-op for streaming formatters."""

note 

note(message)

Print a status note as JSON.

Source code in src/ruff_sync/formatters.py 
332
333
334
def note(self, message: str) -> None:
    """Print a status note as JSON."""
    print(json.dumps({"level": "note", "message": message}))

info 

info(message, logger=None)

Print an info message as JSON.

Source code in src/ruff_sync/formatters.py 
336
337
338
339
340
341
def info(self, message: str, logger: logging.Logger | None = None) -> None:
    """Print an info message as JSON."""
    data = {"level": "info", "message": message}
    if logger:
        data["logger"] = logger.name
    print(json.dumps(data))

success 

success(message)

Print a success message as JSON.

Source code in src/ruff_sync/formatters.py 
343
344
345
def success(self, message: str) -> None:
    """Print a success message as JSON."""
    print(json.dumps({"level": "success", "message": message}))

error 

error(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Print an error message as JSON.

Source code in src/ruff_sync/formatters.py 
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
def error(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Print an error message as JSON."""
    data = {"level": "error", "message": message}
    if file_path:
        data["file"] = str(file_path)
    if logger:
        data["logger"] = logger.name
    if drift_key:
        data["drift_key"] = drift_key
    data["check_name"] = check_name
    print(json.dumps(data))

warning 

warning(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Print a warning message as JSON.

Source code in src/ruff_sync/formatters.py 
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
def warning(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Print a warning message as JSON."""
    data = {"level": "warning", "message": message}
    if file_path:
        data["file"] = str(file_path)
    if logger:
        data["logger"] = logger.name
    if drift_key:
        data["drift_key"] = drift_key
    data["check_name"] = check_name
    print(json.dumps(data))

debug 

debug(message, logger=None)

Print a debug message as JSON.

Source code in src/ruff_sync/formatters.py 
385
386
387
388
389
390
def debug(self, message: str, logger: logging.Logger | None = None) -> None:
    """Print a debug message as JSON."""
    data = {"level": "debug", "message": message}
    if logger:
        data["logger"] = logger.name
    print(json.dumps(data))

diff 

diff(diff_text)

Print a unified diff as JSON.

Source code in src/ruff_sync/formatters.py 
392
393
394
395
def diff(self, diff_text: str) -> None:
    """Print a unified diff as JSON."""
    # Strip trailing newline if any, as it's common in diff text
    print(json.dumps({"level": "diff", "message": diff_text.strip()}))

finalize 

finalize()

No-op for streaming formatters.

Source code in src/ruff_sync/formatters.py 
397
398
def finalize(self) -> None:
    """No-op for streaming formatters."""

GitlabLines

Bases: TypedDict

GitLab Code Quality report lines.

Source code in src/ruff_sync/formatters.py 
401
402
403
404
class GitlabLines(TypedDict):
    """GitLab Code Quality report lines."""

    begin: int

begin instance-attribute 

begin

GitlabLocation

Bases: TypedDict

GitLab Code Quality report location.

Source code in src/ruff_sync/formatters.py 
407
408
409
410
411
class GitlabLocation(TypedDict):
    """GitLab Code Quality report location."""

    path: str
    lines: GitlabLines

path instance-attribute 

path

lines instance-attribute 

lines

GitlabIssue

Bases: TypedDict

GitLab Code Quality report issue.

Source code in src/ruff_sync/formatters.py 
414
415
416
417
418
419
420
421
class GitlabIssue(TypedDict):
    """GitLab Code Quality report issue."""

    description: str
    check_name: str
    fingerprint: str
    severity: Literal["info", "minor", "major", "critical", "blocker"]
    location: GitlabLocation

description instance-attribute 

description

check_name instance-attribute 

check_name

fingerprint instance-attribute 

fingerprint

severity instance-attribute 

severity

location instance-attribute 

location

GitlabFormatter

GitLab Code Quality report formatter.

Accumulates issues during the run and writes a single valid JSON array to stdout in finalize(). The CI job redirects stdout to a file::

ruff-sync check --output-format gitlab > gl-code-quality-report.json

An empty array ([]) is emitted when no issues were collected, which signals to GitLab that previously reported issues are now resolved.

Fingerprints are deterministic MD5 hashes so GitLab can track whether an issue was introduced or resolved between branches.

Source code in src/ruff_sync/formatters.py 
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
class GitlabFormatter:
    """GitLab Code Quality report formatter.

    Accumulates issues during the run and writes a single valid JSON array to
    stdout in ``finalize()``.  The CI job redirects stdout to a file::

        ruff-sync check --output-format gitlab > gl-code-quality-report.json

    An empty array (``[]``) is emitted when no issues were collected, which
    signals to GitLab that previously reported issues are now resolved.

    Fingerprints are deterministic MD5 hashes so GitLab can track whether an
    issue was introduced or resolved between branches.
    """

    def __init__(self) -> None:
        """Initialise an empty issue list."""
        self._issues: list[GitlabIssue] = []

    # ------------------------------------------------------------------
    # Protocol methods
    # ------------------------------------------------------------------

    def note(self, message: str) -> None:
        """Delegate to logger only; not representable in the Code Quality schema."""
        LOGGER.info(message)

    def info(self, message: str, logger: logging.Logger | None = None) -> None:
        """Delegate to logger only; not included in the structured report."""
        (logger or LOGGER).info(message)

    def success(self, message: str) -> None:
        """Delegate to logger only; not representable in the Code Quality schema."""
        LOGGER.info(message)

    def error(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Accumulate a major-severity Code Quality issue."""
        (logger or LOGGER).error(message)
        self._issues.append(
            self._make_issue(
                description=message,
                check_name=check_name,
                severity="major",
                file_path=file_path,
                drift_key=drift_key,
            )
        )

    def warning(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Accumulate a minor-severity Code Quality issue."""
        (logger or LOGGER).warning(message)
        self._issues.append(
            self._make_issue(
                description=message,
                check_name=check_name,
                severity="minor",
                file_path=file_path,
                drift_key=drift_key,
            )
        )

    def debug(self, message: str, logger: logging.Logger | None = None) -> None:
        """Delegate to logger only; not included in the structured report."""
        (logger or LOGGER).debug(message)

    def diff(self, diff_text: str) -> None:
        """Ignored by structured formatters — diffs are not representable in JSON report schemas."""

    def finalize(self) -> None:
        """Write the collected issues as a GitLab Code Quality JSON array to stdout.

        Always produces valid JSON: an empty array ``[]`` when no issues were
        collected (signals resolution of previously reported issues to GitLab).
        """
        print(json.dumps(self._issues, indent=2))

    # ------------------------------------------------------------------
    # Internal helpers
    # ------------------------------------------------------------------

    def _make_issue(
        self,
        description: str,
        check_name: str,
        severity: Literal["info", "minor", "major", "critical", "blocker"],
        file_path: pathlib.Path | None,
        drift_key: str | None,
    ) -> GitlabIssue:
        """Build a single Code Quality issue object."""
        # Normalize location.path to be relative to the repo root (no absolute paths).
        if file_path:
            if file_path.is_absolute():
                try:
                    path = str(file_path.relative_to(pathlib.Path.cwd()))
                except ValueError:
                    # If the absolute path is outside the CWD (repo root in CI),
                    # fall back to the filename so GitLab can at least attempt a map.
                    path = file_path.name
            else:
                path = str(file_path)
        else:
            path = "pyproject.toml"

        return {
            "description": description,
            "check_name": check_name,
            "fingerprint": self._make_fingerprint(path, check_name, drift_key),
            "severity": severity,
            "location": {"path": path, "lines": {"begin": 1}},
        }

    @staticmethod
    def _make_fingerprint(path: str, check_name: str, drift_key: str | None) -> str:
        """Return a stable MD5 fingerprint for a Code Quality issue.

        The fingerprint must be deterministic (same inputs → same output on
        every pipeline run) so GitLab can track introduced vs resolved issues.
        Never include timestamps, UUIDs, or any other runtime-variable data.
        """
        # Include check_name to prevent collisions if multiple rules trigger on the same key.
        raw = f"ruff-sync:{check_name}:{path}:{drift_key or ''}"
        return hashlib.md5(raw.encode()).hexdigest()  # noqa: S324

__init__ 

__init__()

Initialise an empty issue list.

Source code in src/ruff_sync/formatters.py 
439
440
441
def __init__(self) -> None:
    """Initialise an empty issue list."""
    self._issues: list[GitlabIssue] = []

note 

note(message)

Delegate to logger only; not representable in the Code Quality schema.

Source code in src/ruff_sync/formatters.py 
447
448
449
def note(self, message: str) -> None:
    """Delegate to logger only; not representable in the Code Quality schema."""
    LOGGER.info(message)

info 

info(message, logger=None)

Delegate to logger only; not included in the structured report.

Source code in src/ruff_sync/formatters.py 
451
452
453
def info(self, message: str, logger: logging.Logger | None = None) -> None:
    """Delegate to logger only; not included in the structured report."""
    (logger or LOGGER).info(message)

success 

success(message)

Delegate to logger only; not representable in the Code Quality schema.

Source code in src/ruff_sync/formatters.py 
455
456
457
def success(self, message: str) -> None:
    """Delegate to logger only; not representable in the Code Quality schema."""
    LOGGER.info(message)

error 

error(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Accumulate a major-severity Code Quality issue.

Source code in src/ruff_sync/formatters.py 
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
def error(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Accumulate a major-severity Code Quality issue."""
    (logger or LOGGER).error(message)
    self._issues.append(
        self._make_issue(
            description=message,
            check_name=check_name,
            severity="major",
            file_path=file_path,
            drift_key=drift_key,
        )
    )

warning 

warning(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Accumulate a minor-severity Code Quality issue.

Source code in src/ruff_sync/formatters.py 
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
def warning(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Accumulate a minor-severity Code Quality issue."""
    (logger or LOGGER).warning(message)
    self._issues.append(
        self._make_issue(
            description=message,
            check_name=check_name,
            severity="minor",
            file_path=file_path,
            drift_key=drift_key,
        )
    )

debug 

debug(message, logger=None)

Delegate to logger only; not included in the structured report.

Source code in src/ruff_sync/formatters.py 
499
500
501
def debug(self, message: str, logger: logging.Logger | None = None) -> None:
    """Delegate to logger only; not included in the structured report."""
    (logger or LOGGER).debug(message)

diff 

diff(diff_text)

Ignored by structured formatters — diffs are not representable in JSON report schemas.

Source code in src/ruff_sync/formatters.py 
503
504
def diff(self, diff_text: str) -> None:
    """Ignored by structured formatters — diffs are not representable in JSON report schemas."""

finalize 

finalize()

Write the collected issues as a GitLab Code Quality JSON array to stdout.

Always produces valid JSON: an empty array [] when no issues were collected (signals resolution of previously reported issues to GitLab).

Source code in src/ruff_sync/formatters.py 
506
507
508
509
510
511
512
def finalize(self) -> None:
    """Write the collected issues as a GitLab Code Quality JSON array to stdout.

    Always produces valid JSON: an empty array ``[]`` when no issues were
    collected (signals resolution of previously reported issues to GitLab).
    """
    print(json.dumps(self._issues, indent=2))

SarifResult

Bases: TypedDict

A single SARIF result (finding).

Source code in src/ruff_sync/formatters.py 
562
563
564
565
566
567
568
569
570
class SarifResult(TypedDict, total=False):
    """A single SARIF result (finding)."""

    ruleId: str
    level: Literal["error", "warning", "note"]
    message: dict[str, str]
    locations: list[dict[str, Any]]
    fingerprints: dict[str, str]
    properties: dict[str, str]

ruleId instance-attribute 

ruleId

level instance-attribute 

level

message instance-attribute 

message

locations instance-attribute 

locations

fingerprints instance-attribute 

fingerprints

properties instance-attribute 

properties

SarifFormatter

SARIF v2.1.0 output formatter.

Accumulates results during the run and writes a complete SARIF document to stdout in finalize(). The CI job redirects stdout to a file::

ruff-sync check --output-format sarif > results.sarif

An empty results list is emitted when no issues were found.

Schema: https://json.schemastore.org/sarif-2.1.0.json

Source code in src/ruff_sync/formatters.py 
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
class SarifFormatter:
    """SARIF v2.1.0 output formatter.

    Accumulates results during the run and writes a complete SARIF document to
    stdout in ``finalize()``.  The CI job redirects stdout to a file::

        ruff-sync check --output-format sarif > results.sarif

    An empty ``results`` list is emitted when no issues were found.

    Schema: https://json.schemastore.org/sarif-2.1.0.json
    """

    _RULE_ID: Final[str] = "RUFF-SYNC-CONFIG-DRIFT"
    _SCHEMA: Final[str] = "https://json.schemastore.org/sarif-2.1.0.json"
    _SARIF_VERSION: Final[str] = "2.1.0"

    def __init__(self) -> None:
        """Initialise with an empty result list."""
        self._results: list[SarifResult] = []

    # ------------------------------------------------------------------
    # Protocol methods
    # ------------------------------------------------------------------

    def note(self, message: str) -> None:
        """Delegate to logger only; not representable in the SARIF schema."""
        LOGGER.info(message)

    def info(self, message: str, logger: logging.Logger | None = None) -> None:
        """Delegate to logger only; not included in the structured report."""
        (logger or LOGGER).info(message)

    def success(self, message: str) -> None:
        """Delegate to logger only; not representable in the SARIF schema."""
        LOGGER.info(message)

    def error(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Accumulate an error-level SARIF result."""
        (logger or LOGGER).error(message)
        self._results.append(
            self._make_result(
                message=message,
                level="error",
                file_path=file_path,
                check_name=check_name,
                drift_key=drift_key,
            )
        )

    def warning(
        self,
        message: str,
        file_path: pathlib.Path | None = None,
        logger: logging.Logger | None = None,
        check_name: str = _DEFAULT_CHECK_NAME,
        drift_key: str | None = None,
    ) -> None:
        """Accumulate a warning-level SARIF result."""
        (logger or LOGGER).warning(message)
        self._results.append(
            self._make_result(
                message=message,
                level="warning",
                file_path=file_path,
                check_name=check_name,
                drift_key=drift_key,
            )
        )

    def debug(self, message: str, logger: logging.Logger | None = None) -> None:
        """Delegate to logger only; not included in the structured report."""
        (logger or LOGGER).debug(message)

    def diff(self, diff_text: str) -> None:
        """Ignored by structured formatters — diffs are not representable in SARIF."""

    def finalize(self) -> None:
        """Write the collected results as a SARIF v2.1.0 document to stdout.

        Rules are de-duplicated from the accumulated results so the ``rules``
        list contains one entry per unique ``ruleId`` seen across all findings.
        """
        seen_ids: set[str] = set()
        rules: list[dict[str, Any]] = []
        for result in self._results:
            rule_id = result["ruleId"]
            if rule_id not in seen_ids:
                seen_ids.add(rule_id)
                rules.append(
                    {
                        "id": rule_id,
                        "name": "ConfigDrift",
                        "shortDescription": {
                            "text": "Ruff configuration has drifted from upstream."
                        },
                        "helpUri": "https://github.com/Kilo59/ruff-sync",
                    }
                )
        if not rules:
            # No findings — emit a single placeholder rule so the SARIF document
            # is always schema-valid (a tool with zero rules is still valid, but
            # some consumers require at least one rule entry).
            rules = [
                {
                    "id": self._RULE_ID,
                    "name": "ConfigDrift",
                    "shortDescription": {"text": "Ruff configuration has drifted from upstream."},
                    "helpUri": "https://github.com/Kilo59/ruff-sync",
                }
            ]
        sarif_doc: dict[str, Any] = {
            "version": self._SARIF_VERSION,
            "$schema": self._SCHEMA,
            "runs": [
                {
                    "tool": {
                        "driver": {
                            "name": "ruff-sync",
                            "informationUri": "https://github.com/Kilo59/ruff-sync",
                            "rules": rules,
                        }
                    },
                    "results": self._results,
                }
            ],
        }
        print(json.dumps(sarif_doc, indent=2))

    # ------------------------------------------------------------------
    # Internal helpers
    # ------------------------------------------------------------------

    def _make_result(
        self,
        message: str,
        level: Literal["error", "warning", "note"],
        file_path: pathlib.Path | None,
        check_name: str | None = None,
        drift_key: str | None = None,
    ) -> SarifResult:
        """Build a single SARIF result object.

        Args:
            message: Human-readable finding text.
            level: SARIF severity level.
            file_path: Source file the finding belongs to.
            check_name: Machine-readable rule identifier.  When provided a
                granular ``ruleId`` of the form ``check_name:drift_key`` is
                used so code-scanning UIs can group findings per key.
            drift_key: Dotted TOML key that drifted (e.g. ``"lint.select"``).
                Included in ``properties`` and used to derive a stable fingerprint.
        """
        artifact_uri = _path_to_artifact_uri(file_path)

        # Build a granular ruleId so findings for different keys are
        # distinguishable in code-scanning UIs (e.g. GitHub Advanced Security).
        if drift_key is not None and check_name is not None:
            rule_id = f"{check_name}:{drift_key}"
        elif check_name is not None:
            rule_id = check_name
        else:
            rule_id = self._RULE_ID

        result: SarifResult = {
            "ruleId": rule_id,
            "level": level,
            "message": {"text": message},
            "locations": [
                {
                    "physicalLocation": {
                        "artifactLocation": {"uri": artifact_uri, "uriBaseId": "%SRCROOT%"},
                        "region": {"startLine": 1},
                    }
                }
            ],
        }

        # Populate custom properties for tooling that reads SARIF property bags.
        props: dict[str, str] = {}
        if check_name is not None:
            props["check_name"] = check_name
        if drift_key is not None:
            props["drift_key"] = drift_key
        if props:
            result["properties"] = props

        # Derive a stable fingerprint so consumers can deduplicate across runs.
        # Never include timestamps or UUIDs — only stable, content-derived data.
        fingerprint = self._make_fingerprint(artifact_uri, rule_id, drift_key)
        # Use a custom SARIF fingerprint key to reflect that this is not a line-hash.
        result["fingerprints"] = {"ruff-sync-fingerprint/v1": fingerprint}

        return result

    @staticmethod
    def _make_fingerprint(artifact_uri: str, rule_id: str, drift_key: str | None) -> str:
        """Return a stable MD5 fingerprint for a SARIF result.

        The fingerprint must be deterministic (same inputs → same output on
        every pipeline run) so consumers can track introduced vs resolved
        findings.  Never include timestamps, UUIDs, or any other
        runtime-variable data.
        """
        raw = f"ruff-sync:{rule_id}:{artifact_uri}:{drift_key or ''}"
        return hashlib.md5(raw.encode()).hexdigest()  # noqa: S324

__init__ 

__init__()

Initialise with an empty result list.

Source code in src/ruff_sync/formatters.py 
590
591
592
def __init__(self) -> None:
    """Initialise with an empty result list."""
    self._results: list[SarifResult] = []

note 

note(message)

Delegate to logger only; not representable in the SARIF schema.

Source code in src/ruff_sync/formatters.py 
598
599
600
def note(self, message: str) -> None:
    """Delegate to logger only; not representable in the SARIF schema."""
    LOGGER.info(message)

info 

info(message, logger=None)

Delegate to logger only; not included in the structured report.

Source code in src/ruff_sync/formatters.py 
602
603
604
def info(self, message: str, logger: logging.Logger | None = None) -> None:
    """Delegate to logger only; not included in the structured report."""
    (logger or LOGGER).info(message)

success 

success(message)

Delegate to logger only; not representable in the SARIF schema.

Source code in src/ruff_sync/formatters.py 
606
607
608
def success(self, message: str) -> None:
    """Delegate to logger only; not representable in the SARIF schema."""
    LOGGER.info(message)

error 

error(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Accumulate an error-level SARIF result.

Source code in src/ruff_sync/formatters.py 
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
def error(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Accumulate an error-level SARIF result."""
    (logger or LOGGER).error(message)
    self._results.append(
        self._make_result(
            message=message,
            level="error",
            file_path=file_path,
            check_name=check_name,
            drift_key=drift_key,
        )
    )

warning 

warning(
    message,
    file_path=None,
    logger=None,
    check_name=_DEFAULT_CHECK_NAME,
    drift_key=None,
)

Accumulate a warning-level SARIF result.

Source code in src/ruff_sync/formatters.py 
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
def warning(
    self,
    message: str,
    file_path: pathlib.Path | None = None,
    logger: logging.Logger | None = None,
    check_name: str = _DEFAULT_CHECK_NAME,
    drift_key: str | None = None,
) -> None:
    """Accumulate a warning-level SARIF result."""
    (logger or LOGGER).warning(message)
    self._results.append(
        self._make_result(
            message=message,
            level="warning",
            file_path=file_path,
            check_name=check_name,
            drift_key=drift_key,
        )
    )

debug 

debug(message, logger=None)

Delegate to logger only; not included in the structured report.

Source code in src/ruff_sync/formatters.py 
650
651
652
def debug(self, message: str, logger: logging.Logger | None = None) -> None:
    """Delegate to logger only; not included in the structured report."""
    (logger or LOGGER).debug(message)

diff 

diff(diff_text)

Ignored by structured formatters — diffs are not representable in SARIF.

Source code in src/ruff_sync/formatters.py 
654
655
def diff(self, diff_text: str) -> None:
    """Ignored by structured formatters — diffs are not representable in SARIF."""

finalize 

finalize()

Write the collected results as a SARIF v2.1.0 document to stdout.

Rules are de-duplicated from the accumulated results so the rules list contains one entry per unique ruleId seen across all findings.

Source code in src/ruff_sync/formatters.py 
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
def finalize(self) -> None:
    """Write the collected results as a SARIF v2.1.0 document to stdout.

    Rules are de-duplicated from the accumulated results so the ``rules``
    list contains one entry per unique ``ruleId`` seen across all findings.
    """
    seen_ids: set[str] = set()
    rules: list[dict[str, Any]] = []
    for result in self._results:
        rule_id = result["ruleId"]
        if rule_id not in seen_ids:
            seen_ids.add(rule_id)
            rules.append(
                {
                    "id": rule_id,
                    "name": "ConfigDrift",
                    "shortDescription": {
                        "text": "Ruff configuration has drifted from upstream."
                    },
                    "helpUri": "https://github.com/Kilo59/ruff-sync",
                }
            )
    if not rules:
        # No findings — emit a single placeholder rule so the SARIF document
        # is always schema-valid (a tool with zero rules is still valid, but
        # some consumers require at least one rule entry).
        rules = [
            {
                "id": self._RULE_ID,
                "name": "ConfigDrift",
                "shortDescription": {"text": "Ruff configuration has drifted from upstream."},
                "helpUri": "https://github.com/Kilo59/ruff-sync",
            }
        ]
    sarif_doc: dict[str, Any] = {
        "version": self._SARIF_VERSION,
        "$schema": self._SCHEMA,
        "runs": [
            {
                "tool": {
                    "driver": {
                        "name": "ruff-sync",
                        "informationUri": "https://github.com/Kilo59/ruff-sync",
                        "rules": rules,
                    }
                },
                "results": self._results,
            }
        ],
    }
    print(json.dumps(sarif_doc, indent=2))

get_formatter 

get_formatter(output_format)

Return the corresponding formatter for the given format.

Source code in src/ruff_sync/formatters.py 
804
805
806
807
808
809
810
811
812
813
814
815
816
def get_formatter(output_format: OutputFormat) -> ResultFormatter:
    """Return the corresponding formatter for the given format."""
    match output_format:
        case OutputFormat.TEXT:
            return TextFormatter()
        case OutputFormat.GITHUB:
            return GithubFormatter()
        case OutputFormat.JSON:
            return JsonFormatter()
        case OutputFormat.GITLAB:
            return GitlabFormatter()
        case OutputFormat.SARIF:
            return SarifFormatter()