Diff Writer

The diff writer compares two Header objects and produces structured API compatibility reports. Each change is classified as breaking or non-breaking. Output is available in JSON or Markdown format.

Writer Class

DiffWriter

DiffWriter(baseline=None, format='json')

Writer that compares two headers and produces API compatibility reports.

Compares a target header against a baseline and produces a structured diff report in either JSON or Markdown format.

Options

baseline : Header | None The baseline header to compare against. If None, an empty header is used (all declarations appear as additions). format : str Output format: "json" (default) or "markdown".

Example

::

from headerkit.writers import get_writer

writer = get_writer("diff", baseline=old_header, format="markdown")
report = writer.write(new_header)

name property

name

Human-readable name of this writer.

format_description property

format_description

Short description of the output format.

write

write(header)

Compare header against baseline and produce a diff report.

Parameters:

Name	Type	Description	Default
header	Header	The target header to compare.	required

Returns:

Type	Description
str	Diff report as JSON or Markdown string.

Core Function

diff_headers

diff_headers(baseline, target)

Compare two Header objects and produce a DiffReport.

Declarations are matched by (kind, name). Anonymous declarations (name is None) are skipped since they cannot be reliably matched.

Parameters:

Name	Type	Description	Default
baseline	Header	The original/old header.	required
target	Header	The new/updated header.	required

Returns:

Type	Description
DiffReport	A DiffReport with all detected changes.

Output Formatters

diff_to_json

diff_to_json(report, indent=2)

Serialize a DiffReport to JSON.

Parameters:

Name	Type	Description	Default
report	DiffReport	The diff report.	required
indent	int | None	JSON indentation level. None for compact output.	2

Returns:

Type	Description
str	JSON string.

diff_to_markdown

diff_to_markdown(report)

Render a DiffReport as human-readable Markdown.

Parameters:

Name	Type	Description	Default
report	DiffReport	The diff report.	required

Returns:

Type	Description
str	Markdown string.

Data Types

DiffReport dataclass

DiffReport(baseline_path, target_path, entries=list())

Complete diff report between two headers.

Parameters:

Name	Type	Description	Default
baseline_path	str	Path of the baseline header file.	required
target_path	str	Path of the target header file.	required
entries	list[DiffEntry]	List of detected differences.	list()

breaking_count property

breaking_count

Number of breaking changes.

non_breaking_count property

non_breaking_count

Number of non-breaking changes.

DiffEntry dataclass

DiffEntry(kind, severity, name, detail, baseline=None, target=None)

A single difference between baseline and target headers.

Parameters:

Name	Type	Description	Default
kind	str	Category of change (e.g., "function_added", "struct_field_removed").	required
severity	str	Either "breaking" or "non_breaking".	required
name	str	Affected declaration name.	required
detail	str	Human-readable description of the change.	required
baseline	str | None	Baseline signature or value, if applicable.	None
target	str | None	Target signature or value, if applicable.	None

Example

from headerkit.backends import get_backend
from headerkit.writers import get_writer

backend = get_backend()

old_header = backend.parse("""
int add(int a, int b);
int multiply(int a, int b);
""", "math_v1.h")

new_header = backend.parse("""
int add(int a, int b);
double multiply(double a, double b);
int subtract(int a, int b);
""", "math_v2.h")

# JSON report
writer = get_writer("diff", baseline=old_header, format="json")
print(writer.write(new_header))

# Markdown report
writer = get_writer("diff", baseline=old_header, format="markdown")
print(writer.write(new_header))

JSON output:

{
  "schema_version": "1.0",
  "baseline": "math_v1.h",
  "target": "math_v2.h",
  "summary": {
    "total": 2,
    "breaking": 1,
    "non_breaking": 1
  },
  "entries": [
    {
      "kind": "function_signature_changed",
      "severity": "breaking",
      "name": "multiply",
      "detail": "return type changed from 'int' to 'double'"
    },
    {
      "kind": "function_added",
      "severity": "non_breaking",
      "name": "subtract",
      "detail": "function 'subtract' added"
    }
  ]
}