oct.git.conventional Namespace Reference

Classes
class	ConventionalCommit

Functions
ConventionalCommit|None	parse_commit_message (str message)
list[str]	validate_commit_message (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*")
	_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.

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 258 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 240 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 214 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 86 of file conventional.py.

Here is the caller graph for this function:

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 154 of file conventional.py.

Here is the call graph for this function:

Variable Documentation

_DBG_CALL_RE

oct.git.conventional._DBG_CALL_RE

protected

Initial value:

=  re.compile(
    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 232 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 61 of file conventional.py.

_HEADER_RE

oct.git.conventional._HEADER_RE

protected

Initial value:

=  re.compile(
    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 51 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 43 of file conventional.py.

MAX_SUBJECT_LENGTH

int oct.git.conventional.MAX_SUBJECT_LENGTH = 72

Definition at line 47 of file conventional.py.