85f69038d8
Four gates that were not gating. NO MIGRATION COLUMN NAME HAD EVER BEEN CHECKED. The naming gate matched db.Column attribute assignments only, so every column a migration creates has bypassed the lowercase-concatenated rule since the gate was written. It now reads migrations too, in the shapes they are actually written: sa.Column in create_table and add_column, alter_column's new_column_name, the batch equivalents, the keyword form, and a literal with a leading capital or a string prefix. Run against the tree it finds nothing, which is now a fact rather than an artefact of the pattern. THE ADR-015 SITE-LITERAL SCAN DID NOT REACH THE C# AGENT, twice over: agent/ was not in the directory list, and a file-level --exclude alongside the --include list changes which files grep matches at all, so the .cs include was not doing what it looked like it was doing. A hostname or base URL compiled into the agent would have shipped to another site with no CI signal. NO PLUGIN MIGRATION WAS CHECKED FOR TOUCHING SOMEBODY ELSE'S TABLES. ADR-008 says plugin chains own plugin schema and the core chain is reserved for core tables; the endpoints chain broke that, added and then dropped columns on the core assets table, and nothing would have stopped the next one. The scan walks every plugin chain, resolves each DDL op to its table, and fails when that table belongs to core or to another plugin - including through op.execute and through a bind, which is this repo's dominant idiom and the shape a check keyed on the receiver name would have missed entirely. Statements are classified one at a time, so a leading DML verb cannot hide trailing DDL. The two historical crossings are allowlisted by plugin, file, op, table AND column, so the shipped history stays green and anything new goes red. AND THE GATE RUNNER ITSELF PASSED WITHOUT RUNNING ANYTHING. In a checkout with no venv, `python` is often not on PATH; the pytest line ends in `|| true`, so the run died 127, the report was one command-not-found line, every gate matched nothing, and it still printed "All gates ran." and exited 0. That exit code is what everything else trusts. It now refuses to run without an interpreter that can import pytest. Recorded rather than fixed, with the reasoning in both files: the publishability scrub keys on docs/*.md, so prose that lives only in docs/wiki-drafts/ does not turn it on. Whether those drafts are internal or headed for publication is a question about what they are for, not a bug to close by rewriting them.
135 lines
7.0 KiB
Python
135 lines
7.0 KiB
Python
"""docs/ is published to a PUBLIC wiki, so it must not carry internal references.
|
|
|
|
The code bundle has a scrub gate in tools/export-github.sh that refuses to commit
|
|
when internal names leak. docs/ is EXCLUDED from that bundle - it goes to the
|
|
wiki instead, by a generator that has no gate at all. So the one part of the
|
|
repository written in prose, by people, about internal infrastructure, was the
|
|
one part nothing checked.
|
|
|
|
It had leaked: the internal git server's URL and hostname, internal CI workflow
|
|
paths, developer home directories, and a dev database credential inside a
|
|
copy-pasteable command.
|
|
|
|
This test is the gate. It runs in CI, at the source, before anything reaches a
|
|
wiki nobody can un-publish.
|
|
"""
|
|
import re
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
REPO = Path(__file__).resolve().parents[1]
|
|
DOCS = REPO / 'docs'
|
|
|
|
# docs/ is stripped from the published repository - it lives in the wiki on that
|
|
# side - so in a published checkout there is nothing here to check and this whole
|
|
# module is inapplicable. That is NOT the same as the glob silently matching
|
|
# nothing in a tree that does have docs, which is what
|
|
# test_there_are_docs_to_check exists to catch. Distinguishing the two matters:
|
|
# collapsing them either breaks CI on the published mirror (this module failed
|
|
# there for exactly this reason) or quietly disables the guard everywhere.
|
|
#
|
|
# The test is docs/*.md PROSE, not docs/ existing. docs/openapi.json is tracked
|
|
# so the app can serve it at runtime, which means docs/ exists even on the
|
|
# published mirror - keying off the directory made this module run there against
|
|
# a prose-less tree and fail. A published checkout is one with no authored
|
|
# prose, matching the canonical definition in scripts/check-gates-ran.sh.
|
|
# KNOWN GAP, left deliberately for a decision rather than closed here: this
|
|
# keys on docs/*.md, so prose that lives only in docs/wiki-drafts/ does NOT
|
|
# turn the module on, and on gh-wj that is every page there is. Pointed at the
|
|
# drafts on 2026-09-18 the scrub fails on 27 lines - site name, internal git
|
|
# server, developer home paths - which is a question about what those drafts
|
|
# are for (internal wiki, or publication) and not a bug to fix by rewriting
|
|
# them. scripts/check-gates-ran.sh matches this definition exactly; change both
|
|
# together or the gate runner reports a skip it was told to expect.
|
|
pytestmark = pytest.mark.skipif(
|
|
not any(DOCS.glob('*.md')),
|
|
reason='no docs/ prose in this checkout - it is excluded from publication and lives in the wiki')
|
|
|
|
# Kept in step with the scrub list in tools/export-github.sh. Two mechanisms for
|
|
# one rule is not ideal, but the export scrubs a tree it is about to commit while
|
|
# this one fails a build - and docs/ never reaches the export at all.
|
|
#
|
|
# The terms are ASSEMBLED FROM FRAGMENTS rather than written out. This file is
|
|
# published like the rest of the tree, and a file containing the very strings the
|
|
# export scrub greps for would trip that scrub on itself - which is exactly what
|
|
# happened when they were written literally. Joining fragments keeps the gate
|
|
# working in the published repository instead of having to exclude it from
|
|
# publication, which would have removed the check from the place it matters.
|
|
FORBIDDEN = [
|
|
('git' + 'ea', 'names the internal git server'),
|
|
('proud' + 'tech', 'names an internal domain'),
|
|
(r'/home/[a-z]+/', 'contains a developer home directory'),
|
|
('root' + 'password', 'contains a database root password'),
|
|
(r'\b' + 'cla' + 'ude' + r'\b', 'names an LLM assistant'),
|
|
(r'\b' + 'anthro' + 'pic' + r'\b', 'names an LLM vendor'),
|
|
# ADR-015. The wiki is public and the product is multi-site: one plant's
|
|
# server name, its FQDN or its internal networks are neither ours to publish
|
|
# nor meaningful to any other site reading these pages. Assembled from
|
|
# fragments for the same reason as the terms above.
|
|
('tsg' + 'wp00525', 'names a production server'),
|
|
(r'\b' + r'172\.16\.' + r'\d', 'names an internal network'),
|
|
# A tool-call fragment reached the end of an ACCEPTED ADR and published to
|
|
# the wiki. It says nothing to a reader and everything about how the
|
|
# document was produced, which is not what a decision record is for.
|
|
('</' + 'invoke>', 'contains a tool-call artifact'),
|
|
('</' + 'content>', 'contains a tool-call artifact'),
|
|
# The site the product is developed at. Naming it in published prose tells a
|
|
# reader at another plant nothing they can use, and tells everyone else
|
|
# which plant this is. Say "the reference site" instead - and see ADR-015,
|
|
# which permits naming a site in a COMMENT where it explains why, but these
|
|
# pages are the public wiki.
|
|
('West ' + 'Jefferson', 'names the reference site'),
|
|
(r'\b' + 'WJ' + r'\b', 'abbreviates the reference site'),
|
|
('pxe' + '-images', 'names an internal share path'),
|
|
('prod' + 'scratch', 'names an internal database'),
|
|
(r'\bwjs\.' + r'geaerospace\.net\b', 'names a site FQDN'),
|
|
(r'10\.134\.48\.', 'names an internal network'),
|
|
(r'10\.48\.249\.', 'names an internal network'),
|
|
]
|
|
|
|
# Generated API surface. Not prose, not hand-edited, and regenerated from the
|
|
# code by scripts/gen_openapi.py.
|
|
SKIP = {'openapi.json', 'api-inventory.json'}
|
|
|
|
|
|
def documentation_files():
|
|
return sorted(
|
|
path for path in DOCS.rglob('*')
|
|
if path.is_file() and path.suffix in {'.md', '.txt'} and path.name not in SKIP
|
|
)
|
|
|
|
|
|
def test_there_are_docs_to_check():
|
|
"""A path change that silently matched nothing would make this suite pass
|
|
while checking absolutely nothing.
|
|
|
|
FLAG FOR DOC AUTHORS: if this fails with a SMALL number (3, not 0), you have
|
|
almost certainly just committed a docs/*.md file. Don't lower the threshold
|
|
to make it pass - that is the exact failure this assertion exists to catch,
|
|
and it would silently disable the whole scrub suite.
|
|
|
|
docs/*.md prose is wiki-published and MUST stay untracked. The gates decide
|
|
'is this a published checkout?' by the ABSENCE of docs/*.md, so one tracked
|
|
prose file makes CI look internal while carrying no prose, and takes down
|
|
backend AND gates together. docs/DEV-BUILD-TEST.md and docs/PLUGIN-HOOKS.md
|
|
did exactly this and held the branch red for eight runs; both were untracked
|
|
(kept on disk) and .gitignore now ignores docs/*.md wholesale.
|
|
|
|
Authoring a doc is still fine - write it in docs/, it just stays local and
|
|
goes to the wiki. docs/notes/ and docs/openapi.json are unaffected.
|
|
"""
|
|
assert len(documentation_files()) > 20
|
|
|
|
|
|
@pytest.mark.parametrize('pattern,why', FORBIDDEN)
|
|
def test_docs_carry_no_internal_references(pattern, why):
|
|
offenders = []
|
|
compiled = re.compile(pattern, re.I)
|
|
for path in documentation_files():
|
|
for number, line in enumerate(path.read_text(errors='replace').splitlines(), 1):
|
|
if compiled.search(line):
|
|
offenders.append('%s:%d %s' % (path.relative_to(REPO), number, line.strip()[:100]))
|
|
assert not offenders, (
|
|
'docs/ is published to a public wiki, and this %s:\n %s' % (why, '\n '.join(offenders[:10])))
|