Skip to content
Merged
11 changes: 9 additions & 2 deletions docs/architecture/software-factory-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -1064,10 +1064,17 @@ ci_workflows: ["CI"]
verify:
setup: "scripts/factory-setup.sh"
test: "scripts/factory-test.sh"
protected_paths: ["scripts/factory-setup.sh", "scripts/factory-test.sh", ".github/**", "CODEOWNERS"]
protected_paths: ["scripts/factory-setup.sh", "scripts/factory-test.sh", ".github/", "CODEOWNERS"]
reviewers: [coderabbit, cubic, gemini-code-assist, sonarqube-cloud]
```

Its `protected_paths` are in the syntax of `config/hooks.json`'s paths, read alike by the Kernel's matcher and the
session hooks': a final `/` is the directory and everything below it, `*` is any part of one name, and case is
ignored. `**` as a whole name is any run of names, which both matchers read, as a rubric's paths use it (decision 0029),
though `config/hooks.json` itself names none. So `.github/*` leaves `.github/workflows/` open, and `CODEOWNERS` leaves
`.github/CODEOWNERS` open. They name the setup and test scripts. `schemas/consumer.schema.json` and
`tools/check_examples.py` hold them to it ("Consumer entry: its protected_paths in the hooks' syntax", issue 141).

Adopting the Factory is more than this entry. The repo also needs the two scripts, a ruleset that
matches, the machine user as a code owner, and its Advisory reviewers configured. A **readiness
check** in each pass compares every Consumer repo with that list and publishes what is missing, so
Expand Down Expand Up @@ -2183,7 +2190,7 @@ Run by `factory / verify` over the manifests and the authority table.
- An Intent that decides a gate and owns no category of Finding, as the readiness Intent does, has a promotion record of its own before any Effect of it is applied.
- A Role named `owner` of a category has a promotion record. A `shadow` Role's decision is never
read by the gate.
- Every Consumer entry names an owner Role, a setup command, a test command and protected paths.
- Every Consumer entry names an owner Role, a setup script, a test script and protected paths that name both.

The interaction matrix in §5.1 is generated from this data in the Factory repo. A stale copy fails
the check.
Expand Down
28 changes: 28 additions & 0 deletions examples/consumer.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"schema": "consumer/1",
"repo": "combsmith/markets",
"ring": "next",
"owner_role": "devops-lead",
"ci_workflows": [
"CI"
],
"verify": {
"setup": "scripts/factory-setup.sh",
"test": "scripts/factory-test.sh",
"protected_paths": [
"scripts/factory-setup.sh",
"scripts/factory-test.sh",
".github/",
"CODEOWNERS",
"docs/CODEOWNERS",
"tests/**/conftest.py",
"**/*.lock"
]
},
"reviewers": [
"coderabbit",
"cubic",
"gemini-code-assist",
"sonarqube-cloud"
]
}
24 changes: 24 additions & 0 deletions examples/invalid/consumer.a-glob-of-another-syntax.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"schema": "consumer/1",
"repo": "combsmith/markets",
"ring": "next",
"owner_role": "devops-lead",
"ci_workflows": [
"CI"
],
"verify": {
"setup": "scripts/factory-setup.sh",
"test": "scripts/factory-test.sh",
"protected_paths": [
"scripts/factory-setup.sh",
"scripts/factory-test.sh",
"scripts/factory-?.sh"
]
},
"reviewers": [
"coderabbit",
"cubic",
"gemini-code-assist",
"sonarqube-cloud"
]
}
24 changes: 24 additions & 0 deletions examples/invalid/consumer.a-path-from-the-root.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"schema": "consumer/1",
"repo": "combsmith/markets",
"ring": "next",
"owner_role": "devops-lead",
"ci_workflows": [
"CI"
],
"verify": {
"setup": "scripts/factory-setup.sh",
"test": "scripts/factory-test.sh",
"protected_paths": [
"scripts/factory-setup.sh",
"scripts/factory-test.sh",
"/CODEOWNERS"
]
},
"reviewers": [
"coderabbit",
"cubic",
"gemini-code-assist",
"sonarqube-cloud"
]
}
24 changes: 24 additions & 0 deletions examples/invalid/consumer.a-path-that-climbs-out.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"schema": "consumer/1",
"repo": "combsmith/markets",
"ring": "next",
"owner_role": "devops-lead",
"ci_workflows": [
"CI"
],
"verify": {
"setup": "scripts/factory-setup.sh",
"test": "scripts/factory-test.sh",
"protected_paths": [
"scripts/factory-setup.sh",
"scripts/factory-test.sh",
"../CODEOWNERS"
]
},
"reviewers": [
"coderabbit",
"cubic",
"gemini-code-assist",
"sonarqube-cloud"
]
}
24 changes: 24 additions & 0 deletions examples/invalid/consumer.a-script-left-unprotected.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"schema": "consumer/1",
"repo": "combsmith/markets",
"ring": "next",
"owner_role": "devops-lead",
"ci_workflows": [
"CI"
],
"verify": {
"setup": "scripts/factory-setup.sh",
"test": "scripts/factory-test.sh",
"protected_paths": [
"scripts/factory-setup.sh",
".github/",
"CODEOWNERS"
]
},
"reviewers": [
"coderabbit",
"cubic",
"gemini-code-assist",
"sonarqube-cloud"
]
}
29 changes: 29 additions & 0 deletions examples/invalid/consumer.a-script-named-by-a-pattern.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
{
"schema": "consumer/1",
"repo": "combsmith/markets",
"ring": "next",
"owner_role": "devops-lead",
"ci_workflows": [
"CI"
],
"verify": {
"setup": "scripts/*-setup.sh",
"test": "scripts/factory-test.sh",
"protected_paths": [
"scripts/factory-setup.sh",
"scripts/factory-test.sh",
".github/",
"CODEOWNERS",
"docs/CODEOWNERS",
"tests/**/conftest.py",
"**/*.lock",
"scripts/"
]
},
"reviewers": [
"coderabbit",
"cubic",
"gemini-code-assist",
"sonarqube-cloud"
]
}
89 changes: 89 additions & 0 deletions schemas/consumer.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "consumer/1: how one Consumer repo is served (design section 3.12). A data file: its path is its identity and the commit its Release. Its protected paths are in the one syntax of config/hooks.json, read alike by the Kernel's matcher (kernel/derive.py, matches) and the session hooks' (tools/hooks/protected.py, entries); and they name its setup and test scripts, which tools/check_examples.py holds. What reads an entry, the readiness check and apply's refusal for a Consumer repo, is slice 3's.",
"type": "object",
"additionalProperties": false,
"required": [
"schema",
"repo",
"ring",
"owner_role",
"ci_workflows",
"verify",
"reviewers"
],
"properties": {
"schema": {
"const": "consumer/1"
},
"repo": {
"type": "string",
"pattern": "^[A-Za-z0-9-]+/[A-Za-z0-9._-]+$"
},
"ring": {
"description": "The Channel that serves the repo, as release/rings.json names it.",
"enum": [
"next",
"stable"
]
},
"owner_role": {
"type": "string",
"pattern": "^[a-z][a-z-]*[a-z]$"
},
"ci_workflows": {
"description": "The name of each of the repo's own workflows whose checks the Factory reads, as GitHub shows it.",
"type": "array",
"minItems": 1,
"uniqueItems": true,
Comment thread
don-petry marked this conversation as resolved.
Resolved
"items": {
"type": "string",
"minLength": 1
}
},
"verify": {
"type": "object",
"additionalProperties": false,
"required": [
"setup",
"test",
"protected_paths"
],
"properties": {
"setup": {
"description": "The repo's setup script, by its path from the top of the repo.",
"$ref": "#/$defs/file"
},
"test": {
"description": "The repo's test script, by its path from the top of the repo.",
"$ref": "#/$defs/file"
},
"protected_paths": {
"description": "What apply refuses a Role's push to without a person (slice 3's): relative to the top of the repo; a path ending in / is a directory and all below it; * stands for any part of one name; ** as a whole name for any run of names, which both matchers read, as a rubric's paths use it (decision 0029), though config/hooks.json itself names none; case is ignored (issue 141, decision 0020). Its setup and test scripts are among them.",
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"$ref": "hooks.schema.json#/$defs/path"
}
}
}
},
"reviewers": {
"description": "The repo's Advisory reviewers, by the name the Factory gives each, one at least: adopting the Factory needs them configured (design section 3.12).",
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*$"
}
}
},
"$defs": {
"file": {
"type": "string",
"pattern": "^(?!.*(^|/)\\.{1,2}(/|$))[A-Za-z0-9_.-]+(/[A-Za-z0-9_.-]+)*$"
}
}
}
66 changes: 66 additions & 0 deletions tests/test_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -1217,6 +1217,72 @@ def test_what_the_machine_user_may_never_hold_has_a_counter_example(self): # is
names = {path.name for path in (ROOT / "examples" / "invalid").glob("machine-user.*.json")}
self.assertEqual(len(names), 6)

