oct.git.conventional module

oct.git.conventional module#

Purpose#

Conventional Commits parser and validator (Phase 4D — G-D1, G-D2, G-D5).

Responsibilities#

  • Parse commit messages into structured ConventionalCommit objects.

  • Validate commit messages against the Conventional Commits specification with Option C extensions (blueprint §6).

  • Format validation errors for human-readable display.

  • Analyse git diffs for _dbg diagnostics impact (ChatGPT contribution).

Diagnostics#

Domain: GIT Levels:

L2 — validation lifecycle L3 — parsing details L4 — diagnostics impact analysis

Contracts#

  • validate_commit_message never raises; always returns a list.

  • parse_commit_message returns None for unparseable messages.

  • analyse_diagnostics_impact is best-effort; returns empty list on error.

class oct.git.conventional.ConventionalCommit(type: str, scope: str | None, subject: str, body: str, footer: str, breaking: bool)[source]#

Bases: object

Parsed representation of a Conventional Commit message.

body: str#
breaking: bool#
footer: str#
scope: str | None#
subject: str#
type: str#
oct.git.conventional.analyse_diagnostics_impact(diff_text: str) → list[str][source]#

Analyse a unified diff for _dbg-related changes.

Scans added (+) and removed (-) lines for _dbg() calls. Returns a list of human-readable impact lines, e.g.:

+ Added: GIT domain (L2)
- Removed: AUTH domain (L3)

Returns an empty list if no _dbg changes are detected or if the diff cannot be parsed. This function is best-effort and never raises.

oct.git.conventional.format_validation_errors(errors: list[str]) → str[source]#

Format validation errors for display.

Returns a multi-line string with bullet points and an example.

oct.git.conventional.parse_commit_message(message: str) → ConventionalCommit | None[source]#

Parse a commit message into a ConventionalCommit.

Returns None if the first line does not match the Conventional Commits type[(scope)][!]: subject pattern.

oct.git.conventional.validate_commit_message(message: str) → list[str][source]#

Validate a commit message against Conventional Commits rules.

Returns a list of human-readable error strings. An empty list means the message is valid.

Rules checked: 1. Must match Conventional Commits pattern. 2. Type must be one of COMMIT_TYPES. 3. Subject must start with a lowercase letter. 4. Subject must not end with a period. 5. First line (header) must be ≤ MAX_SUBJECT_LENGTH characters. 6. Subject must not be empty.