semantics

2026-05-26 09:30:41 +03:00
parent 1e7bcecaea
commit 9ffa8af1dc
623 changed files with 28045 additions and 26557 deletions
--- a/backend/src/scripts/clean_release_cli.py
+++ b/backend/src/scripts/clean_release_cli.py
@@ -1,6 +1,6 @@
 # #region CleanReleaseCliScript [C:3] [TYPE Module] [SEMANTICS clean-release, artifact, manifest, candidate, cli]
 # @BRIEF Provide headless CLI commands for candidate registration, artifact import and manifest build.
-# @LAYER: Scripts
+# @LAYER Service
 # @RELATION CALLS -> ComplianceOrchestrator

 from __future__ import annotations
@@ -103,8 +103,8 @@ def build_parser() -> argparse.ArgumentParser:

 # #region run_candidate_register [TYPE Function]
 # @BRIEF Register candidate in repository via CLI command.
-# @PRE: Candidate ID must be unique.
-# @POST: Candidate is persisted in DRAFT status.
+# @PRE  Candidate ID must be unique.
+# @POST  Candidate is persisted in DRAFT status.
 def run_candidate_register(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository

@@ -132,8 +132,8 @@ def run_candidate_register(args: argparse.Namespace) -> int:

 # #region run_artifact_import [TYPE Function]
 # @BRIEF Import single artifact for existing candidate.
-# @PRE: Candidate must exist.
-# @POST: Artifact is persisted for candidate.
+# @PRE  Candidate must exist.
+# @POST  Artifact is persisted for candidate.
 def run_artifact_import(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository

@@ -165,8 +165,8 @@ def run_artifact_import(args: argparse.Namespace) -> int:

 # #region run_manifest_build [TYPE Function]
 # @BRIEF Build immutable manifest snapshot for candidate.
-# @PRE: Candidate must exist.
-# @POST: New manifest version is persisted.
+# @PRE  Candidate must exist.
+# @POST  New manifest version is persisted.
 def run_manifest_build(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository
    from ..services.clean_release.manifest_service import build_manifest_snapshot
@@ -199,8 +199,8 @@ def run_manifest_build(args: argparse.Namespace) -> int:

 # #region run_compliance_run [TYPE Function]
 # @BRIEF Execute compliance run for candidate with optional manifest fallback.
-# @PRE: Candidate exists and trusted snapshots are configured.
-# @POST: Returns run payload and exit code 0 on success.
+# @PRE  Candidate exists and trusted snapshots are configured.
+# @POST  Returns run payload and exit code 0 on success.
 def run_compliance_run(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository, get_config_manager

@@ -238,8 +238,8 @@ def run_compliance_run(args: argparse.Namespace) -> int:

 # #region run_compliance_status [TYPE Function]
 # @BRIEF Read run status by run id.
-# @PRE: Run exists.
-# @POST: Returns run status payload.
+# @PRE  Run exists.
+# @POST  Returns run status payload.
 def run_compliance_status(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository

@@ -270,8 +270,8 @@ def run_compliance_status(args: argparse.Namespace) -> int:

 # #region _to_payload [TYPE Function]
 # @BRIEF Serialize domain models for CLI JSON output across SQLAlchemy/Pydantic variants.
-# @PRE: value is serializable model or primitive object.
-# @POST: Returns dictionary payload without mutating value.
+# @PRE  value is serializable model or primitive object.
+# @POST  Returns dictionary payload without mutating value.
 def _to_payload(value: Any) -> dict[str, Any]:
    def _normalize(raw: Any) -> Any:
        if isinstance(raw, datetime):
@@ -300,8 +300,8 @@ def _to_payload(value: Any) -> dict[str, Any]:

 # #region run_compliance_report [TYPE Function]
 # @BRIEF Read immutable report by run id.
-# @PRE: Run and report exist.
-# @POST: Returns report payload.
+# @PRE  Run and report exist.
+# @POST  Returns report payload.
 def run_compliance_report(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository

@@ -327,8 +327,8 @@ def run_compliance_report(args: argparse.Namespace) -> int:

 # #region run_compliance_violations [TYPE Function]
 # @BRIEF Read run violations by run id.
-# @PRE: Run exists.
-# @POST: Returns violations payload.
+# @PRE  Run exists.
+# @POST  Returns violations payload.
 def run_compliance_violations(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository

@@ -352,8 +352,8 @@ def run_compliance_violations(args: argparse.Namespace) -> int:

 # #region run_approve [TYPE Function]
 # @BRIEF Approve candidate based on immutable PASSED report.
-# @PRE: Candidate and report exist; report is PASSED.
-# @POST: Persists APPROVED decision and returns success payload.
+# @PRE  Candidate and report exist; report is PASSED.
+# @POST  Persists APPROVED decision and returns success payload.
 def run_approve(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository

@@ -383,8 +383,8 @@ def run_approve(args: argparse.Namespace) -> int:

 # #region run_reject [TYPE Function]
 # @BRIEF Reject candidate without mutating compliance evidence.
-# @PRE: Candidate and report exist.
-# @POST: Persists REJECTED decision and returns success payload.
+# @PRE  Candidate and report exist.
+# @POST  Persists REJECTED decision and returns success payload.
 def run_reject(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository

@@ -414,8 +414,8 @@ def run_reject(args: argparse.Namespace) -> int:

 # #region run_publish [TYPE Function]
 # @BRIEF Publish approved candidate to target channel.
-# @PRE: Candidate is approved and report belongs to candidate.
-# @POST: Appends ACTIVE publication record and returns payload.
+# @PRE  Candidate is approved and report belongs to candidate.
+# @POST  Appends ACTIVE publication record and returns payload.
 def run_publish(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository

@@ -442,8 +442,8 @@ def run_publish(args: argparse.Namespace) -> int:

 # #region run_revoke [TYPE Function]
 # @BRIEF Revoke active publication record.
-# @PRE: Publication id exists and is ACTIVE.
-# @POST: Publication record status becomes REVOKED.
+# @PRE  Publication id exists and is ACTIVE.
+# @POST  Publication record status becomes REVOKED.
 def run_revoke(args: argparse.Namespace) -> int:
    from ..dependencies import get_clean_release_repository

--- a/backend/src/scripts/clean_release_tui.py
+++ b/backend/src/scripts/clean_release_tui.py
@@ -1,10 +1,10 @@
 # #region CleanReleaseTuiScript [C:3] [TYPE Module] [SEMANTICS clean-release, validate, compliance, release, tui-facade-adapter]
 # @BRIEF Interactive terminal interface for Enterprise Clean Release compliance validation.
-# @LAYER: UI
+# @LAYER UI
 # @RELATION DEPENDS_ON -> [ComplianceExecutionService]
 # @RELATION DEPENDS_ON -> [CleanReleaseRepository]
-# @INVARIANT: TUI refuses startup in non-TTY environments; headless flow is CLI/API only.
-# @DATA_CONTRACT: CLIArgs -> TUIExitCode
+# @INVARIANT  TUI refuses startup in non-TTY environments; headless flow is CLI/API only.
+# @DATA_CONTRACT  CLIArgs -> TUIExitCode
 import contextlib
 import curses
 from datetime import UTC, datetime
@@ -50,8 +50,8 @@ from src.services.clean_release.repository import CleanReleaseRepository

 # #region TuiFacadeAdapter [TYPE Class]
 # @BRIEF Thin TUI adapter that routes business mutations through application services.
-# @PRE: repository contains candidate and trusted policy/registry snapshots for execution.
-# @POST: Business actions return service results/errors without direct TUI-owned mutations.
+# @PRE  repository contains candidate and trusted policy/registry snapshots for execution.
+# @POST  Business actions return service results/errors without direct TUI-owned mutations.
 class TuiFacadeAdapter:
    def __init__(self, repository: CleanReleaseRepository):
        self.repository = repository
@@ -186,11 +186,11 @@ class TuiFacadeAdapter:
 # #endregion TuiFacadeAdapter
 # #region CleanReleaseTUI [TYPE Class]
 # @BRIEF Curses-based application for compliance monitoring.
-# @UX_STATE: READY -> Waiting for operator to start checks (F5).
-# @UX_STATE: RUNNING -> Executing compliance stages with progress feedback.
-# @UX_STATE: COMPLIANT -> Release candidate passed all checks.
-# @UX_STATE: BLOCKED -> Violations detected, release forbidden.
-# @UX_FEEDBACK: Red alerts for BLOCKED status, Green for COMPLIANT.
+# @UX_STATE  READY -> Waiting for operator to start checks (F5).
+# @UX_STATE  RUNNING -> Executing compliance stages with progress feedback.
+# @UX_STATE  COMPLIANT -> Release candidate passed all checks.
+# @UX_STATE  BLOCKED -> Violations detected, release forbidden.
+# @UX_FEEDBACK  Red alerts for BLOCKED status, Green for COMPLIANT.
 class CleanReleaseTUI:
    def __init__(self, stdscr: curses.window):
        self.stdscr = stdscr
@@ -474,10 +474,10 @@ class CleanReleaseTUI:
        self.stdscr.attron(curses.color_pair(1))
        self.stdscr.addstr(max_y - 1, 0, footer_text[:max_x])
        self.stdscr.attroff(curses.color_pair(1))
-    # [DEF:run_checks:Function]
+    # #region run_checks
    # @PURPOSE: Execute compliance run via facade adapter and update UI state.
-    # @PRE: Candidate and policy snapshots are present in repository.
-    # @POST: UI reflects final run/report/violation state from service result.
+    # @PRE  Candidate and policy snapshots are present in repository.
+    # @POST  UI reflects final run/report/violation state from service result.
    def run_checks(self):
        self.status = "RUNNING"
        self.report_id = None
@@ -514,7 +514,7 @@ class CleanReleaseTUI:
            self.status = CheckFinalStatus.FAILED
        self.refresh_overview()
        self.refresh_screen()
-    # [/DEF:run_checks:Function]
+    # #endregion run_checks
    def build_manifest(self):
        try:
            manifest = self.facade.build_manifest(
--- a/backend/src/scripts/create_admin.py
+++ b/backend/src/scripts/create_admin.py
@@ -1,14 +1,14 @@
 # #region CreateAdminScript [C:5] [TYPE Module] [SEMANTICS admin, search, user, cli]
 #
 # @BRIEF CLI tool for creating the initial admin user.
-# @LAYER: Infrastructure
-# @RELATION USES -> [AuthSecurityModule]
-# @RELATION USES -> [DatabaseModule]
-# @RELATION USES -> [AuthModels]
+# @LAYER Infrastructure
+# @RELATION CALLS -> [AuthSecurityModule]
+# @RELATION CALLS -> [DatabaseModule]
+# @RELATION CALLS -> [AuthModels]
 #
-# @INVARIANT: Admin user must have the "Admin" role.
-# @SIDE_EFFECT: Writes admin user to database
-# @DATA_CONTRACT: CLIArgs -> AdminUser
+# @INVARIANT  Admin user must have the "Admin" role.
+# @SIDE_EFFECT  Writes admin user to database
+# @DATA_CONTRACT  CLIArgs -> AdminUser

 import argparse
 from pathlib import Path
@@ -26,8 +26,8 @@ from src.models.auth import Role, User

 # #region create_admin [TYPE Function]
 # @BRIEF Creates an admin user and necessary roles/permissions.
-# @PRE:     username and password provided via CLI.
-# @POST:    Admin user exists in auth.db.
+# @PRE      username and password provided via CLI.
+# @POST     Admin user exists in auth.db.
 #
 def create_admin(username, password, email=None):
    seed_trace_id()
--- a/backend/src/scripts/delete_running_tasks.py
+++ b/backend/src/scripts/delete_running_tasks.py
@@ -4,7 +4,6 @@
 # @LAYER Infrastructure
 # @SEMANTICS maintenance, database, cleanup
 # @RELATION DEPENDS_ON ->[TaskRecord]
-# @RELATION DEPENDS_ON ->[TaskRecord]

 from sqlalchemy.orm import Session

@@ -43,7 +42,6 @@ def delete_running_tasks():
    finally:
        session.close()
 # #endregion delete_running_tasks
-# [/DEF:delete_running_tasks:Function]

 if __name__ == "__main__":
    delete_running_tasks()
--- a/backend/src/scripts/init_auth_db.py
+++ b/backend/src/scripts/init_auth_db.py
@@ -1,12 +1,12 @@
 # #region InitAuthDbScript [C:2] [TYPE Module] [SEMANTICS auth]
 #
 # @BRIEF Initializes the auth database and creates the necessary tables.
-# @LAYER:     Scripts
-# @RELATION CALLS -> init_db
-# @RELATION CALLS -> ensure_encryption_key
-# @RELATION CALLS -> seed_permissions
+# @LAYER Service
+# @RELATION CALLS -> [init_db]
+# @RELATION CALLS -> [ensure_encryption_key]
+# @RELATION CALLS -> [seed_permissions]
 #
-# @INVARIANT: Safe to run multiple times (idempotent).
+# @INVARIANT  Safe to run multiple times (idempotent).

 from pathlib import Path
 import sys
@@ -23,10 +23,10 @@ from src.scripts.seed_permissions import seed_permissions

 # #region run_init [C:3] [TYPE Function]
 # @BRIEF Main entry point for the initialization script.
-# @POST:    auth.db is initialized with the correct schema and seeded permissions.
-# @RELATION CALLS -> ensure_encryption_key
-# @RELATION CALLS -> init_db
-# @RELATION CALLS -> seed_permissions
+# @POST     auth.db is initialized with the correct schema and seeded permissions.
+# @RELATION CALLS -> [ensure_encryption_key]
+# @RELATION CALLS -> [init_db]
+# @RELATION CALLS -> [seed_permissions]
 def run_init():
    seed_trace_id()
    with belief_scope("init_auth_db"):
--- a/backend/src/scripts/seed_permissions.py
+++ b/backend/src/scripts/seed_permissions.py
@@ -1,15 +1,15 @@
 # #region SeedPermissionsScript [C:5] [TYPE Module] [SEMANTICS rbac, search, auth]
 #
 # @BRIEF Populates the auth database with initial system permissions.
-# @LAYER: Infrastructure
+# @LAYER Infrastructure
 # @RELATION DEPENDS_ON -> AuthSessionLocal
 # @RELATION DEPENDS_ON -> Permission
 # @RELATION DEPENDS_ON -> Role
 # @RELATION DEPENDS_ON -> AuthRepository
 #
-# @INVARIANT: Safe to run multiple times (idempotent).
-# @SIDE_EFFECT: Writes permissions to database
-# @DATA_CONTRACT: CLIArgs -> SeedSummary
+# @INVARIANT  Safe to run multiple times (idempotent).
+# @SIDE_EFFECT  Writes permissions to database
+# @DATA_CONTRACT  CLIArgs -> SeedSummary

 from pathlib import Path
 import sys
@@ -62,7 +62,7 @@ INITIAL_PERMISSIONS = [

 # #region seed_permissions [C:3] [TYPE Function]
 # @BRIEF Inserts missing permissions into the database.
-# @POST:    All INITIAL_PERMISSIONS exist in the DB.
+# @POST     All INITIAL_PERMISSIONS exist in the DB.
 # @RELATION DEPENDS_ON -> AuthSessionLocal
 # @RELATION DEPENDS_ON -> Permission
 # @RELATION DEPENDS_ON -> Role
--- a/backend/src/scripts/seed_superset_load_test.py
+++ b/backend/src/scripts/seed_superset_load_test.py
@@ -1,11 +1,11 @@
 # #region SeedSupersetLoadTestScript [C:5] [TYPE Module] [SEMANTICS superset, validate]
 #
 # @BRIEF Creates randomized load-test data in Superset by cloning chart configurations and creating dashboards in target environments.
-# @LAYER: Infrastructure
-# @RELATION USES -> [ConfigManager]
-# @RELATION USES -> [SupersetClient]
-# @INVARIANT: Created chart and dashboard names are globally unique for one script run.
-# @DATA_CONTRACT: CLIArgs -> TestDataSummary
+# @LAYER Infrastructure
+# @RELATION CALLS -> [ConfigManager]
+# @RELATION CALLS -> [SupersetClient]
+# @INVARIANT  Created chart and dashboard names are globally unique for one script run.
+# @DATA_CONTRACT  CLIArgs -> TestDataSummary

 import argparse
 import json
@@ -25,8 +25,8 @@ from src.core.superset_client import SupersetClient

 # #region _parse_args [TYPE Function]
 # @BRIEF Parses CLI arguments for load-test data generation.
-# @PRE: Script is called from CLI.
-# @POST: Returns validated argument namespace.
+# @PRE  Script is called from CLI.
+# @POST  Returns validated argument namespace.
 def _parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Seed Superset with load-test charts and dashboards"
@@ -69,8 +69,8 @@ def _parse_args() -> argparse.Namespace:

 # #region _extract_result_payload [TYPE Function]
 # @BRIEF Normalizes Superset API payloads that may be wrapped in `result`.
-# @PRE: payload is a JSON-decoded API response.
-# @POST: Returns the unwrapped object when present.
+# @PRE  payload is a JSON-decoded API response.
+# @POST  Returns the unwrapped object when present.
 def _extract_result_payload(payload: dict) -> dict:
    result = payload.get("result")
    if isinstance(result, dict):
@@ -83,8 +83,8 @@ def _extract_result_payload(payload: dict) -> dict:

 # #region _extract_created_id [TYPE Function]
 # @BRIEF Extracts object ID from create/update API response.
-# @PRE: payload is a JSON-decoded API response.
-# @POST: Returns integer object ID or None if missing.
+# @PRE  payload is a JSON-decoded API response.
+# @POST  Returns integer object ID or None if missing.
 def _extract_created_id(payload: dict) -> int | None:
    direct_id = payload.get("id")
    if isinstance(direct_id, int):
@@ -100,8 +100,8 @@ def _extract_created_id(payload: dict) -> int | None:

 # #region _generate_unique_name [TYPE Function]
 # @BRIEF Generates globally unique random names for charts/dashboards.
-# @PRE: used_names is mutable set for collision tracking.
-# @POST: Returns a unique string and stores it in used_names.
+# @PRE  used_names is mutable set for collision tracking.
+# @POST  Returns a unique string and stores it in used_names.
 def _generate_unique_name(prefix: str, used_names: set[str], rng: random.Random) -> str:
    adjectives = [
        "amber",
@@ -140,8 +140,8 @@ def _generate_unique_name(prefix: str, used_names: set[str], rng: random.Random)

 # #region _resolve_target_envs [TYPE Function]
 # @BRIEF Resolves requested environment IDs from configuration.
-# @PRE: env_ids is non-empty.
-# @POST: Returns mapping env_id -> configured environment object.
+# @PRE  env_ids is non-empty.
+# @POST  Returns mapping env_id -> configured environment object.
 def _resolve_target_envs(env_ids: list[str]) -> dict[str, Environment]:
    config_manager = ConfigManager()
    configured = {env.id: env for env in config_manager.get_environments()}
@@ -167,8 +167,8 @@ def _resolve_target_envs(env_ids: list[str]) -> dict[str, Environment]:

 # #region _build_chart_template_pool [TYPE Function]
 # @BRIEF Builds a pool of source chart templates to clone in one environment.
-# @PRE: Client is authenticated.
-# @POST: Returns non-empty list of chart payload templates.
+# @PRE  Client is authenticated.
+# @POST  Returns non-empty list of chart payload templates.
 def _build_chart_template_pool(
    client: SupersetClient, pool_size: int, rng: random.Random
 ) -> list[dict]:
@@ -242,9 +242,9 @@ def _build_chart_template_pool(

 # #region seed_superset_load_data [TYPE Function]
 # @BRIEF Creates dashboards and cloned charts for load testing across target environments.
-# @PRE: Target environments must be reachable and authenticated.
-# @POST: Returns execution statistics dictionary.
-# @SIDE_EFFECT: Creates objects in Superset environments.
+# @PRE  Target environments must be reachable and authenticated.
+# @POST  Returns execution statistics dictionary.
+# @SIDE_EFFECT  Creates objects in Superset environments.
 def seed_superset_load_data(args: argparse.Namespace) -> dict:
    seed_trace_id()
    rng = random.Random(args.seed)
@@ -370,8 +370,8 @@ def seed_superset_load_data(args: argparse.Namespace) -> dict:

 # #region main [TYPE Function]
 # @BRIEF CLI entrypoint for Superset load-test data seeding.
-# @PRE: Command line arguments are valid.
-# @POST: Prints summary and exits with non-zero status on failure.
+# @PRE  Command line arguments are valid.
+# @POST  Prints summary and exits with non-zero status on failure.
 def main() -> None:
    seed_trace_id()
    with belief_scope("seed_superset_load_test.main"):