def test_a_consumer_entrys_protected_paths_are_in_the_hooks_syntax_and_read_by_one_matcher(self): # issue 141
# A Consumer entry's protected paths are config/hooks.json's own paths (decision 0020): the schema holds each
# to that syntax and refuses a list with none, and the Kernel and the session hooks read each alike.
from tools import jsonschema_lite
from tools.hooks import protected
self.assertEqual([p for p in check_examples.run(ROOT) if "consumer" in p], [])
schemas = {p.name[: -len(".schema.json")]: json.loads(p.read_text()) for p in (ROOT / "schemas").glob("*.schema.json")}
entry = json.loads((ROOT / "examples" / "consumer.json").read_text())
patterns = entry["verify"]["protected_paths"]
for wrong in ([], ["CODEOWNERS", "CODEOWNERS"], ["/CODEOWNERS"], ["scripts/factory-?.sh"], ["../CODEOWNERS"],
["docs//CODEOWNERS"], ["./CODEOWNERS"], ["scripts/{a,b}.sh"], ["C:\\scripts"]):
bad = copy.deepcopy(entry)
bad["verify"]["protected_paths"] = wrong
self.assertTrue(jsonschema_lite.validate(bad, schemas["consumer"], schemas=schemas), wrong)
bad = copy.deepcopy(entry)
del bad["verify"]["protected_paths"]
self.assertTrue(jsonschema_lite.validate(bad, schemas["consumer"], schemas=schemas))
# The rest of the entry is held whole too: each field there, each in its shape, nothing beside them.
for where, wrong in ((("repo",), "markets"), (("ring",), "canary"), (("owner_role",), "devops-"), (("ci_workflows",), []),
(("ci_workflows",), ["CI", "CI"]), (("ci_workflows",), [""]), (("verify", "setup"), "/bin/sh"),
(("verify", "test"), "../t.sh"), (("verify", "test"), "scripts/factory-*.sh"),
(("reviewers",), ["cubic", "cubic"]), (("reviewers",), ["Cubic"]), (("reviewers",), []), (("extra",), True),
(("owner_role",), None), (("repo",), 1), (("reviewers",), "cubic"), (("ci_workflows",), "CI"),
(("verify",), "scripts/"), (("verify", "protected_paths"), "CODEOWNERS"), (("verify", "setup"), 1),
(("verify", "extra"), True)):
bad = copy.deepcopy(entry)
parent = bad
for key in where[:-1]:
parent = parent[key]
parent[where[-1]] = wrong
self.assertTrue(jsonschema_lite.validate(bad, schemas["consumer"], schemas=schemas), (where, wrong))
for where in (("repo",), ("ring",), ("owner_role",), ("ci_workflows",), ("verify",), ("reviewers",), ("verify", "setup"), ("verify", "test")):
bad = copy.deepcopy(entry)
parent = bad
for key in where[:-1]:
parent = parent[key]
del parent[where[-1]]
self.assertTrue(jsonschema_lite.validate(bad, schemas["consumer"], schemas=schemas), where)
# Its setup and test scripts are among its protected paths, read by the Kernel's matcher, in an example as in a
# counter-example, or an author could weaken the tests it is judged by.
self.assertEqual(check_examples._unprotected(entry), [])
for paths, said in ((["scripts/factory-setup.sh"], "does not protect its own scripts/factory-test.sh"),
(["CODEOWNERS"], "protects neither its own scripts/factory-setup.sh nor scripts/factory-test.sh"),
(["scripts/factory-test.sh"], "does not protect its own scripts/factory-setup.sh"),
(["scripts/*-setup.sh", "SCRIPTS/"], "")):
bad = copy.deepcopy(entry)
bad["verify"]["protected_paths"] = paths
self.assertEqual(check_examples._unprotected(bad), ["$.verify: " + said] if said else [], paths)
bad["verify"]["protected_paths"] = ["scripts/factory-setup.sh"]
root = clone({"examples/consumer.json": json.dumps(bad)})
self.assertTrue(caught(check_examples.run(root), "consumer.json: $.verify: does not protect its own scripts/factory-test.sh"))
# Each the schema lets through is one the Kernel reads, and each the Kernel refuses the schema refuses too.
for pattern in patterns + ["*/__init__.*", "a/**/b/", "**"]:
self.assertTrue(derive.readable_pattern(pattern), pattern)
for pattern in ("/CODEOWNERS", "../CODEOWNERS", "docs//CODEOWNERS", "./CODEOWNERS"):
self.assertFalse(derive.readable_pattern(pattern), pattern)
# One matcher: what the Kernel finds each path to be, the session hooks find it to be, in any case.
hooks = protected.entries([(p, "") for p in patterns])
for path, want in (("scripts/factory-setup.sh", ["scripts/factory-setup.sh"]), ("SCRIPTS/Factory-Test.sh", ["scripts/factory-test.sh"]),
(".github/workflows/ci.yml", [".github/"]), (".github", [".github/"]), ("CODEOWNERS", ["CODEOWNERS"]),
("tests/conftest.py", ["tests/**/conftest.py"]),
("tests/a/b/conftest.py", ["tests/**/conftest.py"]), ("poetry.lock", ["**/*.lock"]),
("a/b/poetry.lock", ["**/*.lock"]), ("docs/CODEOWNERS", ["docs/CODEOWNERS"]), ("scripts/other.sh", []), (".githubx/a", [])):
self.assertEqual([p for p in patterns if derive.matches(p, path)], want, path)
self.assertEqual([p for p, _, _, whole in hooks if whole.match(path.casefold())], want, path)

def machine_users_live_answers(self, held: dict) -> list:
"""What GitHub answers when nothing has drifted: the org's repos hold the two left out, an archived one and an
advisory's fork, and each repo has another team beside the code owners'."""
Expand Down
Loading
Loading