|
| str|None | generate_branch_name_from_message (str message) |
| bool | is_protected_branch (str|None branch, dict|None octrc) |
| tuple[bool, str] | validate_branch_name (str|None branch, dict|None octrc) |
| Profile | _resolve_auto_profile (str|None branch) |
| Profile | resolve_effective_profile (str|None branch, dict|None octrc, str|None cli_override) |
| int | apply_profile_policy (str profile, "QualityGateResult" result) |
| tuple[bool, str] | check_protected_branch_commit (str|None branch, dict|None octrc, str profile) |
| tuple[bool, str] | validate_ignore_pattern (str pattern) |
| list[str] | _read_gitignore (Path repo_root) |
| None | _write_gitignore (Path repo_root, list[str] lines) |
| tuple[int, int] | _find_oct_block (list[str] lines) |
| tuple[list[str], list[str]] | list_ignore_patterns (Path repo_root) |
| list[str] | add_ignore_patterns (Path repo_root, list[str] patterns) |
| tuple[bool, str] | remove_ignore_pattern (Path repo_root, str pattern) |
Purpose
-------
Encode the Phase 4B profile-aware enforcement rules for the ``oct git``
quality gate. Maps a combination of profile (``proto`` / ``compact`` /
``strict``), branch context, and raw check findings to a semantic exit
code in the range 0..5 defined by blueprint §5.3.
Responsibilities
----------------
- Resolve the effective lint profile from CLI / octrc / branch context,
honouring the protected-branch override (blueprint §7.2).
- Apply the profile enforcement matrix (blueprint §5.3 / §7.1) to a
:class:`~oct.git.quality_gate.QualityGateResult` and return the
matching exit code.
- Enforce the invariant "secrets always blocks" regardless of profile
(blueprint §5.3 final clause).
- Manage the OCT-managed block in ``.gitignore`` — add/remove/list
patterns inside the fenced block, leaving user-managed lines alone.
Diagnostics
-----------
Domain: GIT
Levels:
L3 — profile resolution and policy decisions
L4 — per-field raw counts during exit-code derivation
Contracts
---------
- This module is pure: no filesystem, no subprocess, no Click.
- ``resolve_effective_profile`` never raises; unknown values collapse
to the documented default.
- ``apply_profile_policy`` depends only on the ``QualityGateResult``
dataclass defined in :mod:`oct.git.quality_gate`.
- Precedence for the exit code is strictly: 5 > 4 > 3 > 2 > 1 > 0.
| int oct.git.policy.apply_profile_policy |
( |
str | profile, |
|
|
"QualityGateResult" | result ) |
Derive the semantic exit code for a quality-gate result.
Exit code table (blueprint §5.3, verbatim):
==== ==========================================================
Code Meaning
==== ==========================================================
0 all checks pass
1 lint violations (blocking under this profile)
2 format violations (blocking under this profile)
3 both lint and format violations
4 test failures (when ``--include-tests``)
5 secrets detected — always blocking
==== ==========================================================
Precedence: ``5 > 4 > 3 > 2 > 1 > 0``. The first rule that matches
wins. Because secrets takes precedence, a profile that would
otherwise return 0 (e.g. ``proto`` with warnings-only lint) still
returns 5 if secrets are present. This is the "secrets always
blocks" invariant.
For profiles where a check is not blocking (``proto`` lint is
``warn``; ``proto`` format is ``skip``), the corresponding violation
counter never contributes to the exit code even if non-zero.
Parameters
----------
profile
One of ``"proto"``, ``"compact"``, ``"strict"``. Unknown values
degrade to :data:`DEFAULT_PROFILE`.
result
A :class:`~oct.git.quality_gate.QualityGateResult` with the raw
counts from a completed gate run.
Definition at line 419 of file policy.py.
| tuple[bool, str] oct.git.policy.check_protected_branch_commit |
( |
str | None | branch, |
|
|
dict | None | octrc, |
|
|
str | profile ) |
Check if committing directly to a protected branch.
Returns ``(blocked, message)``:
- On a **non-protected branch**: ``(False, "")``.
- On a protected branch in ``strict`` profile: ``(True, error_msg)``.
- On a protected branch in other profiles: ``(False, warning_msg)``.
The caller is responsible for printing the message and aborting if
``blocked`` is ``True``.
Definition at line 497 of file policy.py.
| tuple[bool, str] oct.git.policy.validate_branch_name |
( |
str | None | branch, |
|
|
dict | None | octrc ) |
Validate *branch* against the configured naming patterns.
Returns ``(valid, message)``:
- ``git.branch_naming.enabled`` is ``False`` → ``(True, "")``
- ``branch`` is ``None`` (detached HEAD) → ``(True, "")``
- Branch matches at least one pattern → ``(True, "")``
- No pattern matches → ``(False, "Branch name '...' does not ...")``
Patterns default to :data:`DEFAULT_BRANCH_PATTERNS` when not
overridden in ``.octrc.json``.
Definition at line 249 of file policy.py.
| tuple[bool, str] oct.git.policy.validate_ignore_pattern |
( |
str | pattern | ) |
|
Return ``(valid, message)`` for a candidate gitignore pattern.
Rejects empty strings, patterns containing newlines, leading ``!``
(negation — too easy to weaponise via ``oct git ignore``), absolute
paths (leading ``/`` is interpreted as anchored to repo root which
is allowed by gitignore but our policy is to require relative
patterns), and any character outside :data:`_VALID_PATTERN_RE`.
Definition at line 546 of file policy.py.
1.15.0