Quality Assurance

The provisioning repository enforces code quality and prose hygiene through a suite of automated, vendored Python tools integrated directly into the Git pre-push workflow. These checks ensure that hand-authored code remains modular, documentation remains free of AI-generated artifacts, and branching conventions are strictly maintained. The gates operate locally before any changes are transmitted to remote repositories, providing immediate feedback to engineers.

File Size Limits

To prevent code bloat and encourage modular design, the repository enforces a strict line-count ceiling on hand-authored code files. This check is implemented in tools/check_file_ceiling.py and is executed as part of the pre-push hook ¹.

The gate applies to specific programming languages identified by file extension, including Python, Go, JavaScript, TypeScript, Astro, Shell, CSS, and HTML. Files are excluded from this check if they are binary, generated, or part of standard dependency lockfiles (e.g., package-lock.json, go.sum). The line count is calculated using the formula n_lines = text.count("\n") + 1.

Any hand-authored code file exceeding 1000 lines causes the check to fail with a non-zero exit code, listing the offending files sorted by size. There is no grandfathering or allowlist; files must be refactored into smaller modules to pass.

Prose Hygiene

The repository bans specific markers of AI-generated prose to maintain a consistent, human-authored documentation style. This is enforced by tools/check_prose_hygiene.py, which scans tracked text files for em/en-dashes, decorative emoji, and stock AI-speak phrases ².

The gate supports two modes: a default check mode that fails if violations are found, and a --fix mode that automatically replaces em/en-dashes with hyphens and removes decorative emoji. AI-speak phrases are reported for manual rewording and are not auto-fixed. A file can opt out of these checks by including the marker prose-hygiene: allow.

CI/CD and Pre-Push Integration

These quality checks are integrated into the repository’s Git pre-push hook located at .githooks/pre-push ³. This hook runs locally before any push is accepted, ensuring that code and prose standards are met before they reach the remote repository.

The hook first executes the file ceiling check. If any file exceeds the 1000-line limit, the push is aborted with an error message instructing the engineer to split the file. Next, it runs the prose hygiene check. If violations are detected, the push is blocked, and the engineer is instructed to run the --fix command and manually reword any AI-speak phrases.

Additionally, the pre-push hook enforces branching conventions by blocking pushes of the dev branch to the public remote, ensuring that only main is published. This ensures that the public-facing codebase remains clean and adheres to the established quality gates.

tools/check_file_ceiling.py L1-120 (showing 40 of 120)

#!/usr/bin/env python3
"""House line-count ceiling check (vendored, stdlib-only, no AI).

VENDORED FILE - do not edit by hand. Regenerate with
``sddc repo audit vendor-ceiling`` from the sddcinfo monorepo. It is a
self-contained port of that monorepo's ``repo_audit`` ceiling logic, using the
identical file classification and ``n_lines = text.count("\n") + 1`` count, so
this gate agrees exactly with ``sddc repo audit ceiling``.

Hand-authored code only (generated lockfiles, binaries, data, config and docs
are excluded). No allowlist - any code file over the ceiling fails, with no
grandfathering. Run it from a repo root (or pass a path); exits non-zero and
prints offenders worst-first when any code file exceeds the ceiling.
"""

from __future__ import annotations

import subprocess
import sys
from pathlib import Path

MAX_FILE_LINES = 1000

# Hand-authored code languages this gate applies to.
CODE_LANGS = {"python", "go", "javascript", "typescript", "astro", "shell", "css", "html"}

_LANG_BY_SUFFIX = {
    ".py": "python",
    ".pyi": "python",
    ".go": "go",
    ".js": "javascript",
    ".mjs": "javascript",
    ".ts": "typescript",
    ".tsx": "typescript",
    ".jsx": "javascript",
    ".astro": "astro",
    ".sh": "shell",
    ".bash": "shell",
    ".css": "css",
    ".html": "html",

tools/check_prose_hygiene.py L1-120 (showing 40 of 120)

#!/usr/bin/env python3
"""Prose-hygiene gate (vendored, stdlib-only, no AI).

VENDORED FILE: do not edit by hand; regenerate from the upstream generator.
Self-contained: scans tracked text files for the AI-generated-prose tells this
project bans -- em/en-dashes, decorative emoji, and stock AI-speak phrases --
and fails if any remain. Run as a pre-commit / pre-push / CI gate so the cruft
can never accrete again.

Two modes:
  (default)  report offenders and exit non-zero if any are found  (the GATE)
  --fix      deterministically repair the auto-fixable ones in place
             (dashes -> hyphen, decorative emoji removed); AI-speak phrases are
             reported for manual rewording, never auto-reworded.

A file may opt out of fixing/checking with a line containing the marker
``prose-hygiene: allow`` (for the rare file that legitimately carries the
characters -- e.g. the detector that defines these very patterns).
"""

from __future__ import annotations

import re
import subprocess
import sys
from pathlib import Path

_ALLOW_MARKER = "prose-hygiene: allow"

# Dash family that reads as AI-generated punctuation: em-dash, en-dash,
# horizontal bar, figure dash. All collapse to a plain hyphen.
_DASHES = "—–―‒"
_DASH_RE = re.compile(f"[{_DASHES}]")

# Decorative emoji ranges. Only flagged/stripped where DECORATIVE -- in a
# comment or a docs file -- never in UI markup (HTML/astro/jsx elements) or
# code strings, where emoji are functional (menu glyphs, status marks, icons)
# and removing them would break the product.
_EMOJI_RE = re.compile(
    "[\U0001f300-\U0001faff\U00002600-\U000027bf\U0001f1e6-\U0001f1ff\U00002b00-\U00002bff]"

.githooks/pre-push L1-45 (showing 40 of 45)

#!/usr/bin/env bash
# Enforce two-repo convention:
# - Work happens on dev; promotion to main is via PR dev→main
# - Only 'main' is published to the public remote
# - Never push dev directly to public

remote="$1"
remote_url="$2"

# Enforce the 1000-line file-size ceiling on hand-authored code.
if ! python3 tools/check_file_ceiling.py .; then
    echo "ERROR: file-size ceiling exceeded (>1000 lines)."
    echo "  Split the offending file(s) below 1000 lines before pushing."
    exit 1
fi

# Enforce prose hygiene (no em/en-dashes, decorative emoji, or AI-speak).
if ! python3 tools/check_prose_hygiene.py .; then
    echo "ERROR: prose-hygiene gate failed."
    echo "  Run 'python3 tools/check_prose_hygiene.py --fix .' then reword any AI-speak."
    exit 1
fi

while IFS= read -r local_ref _ remote_ref _; do
    branch="${remote_ref#refs/heads/}"
    
    # Block pushing dev to public remote
    if [[ "$remote_url" == *"sddcinfo/provisioning"* ]] && \
       [[ "$remote_url" != *"provisioning-private"* ]] && \
       [[ "$branch" == "dev" ]]; then
        echo "ERROR: Do not push 'dev' to the public remote."
        echo "  Only 'main' is published to sddcinfo/provisioning."
        echo "  Merge dev→main via PR, then: git push public main"
        exit 1
    fi
    
    # Block pushing directly to main without going through dev
    if [[ "$branch" == "main" ]] && [[ "$remote_url" == *"provisioning-private"* ]]; then
        # Allow - this is normal promotion flow
        :