Classes
class	ConventionalCommit

Functions
str	_strip_plan_prefix (str header)
ConventionalCommit\|None	parse_commit_message (str message)
list[str]	validate_commit_message (str message)
list[str]	validate_ai_model_trailer (str message)
str	format_validation_errors (list[str] errors)
list[str]	analyse_diagnostics_impact (str diff_text)
list[str]	_analyse_diagnostics_impact_inner (str diff_text)

Variables
tuple	COMMIT_TYPES
int	MAX_SUBJECT_LENGTH = 72
	_HEADER_RE
	_FOOTER_RE = re.compile(r"^[\w-]+\s:\s\|^BREAKING CHANGE\s:\s")
	_PLAN_PREFIX_RE = re.compile(r"^(?:\‍[[^\‍]\n]+\‍]\s*)+")
	_AI_MODEL_TRAILER_RE
	_DBG_CALL_RE

Detailed Description

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.

Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)

Function Documentation

◆ _analyse_diagnostics_impact_inner()

list[str] oct.git.conventional._analyse_diagnostics_impact_inner ( str diff_text )

protected

Inner implementation of diagnostics impact analysis.

Definition at line 348 of file conventional.py.

Here is the caller graph for this function:

◆ _strip_plan_prefix()

str oct.git.conventional._strip_plan_prefix ( str header )

protected

Return *header* without an optional leading Option C plan/area prefix.

``"[151.T6][oct] feat: x"`` -> ``"feat: x"``; a header with no leading
``[...]`` prefix is returned unchanged. Used by both the parser and the
header-length validator so the Conventional Commits rules apply to the
conventional portion, not the project metadata.

Definition at line 93 of file conventional.py.

Here is the caller graph for this function:

◆ analyse_diagnostics_impact()

list[str] oct.git.conventional.analyse_diagnostics_impact ( str diff_text )

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.

Definition at line 328 of file conventional.py.

Here is the call graph for this function:

◆ format_validation_errors()

str oct.git.conventional.format_validation_errors ( list[str] errors )

Format validation errors for display.

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

Definition at line 301 of file conventional.py.

◆ parse_commit_message()

ConventionalCommit | None oct.git.conventional.parse_commit_message ( str message )

Parse a commit message into a :class:`ConventionalCommit`.

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

Definition at line 127 of file conventional.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ validate_ai_model_trailer()

list[str] oct.git.conventional.validate_ai_model_trailer ( str message )

Validate presence of the Option C ``AI-Model:`` commit trailer.

Returns a list of human-readable error strings; an empty list means an
``AI-Model: <name> <version>`` trailer is present and well-formed. This
is the Option C commit-forensics convention (Plan 151 T6, inventory
item 4): every commit body must name the LLM that did the reasoning.

Presence validation only - the trailer value must contain at least a
model name and a version (two or more whitespace-separated tokens).
Never raises; always returns a list.

Definition at line 263 of file conventional.py.

◆ validate_commit_message()

list[str] oct.git.conventional.validate_commit_message ( str message )

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 :data:`COMMIT_TYPES`.
3. Subject must start with a lowercase letter.
4. Subject must not end with a period.
5. First line (header) must be ≤ :data:`MAX_SUBJECT_LENGTH` characters.
6. Subject must not be empty.

Definition at line 199 of file conventional.py.

Here is the call graph for this function:

Variable Documentation

◆ _AI_MODEL_TRAILER_RE

oct.git.conventional._AI_MODEL_TRAILER_RE

protected

Initial value:

=  re.compile(
    # OCT-LINT: disable=no_hardcoded_secrets reason="Regex patterns and commit-message remediation strings are high-entropy but not credentials"
    r"(?m)^[ \t]*AI-Model:[ \t]*(?P<value>\S.*)$"
)

Definition at line 87 of file conventional.py.

◆ _DBG_CALL_RE

oct.git.conventional._DBG_CALL_RE

protected

Initial value:

=  re.compile(
    # OCT-LINT: disable=no_hardcoded_secrets reason="Regex patterns and commit-message remediation strings are high-entropy but not credentials"
    r'_dbg\‍(\s*["\'](?P<domain>[A-Z_]+)["\']'
    r'(?:\s*,\s*[^,]+)?'  # skip func argument
    r'(?:\s*,\s*[^,]+)?'  # skip message argument
    r'(?:\s*,\s*(?P<level>\d+))?'  # optional level
)

Definition at line 319 of file conventional.py.

◆ _FOOTER_RE

oct.git.conventional._FOOTER_RE = re.compile(r"^[\w-]+\s*:\s*|^BREAKING CHANGE\s*:\s*")

protected

Definition at line 67 of file conventional.py.

◆ _HEADER_RE

oct.git.conventional._HEADER_RE

protected

Initial value:

=  re.compile(
    # OCT-LINT: disable=no_hardcoded_secrets reason="Regex patterns and commit-message remediation strings are high-entropy but not credentials"
    r"^(?P<type>\w+)"          # type word
    r"(?:\‍((?P<scope>[^)]+)\‍))?"  # optional (scope)
    r"(?P<bang>!)?"            # optional breaking indicator
    r"\s*:\s*"                 # colon separator
    r"(?P<subject>.+)$"       # subject text
)

Definition at line 56 of file conventional.py.

◆ _PLAN_PREFIX_RE

oct.git.conventional._PLAN_PREFIX_RE = re.compile(r"^(?:\‍[[^\‍]\n]+\‍]\s*)+")

protected

Definition at line 80 of file conventional.py.

◆ COMMIT_TYPES

tuple oct.git.conventional.COMMIT_TYPES

Initial value:

=  (
    "feat", "fix", "docs", "style", "refactor", "perf", "test", "chore", "sec",
)

Definition at line 48 of file conventional.py.

◆ MAX_SUBJECT_LENGTH

int oct.git.conventional.MAX_SUBJECT_LENGTH = 72

Definition at line 52 of file conventional.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _analyse_diagnostics_impact_inner()

◆ _strip_plan_prefix()

◆ analyse_diagnostics_impact()

◆ format_validation_errors()

◆ parse_commit_message()

◆ validate_ai_model_trailer()

◆ validate_commit_message()

Variable Documentation

◆ _AI_MODEL_TRAILER_RE

◆ _DBG_CALL_RE

◆ _FOOTER_RE

◆ _HEADER_RE

◆ _PLAN_PREFIX_RE

◆ COMMIT_TYPES

◆ MAX_SUBJECT_LENGTH