trex/portfolio-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor docs into technical specs

Browse Source
This commit is contained in:
genichin
2026-04-13 23:20:25 +09:00
parent f3c870553d
commit 256b3709a0
19 changed files with 1713 additions and 2087 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/check_docs_sync.py
+13 -13
View File
@@ -2,11 +2,11 @@
"""Guardrail check for implementation-to-spec synchronization.
Rules:
- If files under app/ change, docs/portfoliohub-spec.md must be part of the same change set.
- If files under app/api/ or app/schemas/ change, docs/api-examples.md must be part of the same change set.
- If files under migrations/versions/ change, docs/db-schema-spec.md must be part of the same change set.
- If files under app/ change, at least one docs/technical/ file must be part of the same change set.
- If files under app/api/ or app/schemas/ change, docs/technical/api-contracts.md must be part of the same change set.
- If files under migrations/versions/ change, docs/technical/persistence-and-migrations.md must be part of the same change set.
- If migrations/versions/ files change, revision IDs found in changed migration files
must appear in docs/db-schema-spec.md.
must appear in docs/technical/persistence-and-migrations.md.
"""
from __future__ import annotations
@@ -18,9 +18,9 @@ import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
GENERAL_SPEC = "docs/portfoliohub-spec.md"
DB_SPEC = "docs/db-schema-spec.md"
API_EXAMPLES_SPEC = "docs/api-examples.md"
TECHNICAL_DOC_PREFIX = "docs/technical/"
DB_SPEC = "docs/technical/persistence-and-migrations.md"
API_EXAMPLES_SPEC = "docs/technical/api-contracts.md"
APP_PREFIX = "app/"
API_PREFIXES = ("app/api/", "app/schemas/")
MIGRATION_PREFIX = "migrations/versions/"
@@ -110,32 +110,32 @@ def run_check(*, staged: bool, against: str | None, head: str) -> int:
errors: list[str] = []
if needs_general_spec and GENERAL_SPEC not in changed_files:
if needs_general_spec and not any(path.startswith(TECHNICAL_DOC_PREFIX) for path in changed_files):
errors.append(
"Application code changed but docs/portfoliohub-spec.md was not updated in the same commit/PR."
"Application code changed but no docs/technical/ document was updated in the same commit/PR."
)
if needs_api_examples and API_EXAMPLES_SPEC not in changed_files:
errors.append(
"API/schema code changed but docs/api-examples.md was not updated in the same commit/PR."
"API/schema code changed but docs/technical/api-contracts.md was not updated in the same commit/PR."
)
if needs_db_spec and DB_SPEC not in changed_files:
errors.append(
"Migration changed but docs/db-schema-spec.md was not updated in the same commit/PR."
"Migration changed but docs/technical/persistence-and-migrations.md was not updated in the same commit/PR."
)
if needs_db_spec:
db_spec_path = ROOT / DB_SPEC
if not db_spec_path.exists():
errors.append("docs/db-schema-spec.md is missing.")
errors.append("docs/technical/persistence-and-migrations.md is missing.")
else:
db_spec_text = db_spec_path.read_text(encoding="utf-8")
changed_revisions = _collect_changed_revision_ids(changed_files)
missing_revisions = [rev for rev in changed_revisions if rev not in db_spec_text]
if missing_revisions:
errors.append(
"Migration revision IDs missing in docs/db-schema-spec.md: "
"Migration revision IDs missing in docs/technical/persistence-and-migrations.md: "
+ ", ".join(sorted(set(missing_revisions)))
)