Portail de conformité

Le portail de conformité, à src/apothem/conformity/gate.py, exécute la fraction mécanique du portail de pré-émission à quinze barres (M1-M15) sur chaque artefact que rédige l'opérateur.

Les commandes de cette page supposent un checkout d'Apothem : faites précéder chacune de celles que vous exécutez de PYTHONPATH=src. Après une installation par script, utilisez PYTHONPATH="$HOME/.apothem/src" à la place de PYTHONPATH=src.

Exécuter le portailCopy Anchor Link

Le portail est consultatif par défaut : il signale les constats et se termine avec le code 0, de sorte qu'une exécution locale ne vous bloque jamais. Ajoutez --strict (ou définissez APOTHEM_CONFORMITY_STRICT=1) pour obtenir un code de sortie non nul en présence d'un constat bloquant — le mode qu'utilisent la CI et pre-commit pour faire échouer une modification en infraction.

# Advisory: report every validator's findings across the repo, exit 0
PYTHONPATH=src python -m apothem.conformity.gate --all .

# Strict: exit non-zero (code 2) when a blocking finding is present
PYTHONPATH=src python -m apothem.conformity.gate --all --strict .

Codes de sortie : 0 propre (ou consultatif), 2 un blocage par constats en mode strict, 3 une erreur d'utilisation : un drapeau ou un nom de validateur inconnu, un fichier qui n'existe pas, ou un répertoire racine qui n'existe pas. --help affiche l'utilisation complète et se termine avec le code 0. Chaque validateur autonome accepte le même --help et se termine avec le code 3 sur un drapeau inconnu ou une racine manquante.

Une racine relative telle que . est résolue en chemin absolu avant l'exécution de tout validateur ; --all . et --all "$PWD" inspectent donc la même arborescence. Chaque validateur signale inspected — le nombre de cibles qu'il a examinées — et --all recopie ce nombre dans chaque entrée de résultat. Un validateur qui n'a rien inspecté signale passed: false, de sorte qu'un mauvais répertoire de travail ne peut pas réussir silencieusement. Les deux validateurs de suites de planification sont l'une des exceptions : les suites de planification vivent dans l'arborescence .apothem/plans/ ignorée par git ; ils signalent donc empty_scope_expected: true sur un checkout propre et réussissent malgré tout. Les validateurs de flux de travail font de même lorsque le projet n'a pas encore de répertoire .github/workflows/, et le validateur des sujets de commit également lorsque la racine n'a aucun historique de commits.

Six validateurs partent de la racine du dépôt et parcourent toute l'arborescence à la recherche des fichiers qu'ils vérifient :

agents-md-coverage-grep
agnosticism-grep
dynamism-grep
freshness-token-grep
plain-language-grep
reference-token-grep

Ceux-ci ignorent les checkouts git imbriqués, tels que les worktrees, les sous-modules et les clones imbriqués, et ignorent les répertoires qui contiennent des dépendances, des environnements virtuels, des caches ou des sorties de build, tels que node_modules, venv et dist. La vérification des plans égarés de no-global-plans-grep s'arrête également à un checkout imbriqué. Une exécution de l'un d'eux rend compte du checkout sur lequel elle a été pointée, et de rien d'autre. Un validateur qui lit un dossier fixe, tel que naming-grep sous src/apothem/, lit tout ce qui se trouve sous ce dossier.

Barres du portailCopy Anchor Link

Vérifications cibléesCopy Anchor Link

# List every registered validator
PYTHONPATH=src python -m apothem.conformity.gate --list

# Run one per-write validator against one file
PYTHONPATH=src python -m apothem.conformity.gate --check multi-surface-coherence src/apothem/rules/my-rule.md

# Run one standalone validator over a root directory
PYTHONPATH=src python -m apothem.conformity.gate --check naming-grep .

# Run every per-write validator against one file
PYTHONPATH=src python -m apothem.conformity.gate src/apothem/rules/my-rule.md

Un validateur par écriture prend le fichier à vérifier, ou --stdin pour lire le contenu depuis l'entrée standard ; sans l'un ni l'autre, il attend une entrée sur l'entrée standard, donc passez le fichier lorsque vous l'exécutez depuis un terminal. Un validateur autonome prend un répertoire racine (le répertoire courant s'il est omis). --list indique à quel groupe appartient chaque validateur.

Le mode --hook (python -m apothem.conformity.gate --hook) est le point d'entrée appelé par l'environnement : il lit sur stdin une charge utile JSON d'entrée d'outil et exécute la chaîne de matchers par écriture sur l'écriture en attente. C'est la forme qu'invoque le hook PreToolUse déployé ; vous l'appelez rarement à la main.

Le mode hook est limité à un ensemble de répertoires. Il n'exécute la chaîne de matchers que sur les écritures dont la cible relève de l'un d'eux ; une écriture située hors de toutes les portées est court-circuitée en une réussite silencieuse. Les valeurs par défaut sont deux racines :

~/.claude      Claude Code
$CODEX_HOME    Codex (~/.codex when CODEX_HOME is not set)

Définissez APOTHEM_CONFORMITY_SCOPE sur un répertoire pour les remplacer :

# Run the per-write matcher chain against one project tree instead
export APOTHEM_CONFORMITY_SCOPE=/path/to/project

Un hook qui semble ne rien faire relève généralement d'une écriture hors portée plutôt que d'un échec — comparez d'abord la cible de l'écriture aux portées ci-dessus.

Intégration CICopy Anchor Link

Le job de qualité de .github/workflows/ci.yml exécute le portail en mode strict (python -m apothem.conformity.gate --all . --strict) sur les pushes vers main et sur les pull requests vers main qui touchent les chemins que ce job surveille. Le flux de travail distinct .github/workflows/conformity.yml exécute le balayage des fixtures (tests/conformity-scenarios/verify.py --strict).