From 7c84a6af2f3d3177c663dd42e1d8c7cf6ff3d5dd Mon Sep 17 00:00:00 2001 From: Willem Drijver Date: Thu, 5 Nov 2026 11:11:31 +0300 Subject: [PATCH] tools/schema.json: the frontmatter rules in one file The allowed values, patterns and folder rules move from check_frontmatter.py and kblib.py into tools/schema.json, with a short description per value. CI reads them from there, and the coming ApolloKnowledgeBase-Manager wizard reads the same file from main, so the wizard and CI can't disagree. The checks give the same results. Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.md | 4 ++ tools/check_frontmatter.py | 40 ++++++++---------- tools/kblib.py | 20 ++++----- tools/schema.json | 87 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 119 insertions(+), 32 deletions(-) create mode 100644 tools/schema.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9886028..70c60fb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -176,6 +176,10 @@ generated_from: # only for document intake, section 11 ### Allowed values +The machine-readable form of these rules is `tools/schema.json`: CI and the +ApolloKnowledgeBase-Manager wizard both read it. Change a rule there and here +together. + - **type:** `reference`, `guide`, `convention`, `best-practice`, `pitfall`, `example`, `lesson` - **status:** diff --git a/tools/check_frontmatter.py b/tools/check_frontmatter.py index 3d0fe1d..af27ab9 100644 --- a/tools/check_frontmatter.py +++ b/tools/check_frontmatter.py @@ -7,32 +7,28 @@ import yaml -from kblib import (HANDLE_RE, ROOT, content_files, expected_type, frontmatter, - maintainers, read, report) - -TYPES = {"reference", "guide", "convention", "best-practice", "pitfall", - "example", "lesson"} -STATUSES = {"draft", "reviewed", "verified", "deprecated"} -ORIGINS = {"human", "ai-assisted", "official"} -COMPONENTS = {"cpu-68080", "saga-video-isabelle", "saga-audio-arne", - "saga-dma-anni", "saga-3d-maggie", "libraries", "devs", - "filesys", "commands", "datatypes", "toolchain", "hardware", - "general"} -OSES = {"any", "apolloos-r10", "amigaos-3.9", "amigaos-3.2"} -MODES = {"any", "os-friendly", "os-takeover"} -BOARDS = {"any", "v4-standalone", "v4-unicorn", "v4-icedrake", "v4-manticore", - "v4-firebird"} +from kblib import (HANDLE_RE, ROOT, SCHEMA, content_files, expected_type, + frontmatter, maintainers, read, report) + +# The allowed values and patterns come from tools/schema.json, which the +# ApolloKnowledgeBase-Manager wizard reads too. +TYPES = set(SCHEMA["types"]) +STATUSES = set(SCHEMA["statuses"]) +ORIGINS = set(SCHEMA["origins"]) +COMPONENTS = set(SCHEMA["components"]) +OSES = set(SCHEMA["oses"]) +MODES = set(SCHEMA["modes"]) +BOARDS = set(SCHEMA["boards"]) # Kinds of source, highest rank first (CONTRIBUTING.md section 4). -BASES = ["core-developer", "measured", "official", "source-code", "other"] +BASES = list(SCHEMA["bases"]) # "any", one core ("Core 12841"), a range ("Core 12830-12840") or a minimum # ("Core 12841+"). -CORE_RE = re.compile(r"^(any|Core \d+(\+|-\d+)?)$") -REQUIRED = ["title", "type", "owner", "status", "origin", "components", - "applies_to"] -NEEDS_SOURCES = {"reference", "best-practice"} +CORE_RE = re.compile(SCHEMA["core_pattern"]) +REQUIRED = list(SCHEMA["required"]) +NEEDS_SOURCES = set(SCHEMA["needs_sources"]) -KEBAB_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*\.md$") -LESSON_RE = re.compile(r"^\d{4}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*\.md$") +KEBAB_RE = re.compile(SCHEMA["kebab_pattern"]) +LESSON_RE = re.compile(SCHEMA["lesson_pattern"]) def check_values(at, key, allowed): diff --git a/tools/kblib.py b/tools/kblib.py index f268620..7b4f52f 100644 --- a/tools/kblib.py +++ b/tools/kblib.py @@ -1,4 +1,5 @@ """Shared helpers for ApolloKnowledgeBase CI scripts.""" +import json import os import re import sys @@ -12,19 +13,18 @@ SKIP_DIRS = {"templates", "seed", "sources", "tools", "skills", "evals", ".github", ".git"} +# The rules live in tools/schema.json, shared with the ApolloKnowledgeBase- +# Manager wizard. +with open(os.path.join(ROOT, "tools", "schema.json"), encoding="utf-8") as _f: + SCHEMA = json.load(_f) + # The four knowledge pillars. Files in a pillar are references, except in # its best-practices/ and pitfalls/ subfolders. -PILLARS = {"core", "hardware", "os", "toolchain"} -PILLAR_SUBFOLDER_TYPES = {"best-practices": "best-practice", - "pitfalls": "pitfall"} +PILLARS = set(SCHEMA["pillars"]) +PILLAR_SUBFOLDER_TYPES = dict(SCHEMA["pillar_subfolder_types"]) # Expected `type` per cross-cutting top-level folder. -FOLDER_TYPES = { - "guides": "guide", - "conventions": "convention", - "examples": "example", - "lessons": "lesson", -} +FOLDER_TYPES = dict(SCHEMA["folder_types"]) MAINTAINERS_FILE = os.path.join(ROOT, ".github", "CODEOWNERS.base") @@ -50,7 +50,7 @@ def maintainers(): return set() -HANDLE_RE = re.compile(r"^@?[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$") +HANDLE_RE = re.compile(SCHEMA["handle_pattern"]) FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL) diff --git a/tools/schema.json b/tools/schema.json new file mode 100644 index 0000000..c35844d --- /dev/null +++ b/tools/schema.json @@ -0,0 +1,87 @@ +{ + "comment": "The frontmatter and placement rules of the knowledge base, in one place. Read by tools/check_frontmatter.py and tools/kblib.py (CI) and by the ApolloKnowledgeBase-Manager wizard. Change a rule here, and CONTRIBUTING.md with it.", + "types": { + "reference": "Facts: registers, APIs, behaviour, numbers", + "best-practice": "A technique that makes code faster, smaller or more robust, with evidence", + "pitfall": "A trap: symptom, cause, wrong and right code, evidence", + "guide": "Step-by-step how-to", + "example": "Small, compiling, tested code", + "convention": "A team rule for code or process", + "lesson": "What a project learned, for the lessons loop" + }, + "statuses": { + "draft": "Unreviewed", + "reviewed": "Checked by its owner", + "verified": "Tested on real hardware (needs last_verified)", + "deprecated": "Do not use (needs superseded_by)" + }, + "origins": { + "human": "Written by a person", + "ai-assisted": "Drafted with an AI", + "official": "Converted from official Apollo documentation (maintainers only)" + }, + "components": { + "cpu-68080": "The 68080 CPU, AMMX, FPU", + "saga-video-isabelle": "SAGA video (Isabelle)", + "saga-audio-arne": "SAGA audio (Arne)", + "saga-dma-anni": "SAGA DMA (Anni)", + "saga-3d-maggie": "SAGA 3D (Maggie)", + "libraries": "OS libraries", + "devs": "Devices and drivers", + "filesys": "Filesystems", + "commands": "Shell commands", + "datatypes": "Datatypes", + "toolchain": "ApolloCrossDev: compilers, assembler, libraries", + "hardware": "The V4 boards: connectors, headers, memory", + "general": "Anything else" + }, + "oses": { + "any": "Any OS", + "apolloos-r10": "ApolloOS R10", + "amigaos-3.9": "AmigaOS 3.9", + "amigaos-3.2": "AmigaOS 3.2" + }, + "modes": { + "any": "Any execution mode", + "os-friendly": "Uses the OS; direct SAGA access only at the developer's discretion", + "os-takeover": "Takes over the machine (games, demos) and restores it on exit" + }, + "boards": { + "any": "Every V4 model", + "v4-standalone": "V4 Standalone (SA)", + "v4-unicorn": "V4 UniCorn (UNI, A6000)", + "v4-icedrake": "V4 IceDrake (ICE)", + "v4-manticore": "V4 Manticore (MC)", + "v4-firebird": "V4 Firebird (FB)" + }, + "bases": { + "core-developer": "(G) the core developer", + "measured": "(M) measured on V4 hardware", + "official": "(official) official Apollo documentation", + "source-code": "(SRC) source code", + "other": "Anything else" + }, + "core_pattern": "^(any|Core \\d+(\\+|-\\d+)?)$", + "core_examples": ["any", "Core 12841", "Core 12830-12840", "Core 12841+"], + "required": ["title", "type", "owner", "status", "origin", "components", "applies_to"], + "needs_sources": ["reference", "best-practice"], + "kebab_pattern": "^[a-z0-9]+(-[a-z0-9]+)*\\.md$", + "lesson_pattern": "^\\d{4}-\\d{2}-[a-z0-9]+(-[a-z0-9]+)*\\.md$", + "handle_pattern": "^@?[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$", + "pillars": { + "core": "The 68080 and SAGA", + "hardware": "The V4 boards", + "os": "ApolloOS and AmigaOS on V4", + "toolchain": "ApolloCrossDev" + }, + "pillar_subfolder_types": { + "best-practices": "best-practice", + "pitfalls": "pitfall" + }, + "folder_types": { + "guides": "guide", + "conventions": "convention", + "examples": "example", + "lessons": "lesson" + } +}