4995456136
The publishability gate caught internal tooling names and developer paths but nothing site-specific, so roughly sixty leaks reached the wiki: the site name in ten documents, real fleet hostnames in the collector and GE-Enforce examples, an internal database name through the whole import guide, imaging-share paths, and a maintainer's username as the Deciders line of every ADR and inside a generated curl example. None of it is a security matter on an air-gapped fleet. It matters because these pages are read by engineers at other plants, and a document that names one site throughout reads as that site's notes rather than a product's documentation - which is exactly what it then gets treated as. Examples now use neutral hostnames, the site is "the reference site" where the distinction carries meaning, and ADRs are decided by "ShopDB maintainers". The gate carries all of these patterns, so the next one fails a build. Two documents leave docs/ because they were never written for an outside reader. PROJECT-REVIEW.md is an internal health memo pinned to a commit from July, whose headline finding (an untracked playbook) has since been fixed - it is history, and git holds it. PILOT-DEPLOY.md is one site's own cutover runbook, complete with a "re-measure before publishing" placeholder; it moves next to the loader it belongs to, in scripts/site_imports/wjf/. ADR-015 is AMENDED rather than rewritten. Its enforcement section still said report-only and its backlog still listed hardcodes that are now cleared, which left the record contradicting itself. The amendment says what changed and why the report-only period ended; the original text stays, because what the decision looked like when it was taken is the part worth keeping. Also corrects llms.txt's response envelope, which had errors at the top level and pagination at meta.total. Both are nested one deeper, so anything written against that description read undefined on every error it tried to handle.
105 lines
5.1 KiB
Python
105 lines
5.1 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.
|
|
pytestmark = pytest.mark.skipif(
|
|
not DOCS.is_dir(),
|
|
reason='no docs/ 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."""
|
|
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])))
|