busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

fix: commit semantic repair changes

Browse Source
This commit is contained in:
busya
2026-03-21 11:22:25 +03:00
parent 0900208c1a
commit abee05558f
272 changed files with 4603 additions and 1668 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
backend/src/api/auth.py
View File

@@ -24,11 +24,13 @@ import starlette.requests
# [/SECTION]
# [DEF:router:Variable]
# @RELATION: DEPENDS_ON -> fastapi.APIRouter
# @COMPLEXITY: 1
# @PURPOSE: APIRouter instance for authentication routes.
router = APIRouter(prefix="/api/auth", tags=["auth"])
# [/DEF:router:Variable]
# [DEF:login_for_access_token:Function]
# @COMPLEXITY: 3
# @PURPOSE: Authenticates a user and returns a JWT access token.
@@ -38,18 +40,19 @@ router = APIRouter(prefix="/api/auth", tags=["auth"])
# @PARAM: form_data (OAuth2PasswordRequestForm) - Login credentials.
# @PARAM: db (Session) - Auth database session.
# @RETURN: Token - The generated JWT token.
# @RELATION: CALLS -> [AuthService.authenticate_user]
# @RELATION: CALLS -> [AuthService.create_session]
# @RELATION: CALLS -> [authenticate_user]
# @RELATION: CALLS -> [create_session]
@router.post("/login", response_model=Token)
async def login_for_access_token(
form_data: OAuth2PasswordRequestForm = Depends(),
db: Session = Depends(get_auth_db)
form_data: OAuth2PasswordRequestForm = Depends(), db: Session = Depends(get_auth_db)
):
with belief_scope("api.auth.login"):
auth_service = AuthService(db)
user = auth_service.authenticate_user(form_data.username, form_data.password)
if not user:
log_security_event("LOGIN_FAILED", form_data.username, {"reason": "Invalid credentials"})
log_security_event(
"LOGIN_FAILED", form_data.username, {"reason": "Invalid credentials"}
)
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect username or password",
@@ -57,8 +60,11 @@ async def login_for_access_token(
)
log_security_event("LOGIN_SUCCESS", user.username, {"source": "LOCAL"})
return auth_service.create_session(user)
# [/DEF:login_for_access_token:Function]
# [DEF:read_users_me:Function]
# @COMPLEXITY: 3
# @PURPOSE: Retrieves the profile of the currently authenticated user.
@@ -71,8 +77,11 @@ async def login_for_access_token(
async def read_users_me(current_user: UserSchema = Depends(get_current_user)):
with belief_scope("api.auth.me"):
return current_user
# [/DEF:read_users_me:Function]
# [DEF:logout:Function]
# @COMPLEXITY: 3
# @PURPOSE: Logs out the current user (placeholder for session revocation).
@@ -87,8 +96,11 @@ async def logout(current_user: UserSchema = Depends(get_current_user)):
# In a stateless JWT setup, client-side token deletion is primary.
# Server-side revocation (blacklisting) can be added here if needed.
return {"message": "Successfully logged out"}
# [/DEF:logout:Function]
# [DEF:login_adfs:Function]
# @COMPLEXITY: 3
# @PURPOSE: Initiates the ADFS OIDC login flow.
@@ -100,34 +112,43 @@ async def login_adfs(request: starlette.requests.Request):
if not is_adfs_configured():
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="ADFS is not configured. Please set ADFS_CLIENT_ID, ADFS_CLIENT_SECRET, and ADFS_METADATA_URL environment variables."
detail="ADFS is not configured. Please set ADFS_CLIENT_ID, ADFS_CLIENT_SECRET, and ADFS_METADATA_URL environment variables.",
)
redirect_uri = request.url_for('auth_callback_adfs')
redirect_uri = request.url_for("auth_callback_adfs")
return await oauth.adfs.authorize_redirect(request, str(redirect_uri))
# [/DEF:login_adfs:Function]
# [DEF:auth_callback_adfs:Function]
# @COMPLEXITY: 3
# @PURPOSE: Handles the callback from ADFS after successful authentication.
# @POST: Provisions user JIT and returns session token.
# @RELATION: CALLS -> [AuthService.provision_adfs_user]
# @RELATION: CALLS -> [AuthService.create_session]
# @RELATION: CALLS -> [provision_adfs_user]
# @RELATION: CALLS -> [create_session]
@router.get("/callback/adfs", name="auth_callback_adfs")
async def auth_callback_adfs(request: starlette.requests.Request, db: Session = Depends(get_auth_db)):
async def auth_callback_adfs(
request: starlette.requests.Request, db: Session = Depends(get_auth_db)
):
with belief_scope("api.auth.callback_adfs"):
if not is_adfs_configured():
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="ADFS is not configured. Please set ADFS_CLIENT_ID, ADFS_CLIENT_SECRET, and ADFS_METADATA_URL environment variables."
detail="ADFS is not configured. Please set ADFS_CLIENT_ID, ADFS_CLIENT_SECRET, and ADFS_METADATA_URL environment variables.",
)
token = await oauth.adfs.authorize_access_token(request)
user_info = token.get('userinfo')
user_info = token.get("userinfo")
if not user_info:
raise HTTPException(status_code=400, detail="Failed to retrieve user info from ADFS")
raise HTTPException(
status_code=400, detail="Failed to retrieve user info from ADFS"
)
auth_service = AuthService(db)
user = auth_service.provision_adfs_user(user_info)
return auth_service.create_session(user)
# [/DEF:auth_callback_adfs:Function]
# [/DEF:AuthApi:Module]

76
backend/src/api/routes/__tests__/test_assistant_api.py
View File

@@ -1,5 +1,5 @@
# [DEF:AssistantApiTests:Module]
# @C: 3
# @COMPLEXITY: 3
# @SEMANTICS: tests, assistant, api
# @PURPOSE: Validate assistant API endpoint logic via direct async handler invocation.
# @RELATION: DEPENDS_ON -> backend.src.api.routes.assistant
@@ -21,15 +21,26 @@ from src.models.assistant import AssistantMessageRecord
# [DEF:_run_async:Function]
# @RELATION: BINDS_TO -> AssistantApiTests
def _run_async(coro):
return asyncio.run(coro)
# [/DEF:_run_async:Function]
# [DEF:_FakeTask:Class]
# @RELATION: BINDS_TO -> [AssistantApiTests]
class _FakeTask:
def __init__(self, id, status="SUCCESS", plugin_id="unknown", params=None, result=None, user_id=None):
def __init__(
self,
id,
status="SUCCESS",
plugin_id="unknown",
params=None,
result=None,
user_id=None,
):
self.id = id
self.status = status
self.plugin_id = plugin_id
@@ -38,18 +49,29 @@ class _FakeTask:
self.user_id = user_id
self.started_at = datetime.utcnow()
self.finished_at = datetime.utcnow()
# [/DEF:_FakeTask:Class]
# [DEF:_FakeTaskManager:Class]
# @RELATION: BINDS_TO -> [AssistantApiTests]
# @COMPLEXITY: 2
# @PURPOSE: In-memory task manager stub that records created tasks for route-level assertions.
# @INVARIANT: create_task stores tasks retrievable by get_task/get_tasks without external side effects.
class _FakeTaskManager:
def __init__(self):
self.tasks = {}
async def create_task(self, plugin_id, params, user_id=None):
task_id = f"task-{uuid.uuid4().hex[:8]}"
task = _FakeTask(task_id, status="STARTED", plugin_id=plugin_id, params=params, user_id=user_id)
task = _FakeTask(
task_id,
status="STARTED",
plugin_id=plugin_id,
params=params,
user_id=user_id,
)
self.tasks[task_id] = task
return task
@@ -57,10 +79,14 @@ class _FakeTaskManager:
return self.tasks.get(task_id)
def get_tasks(self, limit=20, offset=0):
return sorted(self.tasks.values(), key=lambda t: t.id, reverse=True)[offset : offset + limit]
return sorted(self.tasks.values(), key=lambda t: t.id, reverse=True)[
offset : offset + limit
]
def get_all_tasks(self):
return list(self.tasks.values())
# [/DEF:_FakeTaskManager:Class]
@@ -79,14 +105,19 @@ class _FakeConfigManager:
class _Settings:
default_environment_id = "dev"
llm = {}
class _Config:
settings = _Settings()
environments = []
return _Config()
# [/DEF:_FakeConfigManager:Class]
# [DEF:_admin_user:Function]
# @RELATION: BINDS_TO -> AssistantApiTests
def _admin_user():
user = MagicMock(spec=User)
user.id = "u-admin"
@@ -95,16 +126,21 @@ def _admin_user():
role.name = "Admin"
user.roles = [role]
return user
# [/DEF:_admin_user:Function]
# [DEF:_limited_user:Function]
# @RELATION: BINDS_TO -> AssistantApiTests
def _limited_user():
user = MagicMock(spec=User)
user.id = "u-limited"
user.username = "limited"
user.roles = []
return user
# [/DEF:_limited_user:Function]
@@ -136,11 +172,16 @@ class _FakeQuery:
def count(self):
return len(self.items)
# [/DEF:_FakeQuery:Class]
# [DEF:_FakeDb:Class]
# @RELATION: BINDS_TO -> [AssistantApiTests]
# @COMPLEXITY: 2
# @PURPOSE: Explicit in-memory DB session double limited to assistant message persistence paths.
# @INVARIANT: query/add/merge stay deterministic and never emulate unrelated SQLAlchemy behavior.
class _FakeDb:
def __init__(self):
self.added = []
@@ -164,19 +205,25 @@ class _FakeDb:
def refresh(self, obj):
pass
# [/DEF:_FakeDb:Class]
# [DEF:_clear_assistant_state:Function]
# @RELATION: BINDS_TO -> AssistantApiTests
def _clear_assistant_state():
assistant_routes.CONVERSATIONS.clear()
assistant_routes.USER_ACTIVE_CONVERSATION.clear()
assistant_routes.CONFIRMATIONS.clear()
assistant_routes.ASSISTANT_AUDIT.clear()
# [/DEF:_clear_assistant_state:Function]
# [DEF:test_unknown_command_returns_needs_clarification:Function]
# @RELATION: BINDS_TO -> AssistantApiTests
# @PURPOSE: Unknown command should return clarification state and unknown intent.
def test_unknown_command_returns_needs_clarification(monkeypatch):
_clear_assistant_state()
@@ -185,35 +232,44 @@ def test_unknown_command_returns_needs_clarification(monkeypatch):
# We mock LLM planner to return low confidence
monkeypatch.setattr(assistant_routes, "_plan_intent_with_llm", lambda *a, **k: None)
resp = _run_async(assistant_routes.send_message(
resp = _run_async(
assistant_routes.send_message(
req,
current_user=_admin_user(),
task_manager=_FakeTaskManager(),
config_manager=_FakeConfigManager(),
db=_FakeDb()
))
db=_FakeDb(),
)
)
assert resp.state == "needs_clarification"
assert "уточните" in resp.text.lower() or "неоднозначна" in resp.text.lower()
# [/DEF:test_unknown_command_returns_needs_clarification:Function]
# [DEF:test_capabilities_question_returns_successful_help:Function]
# @RELATION: BINDS_TO -> AssistantApiTests
# @PURPOSE: Capability query should return deterministic help response.
def test_capabilities_question_returns_successful_help(monkeypatch):
_clear_assistant_state()
req = assistant_routes.AssistantMessageRequest(message="что ты умеешь?")
resp = _run_async(assistant_routes.send_message(
resp = _run_async(
assistant_routes.send_message(
req,
current_user=_admin_user(),
task_manager=_FakeTaskManager(),
config_manager=_FakeConfigManager(),
db=_FakeDb()
))
db=_FakeDb(),
)
)
assert resp.state == "success"
assert "я могу сделать" in resp.text.lower()
# [/DEF:test_capabilities_question_returns_successful_help:Function]
# ... (rest of file trimmed for length, I've seen it and I'll keep the existing [DEF]s as is but add @RELATION)

49
backend/src/api/routes/__tests__/test_assistant_authz.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.api.routes.__tests__.test_assistant_authz:Module]
# [DEF:TestAssistantAuthz:Module]
# @COMPLEXITY: 3
# @SEMANTICS: tests, assistant, authz, confirmation, rbac
# @PURPOSE: Verify assistant confirmation ownership, expiration, and deny behavior for restricted users.
@@ -16,8 +16,12 @@ from fastapi import HTTPException
# Force isolated sqlite databases for test module before dependencies import.
os.environ.setdefault("DATABASE_URL", "sqlite:////tmp/ss_tools_assistant_authz.db")
os.environ.setdefault("TASKS_DATABASE_URL", "sqlite:////tmp/ss_tools_assistant_authz_tasks.db")
os.environ.setdefault("AUTH_DATABASE_URL", "sqlite:////tmp/ss_tools_assistant_authz_auth.db")
os.environ.setdefault(
"TASKS_DATABASE_URL", "sqlite:////tmp/ss_tools_assistant_authz_tasks.db"
)
os.environ.setdefault(
"AUTH_DATABASE_URL", "sqlite:////tmp/ss_tools_assistant_authz_auth.db"
)
from src.api.routes import assistant as assistant_module
from src.models.assistant import (
@@ -28,6 +32,7 @@ from src.models.assistant import (
# [DEF:_run_async:Function]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 1
# @PURPOSE: Execute async endpoint handler in synchronous test context.
# @PRE: coroutine is awaitable endpoint invocation.
@@ -37,7 +42,10 @@ def _run_async(coroutine):
# [/DEF:_run_async:Function]
# [DEF:_FakeTask:Class]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 1
# @PURPOSE: Lightweight task model used for assistant authz tests.
class _FakeTask:
@@ -49,8 +57,10 @@ class _FakeTask:
# [/DEF:_FakeTask:Class]
# [DEF:_FakeTaskManager:Class]
# @COMPLEXITY: 1
# @PURPOSE: Minimal task manager for deterministic operation creation and lookup.
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 2
# @PURPOSE: In-memory task manager double that records assistant-created tasks deterministically.
# @INVARIANT: Only create_task/get_task/get_tasks behavior used by assistant authz routes is emulated.
class _FakeTaskManager:
def __init__(self):
self._created = []
@@ -73,6 +83,7 @@ class _FakeTaskManager:
# [/DEF:_FakeTaskManager:Class]
# [DEF:_FakeConfigManager:Class]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 1
# @PURPOSE: Provide deterministic environment aliases required by intent parsing.
class _FakeConfigManager:
@@ -85,6 +96,7 @@ class _FakeConfigManager:
# [/DEF:_FakeConfigManager:Class]
# [DEF:_admin_user:Function]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 1
# @PURPOSE: Build admin principal fixture.
# @PRE: Test requires privileged principal for risky operations.
@@ -96,6 +108,7 @@ def _admin_user():
# [/DEF:_admin_user:Function]
# [DEF:_other_admin_user:Function]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 1
# @PURPOSE: Build second admin principal fixture for ownership tests.
# @PRE: Ownership mismatch scenario needs distinct authenticated actor.
@@ -107,6 +120,7 @@ def _other_admin_user():
# [/DEF:_other_admin_user:Function]
# [DEF:_limited_user:Function]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 1
# @PURPOSE: Build limited principal without required assistant execution privileges.
# @PRE: Permission denial scenario needs non-admin actor.
@@ -117,7 +131,10 @@ def _limited_user():
# [/DEF:_limited_user:Function]
# [DEF:_FakeQuery:Class]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 1
# @PURPOSE: Minimal chainable query object for fake DB interactions.
class _FakeQuery:
@@ -150,8 +167,10 @@ class _FakeQuery:
# [/DEF:_FakeQuery:Class]
# [DEF:_FakeDb:Class]
# @COMPLEXITY: 1
# @PURPOSE: In-memory session substitute for assistant route persistence calls.
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 2
# @PURPOSE: In-memory DB session double constrained to assistant message/confirmation/audit persistence paths.
# @INVARIANT: query/add/merge are intentionally narrow and must not claim full SQLAlchemy Session semantics.
class _FakeDb:
def __init__(self):
self._messages = []
@@ -197,6 +216,7 @@ class _FakeDb:
# [/DEF:_FakeDb:Class]
# [DEF:_clear_assistant_state:Function]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @COMPLEXITY: 1
# @PURPOSE: Reset assistant process-local state between test cases.
# @PRE: Assistant globals may contain state from prior tests.
@@ -209,7 +229,10 @@ def _clear_assistant_state():
# [/DEF:_clear_assistant_state:Function]
# [DEF:test_confirmation_owner_mismatch_returns_403:Function]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @PURPOSE: Confirm endpoint should reject requests from user that does not own the confirmation token.
# @PRE: Confirmation token is created by first admin actor.
# @POST: Second actor receives 403 on confirm operation.
@@ -245,7 +268,10 @@ def test_confirmation_owner_mismatch_returns_403():
# [/DEF:test_confirmation_owner_mismatch_returns_403:Function]
# [DEF:test_expired_confirmation_cannot_be_confirmed:Function]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @PURPOSE: Expired confirmation token should be rejected and not create task.
# @PRE: Confirmation token exists and is manually expired before confirm request.
# @POST: Confirm endpoint raises 400 and no task is created.
@@ -265,7 +291,9 @@ def test_expired_confirmation_cannot_be_confirmed():
db=db,
)
)
assistant_module.CONFIRMATIONS[create.confirmation_id].expires_at = datetime.utcnow() - timedelta(minutes=1)
assistant_module.CONFIRMATIONS[create.confirmation_id].expires_at = (
datetime.utcnow() - timedelta(minutes=1)
)
with pytest.raises(HTTPException) as exc:
_run_async(
@@ -282,7 +310,10 @@ def test_expired_confirmation_cannot_be_confirmed():
# [/DEF:test_expired_confirmation_cannot_be_confirmed:Function]
# [DEF:test_limited_user_cannot_launch_restricted_operation:Function]
# @RELATION: BINDS_TO -> TestAssistantAuthz
# @PURPOSE: Limited user should receive denied state for privileged operation.
# @PRE: Restricted user attempts dangerous deploy command.
# @POST: Assistant returns denied state and does not execute operation.
@@ -303,4 +334,4 @@ def test_limited_user_cannot_launch_restricted_operation():
# [/DEF:test_limited_user_cannot_launch_restricted_operation:Function]
# [/DEF:backend.src.api.routes.__tests__.test_assistant_authz:Module]
# [/DEF:TestAssistantAuthz:Module]

42
backend/src/api/routes/__tests__/test_clean_release_api.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.tests.api.routes.test_clean_release_api:Module]
# [DEF:TestCleanReleaseApi:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, api, clean-release, checks, reports
# @PURPOSE: Contract tests for clean release checks and reports endpoints.
# @LAYER: Domain
# @RELATION: TESTS -> backend.src.api.routes.clean_release
# @INVARIANT: API returns deterministic payload shapes for checks and reports.
from datetime import datetime, timezone
@@ -25,6 +25,8 @@ from src.models.clean_release import (
from src.services.clean_release.repository import CleanReleaseRepository
# [DEF:_repo_with_seed_data:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseApi
def _repo_with_seed_data() -> CleanReleaseRepository:
repo = CleanReleaseRepository()
repo.save_candidate(
@@ -72,6 +74,11 @@ def _repo_with_seed_data() -> CleanReleaseRepository:
return repo
# [/DEF:_repo_with_seed_data:Function]
# [DEF:test_start_check_and_get_status_contract:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseApi
def test_start_check_and_get_status_contract():
repo = _repo_with_seed_data()
app.dependency_overrides[get_clean_release_repository] = lambda: repo
@@ -89,7 +96,9 @@ def test_start_check_and_get_status_contract():
)
assert start.status_code == 202
payload = start.json()
assert set(["check_run_id", "candidate_id", "status", "started_at"]).issubset(payload.keys())
assert set(["check_run_id", "candidate_id", "status", "started_at"]).issubset(
payload.keys()
)
check_run_id = payload["check_run_id"]
status_resp = client.get(f"/api/clean-release/checks/{check_run_id}")
@@ -102,6 +111,11 @@ def test_start_check_and_get_status_contract():
app.dependency_overrides.clear()
# [/DEF:test_start_check_and_get_status_contract:Function]
# [DEF:test_get_report_not_found_returns_404:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseApi
def test_get_report_not_found_returns_404():
repo = _repo_with_seed_data()
app.dependency_overrides[get_clean_release_repository] = lambda: repo
@@ -112,6 +126,12 @@ def test_get_report_not_found_returns_404():
finally:
app.dependency_overrides.clear()
# [/DEF:test_get_report_not_found_returns_404:Function]
# [DEF:test_get_report_success:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseApi
def test_get_report_success():
repo = _repo_with_seed_data()
report = ComplianceReport(
@@ -123,7 +143,7 @@ def test_get_report_success():
operator_summary="all systems go",
structured_payload_ref="manifest-1",
violations_count=0,
blocking_violations_count=0
blocking_violations_count=0,
)
repo.save_report(report)
app.dependency_overrides[get_clean_release_repository] = lambda: repo
@@ -135,8 +155,12 @@ def test_get_report_success():
finally:
app.dependency_overrides.clear()
# [/DEF:backend.tests.api.routes.test_clean_release_api:Module]
# [/DEF:test_get_report_success:Function]
# [DEF:test_prepare_candidate_api_success:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseApi
def test_prepare_candidate_api_success():
repo = _repo_with_seed_data()
app.dependency_overrides[get_clean_release_repository] = lambda: repo
@@ -146,7 +170,9 @@ def test_prepare_candidate_api_success():
"/api/clean-release/candidates/prepare",
json={
"candidate_id": "2026.03.03-rc1",
"artifacts": [{"path": "file1.txt", "category": "system-init", "reason": "core"}],
"artifacts": [
{"path": "file1.txt", "category": "system-init", "reason": "core"}
],
"sources": ["repo.intra.company.local"],
"operator_id": "operator-1",
},
@@ -157,3 +183,7 @@ def test_prepare_candidate_api_success():
assert "manifest_id" in data
finally:
app.dependency_overrides.clear()
# [/DEF:test_prepare_candidate_api_success:Function]
# [/DEF:TestCleanReleaseApi:Module]

13
backend/src/api/routes/__tests__/test_clean_release_legacy_compat.py
View File

@@ -1,8 +1,8 @@
# [DEF:backend.src.api.routes.__tests__.test_clean_release_legacy_compat:Module]
# [DEF:TestCleanReleaseLegacyCompat:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @PURPOSE: Compatibility tests for legacy clean-release API paths retained during v2 migration.
# @LAYER: Tests
# @RELATION: TESTS -> backend.src.api.routes.clean_release
from __future__ import annotations
@@ -29,6 +29,7 @@ from src.services.clean_release.repository import CleanReleaseRepository
# [DEF:_seed_legacy_repo:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseLegacyCompat
# @PURPOSE: Seed in-memory repository with minimum trusted data for legacy endpoint contracts.
# @PRE: Repository is empty.
# @POST: Candidate, policy, registry and manifest are available for legacy checks flow.
@@ -111,6 +112,8 @@ def _seed_legacy_repo() -> CleanReleaseRepository:
# [/DEF:_seed_legacy_repo:Function]
# [DEF:test_legacy_prepare_endpoint_still_available:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseLegacyCompat
def test_legacy_prepare_endpoint_still_available() -> None:
repo = _seed_legacy_repo()
app.dependency_overrides[get_clean_release_repository] = lambda: repo
@@ -133,6 +136,10 @@ def test_legacy_prepare_endpoint_still_available() -> None:
app.dependency_overrides.clear()
# [/DEF:test_legacy_prepare_endpoint_still_available:Function]
# [DEF:test_legacy_checks_endpoints_still_available:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseLegacyCompat
def test_legacy_checks_endpoints_still_available() -> None:
repo = _seed_legacy_repo()
app.dependency_overrides[get_clean_release_repository] = lambda: repo
@@ -162,4 +169,4 @@ def test_legacy_checks_endpoints_still_available() -> None:
app.dependency_overrides.clear()
# [/DEF:backend.src.api.routes.__tests__.test_clean_release_legacy_compat:Module]
# [/DEF:TestCleanReleaseLegacyCompat:Module]# [/DEF:test_legacy_checks_endpoints_still_available:Function]

12
backend/src/api/routes/__tests__/test_clean_release_source_policy.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.tests.api.routes.test_clean_release_source_policy:Module]
# [DEF:TestCleanReleaseSourcePolicy:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, api, clean-release, source-policy
# @PURPOSE: Validate API behavior for source isolation violations in clean release preparation.
# @LAYER: Domain
# @RELATION: TESTS -> backend.src.api.routes.clean_release
# @INVARIANT: External endpoints must produce blocking violation entries.
from datetime import datetime, timezone
@@ -22,6 +22,8 @@ from src.models.clean_release import (
from src.services.clean_release.repository import CleanReleaseRepository
# [DEF:_repo_with_seed_data:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseSourcePolicy
def _repo_with_seed_data() -> CleanReleaseRepository:
repo = CleanReleaseRepository()
@@ -72,6 +74,10 @@ def _repo_with_seed_data() -> CleanReleaseRepository:
return repo
# [/DEF:_repo_with_seed_data:Function]
# [DEF:test_prepare_candidate_blocks_external_source:Function]
# @RELATION: BINDS_TO -> TestCleanReleaseSourcePolicy
def test_prepare_candidate_blocks_external_source():
repo = _repo_with_seed_data()
app.dependency_overrides[get_clean_release_repository] = lambda: repo
@@ -97,4 +103,4 @@ def test_prepare_candidate_blocks_external_source():
app.dependency_overrides.clear()
# [/DEF:backend.tests.api.routes.test_clean_release_source_policy:Module]
# [/DEF:TestCleanReleaseSourcePolicy:Module]# [/DEF:test_prepare_candidate_blocks_external_source:Function]

42
backend/src/api/routes/__tests__/test_clean_release_v2_api.py
View File

@@ -23,7 +23,10 @@ from src.services.clean_release.enums import CandidateStatus
client = TestClient(app)
# [REASON] Implementing API contract tests for candidate/artifact/manifest endpoints (T012).
# [DEF:test_candidate_registration_contract:Function]
# @RELATION: BINDS_TO -> CleanReleaseV2ApiTests
def test_candidate_registration_contract():
"""
@TEST_SCENARIO: candidate_registration -> Should return 201 and candidate DTO.
@@ -33,7 +36,7 @@ def test_candidate_registration_contract():
"id": "rc-test-001",
"version": "1.0.0",
"source_snapshot_ref": "git:sha123",
"created_by": "test-user"
"created_by": "test-user",
}
response = client.post("/api/v2/clean-release/candidates", json=payload)
assert response.status_code == 201
@@ -41,6 +44,12 @@ def test_candidate_registration_contract():
assert data["id"] == "rc-test-001"
assert data["status"] == CandidateStatus.DRAFT.value
# [/DEF:test_candidate_registration_contract:Function]
# [DEF:test_artifact_import_contract:Function]
# @RELATION: BINDS_TO -> CleanReleaseV2ApiTests
def test_artifact_import_contract():
"""
@TEST_SCENARIO: artifact_import -> Should return 200 and success status.
@@ -51,25 +60,30 @@ def test_artifact_import_contract():
"id": candidate_id,
"version": "1.0.0",
"source_snapshot_ref": "git:sha123",
"created_by": "test-user"
"created_by": "test-user",
}
create_response = client.post("/api/v2/clean-release/candidates", json=bootstrap_candidate)
create_response = client.post(
"/api/v2/clean-release/candidates", json=bootstrap_candidate
)
assert create_response.status_code == 201
payload = {
"artifacts": [
{
"id": "art-1",
"path": "bin/app.exe",
"sha256": "hash123",
"size": 1024
}
{"id": "art-1", "path": "bin/app.exe", "sha256": "hash123", "size": 1024}
]
}
response = client.post(f"/api/v2/clean-release/candidates/{candidate_id}/artifacts", json=payload)
response = client.post(
f"/api/v2/clean-release/candidates/{candidate_id}/artifacts", json=payload
)
assert response.status_code == 200
assert response.json()["status"] == "success"
# [/DEF:test_artifact_import_contract:Function]
# [DEF:test_manifest_build_contract:Function]
# @RELATION: BINDS_TO -> CleanReleaseV2ApiTests
def test_manifest_build_contract():
"""
@TEST_SCENARIO: manifest_build -> Should return 201 and manifest DTO.
@@ -80,9 +94,11 @@ def test_manifest_build_contract():
"id": candidate_id,
"version": "1.0.0",
"source_snapshot_ref": "git:sha123",
"created_by": "test-user"
"created_by": "test-user",
}
create_response = client.post("/api/v2/clean-release/candidates", json=bootstrap_candidate)
create_response = client.post(
"/api/v2/clean-release/candidates", json=bootstrap_candidate
)
assert create_response.status_code == 201
response = client.post(f"/api/v2/clean-release/candidates/{candidate_id}/manifests")
@@ -91,4 +107,6 @@ def test_manifest_build_contract():
assert "manifest_digest" in data
assert data["candidate_id"] == candidate_id
# [/DEF:test_manifest_build_contract:Function]
# [/DEF:CleanReleaseV2ApiTests:Module]

12
backend/src/api/routes/__tests__/test_clean_release_v2_release_api.py
View File

@@ -23,6 +23,8 @@ test_app.include_router(clean_release_v2_router)
client = TestClient(test_app)
# [DEF:_seed_candidate_and_passed_report:Function]
# @RELATION: BINDS_TO -> CleanReleaseV2ReleaseApiTests
def _seed_candidate_and_passed_report() -> tuple[str, str]:
repository = get_clean_release_repository()
candidate_id = f"api-release-candidate-{uuid4()}"
@@ -52,6 +54,10 @@ def _seed_candidate_and_passed_report() -> tuple[str, str]:
return candidate_id, report_id
# [/DEF:_seed_candidate_and_passed_report:Function]
# [DEF:test_release_approve_and_publish_revoke_contract:Function]
# @RELATION: BINDS_TO -> CleanReleaseV2ReleaseApiTests
def test_release_approve_and_publish_revoke_contract() -> None:
"""Contract for approve -> publish -> revoke lifecycle endpoints."""
candidate_id, report_id = _seed_candidate_and_passed_report()
@@ -90,6 +96,10 @@ def test_release_approve_and_publish_revoke_contract() -> None:
assert revoke_payload["publication"]["status"] == "REVOKED"
# [/DEF:test_release_approve_and_publish_revoke_contract:Function]
# [DEF:test_release_reject_contract:Function]
# @RELATION: BINDS_TO -> CleanReleaseV2ReleaseApiTests
def test_release_reject_contract() -> None:
"""Contract for reject endpoint."""
candidate_id, report_id = _seed_candidate_and_passed_report()
@@ -104,4 +114,4 @@ def test_release_reject_contract() -> None:
assert payload["decision"] == "REJECTED"
# [/DEF:CleanReleaseV2ReleaseApiTests:Module]
# [/DEF:CleanReleaseV2ReleaseApiTests:Module]# [/DEF:test_release_reject_contract:Function]

7
backend/src/api/routes/__tests__/test_connections_routes.py
View File

@@ -39,6 +39,8 @@ def db_session():
session.close()
# [DEF:test_list_connections_bootstraps_missing_table:Function]
# @RELATION: BINDS_TO -> ConnectionsRoutesTests
def test_list_connections_bootstraps_missing_table(db_session):
from src.api.routes.connections import list_connections
@@ -49,6 +51,10 @@ def test_list_connections_bootstraps_missing_table(db_session):
assert "connection_configs" in inspector.get_table_names()
# [/DEF:test_list_connections_bootstraps_missing_table:Function]
# [DEF:test_create_connection_bootstraps_missing_table:Function]
# @RELATION: BINDS_TO -> ConnectionsRoutesTests
def test_create_connection_bootstraps_missing_table(db_session):
from src.api.routes.connections import ConnectionCreate, create_connection
@@ -70,3 +76,4 @@ def test_create_connection_bootstraps_missing_table(db_session):
assert "connection_configs" in inspector.get_table_names()
# [/DEF:ConnectionsRoutesTests:Module]
# [/DEF:test_create_connection_bootstraps_missing_table:Function]

280
backend/src/api/routes/__tests__/test_dashboards.py
View File

@@ -10,7 +10,14 @@ from datetime import datetime, timezone
from fastapi.testclient import TestClient
from src.app import app
from src.api.routes.dashboards import DashboardsResponse
from src.dependencies import get_current_user, has_permission, get_config_manager, get_task_manager, get_resource_service, get_mapping_service
from src.dependencies import (
get_current_user,
has_permission,
get_config_manager,
get_task_manager,
get_resource_service,
get_mapping_service,
)
from src.core.database import get_db
from src.services.profile_service import ProfileService as DomainProfileService
@@ -23,6 +30,7 @@ admin_role = MagicMock()
admin_role.name = "Admin"
mock_user.roles.append(admin_role)
@pytest.fixture(autouse=True)
def mock_deps():
config_manager = MagicMock()
@@ -39,9 +47,15 @@ def mock_deps():
app.dependency_overrides[get_current_user] = lambda: mock_user
app.dependency_overrides[get_db] = lambda: db
app.dependency_overrides[has_permission("plugin:migration", "READ")] = lambda: mock_user
app.dependency_overrides[has_permission("plugin:migration", "EXECUTE")] = lambda: mock_user
app.dependency_overrides[has_permission("plugin:backup", "EXECUTE")] = lambda: mock_user
app.dependency_overrides[has_permission("plugin:migration", "READ")] = (
lambda: mock_user
)
app.dependency_overrides[has_permission("plugin:migration", "EXECUTE")] = (
lambda: mock_user
)
app.dependency_overrides[has_permission("plugin:backup", "EXECUTE")] = (
lambda: mock_user
)
app.dependency_overrides[has_permission("tasks", "READ")] = lambda: mock_user
yield {
@@ -53,10 +67,12 @@ def mock_deps():
}
app.dependency_overrides.clear()
client = TestClient(app)
# [DEF:test_get_dashboards_success:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboards listing returns a populated response that satisfies the schema contract.
# @TEST: GET /api/dashboards returns 200 and valid schema
# @PRE: env_id exists
@@ -69,15 +85,17 @@ def test_get_dashboards_success(mock_deps):
mock_deps["task"].get_all_tasks.return_value = []
# @TEST_FIXTURE: dashboard_list_happy -> {"id": 1, "title": "Main Revenue"}
mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
mock_deps["resource"].get_dashboards_with_status = AsyncMock(
return_value=[
{
"id": 1,
"title": "Main Revenue",
"slug": "main-revenue",
"git_status": {"branch": "main", "sync_status": "OK"},
"last_task": {"task_id": "task-1", "status": "SUCCESS"}
"last_task": {"task_id": "task-1", "status": "SUCCESS"},
}
])
]
)
response = client.get("/api/dashboards?env_id=prod")
@@ -96,6 +114,7 @@ def test_get_dashboards_success(mock_deps):
# [DEF:test_get_dashboards_with_search:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboards listing applies the search filter and returns only matching rows.
# @TEST: GET /api/dashboards filters by search term
# @PRE: search parameter provided
@@ -108,9 +127,22 @@ def test_get_dashboards_with_search(mock_deps):
async def mock_get_dashboards(env, tasks, include_git_status=False):
return [
{"id": 1, "title": "Sales Report", "slug": "sales", "git_status": {"branch": "main", "sync_status": "OK"}, "last_task": None},
{"id": 2, "title": "Marketing Dashboard", "slug": "marketing", "git_status": {"branch": "main", "sync_status": "OK"}, "last_task": None}
{
"id": 1,
"title": "Sales Report",
"slug": "sales",
"git_status": {"branch": "main", "sync_status": "OK"},
"last_task": None,
},
{
"id": 2,
"title": "Marketing Dashboard",
"slug": "marketing",
"git_status": {"branch": "main", "sync_status": "OK"},
"last_task": None,
},
]
mock_deps["resource"].get_dashboards_with_status = AsyncMock(
side_effect=mock_get_dashboards
)
@@ -128,6 +160,7 @@ def test_get_dashboards_with_search(mock_deps):
# [DEF:test_get_dashboards_empty:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboards listing returns an empty payload for an environment without dashboards.
# @TEST_EDGE: empty_dashboards -> {env_id: 'empty_env', expected_total: 0}
def test_get_dashboards_empty(mock_deps):
@@ -145,10 +178,13 @@ def test_get_dashboards_empty(mock_deps):
assert len(data["dashboards"]) == 0
assert data["total_pages"] == 1
DashboardsResponse(**data)
# [/DEF:test_get_dashboards_empty:Function]
# [DEF:test_get_dashboards_superset_failure:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboards listing surfaces a 503 contract when Superset access fails.
# @TEST_EDGE: external_superset_failure -> {env_id: 'bad_conn', status: 503}
def test_get_dashboards_superset_failure(mock_deps):
@@ -164,10 +200,13 @@ def test_get_dashboards_superset_failure(mock_deps):
response = client.get("/api/dashboards?env_id=bad_conn")
assert response.status_code == 503
assert "Failed to fetch dashboards" in response.json()["detail"]
# [/DEF:test_get_dashboards_superset_failure:Function]
# [DEF:test_get_dashboards_env_not_found:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboards listing returns 404 when the requested environment does not exist.
# @TEST: GET /api/dashboards returns 404 if env_id missing
# @PRE: env_id does not exist
@@ -184,6 +223,7 @@ def test_get_dashboards_env_not_found(mock_deps):
# [DEF:test_get_dashboards_invalid_pagination:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboards listing rejects invalid pagination parameters with 400 responses.
# @TEST: GET /api/dashboards returns 400 for invalid page/page_size
# @PRE: page < 1 or page_size > 100
@@ -201,10 +241,13 @@ def test_get_dashboards_invalid_pagination(mock_deps):
response = client.get("/api/dashboards?env_id=prod&page_size=101")
assert response.status_code == 400
assert "Page size must be between 1 and 100" in response.json()["detail"]
# [/DEF:test_get_dashboards_invalid_pagination:Function]
# [DEF:test_get_dashboard_detail_success:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboard detail returns charts and datasets for an existing dashboard.
# @TEST: GET /api/dashboards/{id} returns dashboard detail with charts and datasets
def test_get_dashboard_detail_success(mock_deps):
@@ -229,7 +272,7 @@ def test_get_dashboard_detail_success(mock_deps):
"viz_type": "line",
"dataset_id": 7,
"last_modified": "2026-02-19T10:00:00+00:00",
"overview": "line"
"overview": "line",
}
],
"datasets": [
@@ -239,11 +282,11 @@ def test_get_dashboard_detail_success(mock_deps):
"schema": "mart",
"database": "Analytics",
"last_modified": "2026-02-18T10:00:00+00:00",
"overview": "mart.fact_revenue"
"overview": "mart.fact_revenue",
}
],
"chart_count": 1,
"dataset_count": 1
"dataset_count": 1,
}
mock_client_cls.return_value = mock_client
@@ -254,10 +297,13 @@ def test_get_dashboard_detail_success(mock_deps):
assert payload["id"] == 42
assert payload["chart_count"] == 1
assert payload["dataset_count"] == 1
# [/DEF:test_get_dashboard_detail_success:Function]
# [DEF:test_get_dashboard_detail_env_not_found:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboard detail returns 404 when the requested environment is missing.
# @TEST: GET /api/dashboards/{id} returns 404 for missing environment
def test_get_dashboard_detail_env_not_found(mock_deps):
@@ -267,10 +313,13 @@ def test_get_dashboard_detail_env_not_found(mock_deps):
assert response.status_code == 404
assert "Environment not found" in response.json()["detail"]
# [/DEF:test_get_dashboard_detail_env_not_found:Function]
# [DEF:test_migrate_dashboards_success:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: POST /api/dashboards/migrate creates migration task
# @PRE: Valid source_env_id, target_env_id, dashboard_ids
# @PURPOSE: Validate dashboard migration request creates an async task and returns its identifier.
@@ -292,8 +341,8 @@ def test_migrate_dashboards_success(mock_deps):
"source_env_id": "source",
"target_env_id": "target",
"dashboard_ids": [1, 2, 3],
"db_mappings": {"old_db": "new_db"}
}
"db_mappings": {"old_db": "new_db"},
},
)
assert response.status_code == 200
@@ -307,6 +356,7 @@ def test_migrate_dashboards_success(mock_deps):
# [DEF:test_migrate_dashboards_no_ids:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: POST /api/dashboards/migrate returns 400 for empty dashboard_ids
# @PRE: dashboard_ids is empty
# @PURPOSE: Validate dashboard migration rejects empty dashboard identifier lists.
@@ -317,8 +367,8 @@ def test_migrate_dashboards_no_ids(mock_deps):
json={
"source_env_id": "source",
"target_env_id": "target",
"dashboard_ids": []
}
"dashboard_ids": [],
},
)
assert response.status_code == 400
@@ -329,6 +379,7 @@ def test_migrate_dashboards_no_ids(mock_deps):
# [DEF:test_migrate_dashboards_env_not_found:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate migration creation returns 404 when the source environment cannot be resolved.
# @PRE: source_env_id and target_env_id are valid environment IDs
def test_migrate_dashboards_env_not_found(mock_deps):
@@ -336,18 +387,17 @@ def test_migrate_dashboards_env_not_found(mock_deps):
mock_deps["config"].get_environments.return_value = []
response = client.post(
"/api/dashboards/migrate",
json={
"source_env_id": "ghost",
"target_env_id": "t",
"dashboard_ids": [1]
}
json={"source_env_id": "ghost", "target_env_id": "t", "dashboard_ids": [1]},
)
assert response.status_code == 404
assert "Source environment not found" in response.json()["detail"]
# [/DEF:test_migrate_dashboards_env_not_found:Function]
# [DEF:test_backup_dashboards_success:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: POST /api/dashboards/backup creates backup task
# @PRE: Valid env_id, dashboard_ids
# @PURPOSE: Validate dashboard backup request creates an async backup task and returns its identifier.
@@ -363,11 +413,7 @@ def test_backup_dashboards_success(mock_deps):
response = client.post(
"/api/dashboards/backup",
json={
"env_id": "prod",
"dashboard_ids": [1, 2, 3],
"schedule": "0 0 * * *"
}
json={"env_id": "prod", "dashboard_ids": [1, 2, 3], "schedule": "0 0 * * *"},
)
assert response.status_code == 200
@@ -381,24 +427,24 @@ def test_backup_dashboards_success(mock_deps):
# [DEF:test_backup_dashboards_env_not_found:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate backup task creation returns 404 when the target environment is missing.
# @PRE: env_id is a valid environment ID
def test_backup_dashboards_env_not_found(mock_deps):
"""@PRE: env_id is a valid environment ID."""
mock_deps["config"].get_environments.return_value = []
response = client.post(
"/api/dashboards/backup",
json={
"env_id": "ghost",
"dashboard_ids": [1]
}
"/api/dashboards/backup", json={"env_id": "ghost", "dashboard_ids": [1]}
)
assert response.status_code == 404
assert "Environment not found" in response.json()["detail"]
# [/DEF:test_backup_dashboards_env_not_found:Function]
# [DEF:test_get_database_mappings_success:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: GET /api/dashboards/db-mappings returns mapping suggestions
# @PRE: Valid source_env_id, target_env_id
# @PURPOSE: Validate database mapping suggestions are returned for valid source and target environments.
@@ -410,17 +456,21 @@ def test_get_database_mappings_success(mock_deps):
mock_target.id = "staging"
mock_deps["config"].get_environments.return_value = [mock_source, mock_target]
mock_deps["mapping"].get_suggestions = AsyncMock(return_value=[
mock_deps["mapping"].get_suggestions = AsyncMock(
return_value=[
{
"source_db": "old_sales",
"target_db": "new_sales",
"source_db_uuid": "uuid-1",
"target_db_uuid": "uuid-2",
"confidence": 0.95
"confidence": 0.95,
}
])
]
)
response = client.get("/api/dashboards/db-mappings?source_env_id=prod&target_env_id=staging")
response = client.get(
"/api/dashboards/db-mappings?source_env_id=prod&target_env_id=staging"
)
assert response.status_code == 200
data = response.json()
@@ -433,17 +483,23 @@ def test_get_database_mappings_success(mock_deps):
# [DEF:test_get_database_mappings_env_not_found:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate database mapping suggestions return 404 when either environment is missing.
# @PRE: source_env_id and target_env_id are valid environment IDs
def test_get_database_mappings_env_not_found(mock_deps):
"""@PRE: source_env_id must be a valid environment."""
mock_deps["config"].get_environments.return_value = []
response = client.get("/api/dashboards/db-mappings?source_env_id=ghost&target_env_id=t")
response = client.get(
"/api/dashboards/db-mappings?source_env_id=ghost&target_env_id=t"
)
assert response.status_code == 404
# [/DEF:test_get_database_mappings_env_not_found:Function]
# [DEF:test_get_dashboard_tasks_history_filters_success:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboard task history returns only related backup and LLM tasks.
# @TEST: GET /api/dashboards/{id}/tasks returns backup and llm tasks for dashboard
def test_get_dashboard_tasks_history_filters_success(mock_deps):
@@ -484,11 +540,17 @@ def test_get_dashboard_tasks_history_filters_success(mock_deps):
data = response.json()
assert data["dashboard_id"] == 42
assert len(data["items"]) == 2
assert {item["plugin_id"] for item in data["items"]} == {"llm_dashboard_validation", "superset-backup"}
assert {item["plugin_id"] for item in data["items"]} == {
"llm_dashboard_validation",
"superset-backup",
}
# [/DEF:test_get_dashboard_tasks_history_filters_success:Function]
# [DEF:test_get_dashboard_thumbnail_success:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Validate dashboard thumbnail endpoint proxies image bytes and content type from Superset.
# @TEST: GET /api/dashboards/{id}/thumbnail proxies image bytes from Superset
def test_get_dashboard_thumbnail_success(mock_deps):
@@ -516,26 +578,34 @@ def test_get_dashboard_thumbnail_success(mock_deps):
assert response.status_code == 200
assert response.content == b"fake-image-bytes"
assert response.headers["content-type"].startswith("image/png")
# [/DEF:test_get_dashboard_thumbnail_success:Function]
# [DEF:_build_profile_preference_stub:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Creates profile preference payload stub for dashboards filter contract tests.
# @PRE: username can be empty; enabled indicates profile-default toggle state.
# @POST: Returns object compatible with ProfileService.get_my_preference contract.
def _build_profile_preference_stub(username: str, enabled: bool):
preference = MagicMock()
preference.superset_username = username
preference.superset_username_normalized = str(username or "").strip().lower() or None
preference.superset_username_normalized = (
str(username or "").strip().lower() or None
)
preference.show_only_my_dashboards = bool(enabled)
payload = MagicMock()
payload.preference = preference
return payload
# [/DEF:_build_profile_preference_stub:Function]
# [DEF:_matches_actor_case_insensitive:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @PURPOSE: Applies trim + case-insensitive owners OR modified_by matching used by route contract tests.
# @PRE: owners can be None or list-like values.
# @POST: Returns True when bound username matches any owner or modified_by.
@@ -551,11 +621,16 @@ def _matches_actor_case_insensitive(bound_username, owners, modified_by):
owner_tokens.append(token)
modified_token = str(modified_by or "").strip().lower()
return normalized_bound in owner_tokens or bool(modified_token and modified_token == normalized_bound)
return normalized_bound in owner_tokens or bool(
modified_token and modified_token == normalized_bound
)
# [/DEF:_matches_actor_case_insensitive:Function]
# [DEF:test_get_dashboards_profile_filter_contract_owners_or_modified_by:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: GET /api/dashboards applies profile-default filter with owners OR modified_by trim+case-insensitive semantics.
# @PURPOSE: Validate profile-default filtering matches owner and modifier aliases using normalized Superset actor values.
# @PRE: Current user has enabled profile-default preference and bound username.
@@ -565,7 +640,8 @@ def test_get_dashboards_profile_filter_contract_owners_or_modified_by(mock_deps)
mock_env.id = "prod"
mock_deps["config"].get_environments.return_value = [mock_env]
mock_deps["task"].get_all_tasks.return_value = []
mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
mock_deps["resource"].get_dashboards_with_status = AsyncMock(
return_value=[
{
"id": 1,
"title": "Owner Match",
@@ -587,7 +663,8 @@ def test_get_dashboards_profile_filter_contract_owners_or_modified_by(mock_deps)
"owners": ["another-user"],
"modified_by": "nobody",
},
])
]
)
with patch("src.api.routes.dashboards.ProfileService") as profile_service_cls:
profile_service = MagicMock()
@@ -595,7 +672,9 @@ def test_get_dashboards_profile_filter_contract_owners_or_modified_by(mock_deps)
username=" JOHN_DOE ",
enabled=True,
)
profile_service.matches_dashboard_actor.side_effect = _matches_actor_case_insensitive
profile_service.matches_dashboard_actor.side_effect = (
_matches_actor_case_insensitive
)
profile_service_cls.return_value = profile_service
response = client.get(
@@ -612,10 +691,13 @@ def test_get_dashboards_profile_filter_contract_owners_or_modified_by(mock_deps)
assert payload["effective_profile_filter"]["override_show_all"] is False
assert payload["effective_profile_filter"]["username"] == "john_doe"
assert payload["effective_profile_filter"]["match_logic"] == "owners_or_modified_by"
# [/DEF:test_get_dashboards_profile_filter_contract_owners_or_modified_by:Function]
# [DEF:test_get_dashboards_override_show_all_contract:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: GET /api/dashboards honors override_show_all and disables profile-default filter for current page.
# @PURPOSE: Validate override_show_all bypasses profile-default filtering without changing dashboard list semantics.
# @PRE: Profile-default preference exists but override_show_all=true query is provided.
@@ -625,10 +707,24 @@ def test_get_dashboards_override_show_all_contract(mock_deps):
mock_env.id = "prod"
mock_deps["config"].get_environments.return_value = [mock_env]
mock_deps["task"].get_all_tasks.return_value = []
mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
{"id": 1, "title": "Dash A", "slug": "dash-a", "owners": ["john_doe"], "modified_by": "john_doe"},
{"id": 2, "title": "Dash B", "slug": "dash-b", "owners": ["other"], "modified_by": "other"},
])
mock_deps["resource"].get_dashboards_with_status = AsyncMock(
return_value=[
{
"id": 1,
"title": "Dash A",
"slug": "dash-a",
"owners": ["john_doe"],
"modified_by": "john_doe",
},
{
"id": 2,
"title": "Dash B",
"slug": "dash-b",
"owners": ["other"],
"modified_by": "other",
},
]
)
with patch("src.api.routes.dashboards.ProfileService") as profile_service_cls:
profile_service = MagicMock()
@@ -636,7 +732,9 @@ def test_get_dashboards_override_show_all_contract(mock_deps):
username="john_doe",
enabled=True,
)
profile_service.matches_dashboard_actor.side_effect = _matches_actor_case_insensitive
profile_service.matches_dashboard_actor.side_effect = (
_matches_actor_case_insensitive
)
profile_service_cls.return_value = profile_service
response = client.get(
@@ -654,10 +752,13 @@ def test_get_dashboards_override_show_all_contract(mock_deps):
assert payload["effective_profile_filter"]["username"] is None
assert payload["effective_profile_filter"]["match_logic"] is None
profile_service.matches_dashboard_actor.assert_not_called()
# [/DEF:test_get_dashboards_override_show_all_contract:Function]
# [DEF:test_get_dashboards_profile_filter_no_match_results_contract:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: GET /api/dashboards returns empty result set when profile-default filter is active and no dashboard actors match.
# @PURPOSE: Validate profile-default filtering returns an empty dashboard page when no actor aliases match the bound user.
# @PRE: Profile-default preference is enabled with bound username and all dashboards are non-matching.
@@ -667,7 +768,8 @@ def test_get_dashboards_profile_filter_no_match_results_contract(mock_deps):
mock_env.id = "prod"
mock_deps["config"].get_environments.return_value = [mock_env]
mock_deps["task"].get_all_tasks.return_value = []
mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
mock_deps["resource"].get_dashboards_with_status = AsyncMock(
return_value=[
{
"id": 101,
"title": "Team Dashboard",
@@ -682,7 +784,8 @@ def test_get_dashboards_profile_filter_no_match_results_contract(mock_deps):
"owners": ["ops-user"],
"modified_by": "ops-user",
},
])
]
)
with patch("src.api.routes.dashboards.ProfileService") as profile_service_cls:
profile_service = MagicMock()
@@ -690,7 +793,9 @@ def test_get_dashboards_profile_filter_no_match_results_contract(mock_deps):
username="john_doe",
enabled=True,
)
profile_service.matches_dashboard_actor.side_effect = _matches_actor_case_insensitive
profile_service.matches_dashboard_actor.side_effect = (
_matches_actor_case_insensitive
)
profile_service_cls.return_value = profile_service
response = client.get(
@@ -710,10 +815,13 @@ def test_get_dashboards_profile_filter_no_match_results_contract(mock_deps):
assert payload["effective_profile_filter"]["override_show_all"] is False
assert payload["effective_profile_filter"]["username"] == "john_doe"
assert payload["effective_profile_filter"]["match_logic"] == "owners_or_modified_by"
# [/DEF:test_get_dashboards_profile_filter_no_match_results_contract:Function]
# [DEF:test_get_dashboards_page_context_other_disables_profile_default:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: GET /api/dashboards does not auto-apply profile-default filter outside dashboards_main page context.
# @PURPOSE: Validate non-dashboard page contexts suppress profile-default filtering and preserve unfiltered results.
# @PRE: Profile-default preference exists but page_context=other query is provided.
@@ -723,10 +831,24 @@ def test_get_dashboards_page_context_other_disables_profile_default(mock_deps):
mock_env.id = "prod"
mock_deps["config"].get_environments.return_value = [mock_env]
mock_deps["task"].get_all_tasks.return_value = []
mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
{"id": 1, "title": "Dash A", "slug": "dash-a", "owners": ["john_doe"], "modified_by": "john_doe"},
{"id": 2, "title": "Dash B", "slug": "dash-b", "owners": ["other"], "modified_by": "other"},
])
mock_deps["resource"].get_dashboards_with_status = AsyncMock(
return_value=[
{
"id": 1,
"title": "Dash A",
"slug": "dash-a",
"owners": ["john_doe"],
"modified_by": "john_doe",
},
{
"id": 2,
"title": "Dash B",
"slug": "dash-b",
"owners": ["other"],
"modified_by": "other",
},
]
)
with patch("src.api.routes.dashboards.ProfileService") as profile_service_cls:
profile_service = MagicMock()
@@ -734,7 +856,9 @@ def test_get_dashboards_page_context_other_disables_profile_default(mock_deps):
username="john_doe",
enabled=True,
)
profile_service.matches_dashboard_actor.side_effect = _matches_actor_case_insensitive
profile_service.matches_dashboard_actor.side_effect = (
_matches_actor_case_insensitive
)
profile_service_cls.return_value = profile_service
response = client.get(
@@ -752,20 +876,26 @@ def test_get_dashboards_page_context_other_disables_profile_default(mock_deps):
assert payload["effective_profile_filter"]["username"] is None
assert payload["effective_profile_filter"]["match_logic"] is None
profile_service.matches_dashboard_actor.assert_not_called()
# [/DEF:test_get_dashboards_page_context_other_disables_profile_default:Function]
# [DEF:test_get_dashboards_profile_filter_matches_display_alias_without_detail_fanout:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: GET /api/dashboards resolves Superset display-name alias once and filters without per-dashboard detail calls.
# @PURPOSE: Validate profile-default filtering reuses resolved Superset display aliases without triggering per-dashboard detail fanout.
# @PRE: Profile-default filter is active, bound username is `admin`, dashboard actors contain display labels.
# @POST: Route matches by alias (`Superset Admin`) and does not call `SupersetClient.get_dashboard` in list filter path.
def test_get_dashboards_profile_filter_matches_display_alias_without_detail_fanout(mock_deps):
def test_get_dashboards_profile_filter_matches_display_alias_without_detail_fanout(
mock_deps,
):
mock_env = MagicMock()
mock_env.id = "prod"
mock_deps["config"].get_environments.return_value = [mock_env]
mock_deps["task"].get_all_tasks.return_value = []
mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
mock_deps["resource"].get_dashboards_with_status = AsyncMock(
return_value=[
{
"id": 5,
"title": "Alias Match",
@@ -782,19 +912,24 @@ def test_get_dashboards_profile_filter_matches_display_alias_without_detail_fano
"created_by": None,
"modified_by": "Other User",
},
])
]
)
with patch("src.api.routes.dashboards.ProfileService") as profile_service_cls, patch(
"src.api.routes.dashboards.SupersetClient"
) as superset_client_cls, patch(
with (
patch("src.api.routes.dashboards.ProfileService") as profile_service_cls,
patch("src.api.routes.dashboards.SupersetClient") as superset_client_cls,
patch(
"src.api.routes.dashboards.SupersetAccountLookupAdapter"
) as lookup_adapter_cls:
) as lookup_adapter_cls,
):
profile_service = MagicMock()
profile_service.get_my_preference.return_value = _build_profile_preference_stub(
username="admin",
enabled=True,
)
profile_service.matches_dashboard_actor.side_effect = _matches_actor_case_insensitive
profile_service.matches_dashboard_actor.side_effect = (
_matches_actor_case_insensitive
)
profile_service_cls.return_value = profile_service
superset_client = MagicMock()
@@ -826,10 +961,13 @@ def test_get_dashboards_profile_filter_matches_display_alias_without_detail_fano
assert payload["effective_profile_filter"]["applied"] is True
lookup_adapter.get_users_page.assert_called_once()
superset_client.get_dashboard.assert_not_called()
# [/DEF:test_get_dashboards_profile_filter_matches_display_alias_without_detail_fanout:Function]
# [DEF:test_get_dashboards_profile_filter_matches_owner_object_payload_contract:Function]
# @RELATION: BINDS_TO -> DashboardsApiTests
# @TEST: GET /api/dashboards profile-default filter matches Superset owner object payloads.
# @PURPOSE: Validate profile-default filtering accepts owner object payloads once aliases resolve to the bound Superset username.
# @PRE: Profile-default preference is enabled and owners list contains dict payloads.
@@ -839,7 +977,8 @@ def test_get_dashboards_profile_filter_matches_owner_object_payload_contract(moc
mock_env.id = "prod"
mock_deps["config"].get_environments.return_value = [mock_env]
mock_deps["task"].get_all_tasks.return_value = []
mock_deps["resource"].get_dashboards_with_status = AsyncMock(return_value=[
mock_deps["resource"].get_dashboards_with_status = AsyncMock(
return_value=[
{
"id": 701,
"title": "Featured Charts",
@@ -870,11 +1009,15 @@ def test_get_dashboards_profile_filter_matches_owner_object_payload_contract(moc
],
"modified_by": "other_user",
},
])
]
)
with patch("src.api.routes.dashboards.ProfileService") as profile_service_cls, patch(
with (
patch("src.api.routes.dashboards.ProfileService") as profile_service_cls,
patch(
"src.api.routes.dashboards._resolve_profile_actor_aliases",
return_value=["user_1"],
),
):
profile_service = MagicMock(spec=DomainProfileService)
profile_service.get_my_preference.return_value = _build_profile_preference_stub(
@@ -883,7 +1026,8 @@ def test_get_dashboards_profile_filter_matches_owner_object_payload_contract(moc
)
profile_service.matches_dashboard_actor.side_effect = (
lambda bound_username, owners, modified_by: any(
str(owner.get("email", "")).split("@", 1)[0].strip().lower() == str(bound_username).strip().lower()
str(owner.get("email", "")).split("@", 1)[0].strip().lower()
== str(bound_username).strip().lower()
for owner in (owners or [])
if isinstance(owner, dict)
)
@@ -899,6 +1043,8 @@ def test_get_dashboards_profile_filter_matches_owner_object_payload_contract(moc
assert payload["total"] == 1
assert {item["id"] for item in payload["dashboards"]} == {701}
assert payload["dashboards"][0]["title"] == "Featured Charts"
# [/DEF:test_get_dashboards_profile_filter_matches_owner_object_payload_contract:Function]

25
backend/src/api/routes/__tests__/test_dataset_review_api.py
View File

@@ -71,6 +71,7 @@ client = TestClient(app)
# [DEF:_make_user:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
def _make_user():
permissions = [
SimpleNamespace(resource="dataset:session", action="READ"),
@@ -83,6 +84,7 @@ def _make_user():
# [DEF:_make_config_manager:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
def _make_config_manager():
env = Environment(
id="env-1",
@@ -100,6 +102,7 @@ def _make_config_manager():
# [DEF:_make_session:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
def _make_session():
now = datetime.now(timezone.utc)
return DatasetReviewSession(
@@ -123,6 +126,7 @@ def _make_session():
# [DEF:_make_us2_session:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
def _make_us2_session():
now = datetime.now(timezone.utc)
session = _make_session()
@@ -238,6 +242,7 @@ def _make_us2_session():
# [DEF:_make_us3_session:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
def _make_us3_session():
now = datetime.now(timezone.utc)
session = _make_session()
@@ -300,6 +305,7 @@ def _make_us3_session():
# [DEF:_make_preview_ready_session:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
def _make_preview_ready_session():
session = _make_us3_session()
session.readiness_state = ReadinessState.COMPILED_PREVIEW_READY
@@ -310,6 +316,7 @@ def _make_preview_ready_session():
# [DEF:dataset_review_api_dependencies:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
@pytest.fixture(autouse=True)
def dataset_review_api_dependencies():
mock_user = _make_user()
@@ -330,6 +337,7 @@ def dataset_review_api_dependencies():
# [DEF:test_parse_superset_link_dashboard_partial_recovery:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Verify dashboard links recover dataset context and preserve explicit partial-recovery markers.
def test_parse_superset_link_dashboard_partial_recovery():
env = Environment(
@@ -364,6 +372,7 @@ def test_parse_superset_link_dashboard_partial_recovery():
# [DEF:test_parse_superset_link_dashboard_slug_recovery:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Verify dashboard slug links resolve through dashboard detail endpoints and recover dataset context.
def test_parse_superset_link_dashboard_slug_recovery():
env = Environment(
@@ -398,6 +407,7 @@ def test_parse_superset_link_dashboard_slug_recovery():
# [DEF:test_parse_superset_link_dashboard_permalink_partial_recovery:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Verify dashboard permalink links no longer fail parsing and preserve permalink filter state for partial recovery.
def test_parse_superset_link_dashboard_permalink_partial_recovery():
env = Environment(
@@ -442,6 +452,7 @@ def test_parse_superset_link_dashboard_permalink_partial_recovery():
# [DEF:test_parse_superset_link_dashboard_permalink_recovers_dataset_from_nested_dashboard_state:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Verify permalink state with nested dashboard id recovers dataset binding and keeps imported filters.
def test_parse_superset_link_dashboard_permalink_recovers_dataset_from_nested_dashboard_state():
env = Environment(
@@ -481,6 +492,7 @@ def test_parse_superset_link_dashboard_permalink_recovers_dataset_from_nested_da
# [DEF:test_resolve_from_dictionary_prefers_exact_match:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Verify trusted dictionary exact matches outrank fuzzy candidates and unresolved fields stay explicit.
def test_resolve_from_dictionary_prefers_exact_match():
resolver = SemanticSourceResolver()
@@ -519,6 +531,7 @@ def test_resolve_from_dictionary_prefers_exact_match():
# [DEF:test_orchestrator_start_session_preserves_partial_recovery:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Verify session start persists usable recovery-required state when Superset intake is partial.
def test_orchestrator_start_session_preserves_partial_recovery(dataset_review_api_dependencies):
repository = MagicMock()
@@ -580,6 +593,7 @@ def test_orchestrator_start_session_preserves_partial_recovery(dataset_review_ap
# [DEF:test_orchestrator_start_session_bootstraps_recovery_state:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Verify session start persists recovered filters, template variables, and initial execution mappings for review workspace bootstrap.
def test_orchestrator_start_session_bootstraps_recovery_state(dataset_review_api_dependencies):
repository = MagicMock()
@@ -677,6 +691,7 @@ def test_orchestrator_start_session_bootstraps_recovery_state(dataset_review_api
# [DEF:test_start_session_endpoint_returns_created_summary:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Verify POST session lifecycle endpoint returns a persisted ownership-scoped summary.
def test_start_session_endpoint_returns_created_summary(dataset_review_api_dependencies):
session = _make_session()
@@ -703,6 +718,7 @@ def test_start_session_endpoint_returns_created_summary(dataset_review_api_depen
# [DEF:test_get_session_detail_export_and_lifecycle_endpoints:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Verify lifecycle get/patch/delete plus documentation and validation exports remain ownership-scoped and usable.
def test_get_session_detail_export_and_lifecycle_endpoints(dataset_review_api_dependencies):
now = datetime.now(timezone.utc)
@@ -802,6 +818,7 @@ def test_get_session_detail_export_and_lifecycle_endpoints(dataset_review_api_de
# [DEF:test_us2_clarification_endpoints_persist_answer_and_feedback:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Clarification endpoints should expose one current question, persist the answer before advancement, and store feedback on the answer audit record.
def test_us2_clarification_endpoints_persist_answer_and_feedback(dataset_review_api_dependencies):
session = _make_us2_session()
@@ -853,6 +870,7 @@ def test_us2_clarification_endpoints_persist_answer_and_feedback(dataset_review_
# [DEF:test_us2_field_semantic_override_lock_unlock_and_feedback:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Semantic field endpoints should apply manual overrides with lock/provenance invariants and persist feedback independently.
def test_us2_field_semantic_override_lock_unlock_and_feedback(dataset_review_api_dependencies):
session = _make_us2_session()
@@ -913,6 +931,7 @@ def test_us2_field_semantic_override_lock_unlock_and_feedback(dataset_review_api
# [DEF:test_us3_mapping_patch_approval_preview_and_launch_endpoints:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: US3 execution endpoints should persist manual overrides, preserve explicit approval semantics, return contract-shaped preview truth, and expose audited launch handoff.
def test_us3_mapping_patch_approval_preview_and_launch_endpoints(dataset_review_api_dependencies):
session = _make_us3_session()
@@ -1067,6 +1086,7 @@ def test_us3_mapping_patch_approval_preview_and_launch_endpoints(dataset_review_
# [DEF:test_us3_preview_endpoint_returns_failed_preview_without_false_dashboard_not_found_contract_drift:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Preview endpoint should preserve API contract and surface generic upstream preview failures without fabricating dashboard-not-found semantics for non-dashboard 404s.
def test_us3_preview_endpoint_returns_failed_preview_without_false_dashboard_not_found_contract_drift(
dataset_review_api_dependencies,
@@ -1115,6 +1135,7 @@ def test_us3_preview_endpoint_returns_failed_preview_without_false_dashboard_not
# [DEF:test_execution_snapshot_includes_recovered_imported_filters_without_template_mapping:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Recovered imported filters with values should flow into preview filter context even when no template variable mapping exists.
def test_execution_snapshot_includes_recovered_imported_filters_without_template_mapping(
dataset_review_api_dependencies,
@@ -1175,6 +1196,7 @@ def test_execution_snapshot_includes_recovered_imported_filters_without_template
# [DEF:test_execution_snapshot_preserves_mapped_template_variables_and_filter_context:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Mapped template variables should still populate template params while contributing their effective filter context.
def test_execution_snapshot_preserves_mapped_template_variables_and_filter_context(
dataset_review_api_dependencies,
@@ -1209,6 +1231,7 @@ def test_execution_snapshot_preserves_mapped_template_variables_and_filter_conte
# [DEF:test_execution_snapshot_skips_partial_imported_filters_without_values:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Partial imported filters without raw or normalized values must not emit bogus active preview filters.
def test_execution_snapshot_skips_partial_imported_filters_without_values(
dataset_review_api_dependencies,
@@ -1246,6 +1269,7 @@ def test_execution_snapshot_skips_partial_imported_filters_without_values(
# [DEF:test_us3_launch_endpoint_requires_launch_permission:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Launch endpoint should enforce the contract RBAC permission instead of the generic session-manage permission.
def test_us3_launch_endpoint_requires_launch_permission(dataset_review_api_dependencies):
session = _make_us3_session()
@@ -1293,6 +1317,7 @@ def test_us3_launch_endpoint_requires_launch_permission(dataset_review_api_depen
# [/DEF:test_us3_launch_endpoint_requires_launch_permission:Function]
# [DEF:test_semantic_source_version_propagation_preserves_locked_fields:Function]
# @RELATION: BINDS_TO -> DatasetReviewApiTests
# @PURPOSE: Updated semantic source versions should mark unlocked fields reviewable while preserving locked manual values.
def test_semantic_source_version_propagation_preserves_locked_fields():
resolver = SemanticSourceResolver()

46
backend/src/api/routes/__tests__/test_datasets.py
View File

@@ -51,10 +51,13 @@ client = TestClient(app)
# [DEF:test_get_datasets_success:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @PURPOSE: Validate successful datasets listing contract for an existing environment.
# @TEST: GET /api/datasets returns 200 and valid schema
# @PRE: env_id exists
# @POST: Response matches DatasetsResponse schema
# [DEF:test_get_datasets_success:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
def test_get_datasets_success(mock_deps):
# Mock environment
mock_env = MagicMock()
@@ -89,10 +92,15 @@ def test_get_datasets_success(mock_deps):
# [DEF:test_get_datasets_env_not_found:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @PURPOSE: Validate datasets listing returns 404 when the requested environment does not exist.
# @TEST: GET /api/datasets returns 404 if env_id missing
# @PRE: env_id does not exist
# @POST: Returns 404 error
# [/DEF:test_get_datasets_success:Function]
# [DEF:test_get_datasets_env_not_found:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
def test_get_datasets_env_not_found(mock_deps):
mock_deps["config"].get_environments.return_value = []
@@ -106,10 +114,15 @@ def test_get_datasets_env_not_found(mock_deps):
# [DEF:test_get_datasets_invalid_pagination:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @PURPOSE: Validate datasets listing rejects invalid pagination parameters with 400 responses.
# @TEST: GET /api/datasets returns 400 for invalid page/page_size
# @PRE: page < 1 or page_size > 100
# @POST: Returns 400 error
# [/DEF:test_get_datasets_env_not_found:Function]
# [DEF:test_get_datasets_invalid_pagination:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
def test_get_datasets_invalid_pagination(mock_deps):
mock_env = MagicMock()
mock_env.id = "prod"
@@ -135,10 +148,15 @@ def test_get_datasets_invalid_pagination(mock_deps):
# [DEF:test_map_columns_success:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @PURPOSE: Validate map-columns request creates an async mapping task and returns its identifier.
# @TEST: POST /api/datasets/map-columns creates mapping task
# @PRE: Valid env_id, dataset_ids, source_type
# @POST: Returns task_id
# [/DEF:test_get_datasets_invalid_pagination:Function]
# [DEF:test_map_columns_success:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
def test_map_columns_success(mock_deps):
# Mock environment
mock_env = MagicMock()
@@ -170,10 +188,15 @@ def test_map_columns_success(mock_deps):
# [DEF:test_map_columns_invalid_source_type:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @PURPOSE: Validate map-columns rejects unsupported source types with a 400 contract response.
# @TEST: POST /api/datasets/map-columns returns 400 for invalid source_type
# @PRE: source_type is not 'postgresql' or 'xlsx'
# @POST: Returns 400 error
# [/DEF:test_map_columns_success:Function]
# [DEF:test_map_columns_invalid_source_type:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
def test_map_columns_invalid_source_type(mock_deps):
response = client.post(
"/api/datasets/map-columns",
@@ -192,10 +215,15 @@ def test_map_columns_invalid_source_type(mock_deps):
# [DEF:test_generate_docs_success:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @TEST: POST /api/datasets/generate-docs creates doc generation task
# @PRE: Valid env_id, dataset_ids, llm_provider
# @PURPOSE: Validate generate-docs request creates an async documentation task and returns its identifier.
# @POST: Returns task_id
# [/DEF:test_map_columns_invalid_source_type:Function]
# [DEF:test_generate_docs_success:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
def test_generate_docs_success(mock_deps):
# Mock environment
mock_env = MagicMock()
@@ -227,10 +255,15 @@ def test_generate_docs_success(mock_deps):
# [DEF:test_map_columns_empty_ids:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @PURPOSE: Validate map-columns rejects empty dataset identifier lists.
# @TEST: POST /api/datasets/map-columns returns 400 for empty dataset_ids
# @PRE: dataset_ids is empty
# @POST: Returns 400 error
# [/DEF:test_generate_docs_success:Function]
# [DEF:test_map_columns_empty_ids:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
def test_map_columns_empty_ids(mock_deps):
"""@PRE: dataset_ids must be non-empty."""
response = client.post(
@@ -247,10 +280,15 @@ def test_map_columns_empty_ids(mock_deps):
# [DEF:test_generate_docs_empty_ids:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @PURPOSE: Validate generate-docs rejects empty dataset identifier lists.
# @TEST: POST /api/datasets/generate-docs returns 400 for empty dataset_ids
# @PRE: dataset_ids is empty
# @POST: Returns 400 error
# [/DEF:test_map_columns_empty_ids:Function]
# [DEF:test_generate_docs_empty_ids:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
def test_generate_docs_empty_ids(mock_deps):
"""@PRE: dataset_ids must be non-empty."""
response = client.post(
@@ -267,10 +305,15 @@ def test_generate_docs_empty_ids(mock_deps):
# [DEF:test_generate_docs_env_not_found:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @TEST: POST /api/datasets/generate-docs returns 404 for missing env
# @PRE: env_id does not exist
# @PURPOSE: Validate generate-docs returns 404 when the requested environment cannot be resolved.
# @POST: Returns 404 error
# [/DEF:test_generate_docs_empty_ids:Function]
# [DEF:test_generate_docs_env_not_found:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
def test_generate_docs_env_not_found(mock_deps):
"""@PRE: env_id must be a valid environment."""
mock_deps["config"].get_environments.return_value = []
@@ -288,8 +331,11 @@ def test_generate_docs_env_not_found(mock_deps):
# [DEF:test_get_datasets_superset_failure:Function]
# @RELATION: BINDS_TO -> DatasetsApiTests
# @PURPOSE: Validate datasets listing surfaces a 503 contract when Superset access fails.
# @TEST_EDGE: external_superset_failure -> {status: 503}
# [/DEF:test_generate_docs_env_not_found:Function]
def test_get_datasets_superset_failure(mock_deps):
"""@TEST_EDGE: external_superset_failure -> {status: 503}"""
mock_env = MagicMock()

8
backend/src/api/routes/__tests__/test_git_api.py
View File

@@ -11,6 +11,11 @@ from src.api.routes import git as git_routes
from src.models.git import GitServerConfig, GitProvider, GitStatus, GitRepository
# [DEF:DbMock:Class]
# @RELATION: BINDS_TO ->[TestGitApi]
# @COMPLEXITY: 2
# @PURPOSE: In-memory session double for git route tests with minimal query/filter persistence semantics.
# @INVARIANT: Supports only the SQLAlchemy-like operations exercised by this test module.
class DbMock:
def __init__(self, data=None):
self._data = data or []
@@ -79,6 +84,9 @@ class DbMock:
item.last_validated = "2026-03-08T00:00:00Z"
# [/DEF:DbMock:Class]
# [DEF:test_get_git_configs_masks_pat:Function]
# @RELATION: BINDS_TO ->[TestGitApi]
def test_get_git_configs_masks_pat():

20
backend/src/api/routes/__tests__/test_git_status_route.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.src.api.routes.__tests__.test_git_status_route:Module]
# [DEF:TestGitStatusRoute:Module]
# @COMPLEXITY: 3
# @SEMANTICS: tests, git, api, status, no_repo
# @PURPOSE: Validate status endpoint behavior for missing and error repository states.
# @LAYER: Domain (Tests)
# @RELATION: VERIFIES -> [backend.src.api.routes.git]
# @RELATION: VERIFIES -> [GitApi]
from fastapi import HTTPException
import pytest
@@ -14,6 +14,7 @@ from src.api.routes import git as git_routes
# [DEF:test_get_repository_status_returns_no_repo_payload_for_missing_repo:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure missing local repository is represented as NO_REPO payload instead of an API error.
# @PRE: GitService.get_status raises HTTPException(404).
# @POST: Route returns a deterministic NO_REPO status payload.
@@ -37,6 +38,7 @@ def test_get_repository_status_returns_no_repo_payload_for_missing_repo(monkeypa
# [DEF:test_get_repository_status_propagates_non_404_http_exception:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure HTTP exceptions other than 404 are not masked.
# @PRE: GitService.get_status raises HTTPException with non-404 status.
# @POST: Raised exception preserves original status and detail.
@@ -60,6 +62,7 @@ def test_get_repository_status_propagates_non_404_http_exception(monkeypatch):
# [DEF:test_get_repository_diff_propagates_http_exception:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure diff endpoint preserves domain HTTP errors from GitService.
# @PRE: GitService.get_diff raises HTTPException.
# @POST: Endpoint raises same HTTPException values.
@@ -79,6 +82,7 @@ def test_get_repository_diff_propagates_http_exception(monkeypatch):
# [DEF:test_get_history_wraps_unexpected_error_as_500:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure non-HTTP exceptions in history endpoint become deterministic 500 errors.
# @PRE: GitService.get_commit_history raises ValueError.
# @POST: Endpoint returns HTTPException with status 500 and route context.
@@ -98,6 +102,7 @@ def test_get_history_wraps_unexpected_error_as_500(monkeypatch):
# [DEF:test_commit_changes_wraps_unexpected_error_as_500:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure commit endpoint does not leak unexpected errors as 400.
# @PRE: GitService.commit_changes raises RuntimeError.
# @POST: Endpoint raises HTTPException(500) with route context.
@@ -121,6 +126,7 @@ def test_commit_changes_wraps_unexpected_error_as_500(monkeypatch):
# [DEF:test_get_repository_status_batch_returns_mixed_statuses:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure batch endpoint returns per-dashboard statuses in one response.
# @PRE: Some repositories are missing and some are initialized.
# @POST: Returned map includes resolved status for each requested dashboard ID.
@@ -148,6 +154,7 @@ def test_get_repository_status_batch_returns_mixed_statuses(monkeypatch):
# [DEF:test_get_repository_status_batch_marks_item_as_error_on_service_failure:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure batch endpoint marks failed items as ERROR without failing entire request.
# @PRE: GitService raises non-HTTP exception for one dashboard.
# @POST: Failed dashboard status is marked as ERROR.
@@ -173,6 +180,7 @@ def test_get_repository_status_batch_marks_item_as_error_on_service_failure(monk
# [DEF:test_get_repository_status_batch_deduplicates_and_truncates_ids:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure batch endpoint protects server from oversized payloads.
# @PRE: request includes duplicate IDs and more than MAX_REPOSITORY_STATUS_BATCH entries.
# @POST: Result contains unique IDs up to configured cap.
@@ -198,6 +206,7 @@ def test_get_repository_status_batch_deduplicates_and_truncates_ids(monkeypatch)
# [DEF:test_commit_changes_applies_profile_identity_before_commit:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure commit route configures repository identity from profile preferences before commit call.
# @PRE: Profile preference contains git_username/git_email for current user.
# @POST: git_service.configure_identity receives resolved identity and commit proceeds.
@@ -259,6 +268,7 @@ def test_commit_changes_applies_profile_identity_before_commit(monkeypatch):
# [DEF:test_pull_changes_applies_profile_identity_before_pull:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure pull route configures repository identity from profile preferences before pull call.
# @PRE: Profile preference contains git_username/git_email for current user.
# @POST: git_service.configure_identity receives resolved identity and pull proceeds.
@@ -315,6 +325,7 @@ def test_pull_changes_applies_profile_identity_before_pull(monkeypatch):
# [DEF:test_get_merge_status_returns_service_payload:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure merge status route returns service payload as-is.
# @PRE: git_service.get_merge_status returns unfinished merge payload.
# @POST: Route response contains has_unfinished_merge=True.
@@ -347,6 +358,7 @@ def test_get_merge_status_returns_service_payload(monkeypatch):
# [DEF:test_resolve_merge_conflicts_passes_resolution_items_to_service:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure merge resolve route forwards parsed resolutions to service.
# @PRE: resolve_data has one file strategy.
# @POST: Service receives normalized list and route returns resolved files.
@@ -384,6 +396,7 @@ def test_resolve_merge_conflicts_passes_resolution_items_to_service(monkeypatch)
# [DEF:test_abort_merge_calls_service_and_returns_result:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure abort route delegates to service.
# @PRE: Service abort_merge returns aborted status.
# @POST: Route returns aborted status.
@@ -408,6 +421,7 @@ def test_abort_merge_calls_service_and_returns_result(monkeypatch):
# [DEF:test_continue_merge_passes_message_and_returns_commit:Function]
# @RELATION: BINDS_TO -> TestGitStatusRoute
# @PURPOSE: Ensure continue route passes commit message to service.
# @PRE: continue_data.message is provided.
# @POST: Route returns committed status and hash.
@@ -437,4 +451,4 @@ def test_continue_merge_passes_message_and_returns_commit(monkeypatch):
# [/DEF:test_continue_merge_passes_message_and_returns_commit:Function]
# [/DEF:backend.src.api.routes.__tests__.test_git_status_route:Module]
# [/DEF:TestGitStatusRoute:Module]

16
backend/src/api/routes/__tests__/test_migration_routes.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.api.routes.__tests__.test_migration_routes:Module]
# [DEF:TestMigrationRoutes:Module]
#
# @COMPLEXITY: 3
# @PURPOSE: Unit tests for migration API route handlers.
@@ -52,6 +52,8 @@ def db_session():
session.close()
# [DEF:_make_config_manager:Function]
# @RELATION: BINDS_TO -> TestMigrationRoutes
def _make_config_manager(cron="0 2 * * *"):
"""Creates a mock config manager with a realistic AppConfig-like object."""
settings = MagicMock()
@@ -66,6 +68,8 @@ def _make_config_manager(cron="0 2 * * *"):
# --- get_migration_settings tests ---
# [/DEF:_make_config_manager:Function]
@pytest.mark.asyncio
async def test_get_migration_settings_returns_default_cron():
"""Verify the settings endpoint returns the stored cron string."""
@@ -227,6 +231,8 @@ async def test_get_resource_mappings_filter_by_type(db_session):
# --- trigger_sync_now tests ---
@pytest.fixture
# [DEF:_mock_env:Function]
# @RELATION: BINDS_TO -> TestMigrationRoutes
def _mock_env():
"""Creates a mock config environment object."""
env = MagicMock()
@@ -240,6 +246,10 @@ def _mock_env():
return env
# [/DEF:_mock_env:Function]
# [DEF:_make_sync_config_manager:Function]
# @RELATION: BINDS_TO -> TestMigrationRoutes
def _make_sync_config_manager(environments):
"""Creates a mock config manager with environments list."""
settings = MagicMock()
@@ -253,6 +263,8 @@ def _make_sync_config_manager(environments):
return cm
# [/DEF:_make_sync_config_manager:Function]
@pytest.mark.asyncio
async def test_trigger_sync_now_creates_env_row_and_syncs(db_session, _mock_env):
"""Verify that trigger_sync_now creates an Environment row in DB before syncing,
@@ -507,4 +519,4 @@ async def test_dry_run_migration_rejects_same_environment(db_session):
assert exc.value.status_code == 400
# [/DEF:backend.src.api.routes.__tests__.test_migration_routes:Module]
# [/DEF:TestMigrationRoutes:Module]

15
backend/src/api/routes/__tests__/test_profile_api.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.src.api.routes.__tests__.test_profile_api:Module]
# [DEF:TestProfileApi:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, profile, api, preferences, lookup, contract
# @PURPOSE: Verifies profile API route contracts for preference read/update and Superset account lookup.
# @LAYER: API
# @RELATION: TESTS -> backend.src.api.routes.profile
# [SECTION: IMPORTS]
from datetime import datetime, timezone
@@ -34,6 +34,7 @@ client = TestClient(app)
# [DEF:mock_profile_route_dependencies:Function]
# @RELATION: BINDS_TO -> TestProfileApi
# @PURPOSE: Provides deterministic dependency overrides for profile route tests.
# @PRE: App instance is initialized.
# @POST: Dependencies are overridden for current test and restored afterward.
@@ -54,6 +55,7 @@ def mock_profile_route_dependencies():
# [DEF:profile_route_deps_fixture:Function]
# @RELATION: BINDS_TO -> TestProfileApi
# @PURPOSE: Pytest fixture wrapper for profile route dependency overrides.
# @PRE: None.
# @POST: Yields overridden dependencies and clears overrides after test.
@@ -69,6 +71,7 @@ def profile_route_deps_fixture():
# [DEF:_build_preference_response:Function]
# @RELATION: BINDS_TO -> TestProfileApi
# @PURPOSE: Builds stable profile preference response payload for route tests.
# @PRE: user_id is provided.
# @POST: Returns ProfilePreferenceResponse object with deterministic timestamps.
@@ -109,6 +112,7 @@ def _build_preference_response(user_id: str = "u-1") -> ProfilePreferenceRespons
# [DEF:test_get_profile_preferences_returns_self_payload:Function]
# @RELATION: BINDS_TO -> TestProfileApi
# @PURPOSE: Verifies GET /api/profile/preferences returns stable self-scoped payload.
# @PRE: Authenticated user context is available.
# @POST: Response status is 200 and payload contains current user preference.
@@ -141,6 +145,7 @@ def test_get_profile_preferences_returns_self_payload(profile_route_deps_fixture
# [DEF:test_patch_profile_preferences_success:Function]
# @RELATION: BINDS_TO -> TestProfileApi
# @PURPOSE: Verifies PATCH /api/profile/preferences persists valid payload through route mapping.
# @PRE: Valid request payload and authenticated user.
# @POST: Response status is 200 with saved preference payload.
@@ -191,6 +196,7 @@ def test_patch_profile_preferences_success(profile_route_deps_fixture):
# [DEF:test_patch_profile_preferences_validation_error:Function]
# @RELATION: BINDS_TO -> TestProfileApi
# @PURPOSE: Verifies route maps domain validation failure to HTTP 422 with actionable details.
# @PRE: Service raises ProfileValidationError.
# @POST: Response status is 422 and includes validation messages.
@@ -217,6 +223,7 @@ def test_patch_profile_preferences_validation_error(profile_route_deps_fixture):
# [DEF:test_patch_profile_preferences_cross_user_denied:Function]
# @RELATION: BINDS_TO -> TestProfileApi
# @PURPOSE: Verifies route maps domain authorization guard failure to HTTP 403.
# @PRE: Service raises ProfileAuthorizationError.
# @POST: Response status is 403 with denial message.
@@ -242,6 +249,7 @@ def test_patch_profile_preferences_cross_user_denied(profile_route_deps_fixture)
# [DEF:test_lookup_superset_accounts_success:Function]
# @RELATION: BINDS_TO -> TestProfileApi
# @PURPOSE: Verifies lookup route returns success payload with normalized candidates.
# @PRE: Valid environment_id and service success response.
# @POST: Response status is 200 and items list is returned.
@@ -278,6 +286,7 @@ def test_lookup_superset_accounts_success(profile_route_deps_fixture):
# [DEF:test_lookup_superset_accounts_env_not_found:Function]
# @RELATION: BINDS_TO -> TestProfileApi
# @PURPOSE: Verifies lookup route maps missing environment to HTTP 404.
# @PRE: Service raises EnvironmentNotFoundError.
# @POST: Response status is 404 with explicit message.
@@ -295,4 +304,4 @@ def test_lookup_superset_accounts_env_not_found(profile_route_deps_fixture):
assert payload["detail"] == "Environment 'missing-env' not found"
# [/DEF:test_lookup_superset_accounts_env_not_found:Function]
# [/DEF:backend.src.api.routes.__tests__.test_profile_api:Module]
# [/DEF:TestProfileApi:Module]

125
backend/src/api/routes/__tests__/test_reports_api.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.tests.test_reports_api:Module]
# [DEF:TestReportsApi:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, reports, api, contract, pagination, filtering
# @PURPOSE: Contract tests for GET /api/reports defaults, pagination, and filtering behavior.
# @LAYER: Domain (Tests)
# @RELATION: TESTS -> backend.src.api.routes.reports
# @INVARIANT: API response contract contains {items,total,page,page_size,has_next,applied_filters}.
from datetime import datetime, timedelta, timezone
@@ -24,12 +24,26 @@ class _FakeTaskManager:
return self._tasks
# [DEF:_admin_user:Function]
# @RELATION: BINDS_TO -> TestReportsApi
def _admin_user():
admin_role = SimpleNamespace(name="Admin", permissions=[])
return SimpleNamespace(username="test-admin", roles=[admin_role])
def _make_task(task_id: str, plugin_id: str, status: TaskStatus, started_at: datetime, finished_at: datetime = None, result=None):
# [/DEF:_admin_user:Function]
# [DEF:_make_task:Function]
# @RELATION: BINDS_TO -> TestReportsApi
def _make_task(
task_id: str,
plugin_id: str,
status: TaskStatus,
started_at: datetime,
finished_at: datetime = None,
result=None,
):
return Task(
id=task_id,
plugin_id=plugin_id,
@@ -41,12 +55,35 @@ def _make_task(task_id: str, plugin_id: str, status: TaskStatus, started_at: dat
)
# [/DEF:_make_task:Function]
# [DEF:test_get_reports_default_pagination_contract:Function]
# @RELATION: BINDS_TO -> TestReportsApi
def test_get_reports_default_pagination_contract():
now = datetime.utcnow()
tasks = [
_make_task("t-1", "superset-backup", TaskStatus.SUCCESS, now - timedelta(minutes=10), now - timedelta(minutes=9)),
_make_task("t-2", "superset-migration", TaskStatus.FAILED, now - timedelta(minutes=8), now - timedelta(minutes=7)),
_make_task("t-3", "llm_dashboard_validation", TaskStatus.RUNNING, now - timedelta(minutes=6), None),
_make_task(
"t-1",
"superset-backup",
TaskStatus.SUCCESS,
now - timedelta(minutes=10),
now - timedelta(minutes=9),
),
_make_task(
"t-2",
"superset-migration",
TaskStatus.FAILED,
now - timedelta(minutes=8),
now - timedelta(minutes=7),
),
_make_task(
"t-3",
"llm_dashboard_validation",
TaskStatus.RUNNING,
now - timedelta(minutes=6),
None,
),
]
app.dependency_overrides[get_current_user] = lambda: _admin_user()
@@ -58,7 +95,9 @@ def test_get_reports_default_pagination_contract():
assert response.status_code == 200
data = response.json()
assert set(["items", "total", "page", "page_size", "has_next", "applied_filters"]).issubset(data.keys())
assert set(
["items", "total", "page", "page_size", "has_next", "applied_filters"]
).issubset(data.keys())
assert data["page"] == 1
assert data["page_size"] == 20
assert data["total"] == 3
@@ -69,12 +108,35 @@ def test_get_reports_default_pagination_contract():
app.dependency_overrides.clear()
# [/DEF:test_get_reports_default_pagination_contract:Function]
# [DEF:test_get_reports_filter_and_pagination:Function]
# @RELATION: BINDS_TO -> TestReportsApi
def test_get_reports_filter_and_pagination():
now = datetime.utcnow()
tasks = [
_make_task("t-1", "superset-backup", TaskStatus.SUCCESS, now - timedelta(minutes=30), now - timedelta(minutes=29)),
_make_task("t-2", "superset-backup", TaskStatus.FAILED, now - timedelta(minutes=20), now - timedelta(minutes=19)),
_make_task("t-3", "superset-migration", TaskStatus.FAILED, now - timedelta(minutes=10), now - timedelta(minutes=9)),
_make_task(
"t-1",
"superset-backup",
TaskStatus.SUCCESS,
now - timedelta(minutes=30),
now - timedelta(minutes=29),
),
_make_task(
"t-2",
"superset-backup",
TaskStatus.FAILED,
now - timedelta(minutes=20),
now - timedelta(minutes=19),
),
_make_task(
"t-3",
"superset-migration",
TaskStatus.FAILED,
now - timedelta(minutes=10),
now - timedelta(minutes=9),
),
]
app.dependency_overrides[get_current_user] = lambda: _admin_user()
@@ -82,7 +144,9 @@ def test_get_reports_filter_and_pagination():
try:
client = TestClient(app)
response = client.get("/api/reports?task_types=backup&statuses=failed&page=1&page_size=1")
response = client.get(
"/api/reports?task_types=backup&statuses=failed&page=1&page_size=1"
)
assert response.status_code == 200
data = response.json()
@@ -97,12 +161,29 @@ def test_get_reports_filter_and_pagination():
app.dependency_overrides.clear()
# [/DEF:test_get_reports_filter_and_pagination:Function]
# [DEF:test_get_reports_handles_mixed_naive_and_aware_datetimes:Function]
# @RELATION: BINDS_TO -> TestReportsApi
def test_get_reports_handles_mixed_naive_and_aware_datetimes():
naive_now = datetime.utcnow()
aware_now = datetime.now(timezone.utc)
tasks = [
_make_task("t-naive", "superset-backup", TaskStatus.SUCCESS, naive_now - timedelta(minutes=5), naive_now - timedelta(minutes=4)),
_make_task("t-aware", "superset-migration", TaskStatus.FAILED, aware_now - timedelta(minutes=3), aware_now - timedelta(minutes=2)),
_make_task(
"t-naive",
"superset-backup",
TaskStatus.SUCCESS,
naive_now - timedelta(minutes=5),
naive_now - timedelta(minutes=4),
),
_make_task(
"t-aware",
"superset-migration",
TaskStatus.FAILED,
aware_now - timedelta(minutes=3),
aware_now - timedelta(minutes=2),
),
]
app.dependency_overrides[get_current_user] = lambda: _admin_user()
@@ -119,9 +200,22 @@ def test_get_reports_handles_mixed_naive_and_aware_datetimes():
app.dependency_overrides.clear()
# [/DEF:test_get_reports_handles_mixed_naive_and_aware_datetimes:Function]
# [DEF:test_get_reports_invalid_filter_returns_400:Function]
# @RELATION: BINDS_TO -> TestReportsApi
def test_get_reports_invalid_filter_returns_400():
now = datetime.utcnow()
tasks = [_make_task("t-1", "superset-backup", TaskStatus.SUCCESS, now - timedelta(minutes=5), now - timedelta(minutes=4))]
tasks = [
_make_task(
"t-1",
"superset-backup",
TaskStatus.SUCCESS,
now - timedelta(minutes=5),
now - timedelta(minutes=4),
)
]
app.dependency_overrides[get_current_user] = lambda: _admin_user()
app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks)
@@ -136,4 +230,5 @@ def test_get_reports_invalid_filter_returns_400():
app.dependency_overrides.clear()
# [/DEF:backend.tests.test_reports_api:Module]
# [/DEF:test_get_reports_invalid_filter_returns_400:Function]
# [/DEF:TestReportsApi:Module]

35
backend/src/api/routes/__tests__/test_reports_detail_api.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.tests.test_reports_detail_api:Module]
# [DEF:TestReportsDetailApi:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, reports, api, detail, diagnostics
# @PURPOSE: Contract tests for GET /api/reports/{report_id} detail endpoint behavior.
# @LAYER: Domain (Tests)
# @RELATION: TESTS -> backend.src.api.routes.reports
# @INVARIANT: Detail endpoint tests must keep deterministic assertions for success and not-found contracts.
from datetime import datetime, timedelta
@@ -24,11 +24,18 @@ class _FakeTaskManager:
return self._tasks
# [DEF:_admin_user:Function]
# @RELATION: BINDS_TO -> TestReportsDetailApi
def _admin_user():
role = SimpleNamespace(name="Admin", permissions=[])
return SimpleNamespace(username="test-admin", roles=[role])
# [/DEF:_admin_user:Function]
# [DEF:_make_task:Function]
# @RELATION: BINDS_TO -> TestReportsDetailApi
def _make_task(task_id: str, plugin_id: str, status: TaskStatus, result=None):
now = datetime.utcnow()
return Task(
@@ -36,18 +43,30 @@ def _make_task(task_id: str, plugin_id: str, status: TaskStatus, result=None):
plugin_id=plugin_id,
status=status,
started_at=now - timedelta(minutes=2),
finished_at=now - timedelta(minutes=1) if status != TaskStatus.RUNNING else None,
finished_at=now - timedelta(minutes=1)
if status != TaskStatus.RUNNING
else None,
params={"environment_id": "env-1"},
result=result or {"summary": f"{plugin_id} result"},
)
# [/DEF:_make_task:Function]
# [DEF:test_get_report_detail_success:Function]
# @RELATION: BINDS_TO -> TestReportsDetailApi
def test_get_report_detail_success():
task = _make_task(
"detail-1",
"superset-migration",
TaskStatus.FAILED,
result={"error": {"message": "Step failed", "next_actions": ["Check mapping", "Retry"]}},
result={
"error": {
"message": "Step failed",
"next_actions": ["Check mapping", "Retry"],
}
},
)
app.dependency_overrides[get_current_user] = lambda: _admin_user()
@@ -67,6 +86,11 @@ def test_get_report_detail_success():
app.dependency_overrides.clear()
# [/DEF:test_get_report_detail_success:Function]
# [DEF:test_get_report_detail_not_found:Function]
# @RELATION: BINDS_TO -> TestReportsDetailApi
def test_get_report_detail_not_found():
task = _make_task("detail-2", "superset-backup", TaskStatus.SUCCESS)
@@ -81,4 +105,5 @@ def test_get_report_detail_not_found():
app.dependency_overrides.clear()
# [/DEF:backend.tests.test_reports_detail_api:Module]
# [/DEF:test_get_report_detail_not_found:Function]
# [/DEF:TestReportsDetailApi:Module]

33
backend/src/api/routes/__tests__/test_reports_openapi_conformance.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.tests.test_reports_openapi_conformance:Module]
# [DEF:TestReportsOpenapiConformance:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, reports, openapi, conformance
# @PURPOSE: Validate implemented reports payload shape against OpenAPI-required top-level contract fields.
# @LAYER: Domain (Tests)
# @RELATION: TESTS -> specs/020-task-reports-design/contracts/reports-api.openapi.yaml
# @INVARIANT: List and detail payloads include required contract keys.
from datetime import datetime
@@ -24,11 +24,18 @@ class _FakeTaskManager:
return self._tasks
# [DEF:_admin_user:Function]
# @RELATION: BINDS_TO -> TestReportsOpenapiConformance
def _admin_user():
role = SimpleNamespace(name="Admin", permissions=[])
return SimpleNamespace(username="test-admin", roles=[role])
# [/DEF:_admin_user:Function]
# [DEF:_task:Function]
# @RELATION: BINDS_TO -> TestReportsOpenapiConformance
def _task(task_id: str, plugin_id: str, status: TaskStatus):
now = datetime.utcnow()
return Task(
@@ -42,6 +49,11 @@ def _task(task_id: str, plugin_id: str, status: TaskStatus):
)
# [/DEF:_task:Function]
# [DEF:test_reports_list_openapi_required_keys:Function]
# @RELATION: BINDS_TO -> TestReportsOpenapiConformance
def test_reports_list_openapi_required_keys():
tasks = [
_task("r-1", "superset-backup", TaskStatus.SUCCESS),
@@ -56,12 +68,24 @@ def test_reports_list_openapi_required_keys():
assert response.status_code == 200
body = response.json()
required = {"items", "total", "page", "page_size", "has_next", "applied_filters"}
required = {
"items",
"total",
"page",
"page_size",
"has_next",
"applied_filters",
}
assert required.issubset(body.keys())
finally:
app.dependency_overrides.clear()
# [/DEF:test_reports_list_openapi_required_keys:Function]
# [DEF:test_reports_detail_openapi_required_keys:Function]
# @RELATION: BINDS_TO -> TestReportsOpenapiConformance
def test_reports_detail_openapi_required_keys():
tasks = [_task("r-3", "llm_dashboard_validation", TaskStatus.SUCCESS)]
app.dependency_overrides[get_current_user] = lambda: _admin_user()
@@ -78,4 +102,5 @@ def test_reports_detail_openapi_required_keys():
app.dependency_overrides.clear()
# [/DEF:backend.tests.test_reports_openapi_conformance:Module]
# [/DEF:test_reports_detail_openapi_required_keys:Function]
# [/DEF:TestReportsOpenapiConformance:Module]

15
backend/src/api/routes/__tests__/test_tasks_logs.py
View File

@@ -27,6 +27,8 @@ def client():
# @TEST_CONTRACT: get_task_logs_api -> Invariants
# @TEST_FIXTURE: valid_task_logs_request
# [DEF:test_get_task_logs_success:Function]
# @RELATION: BINDS_TO -> __tests__/test_tasks_logs
def test_get_task_logs_success(client):
tc, tm = client
@@ -46,6 +48,10 @@ def test_get_task_logs_success(client):
assert args[0][1].level == "INFO"
# @TEST_EDGE: task_not_found
# [/DEF:test_get_task_logs_success:Function]
# [DEF:test_get_task_logs_not_found:Function]
# @RELATION: BINDS_TO -> __tests__/test_tasks_logs
def test_get_task_logs_not_found(client):
tc, tm = client
tm.get_task.return_value = None
@@ -55,6 +61,10 @@ def test_get_task_logs_not_found(client):
assert response.json()["detail"] == "Task not found"
# @TEST_EDGE: invalid_limit
# [/DEF:test_get_task_logs_not_found:Function]
# [DEF:test_get_task_logs_invalid_limit:Function]
# @RELATION: BINDS_TO -> __tests__/test_tasks_logs
def test_get_task_logs_invalid_limit(client):
tc, tm = client
# limit=0 is ge=1 in Query
@@ -62,6 +72,10 @@ def test_get_task_logs_invalid_limit(client):
assert response.status_code == 422
# @TEST_INVARIANT: response_purity
# [/DEF:test_get_task_logs_invalid_limit:Function]
# [DEF:test_get_task_log_stats_success:Function]
# @RELATION: BINDS_TO -> __tests__/test_tasks_logs
def test_get_task_log_stats_success(client):
tc, tm = client
tm.get_task.return_value = MagicMock()
@@ -71,3 +85,4 @@ def test_get_task_log_stats_success(client):
assert response.status_code == 200
# response_model=LogStats might wrap this, but let's check basic structure
# assuming tm.get_task_log_stats returns something compatible with LogStats
# [/DEF:test_get_task_log_stats_success:Function]

9
backend/src/api/routes/admin.py
View File

@@ -31,6 +31,7 @@ from ...services.rbac_permission_catalog import (
# [/SECTION]
# [DEF:router:Variable]
# @RELATION: DEPENDS_ON -> fastapi.APIRouter
# @PURPOSE: APIRouter instance for admin routes.
router = APIRouter(prefix="/api/admin", tags=["admin"])
# [/DEF:router:Variable]
@@ -42,6 +43,7 @@ router = APIRouter(prefix="/api/admin", tags=["admin"])
# @POST: Returns a list of UserSchema objects.
# @PARAM: db (Session) - Auth database session.
# @RETURN: List[UserSchema] - List of users.
# @RELATION: CALLS -> User
@router.get("/users", response_model=List[UserSchema])
async def list_users(
db: Session = Depends(get_auth_db),
@@ -60,6 +62,7 @@ async def list_users(
# @PARAM: user_in (UserCreate) - New user data.
# @PARAM: db (Session) - Auth database session.
# @RETURN: UserSchema - The created user.
# @RELATION: CALLS -> AuthRepository
@router.post("/users", response_model=UserSchema, status_code=status.HTTP_201_CREATED)
async def create_user(
user_in: UserCreate,
@@ -99,6 +102,7 @@ async def create_user(
# @PARAM: user_in (UserUpdate) - Updated user data.
# @PARAM: db (Session) - Auth database session.
# @RETURN: UserSchema - The updated user profile.
# @RELATION: CALLS -> AuthRepository
@router.put("/users/{user_id}", response_model=UserSchema)
async def update_user(
user_id: str,
@@ -139,6 +143,7 @@ async def update_user(
# @PARAM: user_id (str) - Target user UUID.
# @PARAM: db (Session) - Auth database session.
# @RETURN: None
# @RELATION: CALLS -> AuthRepository
@router.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_user(
user_id: str,
@@ -313,6 +318,7 @@ async def list_permissions(
# [DEF:list_ad_mappings:Function]
# @COMPLEXITY: 3
# @PURPOSE: Lists all AD Group to Role mappings.
# @RELATION: CALLS -> ADGroupMapping
@router.get("/ad-mappings", response_model=List[ADGroupMappingSchema])
async def list_ad_mappings(
db: Session = Depends(get_auth_db),
@@ -323,7 +329,8 @@ async def list_ad_mappings(
# [/DEF:list_ad_mappings:Function]
# [DEF:create_ad_mapping:Function]
# @COMPLEXITY: 3
# @RELATION: CALLS -> AuthRepository
# @COMPLEXITY: 2
# @PURPOSE: Creates a new AD Group mapping.
@router.post("/ad-mappings", response_model=ADGroupMappingSchema)
async def create_ad_mapping(

238
backend/src/api/routes/clean_release.py
View File

@@ -1,5 +1,5 @@
# [DEF:backend.src.api.routes.clean_release:Module]
# @COMPLEXITY: 3
# @COMPLEXITY: 4
# @SEMANTICS: api, clean-release, candidate-preparation, compliance
# @PURPOSE: Expose clean release endpoints for candidate preparation and subsequent compliance flow.
# @LAYER: API
@@ -19,10 +19,20 @@ from ...core.logger import belief_scope, logger
from ...dependencies import get_clean_release_repository, get_config_manager
from ...services.clean_release.preparation_service import prepare_candidate
from ...services.clean_release.repository import CleanReleaseRepository
from ...services.clean_release.compliance_orchestrator import CleanComplianceOrchestrator
from ...services.clean_release.compliance_orchestrator import (
CleanComplianceOrchestrator,
)
from ...services.clean_release.report_builder import ComplianceReportBuilder
from ...services.clean_release.compliance_execution_service import ComplianceExecutionService, ComplianceRunError
from ...services.clean_release.dto import CandidateDTO, ManifestDTO, CandidateOverviewDTO, ComplianceRunDTO
from ...services.clean_release.compliance_execution_service import (
ComplianceExecutionService,
ComplianceRunError,
)
from ...services.clean_release.dto import (
CandidateDTO,
ManifestDTO,
CandidateOverviewDTO,
ComplianceRunDTO,
)
from ...services.clean_release.enums import (
ComplianceDecision,
ComplianceStageName,
@@ -49,6 +59,8 @@ class PrepareCandidateRequest(BaseModel):
artifacts: List[Dict[str, Any]] = Field(default_factory=list)
sources: List[str] = Field(default_factory=list)
operator_id: str = Field(min_length=1)
# [/DEF:PrepareCandidateRequest:Class]
@@ -59,6 +71,8 @@ class StartCheckRequest(BaseModel):
profile: str = Field(default="enterprise-clean")
execution_mode: str = Field(default="tui")
triggered_by: str = Field(default="system")
# [/DEF:StartCheckRequest:Class]
@@ -69,6 +83,8 @@ class RegisterCandidateRequest(BaseModel):
version: str = Field(min_length=1)
source_snapshot_ref: str = Field(min_length=1)
created_by: str = Field(min_length=1)
# [/DEF:RegisterCandidateRequest:Class]
@@ -76,6 +92,8 @@ class RegisterCandidateRequest(BaseModel):
# @PURPOSE: Request schema for candidate artifact import endpoint.
class ImportArtifactsRequest(BaseModel):
artifacts: List[Dict[str, Any]] = Field(default_factory=list)
# [/DEF:ImportArtifactsRequest:Class]
@@ -83,6 +101,8 @@ class ImportArtifactsRequest(BaseModel):
# @PURPOSE: Request schema for manifest build endpoint.
class BuildManifestRequest(BaseModel):
created_by: str = Field(default="system")
# [/DEF:BuildManifestRequest:Class]
@@ -91,6 +111,8 @@ class BuildManifestRequest(BaseModel):
class CreateComplianceRunRequest(BaseModel):
requested_by: str = Field(min_length=1)
manifest_id: str | None = None
# [/DEF:CreateComplianceRunRequest:Class]
@@ -98,14 +120,19 @@ class CreateComplianceRunRequest(BaseModel):
# @PURPOSE: Register a clean-release candidate for headless lifecycle.
# @PRE: Candidate identifier is unique.
# @POST: Candidate is persisted in DRAFT status.
@router.post("/candidates", response_model=CandidateDTO, status_code=status.HTTP_201_CREATED)
@router.post(
"/candidates", response_model=CandidateDTO, status_code=status.HTTP_201_CREATED
)
async def register_candidate_v2_endpoint(
payload: RegisterCandidateRequest,
repository: CleanReleaseRepository = Depends(get_clean_release_repository),
):
existing = repository.get_candidate(payload.id)
if existing is not None:
raise HTTPException(status_code=409, detail={"message": "Candidate already exists", "code": "CANDIDATE_EXISTS"})
raise HTTPException(
status_code=409,
detail={"message": "Candidate already exists", "code": "CANDIDATE_EXISTS"},
)
candidate = ReleaseCandidate(
id=payload.id,
@@ -125,6 +152,8 @@ async def register_candidate_v2_endpoint(
created_by=candidate.created_by,
status=CandidateStatus(candidate.status),
)
# [/DEF:register_candidate_v2_endpoint:Function]
@@ -140,9 +169,15 @@ async def import_candidate_artifacts_v2_endpoint(
):
candidate = repository.get_candidate(candidate_id)
if candidate is None:
raise HTTPException(status_code=404, detail={"message": "Candidate not found", "code": "CANDIDATE_NOT_FOUND"})
raise HTTPException(
status_code=404,
detail={"message": "Candidate not found", "code": "CANDIDATE_NOT_FOUND"},
)
if not payload.artifacts:
raise HTTPException(status_code=400, detail={"message": "Artifacts list is required", "code": "ARTIFACTS_EMPTY"})
raise HTTPException(
status_code=400,
detail={"message": "Artifacts list is required", "code": "ARTIFACTS_EMPTY"},
)
for artifact in payload.artifacts:
required = ("id", "path", "sha256", "size")
@@ -150,7 +185,10 @@ async def import_candidate_artifacts_v2_endpoint(
if field_name not in artifact:
raise HTTPException(
status_code=400,
detail={"message": f"Artifact missing field '{field_name}'", "code": "ARTIFACT_INVALID"},
detail={
"message": f"Artifact missing field '{field_name}'",
"code": "ARTIFACT_INVALID",
},
)
artifact_model = CandidateArtifact(
@@ -172,6 +210,8 @@ async def import_candidate_artifacts_v2_endpoint(
repository.save_candidate(candidate)
return {"status": "success"}
# [/DEF:import_candidate_artifacts_v2_endpoint:Function]
@@ -179,7 +219,11 @@ async def import_candidate_artifacts_v2_endpoint(
# @PURPOSE: Build immutable manifest snapshot for prepared candidate.
# @PRE: Candidate exists and has imported artifacts.
# @POST: Returns created ManifestDTO with incremented version.
@router.post("/candidates/{candidate_id}/manifests", response_model=ManifestDTO, status_code=status.HTTP_201_CREATED)
@router.post(
"/candidates/{candidate_id}/manifests",
response_model=ManifestDTO,
status_code=status.HTTP_201_CREATED,
)
async def build_candidate_manifest_v2_endpoint(
candidate_id: str,
payload: BuildManifestRequest,
@@ -194,7 +238,10 @@ async def build_candidate_manifest_v2_endpoint(
created_by=payload.created_by,
)
except ValueError as exc:
raise HTTPException(status_code=400, detail={"message": str(exc), "code": "MANIFEST_BUILD_ERROR"})
raise HTTPException(
status_code=400,
detail={"message": str(exc), "code": "MANIFEST_BUILD_ERROR"},
)
return ManifestDTO(
id=manifest.id,
@@ -207,6 +254,8 @@ async def build_candidate_manifest_v2_endpoint(
source_snapshot_ref=manifest.source_snapshot_ref,
content_json=manifest.content_json,
)
# [/DEF:build_candidate_manifest_v2_endpoint:Function]
@@ -221,26 +270,53 @@ async def get_candidate_overview_v2_endpoint(
):
candidate = repository.get_candidate(candidate_id)
if candidate is None:
raise HTTPException(status_code=404, detail={"message": "Candidate not found", "code": "CANDIDATE_NOT_FOUND"})
raise HTTPException(
status_code=404,
detail={"message": "Candidate not found", "code": "CANDIDATE_NOT_FOUND"},
)
manifests = repository.get_manifests_by_candidate(candidate_id)
latest_manifest = sorted(manifests, key=lambda m: m.manifest_version, reverse=True)[0] if manifests else None
latest_manifest = (
sorted(manifests, key=lambda m: m.manifest_version, reverse=True)[0]
if manifests
else None
)
runs = [run for run in repository.check_runs.values() if run.candidate_id == candidate_id]
latest_run = sorted(runs, key=lambda run: run.requested_at or datetime.min.replace(tzinfo=timezone.utc), reverse=True)[0] if runs else None
runs = [
run
for run in repository.check_runs.values()
if run.candidate_id == candidate_id
]
latest_run = (
sorted(
runs,
key=lambda run: run.requested_at
or datetime.min.replace(tzinfo=timezone.utc),
reverse=True,
)[0]
if runs
else None
)
latest_report = None
if latest_run is not None:
latest_report = next((r for r in repository.reports.values() if r.run_id == latest_run.id), None)
latest_report = next(
(r for r in repository.reports.values() if r.run_id == latest_run.id), None
)
latest_policy_snapshot = repository.get_policy(latest_run.policy_snapshot_id) if latest_run else None
latest_registry_snapshot = repository.get_registry(latest_run.registry_snapshot_id) if latest_run else None
latest_policy_snapshot = (
repository.get_policy(latest_run.policy_snapshot_id) if latest_run else None
)
latest_registry_snapshot = (
repository.get_registry(latest_run.registry_snapshot_id) if latest_run else None
)
approval_decisions = getattr(repository, "approval_decisions", [])
latest_approval = (
sorted(
[item for item in approval_decisions if item.candidate_id == candidate_id],
key=lambda item: item.decided_at or datetime.min.replace(tzinfo=timezone.utc),
key=lambda item: item.decided_at
or datetime.min.replace(tzinfo=timezone.utc),
reverse=True,
)[0]
if approval_decisions
@@ -252,7 +328,8 @@ async def get_candidate_overview_v2_endpoint(
latest_publication = (
sorted(
[item for item in publication_records if item.candidate_id == candidate_id],
key=lambda item: item.published_at or datetime.min.replace(tzinfo=timezone.utc),
key=lambda item: item.published_at
or datetime.min.replace(tzinfo=timezone.utc),
reverse=True,
)[0]
if publication_records
@@ -266,19 +343,35 @@ async def get_candidate_overview_v2_endpoint(
source_snapshot_ref=candidate.source_snapshot_ref,
status=CandidateStatus(candidate.status),
latest_manifest_id=latest_manifest.id if latest_manifest else None,
latest_manifest_digest=latest_manifest.manifest_digest if latest_manifest else None,
latest_manifest_digest=latest_manifest.manifest_digest
if latest_manifest
else None,
latest_run_id=latest_run.id if latest_run else None,
latest_run_status=RunStatus(latest_run.status) if latest_run else None,
latest_report_id=latest_report.id if latest_report else None,
latest_report_final_status=ComplianceDecision(latest_report.final_status) if latest_report else None,
latest_policy_snapshot_id=latest_policy_snapshot.id if latest_policy_snapshot else None,
latest_policy_version=latest_policy_snapshot.policy_version if latest_policy_snapshot else None,
latest_registry_snapshot_id=latest_registry_snapshot.id if latest_registry_snapshot else None,
latest_registry_version=latest_registry_snapshot.registry_version if latest_registry_snapshot else None,
latest_report_final_status=ComplianceDecision(latest_report.final_status)
if latest_report
else None,
latest_policy_snapshot_id=latest_policy_snapshot.id
if latest_policy_snapshot
else None,
latest_policy_version=latest_policy_snapshot.policy_version
if latest_policy_snapshot
else None,
latest_registry_snapshot_id=latest_registry_snapshot.id
if latest_registry_snapshot
else None,
latest_registry_version=latest_registry_snapshot.registry_version
if latest_registry_snapshot
else None,
latest_approval_decision=latest_approval.decision if latest_approval else None,
latest_publication_id=latest_publication.id if latest_publication else None,
latest_publication_status=latest_publication.status if latest_publication else None,
latest_publication_status=latest_publication.status
if latest_publication
else None,
)
# [/DEF:get_candidate_overview_v2_endpoint:Function]
@@ -311,6 +404,8 @@ async def prepare_candidate_endpoint(
status_code=status.HTTP_400_BAD_REQUEST,
detail={"message": str(exc), "code": "CLEAN_PREPARATION_ERROR"},
)
# [/DEF:prepare_candidate_endpoint:Function]
@@ -327,27 +422,46 @@ async def start_check(
logger.reason("Starting clean-release compliance check run")
policy = repository.get_active_policy()
if policy is None:
raise HTTPException(status_code=409, detail={"message": "Active policy not found", "code": "POLICY_NOT_FOUND"})
raise HTTPException(
status_code=409,
detail={
"message": "Active policy not found",
"code": "POLICY_NOT_FOUND",
},
)
candidate = repository.get_candidate(payload.candidate_id)
if candidate is None:
raise HTTPException(status_code=409, detail={"message": "Candidate not found", "code": "CANDIDATE_NOT_FOUND"})
raise HTTPException(
status_code=409,
detail={
"message": "Candidate not found",
"code": "CANDIDATE_NOT_FOUND",
},
)
manifests = repository.get_manifests_by_candidate(payload.candidate_id)
if not manifests:
logger.explore("No manifest found for candidate; bootstrapping legacy empty manifest for compatibility")
from ...services.clean_release.manifest_builder import build_distribution_manifest
logger.explore(
"No manifest found for candidate; bootstrapping legacy empty manifest for compatibility"
)
from ...services.clean_release.manifest_builder import (
build_distribution_manifest,
)
boot_manifest = build_distribution_manifest(
manifest_id=f"manifest-{payload.candidate_id}",
candidate_id=payload.candidate_id,
policy_id=getattr(policy, "policy_id", None) or getattr(policy, "id", ""),
policy_id=getattr(policy, "policy_id", None)
or getattr(policy, "id", ""),
generated_by=payload.triggered_by,
artifacts=[],
)
repository.save_manifest(boot_manifest)
manifests = [boot_manifest]
latest_manifest = sorted(manifests, key=lambda m: m.manifest_version, reverse=True)[0]
latest_manifest = sorted(
manifests, key=lambda m: m.manifest_version, reverse=True
)[0]
orchestrator = CleanComplianceOrchestrator(repository)
run = orchestrator.start_check_run(
@@ -364,7 +478,7 @@ async def start_check(
stage_name=ComplianceStageName.DATA_PURITY.value,
status=RunStatus.SUCCEEDED.value,
decision=ComplianceDecision.PASSED.value,
details_json={"message": "ok"}
details_json={"message": "ok"},
),
ComplianceStageRun(
id=f"stage-{run.id}-2",
@@ -372,7 +486,7 @@ async def start_check(
stage_name=ComplianceStageName.INTERNAL_SOURCES_ONLY.value,
status=RunStatus.SUCCEEDED.value,
decision=ComplianceDecision.PASSED.value,
details_json={"message": "ok"}
details_json={"message": "ok"},
),
ComplianceStageRun(
id=f"stage-{run.id}-3",
@@ -380,7 +494,7 @@ async def start_check(
stage_name=ComplianceStageName.NO_EXTERNAL_ENDPOINTS.value,
status=RunStatus.SUCCEEDED.value,
decision=ComplianceDecision.PASSED.value,
details_json={"message": "ok"}
details_json={"message": "ok"},
),
ComplianceStageRun(
id=f"stage-{run.id}-4",
@@ -388,14 +502,20 @@ async def start_check(
stage_name=ComplianceStageName.MANIFEST_CONSISTENCY.value,
status=RunStatus.SUCCEEDED.value,
decision=ComplianceDecision.PASSED.value,
details_json={"message": "ok"}
details_json={"message": "ok"},
),
]
run = orchestrator.execute_stages(run, forced_results=forced)
run = orchestrator.finalize_run(run)
if str(run.final_status) in {ComplianceDecision.BLOCKED.value, "CheckFinalStatus.BLOCKED", "BLOCKED"}:
logger.explore("Run ended as BLOCKED, persisting synthetic external-source violation")
if str(run.final_status) in {
ComplianceDecision.BLOCKED.value,
"CheckFinalStatus.BLOCKED",
"BLOCKED",
}:
logger.explore(
"Run ended as BLOCKED, persisting synthetic external-source violation"
)
violation = ComplianceViolation(
id=f"viol-{run.id}",
run_id=run.id,
@@ -403,12 +523,14 @@ async def start_check(
code="EXTERNAL_SOURCE_DETECTED",
severity=ViolationSeverity.CRITICAL.value,
message="Replace with approved internal server",
evidence_json={"location": "external.example.com"}
evidence_json={"location": "external.example.com"},
)
repository.save_violation(violation)
builder = ComplianceReportBuilder(repository)
report = builder.build_report_payload(run, repository.get_violations_by_run(run.id))
report = builder.build_report_payload(
run, repository.get_violations_by_run(run.id)
)
builder.persist_report(report)
logger.reflect(f"Compliance report persisted for run_id={run.id}")
@@ -418,6 +540,8 @@ async def start_check(
"status": "running",
"started_at": run.started_at.isoformat() if run.started_at else None,
}
# [/DEF:start_check:Function]
@@ -426,11 +550,17 @@ async def start_check(
# @PRE: check_run_id references an existing run.
# @POST: Deterministic payload shape includes checks and violations arrays.
@router.get("/checks/{check_run_id}")
async def get_check_status(check_run_id: str, repository: CleanReleaseRepository = Depends(get_clean_release_repository)):
async def get_check_status(
check_run_id: str,
repository: CleanReleaseRepository = Depends(get_clean_release_repository),
):
with belief_scope("clean_release.get_check_status"):
run = repository.get_check_run(check_run_id)
if run is None:
raise HTTPException(status_code=404, detail={"message": "Check run not found", "code": "CHECK_NOT_FOUND"})
raise HTTPException(
status_code=404,
detail={"message": "Check run not found", "code": "CHECK_NOT_FOUND"},
)
logger.reflect(f"Returning check status for check_run_id={check_run_id}")
checks = [
@@ -462,6 +592,8 @@ async def get_check_status(check_run_id: str, repository: CleanReleaseRepository
"checks": checks,
"violations": violations,
}
# [/DEF:get_check_status:Function]
@@ -470,11 +602,17 @@ async def get_check_status(check_run_id: str, repository: CleanReleaseRepository
# @PRE: report_id references an existing report.
# @POST: Returns serialized report object.
@router.get("/reports/{report_id}")
async def get_report(report_id: str, repository: CleanReleaseRepository = Depends(get_clean_release_repository)):
async def get_report(
report_id: str,
repository: CleanReleaseRepository = Depends(get_clean_release_repository),
):
with belief_scope("clean_release.get_report"):
report = repository.get_report(report_id)
if report is None:
raise HTTPException(status_code=404, detail={"message": "Report not found", "code": "REPORT_NOT_FOUND"})
raise HTTPException(
status_code=404,
detail={"message": "Report not found", "code": "REPORT_NOT_FOUND"},
)
logger.reflect(f"Returning compliance report report_id={report_id}")
return {
@@ -482,11 +620,17 @@ async def get_report(report_id: str, repository: CleanReleaseRepository = Depend
"check_run_id": report.run_id,
"candidate_id": report.candidate_id,
"final_status": getattr(report.final_status, "value", report.final_status),
"generated_at": report.generated_at.isoformat() if getattr(report, "generated_at", None) else None,
"generated_at": report.generated_at.isoformat()
if getattr(report, "generated_at", None)
else None,
"operator_summary": getattr(report, "operator_summary", ""),
"structured_payload_ref": getattr(report, "structured_payload_ref", None),
"violations_count": getattr(report, "violations_count", 0),
"blocking_violations_count": getattr(report, "blocking_violations_count", 0),
"blocking_violations_count": getattr(
report, "blocking_violations_count", 0
),
}
# [/DEF:get_report:Function]
# [/DEF:backend.src.api.routes.clean_release:Module]

98
backend/src/api/routes/clean_release_v2.py
View File

@@ -1,16 +1,26 @@
# [DEF:backend.src.api.routes.clean_release_v2:Module]
# @COMPLEXITY: 3
# [DEF:CleanReleaseV2Api:Module]
# @COMPLEXITY: 4
# @PURPOSE: Redesigned clean release API for headless candidate lifecycle.
from fastapi import APIRouter, Depends, HTTPException, status
from typing import List, Dict, Any
from datetime import datetime, timezone
from ...services.clean_release.approval_service import approve_candidate, reject_candidate
from ...services.clean_release.publication_service import publish_candidate, revoke_publication
from ...services.clean_release.approval_service import (
approve_candidate,
reject_candidate,
)
from ...services.clean_release.publication_service import (
publish_candidate,
revoke_publication,
)
from ...services.clean_release.repository import CleanReleaseRepository
from ...dependencies import get_clean_release_repository
from ...services.clean_release.enums import CandidateStatus
from ...models.clean_release import ReleaseCandidate, CandidateArtifact, DistributionManifest
from ...models.clean_release import (
ReleaseCandidate,
CandidateArtifact,
DistributionManifest,
)
from ...services.clean_release.dto import CandidateDTO, ManifestDTO
router = APIRouter(prefix="/api/v2/clean-release", tags=["Clean Release V2"])
@@ -22,6 +32,8 @@ router = APIRouter(prefix="/api/v2/clean-release", tags=["Clean Release V2"])
# @RELATION: USES -> [CandidateDTO]
class ApprovalRequest(dict):
pass
# [/DEF:ApprovalRequest:Class]
@@ -31,6 +43,8 @@ class ApprovalRequest(dict):
# @RELATION: USES -> [CandidateDTO]
class PublishRequest(dict):
pass
# [/DEF:PublishRequest:Class]
@@ -40,8 +54,11 @@ class PublishRequest(dict):
# @RELATION: USES -> [CandidateDTO]
class RevokeRequest(dict):
pass
# [/DEF:RevokeRequest:Class]
# [DEF:register_candidate:Function]
# @COMPLEXITY: 3
# @PURPOSE: Register a new release candidate.
@@ -50,10 +67,12 @@ class RevokeRequest(dict):
# @RETURN: CandidateDTO
# @RELATION: CALLS -> [CleanReleaseRepository.save_candidate]
# @RELATION: USES -> [CandidateDTO]
@router.post("/candidates", response_model=CandidateDTO, status_code=status.HTTP_201_CREATED)
@router.post(
"/candidates", response_model=CandidateDTO, status_code=status.HTTP_201_CREATED
)
async def register_candidate(
payload: Dict[str, Any],
repository: CleanReleaseRepository = Depends(get_clean_release_repository)
repository: CleanReleaseRepository = Depends(get_clean_release_repository),
):
candidate = ReleaseCandidate(
id=payload["id"],
@@ -61,7 +80,7 @@ async def register_candidate(
source_snapshot_ref=payload["source_snapshot_ref"],
created_by=payload["created_by"],
created_at=datetime.now(timezone.utc),
status=CandidateStatus.DRAFT.value
status=CandidateStatus.DRAFT.value,
)
repository.save_candidate(candidate)
return CandidateDTO(
@@ -70,10 +89,13 @@ async def register_candidate(
source_snapshot_ref=candidate.source_snapshot_ref,
created_at=candidate.created_at,
created_by=candidate.created_by,
status=CandidateStatus(candidate.status)
status=CandidateStatus(candidate.status),
)
# [/DEF:register_candidate:Function]
# [DEF:import_artifacts:Function]
# @COMPLEXITY: 3
# @PURPOSE: Associate artifacts with a release candidate.
@@ -84,7 +106,7 @@ async def register_candidate(
async def import_artifacts(
candidate_id: str,
payload: Dict[str, Any],
repository: CleanReleaseRepository = Depends(get_clean_release_repository)
repository: CleanReleaseRepository = Depends(get_clean_release_repository),
):
candidate = repository.get_candidate(candidate_id)
if not candidate:
@@ -96,15 +118,18 @@ async def import_artifacts(
candidate_id=candidate_id,
path=art_data["path"],
sha256=art_data["sha256"],
size=art_data["size"]
size=art_data["size"],
)
# In a real repo we'd have save_artifact
# repository.save_artifact(artifact)
pass
return {"status": "success"}
# [/DEF:import_artifacts:Function]
# [DEF:build_manifest:Function]
# @COMPLEXITY: 3
# @PURPOSE: Generate distribution manifest for a candidate.
@@ -113,10 +138,14 @@ async def import_artifacts(
# @RETURN: ManifestDTO
# @RELATION: CALLS -> [CleanReleaseRepository.save_manifest]
# @RELATION: CALLS -> [CleanReleaseRepository.get_candidate]
@router.post("/candidates/{candidate_id}/manifests", response_model=ManifestDTO, status_code=status.HTTP_201_CREATED)
@router.post(
"/candidates/{candidate_id}/manifests",
response_model=ManifestDTO,
status_code=status.HTTP_201_CREATED,
)
async def build_manifest(
candidate_id: str,
repository: CleanReleaseRepository = Depends(get_clean_release_repository)
repository: CleanReleaseRepository = Depends(get_clean_release_repository),
):
candidate = repository.get_candidate(candidate_id)
if not candidate:
@@ -131,7 +160,7 @@ async def build_manifest(
created_by="system",
created_at=datetime.now(timezone.utc),
source_snapshot_ref=candidate.source_snapshot_ref,
content_json={"items": [], "summary": {}}
content_json={"items": [], "summary": {}},
)
repository.save_manifest(manifest)
@@ -144,10 +173,13 @@ async def build_manifest(
created_at=manifest.created_at,
created_by=manifest.created_by,
source_snapshot_ref=manifest.source_snapshot_ref,
content_json=manifest.content_json
content_json=manifest.content_json,
)
# [/DEF:build_manifest:Function]
# [DEF:approve_candidate_endpoint:Function]
# @COMPLEXITY: 3
# @PURPOSE: Endpoint to record candidate approval.
@@ -167,9 +199,13 @@ async def approve_candidate_endpoint(
comment=payload.get("comment"),
)
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=409, detail={"message": str(exc), "code": "APPROVAL_GATE_ERROR"})
raise HTTPException(
status_code=409, detail={"message": str(exc), "code": "APPROVAL_GATE_ERROR"}
)
return {"status": "ok", "decision": decision.decision, "decision_id": decision.id}
# [/DEF:approve_candidate_endpoint:Function]
@@ -192,9 +228,13 @@ async def reject_candidate_endpoint(
comment=payload.get("comment"),
)
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=409, detail={"message": str(exc), "code": "APPROVAL_GATE_ERROR"})
raise HTTPException(
status_code=409, detail={"message": str(exc), "code": "APPROVAL_GATE_ERROR"}
)
return {"status": "ok", "decision": decision.decision, "decision_id": decision.id}
# [/DEF:reject_candidate_endpoint:Function]
@@ -218,7 +258,10 @@ async def publish_candidate_endpoint(
publication_ref=payload.get("publication_ref"),
)
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=409, detail={"message": str(exc), "code": "PUBLICATION_GATE_ERROR"})
raise HTTPException(
status_code=409,
detail={"message": str(exc), "code": "PUBLICATION_GATE_ERROR"},
)
return {
"status": "ok",
@@ -227,12 +270,16 @@ async def publish_candidate_endpoint(
"candidate_id": publication.candidate_id,
"report_id": publication.report_id,
"published_by": publication.published_by,
"published_at": publication.published_at.isoformat() if publication.published_at else None,
"published_at": publication.published_at.isoformat()
if publication.published_at
else None,
"target_channel": publication.target_channel,
"publication_ref": publication.publication_ref,
"status": publication.status,
},
}
# [/DEF:publish_candidate_endpoint:Function]
@@ -254,7 +301,10 @@ async def revoke_publication_endpoint(
comment=payload.get("comment"),
)
except Exception as exc: # noqa: BLE001
raise HTTPException(status_code=409, detail={"message": str(exc), "code": "PUBLICATION_GATE_ERROR"})
raise HTTPException(
status_code=409,
detail={"message": str(exc), "code": "PUBLICATION_GATE_ERROR"},
)
return {
"status": "ok",
@@ -263,12 +313,16 @@ async def revoke_publication_endpoint(
"candidate_id": publication.candidate_id,
"report_id": publication.report_id,
"published_by": publication.published_by,
"published_at": publication.published_at.isoformat() if publication.published_at else None,
"published_at": publication.published_at.isoformat()
if publication.published_at
else None,
"target_channel": publication.target_channel,
"publication_ref": publication.publication_ref,
"status": publication.status,
},
}
# [/DEF:revoke_publication_endpoint:Function]
# [/DEF:backend.src.api.routes.clean_release_v2:Module]
# [/DEF:CleanReleaseV2Api:Module]

36
backend/src/api/routes/dataset_review.py
View File

@@ -269,7 +269,7 @@ class LaunchDatasetResponse(BaseModel):
# [DEF:_require_auto_review_flag:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Guard US1 dataset review endpoints behind the configured feature flag.
# @RELATION: [DEPENDS_ON] ->[ConfigManager]
def _require_auto_review_flag(config_manager=Depends(get_config_manager)) -> bool:
@@ -284,7 +284,7 @@ def _require_auto_review_flag(config_manager=Depends(get_config_manager)) -> boo
# [DEF:_require_clarification_flag:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Guard clarification-specific US2 endpoints behind the configured feature flag.
# @RELATION: [DEPENDS_ON] ->[ConfigManager]
def _require_clarification_flag(config_manager=Depends(get_config_manager)) -> bool:
@@ -299,7 +299,7 @@ def _require_clarification_flag(config_manager=Depends(get_config_manager)) -> b
# [DEF:_require_execution_flag:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Guard US3 execution endpoints behind the configured feature flag.
# @RELATION: [DEPENDS_ON] ->[ConfigManager]
def _require_execution_flag(config_manager=Depends(get_config_manager)) -> bool:
@@ -322,7 +322,7 @@ def _get_repository(db: Session = Depends(get_db)) -> DatasetReviewSessionReposi
# [DEF:_get_orchestrator:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Build orchestrator dependency for session lifecycle actions.
# @RELATION: [DEPENDS_ON] ->[DatasetReviewOrchestrator]
def _get_orchestrator(
@@ -339,7 +339,7 @@ def _get_orchestrator(
# [DEF:_get_clarification_engine:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Build clarification engine dependency for one-question-at-a-time guided clarification mutations.
# @RELATION: [DEPENDS_ON] ->[ClarificationEngine]
def _get_clarification_engine(
@@ -350,7 +350,7 @@ def _get_clarification_engine(
# [DEF:_serialize_session_summary:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Map SQLAlchemy session aggregate root into stable API summary DTO.
# @RELATION: [DEPENDS_ON] ->[SessionSummary]
def _serialize_session_summary(session: DatasetReviewSession) -> SessionSummary:
@@ -359,7 +359,7 @@ def _serialize_session_summary(session: DatasetReviewSession) -> SessionSummary:
# [DEF:_serialize_session_detail:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Map SQLAlchemy session aggregate root into stable API detail DTO.
# @RELATION: [DEPENDS_ON] ->[SessionDetail]
def _serialize_session_detail(session: DatasetReviewSession) -> SessionDetail:
@@ -368,7 +368,7 @@ def _serialize_session_detail(session: DatasetReviewSession) -> SessionDetail:
# [DEF:_serialize_semantic_field:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Map one semantic field aggregate into stable field-level DTO output.
# @RELATION: [DEPENDS_ON] ->[SemanticFieldEntryDto]
def _serialize_semantic_field(field: SemanticFieldEntry) -> SemanticFieldEntryDto:
@@ -377,7 +377,7 @@ def _serialize_semantic_field(field: SemanticFieldEntry) -> SemanticFieldEntryDt
# [DEF:_serialize_clarification_question_payload:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Convert clarification engine payload into API DTO aligned with the clarification contract.
# @RELATION: [DEPENDS_ON] ->[ClarificationQuestionDto]
def _serialize_clarification_question_payload(
@@ -405,7 +405,7 @@ def _serialize_clarification_question_payload(
# [DEF:_serialize_clarification_state:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Convert clarification engine state into stable API response payload.
# @RELATION: [DEPENDS_ON] ->[ClarificationStateResponse]
def _serialize_clarification_state(
@@ -473,7 +473,7 @@ def _require_owner_mutation_scope(
# [DEF:_record_session_event:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Persist one explicit audit event for an owned dataset-review mutation endpoint.
# @RELATION: [CALLS] ->[SessionEventLogger.log_for_session]
def _record_session_event(
@@ -534,7 +534,7 @@ def _get_owned_field_or_404(
# [DEF:_get_latest_clarification_session_or_404:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Resolve the latest clarification aggregate for one session or raise when clarification is unavailable.
# @RELATION: [DEPENDS_ON] ->[ClarificationSession]
def _get_latest_clarification_session_or_404(
@@ -565,7 +565,7 @@ def _map_candidate_provenance(candidate: SemanticCandidate) -> FieldProvenance:
# [DEF:_resolve_candidate_source_version:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Resolve the semantic source version for one accepted candidate from the loaded session aggregate.
# @RELATION: [DEPENDS_ON] ->[SemanticFieldEntry]
# @RELATION: [DEPENDS_ON] ->[SemanticSource]
@@ -653,7 +653,7 @@ def _update_semantic_field_state(
# [DEF:_serialize_execution_mapping:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Map one persisted execution mapping into stable API DTO output.
# @RELATION: [DEPENDS_ON] ->[ExecutionMappingDto]
def _serialize_execution_mapping(mapping: ExecutionMapping) -> ExecutionMappingDto:
@@ -662,7 +662,7 @@ def _serialize_execution_mapping(mapping: ExecutionMapping) -> ExecutionMappingD
# [DEF:_serialize_run_context:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Map one persisted launch run context into stable API DTO output for SQL Lab handoff confirmation.
# @RELATION: [DEPENDS_ON] ->[DatasetRunContextDto]
def _serialize_run_context(run_context) -> DatasetRunContextDto:
@@ -671,7 +671,7 @@ def _serialize_run_context(run_context) -> DatasetRunContextDto:
# [DEF:_build_sql_lab_redirect_url:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Build a stable SQL Lab redirect URL from the configured Superset environment and persisted run context reference.
# @RELATION: [DEPENDS_ON] ->[DatasetRunContextDto]
def _build_sql_lab_redirect_url(environment_url: str, sql_lab_session_ref: str) -> str:
@@ -692,7 +692,7 @@ def _build_sql_lab_redirect_url(environment_url: str, sql_lab_session_ref: str)
# [DEF:_build_documentation_export:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Produce session documentation export content from current persisted review state.
# @RELATION: [DEPENDS_ON] ->[DatasetReviewSession]
def _build_documentation_export(session: DatasetReviewSession, export_format: ArtifactFormat) -> Dict[str, Any]:
@@ -747,7 +747,7 @@ def _build_documentation_export(session: DatasetReviewSession, export_format: Ar
# [DEF:_build_validation_export:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Produce validation-focused export content from persisted findings and readiness state.
# @RELATION: [DEPENDS_ON] ->[DatasetReviewSession]
def _build_validation_export(session: DatasetReviewSession, export_format: ArtifactFormat) -> Dict[str, Any]:

4
backend/src/api/routes/datasets.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.api.routes.datasets:Module]
# [DEF:DatasetsApi:Module]
#
# @COMPLEXITY: 3
# @SEMANTICS: api, datasets, resources, hub
@@ -423,4 +423,4 @@ async def get_dataset_detail(
raise HTTPException(status_code=503, detail=f"Failed to fetch dataset detail: {str(e)}")
# [/DEF:get_dataset_detail:Function]
# [/DEF:backend.src.api.routes.datasets:Module]
# [/DEF:DatasetsApi:Module]

4
backend/src/api/routes/environments.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.api.routes.environments:Module]
# [DEF:EnvironmentsApi:Module]
#
# @COMPLEXITY: 3
# @SEMANTICS: api, environments, superset, databases
@@ -156,4 +156,4 @@ async def get_environment_databases(
raise HTTPException(status_code=500, detail=f"Failed to fetch databases: {str(e)}")
# [/DEF:get_environment_databases:Function]
# [/DEF:backend.src.api.routes.environments:Module]
# [/DEF:EnvironmentsApi:Module]

6
backend/src/api/routes/git_schemas.py
View File

@@ -1,6 +1,6 @@
# [DEF:backend.src.api.routes.git_schemas:Module]
# [DEF:GitSchemas:Module]
#
# @COMPLEXITY: 3
# @COMPLEXITY: 1
# @SEMANTICS: git, schemas, pydantic, api, contracts
# @PURPOSE: Defines Pydantic models for the Git integration API layer.
# @LAYER: API
@@ -290,4 +290,4 @@ class PromoteResponse(BaseModel):
policy_violation: bool = False
# [/DEF:PromoteResponse:Class]
# [/DEF:backend.src.api.routes.git_schemas:Module]
# [/DEF:GitSchemas:Module]

2
backend/src/api/routes/llm.py
View File

@@ -1,5 +1,5 @@
# [DEF:backend/src/api/routes/llm.py:Module]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @SEMANTICS: api, routes, llm
# @PURPOSE: API routes for LLM provider configuration and management.
# @LAYER: UI (API)

4
backend/src/api/routes/mappings.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.api.routes.mappings:Module]
# [DEF:MappingsApi:Module]
#
# @COMPLEXITY: 3
# @SEMANTICS: api, mappings, database, fuzzy-matching
@@ -127,4 +127,4 @@ async def suggest_mappings_api(
raise HTTPException(status_code=500, detail=str(e))
# [/DEF:suggest_mappings_api:Function]
# [/DEF:backend.src.api.routes.mappings:Module]
# [/DEF:MappingsApi:Module]

8
backend/src/api/routes/profile.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.api.routes.profile:Module]
# [DEF:ProfileApiModule:Module]
#
# @COMPLEXITY: 5
# @SEMANTICS: api, profile, preferences, self-service, account-lookup
@@ -47,6 +47,7 @@ router = APIRouter(prefix="/api/profile", tags=["profile"])
# [DEF:_get_profile_service:Function]
# @RELATION: CALLS -> ProfileService
# @PURPOSE: Build profile service for current request scope.
# @PRE: db session and config manager are available.
# @POST: Returns a ready ProfileService instance.
@@ -60,6 +61,7 @@ def _get_profile_service(db: Session, config_manager, plugin_loader=None) -> Pro
# [DEF:get_preferences:Function]
# @RELATION: CALLS -> ProfileService
# @PURPOSE: Get authenticated user's dashboard filter preference.
# @PRE: Valid JWT and authenticated user context.
# @POST: Returns preference payload for current user only.
@@ -78,6 +80,7 @@ async def get_preferences(
# [DEF:update_preferences:Function]
# @RELATION: CALLS -> ProfileService
# @PURPOSE: Update authenticated user's dashboard filter preference.
# @PRE: Valid JWT and valid request payload.
# @POST: Persists normalized preference for current user or raises validation/authorization errors.
@@ -104,6 +107,7 @@ async def update_preferences(
# [DEF:lookup_superset_accounts:Function]
# @RELATION: CALLS -> ProfileService
# @PURPOSE: Lookup Superset account candidates in selected environment.
# @PRE: Valid JWT, authenticated context, and environment_id query parameter.
# @POST: Returns success or degraded lookup payload with stable shape.
@@ -144,4 +148,4 @@ async def lookup_superset_accounts(
raise HTTPException(status_code=404, detail=str(exc)) from exc
# [/DEF:lookup_superset_accounts:Function]
# [/DEF:backend.src.api.routes.profile:Module]
# [/DEF:ProfileApiModule:Module]

4
backend/src/api/routes/reports.py
View File

@@ -64,7 +64,7 @@ def _parse_csv_enum_list(raw: Optional[str], enum_cls, field_name: str) -> List:
# [DEF:list_reports:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Return paginated unified reports list.
# @PRE: authenticated/authorized request and validated query params.
# @POST: returns {items,total,page,page_size,has_next,applied_filters}.
@@ -131,7 +131,7 @@ async def list_reports(
# [DEF:get_report_detail:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Return one normalized report detail with diagnostics and next actions.
# @PRE: authenticated/authorized request and existing report_id.
# @POST: returns normalized detail envelope or 404 when report is not found.

202
backend/src/api/routes/settings.py
View File

@@ -1,6 +1,6 @@
# [DEF:SettingsRouter:Module]
#
# @COMPLEXITY: 3
# @COMPLEXITY: 4
# @SEMANTICS: settings, api, router, fastapi
# @PURPOSE: Provides API endpoints for managing application settings and Superset environments.
# @LAYER: UI (API)
@@ -23,11 +23,16 @@ from ...core.superset_client import SupersetClient
from ...services.llm_prompt_templates import normalize_llm_settings
from ...models.llm import ValidationPolicy
from ...models.config import AppConfigRecord
from ...schemas.settings import ValidationPolicyCreate, ValidationPolicyUpdate, ValidationPolicyResponse
from ...schemas.settings import (
ValidationPolicyCreate,
ValidationPolicyUpdate,
ValidationPolicyResponse,
)
from ...core.database import get_db
from sqlalchemy.orm import Session
# [/SECTION]
# [DEF:LoggingConfigResponse:Class]
# @COMPLEXITY: 1
# @PURPOSE: Response model for logging configuration with current task log level.
@@ -36,6 +41,8 @@ class LoggingConfigResponse(BaseModel):
level: str
task_log_level: str
enable_belief_state: bool
# [/DEF:LoggingConfigResponse:Class]
router = APIRouter()
@@ -51,11 +58,13 @@ def _normalize_superset_env_url(raw_url: str) -> str:
if normalized.lower().endswith("/api/v1"):
normalized = normalized[: -len("/api/v1")]
return normalized.rstrip("/")
# [/DEF:_normalize_superset_env_url:Function]
# [DEF:_validate_superset_connection_fast:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Run lightweight Superset connectivity validation without full pagination scan.
# @PRE: env contains valid URL and credentials.
# @POST: Raises on auth/API failures; returns None on success.
@@ -71,10 +80,13 @@ def _validate_superset_connection_fast(env: Environment) -> None:
"columns": ["id"],
}
)
# [/DEF:_validate_superset_connection_fast:Function]
# [DEF:get_settings:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Retrieves all application settings.
# @PRE: Config manager is available.
# @POST: Returns masked AppConfig.
@@ -82,7 +94,7 @@ def _validate_superset_connection_fast(env: Environment) -> None:
@router.get("", response_model=AppConfig)
async def get_settings(
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "READ"))
_=Depends(has_permission("admin:settings", "READ")),
):
with belief_scope("get_settings"):
logger.info("[get_settings][Entry] Fetching all settings")
@@ -93,10 +105,13 @@ async def get_settings(
if env.password:
env.password = "********"
return config
# [/DEF:get_settings:Function]
# [DEF:update_global_settings:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Updates global application settings.
# @PRE: New settings are provided.
# @POST: Global settings are updated.
@@ -106,30 +121,36 @@ async def get_settings(
async def update_global_settings(
settings: GlobalSettings,
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "WRITE"))
_=Depends(has_permission("admin:settings", "WRITE")),
):
with belief_scope("update_global_settings"):
logger.info("[update_global_settings][Entry] Updating global settings")
config_manager.update_global_settings(settings)
return settings
# [/DEF:update_global_settings:Function]
# [DEF:get_storage_settings:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Retrieves storage-specific settings.
# @RETURN: StorageConfig - The storage configuration.
@router.get("/storage", response_model=StorageConfig)
async def get_storage_settings(
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "READ"))
_=Depends(has_permission("admin:settings", "READ")),
):
with belief_scope("get_storage_settings"):
return config_manager.get_config().settings.storage
# [/DEF:get_storage_settings:Function]
# [DEF:update_storage_settings:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Updates storage-specific settings.
# @PARAM: storage (StorageConfig) - The new storage settings.
# @POST: Storage settings are updated and saved.
@@ -138,7 +159,7 @@ async def get_storage_settings(
async def update_storage_settings(
storage: StorageConfig,
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "WRITE"))
_=Depends(has_permission("admin:settings", "WRITE")),
):
with belief_scope("update_storage_settings"):
is_valid, message = config_manager.validate_path(storage.root_path)
@@ -149,10 +170,13 @@ async def update_storage_settings(
settings.storage = storage
config_manager.update_global_settings(settings)
return config_manager.get_config().settings.storage
# [/DEF:update_storage_settings:Function]
# [DEF:get_environments:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Lists all configured Superset environments.
# @PRE: Config manager is available.
# @POST: Returns list of environments.
@@ -160,7 +184,7 @@ async def update_storage_settings(
@router.get("/environments", response_model=List[Environment])
async def get_environments(
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "READ"))
_=Depends(has_permission("admin:settings", "READ")),
):
with belief_scope("get_environments"):
logger.info("[get_environments][Entry] Fetching environments")
@@ -169,10 +193,13 @@ async def get_environments(
env.copy(update={"url": _normalize_superset_env_url(env.url)})
for env in environments
]
# [/DEF:get_environments:Function]
# [DEF:add_environment:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Adds a new Superset environment.
# @PRE: Environment data is valid and reachable.
# @POST: Environment is added to config.
@@ -182,7 +209,7 @@ async def get_environments(
async def add_environment(
env: Environment,
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "WRITE"))
_=Depends(has_permission("admin:settings", "WRITE")),
):
with belief_scope("add_environment"):
logger.info(f"[add_environment][Entry] Adding environment {env.id}")
@@ -192,15 +219,22 @@ async def add_environment(
try:
_validate_superset_connection_fast(env)
except Exception as e:
logger.error(f"[add_environment][Coherence:Failed] Connection validation failed: {e}")
raise HTTPException(status_code=400, detail=f"Connection validation failed: {e}")
logger.error(
f"[add_environment][Coherence:Failed] Connection validation failed: {e}"
)
raise HTTPException(
status_code=400, detail=f"Connection validation failed: {e}"
)
config_manager.add_environment(env)
return env
# [/DEF:add_environment:Function]
# [DEF:update_environment:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Updates an existing Superset environment.
# @PRE: ID and valid environment data are provided.
# @POST: Environment is updated in config.
@@ -211,7 +245,7 @@ async def add_environment(
async def update_environment(
id: str,
env: Environment,
config_manager: ConfigManager = Depends(get_config_manager)
config_manager: ConfigManager = Depends(get_config_manager),
):
with belief_scope("update_environment"):
logger.info(f"[update_environment][Entry] Updating environment {id}")
@@ -221,7 +255,9 @@ async def update_environment(
# If password is masked, we need the real one for validation
env_to_validate = env.copy(deep=True)
if env_to_validate.password == "********":
old_env = next((e for e in config_manager.get_environments() if e.id == id), None)
old_env = next(
(e for e in config_manager.get_environments() if e.id == id), None
)
if old_env:
env_to_validate.password = old_env.password
@@ -229,33 +265,42 @@ async def update_environment(
try:
_validate_superset_connection_fast(env_to_validate)
except Exception as e:
logger.error(f"[update_environment][Coherence:Failed] Connection validation failed: {e}")
raise HTTPException(status_code=400, detail=f"Connection validation failed: {e}")
logger.error(
f"[update_environment][Coherence:Failed] Connection validation failed: {e}"
)
raise HTTPException(
status_code=400, detail=f"Connection validation failed: {e}"
)
if config_manager.update_environment(id, env):
return env
raise HTTPException(status_code=404, detail=f"Environment {id} not found")
# [/DEF:update_environment:Function]
# [DEF:delete_environment:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Deletes a Superset environment.
# @PRE: ID is provided.
# @POST: Environment is removed from config.
# @PARAM: id (str) - The ID of the environment to delete.
@router.delete("/environments/{id}")
async def delete_environment(
id: str,
config_manager: ConfigManager = Depends(get_config_manager)
id: str, config_manager: ConfigManager = Depends(get_config_manager)
):
with belief_scope("delete_environment"):
logger.info(f"[delete_environment][Entry] Deleting environment {id}")
config_manager.delete_environment(id)
return {"message": f"Environment {id} deleted"}
# [/DEF:delete_environment:Function]
# [DEF:test_environment_connection:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Tests the connection to a Superset environment.
# @PRE: ID is provided.
# @POST: Returns success or error status.
@@ -263,8 +308,7 @@ async def delete_environment(
# @RETURN: dict - Success message or error.
@router.post("/environments/{id}/test")
async def test_environment_connection(
id: str,
config_manager: ConfigManager = Depends(get_config_manager)
id: str, config_manager: ConfigManager = Depends(get_config_manager)
):
with belief_scope("test_environment_connection"):
logger.info(f"[test_environment_connection][Entry] Testing environment {id}")
@@ -277,15 +321,22 @@ async def test_environment_connection(
try:
_validate_superset_connection_fast(env)
logger.info(f"[test_environment_connection][Coherence:OK] Connection successful for {id}")
logger.info(
f"[test_environment_connection][Coherence:OK] Connection successful for {id}"
)
return {"status": "success", "message": "Connection successful"}
except Exception as e:
logger.error(f"[test_environment_connection][Coherence:Failed] Connection failed for {id}: {e}")
logger.error(
f"[test_environment_connection][Coherence:Failed] Connection failed for {id}: {e}"
)
return {"status": "error", "message": str(e)}
# [/DEF:test_environment_connection:Function]
# [DEF:get_logging_config:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Retrieves current logging configuration.
# @PRE: Config manager is available.
# @POST: Returns logging configuration.
@@ -293,19 +344,22 @@ async def test_environment_connection(
@router.get("/logging", response_model=LoggingConfigResponse)
async def get_logging_config(
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "READ"))
_=Depends(has_permission("admin:settings", "READ")),
):
with belief_scope("get_logging_config"):
logging_config = config_manager.get_config().settings.logging
return LoggingConfigResponse(
level=logging_config.level,
task_log_level=logging_config.task_log_level,
enable_belief_state=logging_config.enable_belief_state
enable_belief_state=logging_config.enable_belief_state,
)
# [/DEF:get_logging_config:Function]
# [DEF:update_logging_config:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Updates logging configuration.
# @PRE: New logging config is provided.
# @POST: Logging configuration is updated and saved.
@@ -315,10 +369,12 @@ async def get_logging_config(
async def update_logging_config(
config: LoggingConfig,
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "WRITE"))
_=Depends(has_permission("admin:settings", "WRITE")),
):
with belief_scope("update_logging_config"):
logger.info(f"[update_logging_config][Entry] Updating logging config: level={config.level}, task_log_level={config.task_log_level}")
logger.info(
f"[update_logging_config][Entry] Updating logging config: level={config.level}, task_log_level={config.task_log_level}"
)
# Get current settings and update logging config
settings = config_manager.get_config().settings
@@ -328,10 +384,13 @@ async def update_logging_config(
return LoggingConfigResponse(
level=config.level,
task_log_level=config.task_log_level,
enable_belief_state=config.enable_belief_state
enable_belief_state=config.enable_belief_state,
)
# [/DEF:update_logging_config:Function]
# [DEF:ConsolidatedSettingsResponse:Class]
# @COMPLEXITY: 1
# @PURPOSE: Response model for consolidated application settings.
@@ -343,10 +402,13 @@ class ConsolidatedSettingsResponse(BaseModel):
logging: dict
storage: dict
notifications: dict = {}
# [/DEF:ConsolidatedSettingsResponse:Class]
# [DEF:get_consolidated_settings:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 4
# @PURPOSE: Retrieves all settings categories in a single call
# @PRE: Config manager is available.
# @POST: Returns all consolidated settings.
@@ -354,15 +416,18 @@ class ConsolidatedSettingsResponse(BaseModel):
@router.get("/consolidated", response_model=ConsolidatedSettingsResponse)
async def get_consolidated_settings(
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "READ"))
_=Depends(has_permission("admin:settings", "READ")),
):
with belief_scope("get_consolidated_settings"):
logger.info("[get_consolidated_settings][Entry] Fetching all consolidated settings")
logger.info(
"[get_consolidated_settings][Entry] Fetching all consolidated settings"
)
config = config_manager.get_config()
from ...services.llm_provider import LLMProviderService
from ...core.database import SessionLocal
db = SessionLocal()
notifications_payload = {}
try:
@@ -376,13 +441,18 @@ async def get_consolidated_settings(
"base_url": p.base_url,
"api_key": "********",
"default_model": p.default_model,
"is_active": p.is_active
} for p in providers
"is_active": p.is_active,
}
for p in providers
]
config_record = db.query(AppConfigRecord).filter(AppConfigRecord.id == "global").first()
config_record = (
db.query(AppConfigRecord).filter(AppConfigRecord.id == "global").first()
)
if config_record and isinstance(config_record.payload, dict):
notifications_payload = config_record.payload.get("notifications", {}) or {}
notifications_payload = (
config_record.payload.get("notifications", {}) or {}
)
finally:
db.close()
@@ -395,12 +465,15 @@ async def get_consolidated_settings(
llm_providers=llm_providers_list,
logging=config.settings.logging.dict(),
storage=config.settings.storage.dict(),
notifications=notifications_payload
notifications=notifications_payload,
)
# [/DEF:get_consolidated_settings:Function]
# [DEF:update_consolidated_settings:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Bulk update application settings from the consolidated view.
# @PRE: User has admin permissions, config is valid.
# @POST: Settings are updated and saved via ConfigManager.
@@ -408,10 +481,12 @@ async def get_consolidated_settings(
async def update_consolidated_settings(
settings_patch: dict,
config_manager: ConfigManager = Depends(get_config_manager),
_ = Depends(has_permission("admin:settings", "WRITE"))
_=Depends(has_permission("admin:settings", "WRITE")),
):
with belief_scope("update_consolidated_settings"):
logger.info("[update_consolidated_settings][Entry] Applying consolidated settings patch")
logger.info(
"[update_consolidated_settings][Entry] Applying consolidated settings patch"
)
current_config = config_manager.get_config()
current_settings = current_config.settings
@@ -443,23 +518,28 @@ async def update_consolidated_settings(
config_manager.update_global_settings(current_settings)
return {"status": "success", "message": "Settings updated"}
# [/DEF:update_consolidated_settings:Function]
# [DEF:get_validation_policies:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Lists all validation policies.
# @RETURN: List[ValidationPolicyResponse] - List of policies.
@router.get("/automation/policies", response_model=List[ValidationPolicyResponse])
async def get_validation_policies(
db: Session = Depends(get_db),
_ = Depends(has_permission("admin:settings", "READ"))
db: Session = Depends(get_db), _=Depends(has_permission("admin:settings", "READ"))
):
with belief_scope("get_validation_policies"):
return db.query(ValidationPolicy).all()
# [/DEF:get_validation_policies:Function]
# [DEF:create_validation_policy:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Creates a new validation policy.
# @PARAM: policy (ValidationPolicyCreate) - The policy data.
# @RETURN: ValidationPolicyResponse - The created policy.
@@ -467,7 +547,7 @@ async def get_validation_policies(
async def create_validation_policy(
policy: ValidationPolicyCreate,
db: Session = Depends(get_db),
_ = Depends(has_permission("admin:settings", "WRITE"))
_=Depends(has_permission("admin:settings", "WRITE")),
):
with belief_scope("create_validation_policy"):
db_policy = ValidationPolicy(**policy.dict())
@@ -475,10 +555,13 @@ async def create_validation_policy(
db.commit()
db.refresh(db_policy)
return db_policy
# [/DEF:create_validation_policy:Function]
# [DEF:update_validation_policy:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Updates an existing validation policy.
# @PARAM: id (str) - The ID of the policy to update.
# @PARAM: policy (ValidationPolicyUpdate) - The updated policy data.
@@ -488,7 +571,7 @@ async def update_validation_policy(
id: str,
policy: ValidationPolicyUpdate,
db: Session = Depends(get_db),
_ = Depends(has_permission("admin:settings", "WRITE"))
_=Depends(has_permission("admin:settings", "WRITE")),
):
with belief_scope("update_validation_policy"):
db_policy = db.query(ValidationPolicy).filter(ValidationPolicy.id == id).first()
@@ -502,17 +585,20 @@ async def update_validation_policy(
db.commit()
db.refresh(db_policy)
return db_policy
# [/DEF:update_validation_policy:Function]
# [DEF:delete_validation_policy:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Deletes a validation policy.
# @PARAM: id (str) - The ID of the policy to delete.
@router.delete("/automation/policies/{id}")
async def delete_validation_policy(
id: str,
db: Session = Depends(get_db),
_ = Depends(has_permission("admin:settings", "WRITE"))
_=Depends(has_permission("admin:settings", "WRITE")),
):
with belief_scope("delete_validation_policy"):
db_policy = db.query(ValidationPolicy).filter(ValidationPolicy.id == id).first()
@@ -522,6 +608,8 @@ async def delete_validation_policy(
db.delete(db_policy)
db.commit()
return {"message": "Policy deleted"}
# [/DEF:delete_validation_policy:Function]
# [/DEF:SettingsRouter:Module]

22
backend/src/api/routes/tasks.py
View File

@@ -1,11 +1,11 @@
# [DEF:TasksRouter:Module]
# @COMPLEXITY: 4
# @COMPLEXITY: 3
# @SEMANTICS: api, router, tasks, create, list, get, logs
# @PURPOSE: Defines the FastAPI router for task-related endpoints, allowing clients to create, list, and get the status of tasks.
# @LAYER: UI (API)
# @RELATION: DEPENDS_ON -> [backend.src.core.task_manager.manager.TaskManager]
# @RELATION: DEPENDS_ON -> [backend.src.core.config_manager.ConfigManager]
# @RELATION: DEPENDS_ON -> [backend.src.services.llm_provider.LLMProviderService]
# @RELATION: DEPENDS_ON -> [TaskManager]
# @RELATION: DEPENDS_ON -> [ConfigManager]
# @RELATION: DEPENDS_ON -> [LLMProviderService]
# [SECTION: IMPORTS]
from typing import List, Dict, Any, Optional
@@ -107,7 +107,7 @@ async def create_task(
# [/DEF:create_task:Function]
# [DEF:list_tasks:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Retrieve a list of tasks with pagination and optional status filter.
# @PARAM: limit (int) - Maximum number of tasks to return.
# @PARAM: offset (int) - Number of tasks to skip.
@@ -147,7 +147,7 @@ async def list_tasks(
# [/DEF:list_tasks:Function]
# [DEF:get_task:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Retrieve the details of a specific task.
# @PARAM: task_id (str) - The unique identifier of the task.
# @PARAM: task_manager (TaskManager) - The task manager instance.
@@ -213,7 +213,7 @@ async def get_task_logs(
# [/DEF:get_task_logs:Function]
# [DEF:get_task_log_stats:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Get statistics about logs for a task (counts by level and source).
# @PARAM: task_id (str) - The unique identifier of the task.
# @PARAM: task_manager (TaskManager) - The task manager instance.
@@ -249,7 +249,7 @@ async def get_task_log_stats(
# [/DEF:get_task_log_stats:Function]
# [DEF:get_task_log_sources:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Get unique sources for a task's logs.
# @PARAM: task_id (str) - The unique identifier of the task.
# @PARAM: task_manager (TaskManager) - The task manager instance.
@@ -269,7 +269,7 @@ async def get_task_log_sources(
# [/DEF:get_task_log_sources:Function]
# [DEF:resolve_task:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Resolve a task that is awaiting mapping.
# @PARAM: task_id (str) - The unique identifier of the task.
# @PARAM: request (ResolveTaskRequest) - The resolution parameters.
@@ -293,7 +293,7 @@ async def resolve_task(
# [/DEF:resolve_task:Function]
# [DEF:resume_task:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Resume a task that is awaiting input (e.g., passwords).
# @PARAM: task_id (str) - The unique identifier of the task.
# @PARAM: request (ResumeTaskRequest) - The input (passwords).
@@ -317,7 +317,7 @@ async def resume_task(
# [/DEF:resume_task:Function]
# [DEF:clear_tasks:Function]
# @COMPLEXITY: 3
# @COMPLEXITY: 2
# @PURPOSE: Clear tasks matching the status filter.
# @PARAM: status (Optional[TaskStatus]) - Filter by task status.
# @PARAM: task_manager (TaskManager) - The task manager instance.

8
backend/src/core/__tests__/test_config_manager_compat.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.core.__tests__.test_config_manager_compat:Module]
# [DEF:TestConfigManagerCompat:Module]
# @COMPLEXITY: 3
# @SEMANTICS: config-manager, compatibility, payload, tests
# @PURPOSE: Verifies ConfigManager compatibility wrappers preserve legacy payload sections.
@@ -12,6 +12,7 @@ from src.core.config_models import AppConfig, Environment, GlobalSettings
# [DEF:test_get_payload_preserves_legacy_sections:Function]
# @RELATION: BINDS_TO -> TestConfigManagerCompat
# @PURPOSE: Ensure get_payload merges typed config into raw payload without dropping legacy sections.
def test_get_payload_preserves_legacy_sections():
manager = ConfigManager.__new__(ConfigManager)
@@ -26,6 +27,7 @@ def test_get_payload_preserves_legacy_sections():
# [DEF:test_save_config_accepts_raw_payload_and_keeps_extras:Function]
# @RELATION: BINDS_TO -> TestConfigManagerCompat
# @PURPOSE: Ensure save_config accepts raw dict payload, refreshes typed config, and preserves extra sections.
def test_save_config_accepts_raw_payload_and_keeps_extras(monkeypatch):
manager = ConfigManager.__new__(ConfigManager)
@@ -53,6 +55,7 @@ def test_save_config_accepts_raw_payload_and_keeps_extras(monkeypatch):
# [DEF:test_save_config_syncs_environment_records_for_fk_backed_flows:Function]
# @RELATION: BINDS_TO -> TestConfigManagerCompat
# @PURPOSE: Ensure saving config mirrors typed environments into relational records required by FK-backed session persistence.
def test_save_config_syncs_environment_records_for_fk_backed_flows():
manager = ConfigManager.__new__(ConfigManager)
@@ -108,6 +111,7 @@ def test_save_config_syncs_environment_records_for_fk_backed_flows():
# [DEF:test_load_config_syncs_environment_records_from_existing_db_payload:Function]
# @RELATION: BINDS_TO -> TestConfigManagerCompat
# @PURPOSE: Ensure loading an existing DB-backed config also mirrors environment rows required by FK-backed runtime flows.
def test_load_config_syncs_environment_records_from_existing_db_payload(monkeypatch):
manager = ConfigManager.__new__(ConfigManager)
@@ -161,4 +165,4 @@ def test_load_config_syncs_environment_records_from_existing_db_payload(monkeypa
assert closed["value"] is True
# [/DEF:test_load_config_syncs_environment_records_from_existing_db_payload:Function]
# [/DEF:backend.src.core.__tests__.test_config_manager_compat:Module]
# [/DEF:TestConfigManagerCompat:Module]

21
backend/src/core/__tests__/test_native_filters.py
View File

@@ -28,6 +28,7 @@ from src.models.filter_state import (
# [DEF:_make_environment:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
def _make_environment() -> Environment:
return Environment(
id="env-1",
@@ -40,6 +41,7 @@ def _make_environment() -> Environment:
# [DEF:test_extract_native_filters_from_permalink:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Extract native filters from a permalink key.
def test_extract_native_filters_from_permalink():
client = SupersetClient(_make_environment())
@@ -86,6 +88,7 @@ def test_extract_native_filters_from_permalink():
# [DEF:test_extract_native_filters_from_permalink_direct_response:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Handle permalink response without result wrapper.
def test_extract_native_filters_from_permalink_direct_response():
client = SupersetClient(_make_environment())
@@ -111,6 +114,7 @@ def test_extract_native_filters_from_permalink_direct_response():
# [DEF:test_extract_native_filters_from_key:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Extract native filters from a native_filters_key.
def test_extract_native_filters_from_key():
client = SupersetClient(_make_environment())
@@ -141,6 +145,7 @@ def test_extract_native_filters_from_key():
# [DEF:test_extract_native_filters_from_key_single_filter:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Handle single filter format in native filter state.
def test_extract_native_filters_from_key_single_filter():
client = SupersetClient(_make_environment())
@@ -165,6 +170,7 @@ def test_extract_native_filters_from_key_single_filter():
# [DEF:test_extract_native_filters_from_key_dict_value:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Handle filter state value as dict instead of JSON string.
def test_extract_native_filters_from_key_dict_value():
client = SupersetClient(_make_environment())
@@ -189,6 +195,7 @@ def test_extract_native_filters_from_key_dict_value():
# [DEF:test_parse_dashboard_url_for_filters_permalink:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Parse permalink URL format.
def test_parse_dashboard_url_for_filters_permalink():
client = SupersetClient(_make_environment())
@@ -206,6 +213,7 @@ def test_parse_dashboard_url_for_filters_permalink():
# [DEF:test_parse_dashboard_url_for_filters_native_key:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Parse native_filters_key URL format with numeric dashboard ID.
def test_parse_dashboard_url_for_filters_native_key():
client = SupersetClient(_make_environment())
@@ -224,6 +232,7 @@ def test_parse_dashboard_url_for_filters_native_key():
# [DEF:test_parse_dashboard_url_for_filters_native_key_slug:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Parse native_filters_key URL format when dashboard reference is a slug, not a numeric ID.
def test_parse_dashboard_url_for_filters_native_key_slug():
client = SupersetClient(_make_environment())
@@ -250,6 +259,7 @@ def test_parse_dashboard_url_for_filters_native_key_slug():
# [DEF:test_parse_dashboard_url_for_filters_native_key_slug_resolution_fails:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Gracefully handle slug resolution failure for native_filters_key URL.
def test_parse_dashboard_url_for_filters_native_key_slug_resolution_fails():
client = SupersetClient(_make_environment())
@@ -265,6 +275,7 @@ def test_parse_dashboard_url_for_filters_native_key_slug_resolution_fails():
# [DEF:test_parse_dashboard_url_for_filters_native_filters_direct:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Parse native_filters direct query param.
def test_parse_dashboard_url_for_filters_native_filters_direct():
client = SupersetClient(_make_environment())
@@ -280,6 +291,7 @@ def test_parse_dashboard_url_for_filters_native_filters_direct():
# [DEF:test_parse_dashboard_url_for_filters_no_filters:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Return empty result when no filters present.
def test_parse_dashboard_url_for_filters_no_filters():
client = SupersetClient(_make_environment())
@@ -294,6 +306,7 @@ def test_parse_dashboard_url_for_filters_no_filters():
# [DEF:test_extra_form_data_merge:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Test ExtraFormDataMerge correctly merges dictionaries.
def test_extra_form_data_merge():
merger = ExtraFormDataMerge()
@@ -329,6 +342,7 @@ def test_extra_form_data_merge():
# [DEF:test_filter_state_model:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Test FilterState Pydantic model.
def test_filter_state_model():
state = FilterState(
@@ -344,6 +358,7 @@ def test_filter_state_model():
# [DEF:test_parsed_native_filters_model:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Test ParsedNativeFilters Pydantic model.
def test_parsed_native_filters_model():
filters = ParsedNativeFilters(
@@ -360,6 +375,7 @@ def test_parsed_native_filters_model():
# [DEF:test_parsed_native_filters_empty:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Test ParsedNativeFilters with no filters.
def test_parsed_native_filters_empty():
filters = ParsedNativeFilters()
@@ -370,6 +386,7 @@ def test_parsed_native_filters_empty():
# [DEF:test_native_filter_data_mask_model:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Test NativeFilterDataMask model.
def test_native_filter_data_mask_model():
data_mask = NativeFilterDataMask(
@@ -386,6 +403,7 @@ def test_native_filter_data_mask_model():
# [DEF:test_recover_imported_filters_reconciles_raw_native_filter_ids_to_metadata_names:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Reconcile raw native filter ids from state to canonical metadata filter names.
def test_recover_imported_filters_reconciles_raw_native_filter_ids_to_metadata_names():
client = MagicMock()
@@ -444,6 +462,7 @@ def test_recover_imported_filters_reconciles_raw_native_filter_ids_to_metadata_n
# [DEF:test_recover_imported_filters_collapses_state_and_metadata_duplicates_into_one_canonical_filter:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Collapse raw-id state entries and metadata entries into one canonical filter.
def test_recover_imported_filters_collapses_state_and_metadata_duplicates_into_one_canonical_filter():
client = MagicMock()
@@ -499,6 +518,7 @@ def test_recover_imported_filters_collapses_state_and_metadata_duplicates_into_o
# [DEF:test_recover_imported_filters_preserves_unmatched_raw_native_filter_ids:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Preserve unmatched raw native filter ids as fallback diagnostics when metadata mapping is unavailable.
def test_recover_imported_filters_preserves_unmatched_raw_native_filter_ids():
client = MagicMock()
@@ -550,6 +570,7 @@ def test_recover_imported_filters_preserves_unmatched_raw_native_filter_ids():
# [DEF:test_extract_imported_filters_preserves_clause_level_native_filter_payload_for_preview:Function]
# @RELATION: BINDS_TO -> NativeFilterExtractionTests
# @PURPOSE: Recovered native filter state should preserve exact Superset clause payload and time extras for preview compilation.
def test_extract_imported_filters_preserves_clause_level_native_filter_payload_for_preview():
extractor = SupersetContextExtractor(_make_environment(), client=MagicMock())

13
backend/src/core/__tests__/test_superset_preview_pipeline.py
View File

@@ -19,6 +19,7 @@ from src.core.utils.network import APIClient, DashboardNotFoundError, SupersetAP
# [DEF:_make_environment:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
def _make_environment() -> Environment:
return Environment(
id="env-1",
@@ -33,6 +34,7 @@ def _make_environment() -> Environment:
# [DEF:_make_requests_http_error:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
def _make_requests_http_error(
status_code: int, url: str
) -> requests.exceptions.HTTPError:
@@ -49,6 +51,7 @@ def _make_requests_http_error(
# [DEF:_make_httpx_status_error:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
def _make_httpx_status_error(status_code: int, url: str) -> httpx.HTTPStatusError:
request = httpx.Request("GET", url)
response = httpx.Response(
@@ -61,6 +64,7 @@ def _make_httpx_status_error(status_code: int, url: str) -> httpx.HTTPStatusErro
# [DEF:test_compile_dataset_preview_prefers_legacy_explore_form_data_strategy:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Superset preview compilation should prefer the legacy form_data transport inferred from browser traffic before falling back to chart-data.
def test_compile_dataset_preview_prefers_legacy_explore_form_data_strategy():
client = SupersetClient(_make_environment())
@@ -146,6 +150,7 @@ def test_compile_dataset_preview_prefers_legacy_explore_form_data_strategy():
# [DEF:test_compile_dataset_preview_falls_back_to_chart_data_after_legacy_failures:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Superset preview compilation should fall back to chart-data when legacy form_data strategies are rejected.
def test_compile_dataset_preview_falls_back_to_chart_data_after_legacy_failures():
client = SupersetClient(_make_environment())
@@ -242,6 +247,7 @@ def test_compile_dataset_preview_falls_back_to_chart_data_after_legacy_failures(
# [DEF:test_build_dataset_preview_query_context_places_recovered_filters_in_chart_style_form_data:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Preview query context should mirror chart-style filter transport so recovered native filters reach Superset compilation.
def test_build_dataset_preview_query_context_places_recovered_filters_in_chart_style_form_data():
client = SupersetClient(_make_environment())
@@ -304,6 +310,7 @@ def test_build_dataset_preview_query_context_places_recovered_filters_in_chart_s
# [DEF:test_build_dataset_preview_query_context_merges_dataset_template_params_and_preserves_user_values:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Preview query context should merge dataset template params for parity with real dataset definitions while preserving explicit session overrides.
def test_build_dataset_preview_query_context_merges_dataset_template_params_and_preserves_user_values():
client = SupersetClient(_make_environment())
@@ -334,6 +341,7 @@ def test_build_dataset_preview_query_context_merges_dataset_template_params_and_
# [DEF:test_build_dataset_preview_query_context_preserves_time_range_from_native_filter_payload:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Preview query context should preserve time-range native filter extras even when dataset defaults differ.
def test_build_dataset_preview_query_context_preserves_time_range_from_native_filter_payload():
client = SupersetClient(_make_environment())
@@ -372,6 +380,7 @@ def test_build_dataset_preview_query_context_preserves_time_range_from_native_fi
# [DEF:test_build_dataset_preview_legacy_form_data_preserves_native_filter_clauses:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Legacy preview form_data should preserve recovered native filter clauses in browser-style fields without duplicating datasource for QueryObjectFactory.
def test_build_dataset_preview_legacy_form_data_preserves_native_filter_clauses():
client = SupersetClient(_make_environment())
@@ -425,6 +434,7 @@ def test_build_dataset_preview_legacy_form_data_preserves_native_filter_clauses(
# [DEF:test_sync_network_404_mapping_keeps_non_dashboard_endpoints_generic:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Sync network client should reserve dashboard-not-found translation for dashboard endpoints only.
def test_sync_network_404_mapping_keeps_non_dashboard_endpoints_generic():
client = APIClient(
@@ -448,6 +458,7 @@ def test_sync_network_404_mapping_keeps_non_dashboard_endpoints_generic():
# [DEF:test_sync_network_404_mapping_translates_dashboard_endpoints:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Sync network client should still translate dashboard endpoint 404 responses into dashboard-not-found errors.
def test_sync_network_404_mapping_translates_dashboard_endpoints():
client = APIClient(
@@ -470,6 +481,7 @@ def test_sync_network_404_mapping_translates_dashboard_endpoints():
# [DEF:test_async_network_404_mapping_keeps_non_dashboard_endpoints_generic:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Async network client should reserve dashboard-not-found translation for dashboard endpoints only.
@pytest.mark.asyncio
async def test_async_network_404_mapping_keeps_non_dashboard_endpoints_generic():
@@ -499,6 +511,7 @@ async def test_async_network_404_mapping_keeps_non_dashboard_endpoints_generic()
# [DEF:test_async_network_404_mapping_translates_dashboard_endpoints:Function]
# @RELATION: BINDS_TO -> SupersetPreviewPipelineTests
# @PURPOSE: Async network client should still translate dashboard endpoint 404 responses into dashboard-not-found errors.
@pytest.mark.asyncio
async def test_async_network_404_mapping_translates_dashboard_endpoints():

39
backend/src/core/__tests__/test_superset_profile_lookup.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.src.core.__tests__.test_superset_profile_lookup:Module]
# [DEF:TestSupersetProfileLookup:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, superset, profile, lookup, fallback, sorting
# @PURPOSE: Verifies Superset profile lookup adapter payload normalization and fallback error precedence.
# @LAYER: Domain
# @RELATION: TESTS -> backend.src.core.superset_profile_lookup
# [SECTION: IMPORTS]
import json
@@ -23,7 +23,10 @@ from src.core.utils.network import AuthenticationError, SupersetAPIError
# [DEF:_RecordingNetworkClient:Class]
# @RELATION: BINDS_TO -> TestSupersetProfileLookup
# @COMPLEXITY: 2
# @PURPOSE: Records request payloads and returns scripted responses for deterministic adapter tests.
# @INVARIANT: Each request consumes one scripted response in call order and persists call metadata.
class _RecordingNetworkClient:
# [DEF:__init__:Function]
# @PURPOSE: Initializes scripted network responses.
@@ -32,6 +35,7 @@ class _RecordingNetworkClient:
def __init__(self, scripted_responses: List[Any]):
self._scripted_responses = scripted_responses
self.calls: List[Dict[str, Any]] = []
# [/DEF:__init__:Function]
# [DEF:request:Function]
@@ -57,11 +61,15 @@ class _RecordingNetworkClient:
if isinstance(response, Exception):
raise response
return response
# [/DEF:request:Function]
# [/DEF:_RecordingNetworkClient:Class]
# [DEF:test_get_users_page_sends_lowercase_order_direction:Function]
# @RELATION: BINDS_TO -> TestSupersetProfileLookup
# @PURPOSE: Ensures adapter sends lowercase order_direction compatible with Superset rison schema.
# @PRE: Adapter is initialized with recording network client.
# @POST: First request query payload contains order_direction='asc' for asc sort.
@@ -69,7 +77,9 @@ def test_get_users_page_sends_lowercase_order_direction():
client = _RecordingNetworkClient(
scripted_responses=[{"result": [{"username": "admin"}], "count": 1}]
)
adapter = SupersetAccountLookupAdapter(network_client=client, environment_id="ss-dev")
adapter = SupersetAccountLookupAdapter(
network_client=client, environment_id="ss-dev"
)
adapter.get_users_page(
search="admin",
@@ -81,10 +91,13 @@ def test_get_users_page_sends_lowercase_order_direction():
sent_query = json.loads(client.calls[0]["params"]["q"])
assert sent_query["order_direction"] == "asc"
# [/DEF:test_get_users_page_sends_lowercase_order_direction:Function]
# [DEF:test_get_users_page_preserves_primary_schema_error_over_fallback_auth_error:Function]
# @RELATION: BINDS_TO -> TestSupersetProfileLookup
# @PURPOSE: Ensures fallback auth error does not mask primary schema/query failure.
# @PRE: Primary endpoint fails with SupersetAPIError and fallback fails with AuthenticationError.
# @POST: Raised exception remains primary SupersetAPIError (non-auth) to preserve root cause.
@@ -95,17 +108,22 @@ def test_get_users_page_preserves_primary_schema_error_over_fallback_auth_error(
AuthenticationError(),
]
)
adapter = SupersetAccountLookupAdapter(network_client=client, environment_id="ss-dev")
adapter = SupersetAccountLookupAdapter(
network_client=client, environment_id="ss-dev"
)
with pytest.raises(SupersetAPIError) as exc_info:
adapter.get_users_page(sort_order="asc")
assert "API Error 400" in str(exc_info.value)
assert not isinstance(exc_info.value, AuthenticationError)
# [/DEF:test_get_users_page_preserves_primary_schema_error_over_fallback_auth_error:Function]
# [DEF:test_get_users_page_uses_fallback_endpoint_when_primary_fails:Function]
# @RELATION: BINDS_TO -> TestSupersetProfileLookup
# @PURPOSE: Verifies adapter retries second users endpoint and succeeds when fallback is healthy.
# @PRE: Primary endpoint fails; fallback returns valid users payload.
# @POST: Result status is success and both endpoints were attempted in order.
@@ -116,13 +134,20 @@ def test_get_users_page_uses_fallback_endpoint_when_primary_fails():
{"result": [{"username": "admin"}], "count": 1},
]
)
adapter = SupersetAccountLookupAdapter(network_client=client, environment_id="ss-dev")
adapter = SupersetAccountLookupAdapter(
network_client=client, environment_id="ss-dev"
)
result = adapter.get_users_page()
assert result["status"] == "success"
assert [call["endpoint"] for call in client.calls] == ["/security/users/", "/security/users"]
assert [call["endpoint"] for call in client.calls] == [
"/security/users/",
"/security/users",
]
# [/DEF:test_get_users_page_uses_fallback_endpoint_when_primary_fails:Function]
# [/DEF:backend.src.core.__tests__.test_superset_profile_lookup:Module]
# [/DEF:TestSupersetProfileLookup:Module]

25
backend/src/core/__tests__/test_throttled_scheduler.py
View File

@@ -3,9 +3,12 @@ from datetime import time, date, datetime, timedelta
from src.core.scheduler import ThrottledSchedulerConfigurator
# [DEF:test_throttled_scheduler:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @PURPOSE: Unit tests for ThrottledSchedulerConfigurator distribution logic.
# [DEF:test_calculate_schedule_even_distribution:Function]
# @RELATION: BINDS_TO -> test_throttled_scheduler
def test_calculate_schedule_even_distribution():
"""
@TEST_SCENARIO: 3 tasks in a 2-hour window should be spaced 1 hour apart.
@@ -22,6 +25,10 @@ def test_calculate_schedule_even_distribution():
assert schedule[1] == datetime(2024, 1, 1, 2, 0)
assert schedule[2] == datetime(2024, 1, 1, 3, 0)
# [/DEF:test_calculate_schedule_even_distribution:Function]
# [DEF:test_calculate_schedule_midnight_crossing:Function]
# @RELATION: BINDS_TO -> test_throttled_scheduler
def test_calculate_schedule_midnight_crossing():
"""
@TEST_SCENARIO: Window from 23:00 to 01:00 (next day).
@@ -38,6 +45,10 @@ def test_calculate_schedule_midnight_crossing():
assert schedule[1] == datetime(2024, 1, 2, 0, 0)
assert schedule[2] == datetime(2024, 1, 2, 1, 0)
# [/DEF:test_calculate_schedule_midnight_crossing:Function]
# [DEF:test_calculate_schedule_single_task:Function]
# @RELATION: BINDS_TO -> test_throttled_scheduler
def test_calculate_schedule_single_task():
"""
@TEST_SCENARIO: Single task should be scheduled at start time.
@@ -52,6 +63,10 @@ def test_calculate_schedule_single_task():
assert len(schedule) == 1
assert schedule[0] == datetime(2024, 1, 1, 1, 0)
# [/DEF:test_calculate_schedule_single_task:Function]
# [DEF:test_calculate_schedule_empty_list:Function]
# @RELATION: BINDS_TO -> test_throttled_scheduler
def test_calculate_schedule_empty_list():
"""
@TEST_SCENARIO: Empty dashboard list returns empty schedule.
@@ -65,6 +80,10 @@ def test_calculate_schedule_empty_list():
assert schedule == []
# [/DEF:test_calculate_schedule_empty_list:Function]
# [DEF:test_calculate_schedule_zero_window:Function]
# @RELATION: BINDS_TO -> test_throttled_scheduler
def test_calculate_schedule_zero_window():
"""
@TEST_SCENARIO: Window start == end. All tasks at start time.
@@ -80,6 +99,10 @@ def test_calculate_schedule_zero_window():
assert schedule[0] == datetime(2024, 1, 1, 1, 0)
assert schedule[1] == datetime(2024, 1, 1, 1, 0)
# [/DEF:test_calculate_schedule_zero_window:Function]
# [DEF:test_calculate_schedule_very_small_window:Function]
# @RELATION: BINDS_TO -> test_throttled_scheduler
def test_calculate_schedule_very_small_window():
"""
@TEST_SCENARIO: Window smaller than number of tasks (in seconds).
@@ -96,4 +119,4 @@ def test_calculate_schedule_very_small_window():
assert schedule[1] == datetime(2024, 1, 1, 1, 0, 0, 500000) # 0.5s
assert schedule[2] == datetime(2024, 1, 1, 1, 0, 1)
# [/DEF:test_throttled_scheduler:Module]
# [/DEF:test_throttled_scheduler:Module]# [/DEF:test_calculate_schedule_very_small_window:Function]

19
backend/src/core/async_superset_client.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.core.async_superset_client:Module]
# [DEF:AsyncSupersetClientModule:Module]
#
# @COMPLEXITY: 5
# @SEMANTICS: superset, async, client, httpx, dashboards, datasets
@@ -8,8 +8,8 @@
# @POST: Provides non-blocking API access to Superset resources.
# @SIDE_EFFECT: Performs network I/O via httpx.
# @DATA_CONTRACT: Input[Environment] -> Model[dashboard, chart, dataset]
# @RELATION: [DEPENDS_ON] ->[backend.src.core.superset_client]
# @RELATION: [DEPENDS_ON] ->[backend.src.core.utils.async_network.AsyncAPIClient]
# @RELATION: [DEPENDS_ON] ->[SupersetClientModule]
# @RELATION: [DEPENDS_ON] ->[AsyncAPIClient]
# @INVARIANT: Async dashboard operations reuse shared auth cache and avoid sync requests in async routes.
# [SECTION: IMPORTS]
@@ -25,12 +25,12 @@ from .utils.async_network import AsyncAPIClient
# [/SECTION]
# [DEF:backend.src.core.async_superset_client.AsyncSupersetClient:Class]
# [DEF:AsyncSupersetClient:Class]
# @COMPLEXITY: 3
# @PURPOSE: Async sibling of SupersetClient for dashboard read paths.
# @RELATION: [INHERITS] ->[backend.src.core.superset_client.SupersetClient]
# @RELATION: [DEPENDS_ON] ->[backend.src.core.utils.async_network.AsyncAPIClient]
# @RELATION: [CALLS] ->[backend.src.core.utils.async_network.AsyncAPIClient.request]
# @RELATION: [INHERITS] ->[SupersetClient]
# @RELATION: [DEPENDS_ON] ->[AsyncAPIClient]
# @RELATION: [CALLS] ->[AsyncAPIClient.request]
class AsyncSupersetClient(SupersetClient):
# [DEF:AsyncSupersetClientInit:Function]
# @COMPLEXITY: 3
@@ -67,11 +67,12 @@ class AsyncSupersetClient(SupersetClient):
# [/DEF:AsyncSupersetClientClose:Function]
# [DEF:backend.src.core.async_superset_client.AsyncSupersetClient.get_dashboards_page_async:Function]
# [DEF:get_dashboards_page_async:Function]
# @COMPLEXITY: 3
# @PURPOSE: Fetch one dashboards page asynchronously.
# @POST: Returns total count and page result list.
# @DATA_CONTRACT: Input[query: Optional[Dict]] -> Output[Tuple[int, List[Dict]]]
# @RELATION: [CALLS] -> [AsyncAPIClient.request]
async def get_dashboards_page_async(
self, query: Optional[Dict] = None
) -> Tuple[int, List[Dict]]:
@@ -687,4 +688,4 @@ class AsyncSupersetClient(SupersetClient):
# [/DEF:AsyncSupersetClient:Class]
# [/DEF:backend.src.core.async_superset_client:Module]
# [/DEF:AsyncSupersetClientModule:Module]

4
backend/src/core/auth/__init__.py
View File

@@ -1,3 +1,3 @@
# [DEF:src.core.auth:Package]
# [DEF:AuthPackage:Package]
# @PURPOSE: Authentication and authorization package root.
# [/DEF:src.core.auth:Package]
# [/DEF:AuthPackage:Package]

95
backend/src/core/auth/__tests__/test_auth.py
View File

@@ -2,7 +2,7 @@
# @COMPLEXITY: 3
# @PURPOSE: Unit tests for authentication module
# @LAYER: Domain
# @RELATION: VERIFIES -> src.core.auth
# @RELATION: VERIFIES -> AuthPackage
import sys
from pathlib import Path
@@ -14,6 +14,7 @@ import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from src.core.database import Base
# Import all models to ensure they are registered with Base before create_all - must import both auth and mapping to ensure Base knows about all tables
from src.models import mapping, auth, task, report
from src.models.auth import User, Role, Permission, ADGroupMapping
@@ -24,7 +25,9 @@ from src.core.auth.security import verify_password, get_password_hash
# Create in-memory SQLite database for testing
SQLALCHEMY_DATABASE_URL = "sqlite:///:memory:"
engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False})
engine = create_engine(
SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False}
)
TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
# Create all tables
@@ -55,13 +58,16 @@ def auth_repo(db_session):
return AuthRepository(db_session)
# [DEF:test_create_user:Function]
# @PURPOSE: Verifies that a persisted user can be retrieved with intact credential hash.
# @RELATION: BINDS_TO -> test_auth
def test_create_user(auth_repo):
"""Test user creation"""
user = User(
username="testuser",
email="test@example.com",
password_hash=get_password_hash("testpassword123"),
auth_source="LOCAL"
auth_source="LOCAL",
)
auth_repo.db.add(user)
@@ -74,13 +80,19 @@ def test_create_user(auth_repo):
assert verify_password("testpassword123", retrieved_user.password_hash)
# [/DEF:test_create_user:Function]
# [DEF:test_authenticate_user:Function]
# @PURPOSE: Validates authentication outcomes for valid, wrong-password, and unknown-user cases.
# @RELATION: BINDS_TO -> test_auth
def test_authenticate_user(auth_service, auth_repo):
"""Test user authentication with valid and invalid credentials"""
user = User(
username="testuser",
email="test@example.com",
password_hash=get_password_hash("testpassword123"),
auth_source="LOCAL"
auth_source="LOCAL",
)
auth_repo.db.add(user)
@@ -100,13 +112,19 @@ def test_authenticate_user(auth_service, auth_repo):
assert invalid_user is None
# [/DEF:test_authenticate_user:Function]
# [DEF:test_create_session:Function]
# @PURPOSE: Ensures session creation returns bearer token payload fields.
# @RELATION: BINDS_TO -> test_auth
def test_create_session(auth_service, auth_repo):
"""Test session token creation"""
user = User(
username="testuser",
email="test@example.com",
password_hash=get_password_hash("testpassword123"),
auth_source="LOCAL"
auth_source="LOCAL",
)
auth_repo.db.add(user)
@@ -119,6 +137,12 @@ def test_create_session(auth_service, auth_repo):
assert len(session["access_token"]) > 0
# [/DEF:test_create_session:Function]
# [DEF:test_role_permission_association:Function]
# @PURPOSE: Confirms role-permission many-to-many assignments persist and reload correctly.
# @RELATION: BINDS_TO -> test_auth
def test_role_permission_association(auth_repo):
"""Test role and permission association"""
role = Role(name="Admin", description="System administrator")
@@ -139,6 +163,12 @@ def test_role_permission_association(auth_repo):
assert "admin:users:WRITE" in permissions
# [/DEF:test_role_permission_association:Function]
# [DEF:test_user_role_association:Function]
# @PURPOSE: Confirms user-role assignment persists and is queryable from repository reads.
# @RELATION: BINDS_TO -> test_auth
def test_user_role_association(auth_repo):
"""Test user and role association"""
role = Role(name="Admin", description="System administrator")
@@ -146,7 +176,7 @@ def test_user_role_association(auth_repo):
username="adminuser",
email="admin@example.com",
password_hash=get_password_hash("adminpass123"),
auth_source="LOCAL"
auth_source="LOCAL",
)
user.roles.append(role)
@@ -161,6 +191,12 @@ def test_user_role_association(auth_repo):
assert retrieved_user.roles[0].name == "Admin"
# [/DEF:test_user_role_association:Function]
# [DEF:test_ad_group_mapping:Function]
# @PURPOSE: Verifies AD group mapping rows persist and reference the expected role.
# @RELATION: BINDS_TO -> test_auth
def test_ad_group_mapping(auth_repo):
"""Test AD group mapping"""
role = Role(name="ADFS_Admin", description="ADFS administrators")
@@ -173,18 +209,28 @@ def test_ad_group_mapping(auth_repo):
auth_repo.db.add(mapping)
auth_repo.db.commit()
retrieved_mapping = auth_repo.db.query(ADGroupMapping).filter_by(ad_group="DOMAIN\\ADFS_Admins").first()
retrieved_mapping = (
auth_repo.db.query(ADGroupMapping)
.filter_by(ad_group="DOMAIN\\ADFS_Admins")
.first()
)
assert retrieved_mapping is not None
assert retrieved_mapping.role_id == role.id
# [/DEF:test_ad_group_mapping:Function]
# [DEF:test_authenticate_user_updates_last_login:Function]
# @PURPOSE: Verifies successful authentication updates last_login audit field.
# @RELATION: BINDS_TO -> test_auth
def test_authenticate_user_updates_last_login(auth_service, auth_repo):
"""@SIDE_EFFECT: authenticate_user updates last_login timestamp on success."""
user = User(
username="loginuser",
email="login@example.com",
password_hash=get_password_hash("mypassword"),
auth_source="LOCAL"
auth_source="LOCAL",
)
auth_repo.db.add(user)
auth_repo.db.commit()
@@ -196,6 +242,12 @@ def test_authenticate_user_updates_last_login(auth_service, auth_repo):
assert authenticated.last_login is not None
# [/DEF:test_authenticate_user_updates_last_login:Function]
# [DEF:test_authenticate_inactive_user:Function]
# @PURPOSE: Verifies inactive accounts are rejected during password authentication.
# @RELATION: BINDS_TO -> test_auth
def test_authenticate_inactive_user(auth_service, auth_repo):
"""@PRE: User with is_active=False should not authenticate."""
user = User(
@@ -203,7 +255,7 @@ def test_authenticate_inactive_user(auth_service, auth_repo):
email="inactive@example.com",
password_hash=get_password_hash("testpass"),
auth_source="LOCAL",
is_active=False
is_active=False,
)
auth_repo.db.add(user)
auth_repo.db.commit()
@@ -212,12 +264,24 @@ def test_authenticate_inactive_user(auth_service, auth_repo):
assert result is None
# [/DEF:test_authenticate_inactive_user:Function]
# [DEF:test_verify_password_empty_hash:Function]
# @PURPOSE: Verifies password verification safely rejects empty or null password hashes.
# @RELATION: BINDS_TO -> test_auth
def test_verify_password_empty_hash():
"""@PRE: verify_password with empty/None hash returns False."""
assert verify_password("anypassword", "") is False
assert verify_password("anypassword", None) is False
# [/DEF:test_verify_password_empty_hash:Function]
# [DEF:test_provision_adfs_user_new:Function]
# @PURPOSE: Verifies JIT provisioning creates a new ADFS user and maps group-derived roles.
# @RELATION: BINDS_TO -> test_auth
def test_provision_adfs_user_new(auth_service, auth_repo):
"""@POST: provision_adfs_user creates a new ADFS user with correct roles."""
# Set up a role and AD group mapping
@@ -232,7 +296,7 @@ def test_provision_adfs_user_new(auth_service, auth_repo):
user_info = {
"upn": "newadfsuser@domain.com",
"email": "newadfsuser@domain.com",
"groups": ["DOMAIN\\Viewers"]
"groups": ["DOMAIN\\Viewers"],
}
user = auth_service.provision_adfs_user(user_info)
@@ -244,6 +308,12 @@ def test_provision_adfs_user_new(auth_service, auth_repo):
assert user.roles[0].name == "ADFS_Viewer"
# [/DEF:test_provision_adfs_user_new:Function]
# [DEF:test_provision_adfs_user_existing:Function]
# @PURPOSE: Verifies JIT provisioning reuses existing ADFS user and refreshes role assignments.
# @RELATION: BINDS_TO -> test_auth
def test_provision_adfs_user_existing(auth_service, auth_repo):
"""@POST: provision_adfs_user updates roles for existing user."""
# Create existing user
@@ -251,7 +321,7 @@ def test_provision_adfs_user_existing(auth_service, auth_repo):
username="existingadfs@domain.com",
email="existingadfs@domain.com",
auth_source="ADFS",
is_active=True
is_active=True,
)
auth_repo.db.add(existing)
auth_repo.db.commit()
@@ -259,7 +329,7 @@ def test_provision_adfs_user_existing(auth_service, auth_repo):
user_info = {
"upn": "existingadfs@domain.com",
"email": "existingadfs@domain.com",
"groups": []
"groups": [],
}
user = auth_service.provision_adfs_user(user_info)
@@ -269,3 +339,4 @@ def test_provision_adfs_user_existing(auth_service, auth_repo):
# [/DEF:test_auth:Module]
# [/DEF:test_provision_adfs_user_existing:Function]

6
backend/src/core/auth/config.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.core.auth.config:Module]
# [DEF:AuthConfigModule:Module]
#
# @SEMANTICS: auth, config, settings, jwt, adfs
# @PURPOSE: Centralized configuration for authentication and authorization.
@@ -16,6 +16,7 @@ from pydantic_settings import BaseSettings
# @PURPOSE: Holds authentication-related settings.
# @PRE: Environment variables may be provided via .env file.
# @POST: Returns a configuration object with validated settings.
# @RELATION: INHERITS -> pydantic_settings.BaseSettings
class AuthConfig(BaseSettings):
# JWT Settings
SECRET_KEY: str = Field(default="super-secret-key-change-in-production", env="AUTH_SECRET_KEY")
@@ -41,7 +42,8 @@ class AuthConfig(BaseSettings):
# [DEF:auth_config:Variable]
# @PURPOSE: Singleton instance of AuthConfig.
# @RELATION: DEPENDS_ON -> AuthConfig
auth_config = AuthConfig()
# [/DEF:auth_config:Variable]
# [/DEF:backend.src.core.auth.config:Module]
# [/DEF:AuthConfigModule:Module]

8
backend/src/core/auth/jwt.py
View File

@@ -1,11 +1,11 @@
# [DEF:backend.src.core.auth.jwt:Module]
# [DEF:AuthJwtModule:Module]
#
# @COMPLEXITY: 3
# @SEMANTICS: jwt, token, session, auth
# @PURPOSE: JWT token generation and validation logic.
# @LAYER: Core
# @RELATION: DEPENDS_ON -> jose
# @RELATION: USES -> backend.src.core.auth.config.auth_config
# @RELATION: USES -> auth_config
#
# @INVARIANT: Tokens must include expiration time and user identifier.
@@ -21,6 +21,7 @@ from ..logger import belief_scope
# @PURPOSE: Generates a new JWT access token.
# @PRE: data dict contains 'sub' (user_id) and optional 'scopes' (roles).
# @POST: Returns a signed JWT string.
# @RELATION: DEPENDS_ON -> auth_config
#
# @PARAM: data (dict) - Payload data for the token.
# @PARAM: expires_delta (Optional[timedelta]) - Custom expiration time.
@@ -42,6 +43,7 @@ def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -
# @PURPOSE: Decodes and validates a JWT token.
# @PRE: token is a signed JWT string.
# @POST: Returns the decoded payload if valid.
# @RELATION: DEPENDS_ON -> auth_config
#
# @PARAM: token (str) - The JWT to decode.
# @RETURN: dict - The decoded payload.
@@ -52,4 +54,4 @@ def decode_token(token: str) -> dict:
return payload
# [/DEF:decode_token:Function]
# [/DEF:backend.src.core.auth.jwt:Module]
# [/DEF:AuthJwtModule:Module]

7
backend/src/core/auth/logger.py
View File

@@ -1,10 +1,10 @@
# [DEF:backend.src.core.auth.logger:Module]
# [DEF:AuthLoggerModule:Module]
#
# @COMPLEXITY: 3
# @SEMANTICS: auth, logger, audit, security
# @PURPOSE: Audit logging for security-related events.
# @LAYER: Core
# @RELATION: USES -> backend.src.core.logger.belief_scope
# @RELATION: USES -> belief_scope
#
# @INVARIANT: Must not log sensitive data like passwords or full tokens.
@@ -17,6 +17,7 @@ from datetime import datetime
# @PURPOSE: Logs a security-related event for audit trails.
# @PRE: event_type and username are strings.
# @POST: Security event is written to the application log.
# @RELATION: USES -> logger
# @PARAM: event_type (str) - Type of event (e.g., LOGIN_SUCCESS, PERMISSION_DENIED).
# @PARAM: username (str) - The user involved in the event.
# @PARAM: details (dict) - Additional non-sensitive metadata.
@@ -29,4 +30,4 @@ def log_security_event(event_type: str, username: str, details: dict = None):
logger.info(msg)
# [/DEF:log_security_event:Function]
# [/DEF:backend.src.core.auth.logger:Module]
# [/DEF:AuthLoggerModule:Module]

10
backend/src/core/auth/oauth.py
View File

@@ -1,10 +1,10 @@
# [DEF:backend.src.core.auth.oauth:Module]
# [DEF:AuthOauthModule:Module]
#
# @SEMANTICS: auth, oauth, oidc, adfs
# @PURPOSE: ADFS OIDC configuration and client using Authlib.
# @LAYER: Core
# @RELATION: DEPENDS_ON -> authlib
# @RELATION: USES -> backend.src.core.auth.config.auth_config
# @RELATION: USES -> auth_config
#
# @INVARIANT: Must use secure OIDC flows.
@@ -15,6 +15,7 @@ from .config import auth_config
# [DEF:oauth:Variable]
# @PURPOSE: Global Authlib OAuth registry.
# @RELATION: DEPENDS_ON -> OAuth
oauth = OAuth()
# [/DEF:oauth:Variable]
@@ -22,6 +23,8 @@ oauth = OAuth()
# @PURPOSE: Registers the ADFS OIDC client.
# @PRE: ADFS configuration is provided in auth_config.
# @POST: ADFS client is registered in oauth registry.
# @RELATION: USES -> oauth
# @RELATION: USES -> auth_config
def register_adfs():
if auth_config.ADFS_CLIENT_ID:
oauth.register(
@@ -39,6 +42,7 @@ def register_adfs():
# @PURPOSE: Checks if ADFS is properly configured.
# @PRE: None.
# @POST: Returns True if ADFS client is registered, False otherwise.
# @RELATION: USES -> oauth
# @RETURN: bool - Configuration status.
def is_adfs_configured() -> bool:
"""Check if ADFS OAuth client is registered."""
@@ -48,4 +52,4 @@ def is_adfs_configured() -> bool:
# Initial registration
register_adfs()
# [/DEF:backend.src.core.auth.oauth:Module]
# [/DEF:AuthOauthModule:Module]

22
backend/src/core/auth/repository.py
View File

@@ -1,4 +1,4 @@
# [DEF:AuthRepository:Module]
# [DEF:AuthRepositoryModule:Module]
# @TIER: CRITICAL
# @COMPLEXITY: 5
# @SEMANTICS: auth, repository, database, user, role, permission
@@ -12,6 +12,9 @@
# @RELATION: DEPENDS_ON ->[belief_scope:Function]
# @INVARIANT: All database read/write operations must execute via the injected SQLAlchemy session boundary.
# @DATA_CONTRACT: Session -> [User | Role | Permission | UserDashboardPreference]
# @PRE: Database connection is active.
# @POST: Provides valid access to identity data.
# @SIDE_EFFECT: None at module level.
# [SECTION: IMPORTS]
from typing import List, Optional
@@ -23,6 +26,10 @@ from ..logger import belief_scope, logger
# [DEF:AuthRepository:Class]
# @PURPOSE: Provides low-level CRUD operations for identity and authorization records.
# @PRE: Database session is bound.
# @POST: Entity instances returned safely.
# @SIDE_EFFECT: Performs database reads.
# @RELATION: DEPENDS_ON -> sqlalchemy.orm.Session
class AuthRepository:
# @PURPOSE: Initialize repository with database session.
def __init__(self, db: Session):
@@ -32,6 +39,7 @@ class AuthRepository:
# @PURPOSE: Retrieve user by UUID.
# @PRE: user_id is a valid UUID string.
# @POST: Returns User object if found, else None.
# @RELATION: DEPENDS_ON -> User
def get_user_by_id(self, user_id: str) -> Optional[User]:
with belief_scope("AuthRepository.get_user_by_id"):
logger.reason(f"Fetching user by id: {user_id}")
@@ -44,6 +52,7 @@ class AuthRepository:
# @PURPOSE: Retrieve user by username.
# @PRE: username is a non-empty string.
# @POST: Returns User object if found, else None.
# @RELATION: DEPENDS_ON -> User
def get_user_by_username(self, username: str) -> Optional[User]:
with belief_scope("AuthRepository.get_user_by_username"):
logger.reason(f"Fetching user by username: {username}")
@@ -54,6 +63,8 @@ class AuthRepository:
# [DEF:get_role_by_id:Function]
# @PURPOSE: Retrieve role by UUID with permissions preloaded.
# @RELATION: DEPENDS_ON -> Role
# @RELATION: DEPENDS_ON -> Permission
def get_role_by_id(self, role_id: str) -> Optional[Role]:
with belief_scope("AuthRepository.get_role_by_id"):
return self.db.query(Role).options(selectinload(Role.permissions)).filter(Role.id == role_id).first()
@@ -61,6 +72,7 @@ class AuthRepository:
# [DEF:get_role_by_name:Function]
# @PURPOSE: Retrieve role by unique name.
# @RELATION: DEPENDS_ON -> Role
def get_role_by_name(self, name: str) -> Optional[Role]:
with belief_scope("AuthRepository.get_role_by_name"):
return self.db.query(Role).filter(Role.name == name).first()
@@ -68,6 +80,7 @@ class AuthRepository:
# [DEF:get_permission_by_id:Function]
# @PURPOSE: Retrieve permission by UUID.
# @RELATION: DEPENDS_ON -> Permission
def get_permission_by_id(self, permission_id: str) -> Optional[Permission]:
with belief_scope("AuthRepository.get_permission_by_id"):
return self.db.query(Permission).filter(Permission.id == permission_id).first()
@@ -75,6 +88,7 @@ class AuthRepository:
# [DEF:get_permission_by_resource_action:Function]
# @PURPOSE: Retrieve permission by resource and action tuple.
# @RELATION: DEPENDS_ON -> Permission
def get_permission_by_resource_action(self, resource: str, action: str) -> Optional[Permission]:
with belief_scope("AuthRepository.get_permission_by_resource_action"):
return self.db.query(Permission).filter(
@@ -85,6 +99,7 @@ class AuthRepository:
# [DEF:list_permissions:Function]
# @PURPOSE: List all system permissions.
# @RELATION: DEPENDS_ON -> Permission
def list_permissions(self) -> List[Permission]:
with belief_scope("AuthRepository.list_permissions"):
return self.db.query(Permission).all()
@@ -92,6 +107,7 @@ class AuthRepository:
# [DEF:get_user_dashboard_preference:Function]
# @PURPOSE: Retrieve dashboard filters/preferences for a user.
# @RELATION: DEPENDS_ON -> UserDashboardPreference
def get_user_dashboard_preference(self, user_id: str) -> Optional[UserDashboardPreference]:
with belief_scope("AuthRepository.get_user_dashboard_preference"):
return self.db.query(UserDashboardPreference).filter(
@@ -103,6 +119,8 @@ class AuthRepository:
# @PURPOSE: Retrieve roles that match a list of AD group names.
# @PRE: groups is a list of strings representing AD group identifiers.
# @POST: Returns a list of Role objects mapped to the provided AD groups.
# @RELATION: DEPENDS_ON -> Role
# @RELATION: DEPENDS_ON -> ADGroupMapping
def get_roles_by_ad_groups(self, groups: List[str]) -> List[Role]:
with belief_scope("AuthRepository.get_roles_by_ad_groups"):
logger.reason(f"Fetching roles for AD groups: {groups}")
@@ -115,4 +133,4 @@ class AuthRepository:
# [/DEF:AuthRepository:Class]
# [/DEF:AuthRepository:Module]
# [/DEF:AuthRepositoryModule:Module]

8
backend/src/core/auth/security.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.src.core.auth.security:Module]
# [DEF:AuthSecurityModule:Module]
#
# @SEMANTICS: security, password, hashing, bcrypt
# @PURPOSE: Utility for password hashing and verification using Passlib.
# @LAYER: Core
# @RELATION: DEPENDS_ON -> passlib
# @RELATION: DEPENDS_ON -> bcrypt
#
# @INVARIANT: Uses bcrypt for hashing with standard work factor.
@@ -15,6 +15,7 @@ import bcrypt
# @PURPOSE: Verifies a plain password against a hashed password.
# @PRE: plain_password is a string, hashed_password is a bcrypt hash.
# @POST: Returns True if password matches, False otherwise.
# @RELATION: DEPENDS_ON -> bcrypt
#
# @PARAM: plain_password (str) - The unhashed password.
# @PARAM: hashed_password (str) - The stored hash.
@@ -35,6 +36,7 @@ def verify_password(plain_password: str, hashed_password: str) -> bool:
# @PURPOSE: Generates a bcrypt hash for a plain password.
# @PRE: password is a string.
# @POST: Returns a secure bcrypt hash string.
# @RELATION: DEPENDS_ON -> bcrypt
#
# @PARAM: password (str) - The password to hash.
# @RETURN: str - The generated hash.
@@ -42,4 +44,4 @@ def get_password_hash(password: str) -> str:
return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
# [/DEF:get_password_hash:Function]
# [/DEF:backend.src.core.auth.security:Module]
# [/DEF:AuthSecurityModule:Module]

160
backend/src/core/config_manager.py
View File

@@ -45,7 +45,9 @@ class ConfigManager:
def __init__(self, config_path: str = "config.json"):
with belief_scope("ConfigManager.__init__"):
if not isinstance(config_path, str) or not config_path:
logger.explore("Invalid config_path provided", extra={"path": config_path})
logger.explore(
"Invalid config_path provided", extra={"path": config_path}
)
raise ValueError("config_path must be a non-empty string")
logger.reason(f"Initializing ConfigManager with legacy path: {config_path}")
@@ -57,10 +59,14 @@ class ConfigManager:
configure_logger(self.config.settings.logging)
if not isinstance(self.config, AppConfig):
logger.explore("Config loading resulted in invalid type", extra={"type": type(self.config)})
logger.explore(
"Config loading resulted in invalid type",
extra={"type": type(self.config)},
)
raise TypeError("self.config must be an instance of AppConfig")
logger.reflect("ConfigManager initialization complete")
# [/DEF:__init__:Function]
# [DEF:_default_config:Function]
@@ -69,6 +75,7 @@ class ConfigManager:
with belief_scope("ConfigManager._default_config"):
logger.reason("Building default AppConfig fallback")
return AppConfig(environments=[], settings=GlobalSettings())
# [/DEF:_default_config:Function]
# [DEF:_sync_raw_payload_from_config:Function]
@@ -83,14 +90,19 @@ class ConfigManager:
logger.reason(
"Synchronized raw payload from typed config",
extra={
"environments_count": len(merged_payload.get("environments", []) or []),
"environments_count": len(
merged_payload.get("environments", []) or []
),
"has_settings": "settings" in merged_payload,
"extra_sections": sorted(
key for key in merged_payload.keys() if key not in {"environments", "settings"}
key
for key in merged_payload.keys()
if key not in {"environments", "settings"}
),
},
)
return merged_payload
# [/DEF:_sync_raw_payload_from_config:Function]
# [DEF:_load_from_legacy_file:Function]
@@ -104,14 +116,19 @@ class ConfigManager:
)
return {}
logger.reason("Loading legacy config file", extra={"path": str(self.config_path)})
logger.reason(
"Loading legacy config file", extra={"path": str(self.config_path)}
)
with self.config_path.open("r", encoding="utf-8") as fh:
payload = json.load(fh)
if not isinstance(payload, dict):
logger.explore(
"Legacy config payload is not a JSON object",
extra={"path": str(self.config_path), "type": type(payload).__name__},
extra={
"path": str(self.config_path),
"type": type(payload).__name__,
},
)
raise ValueError("Legacy config payload must be a JSON object")
@@ -120,15 +137,23 @@ class ConfigManager:
extra={"path": str(self.config_path), "keys": sorted(payload.keys())},
)
return payload
# [/DEF:_load_from_legacy_file:Function]
# [DEF:_get_record:Function]
# @PURPOSE: Resolve global configuration record from DB.
def _get_record(self, session: Session) -> Optional[AppConfigRecord]:
with belief_scope("ConfigManager._get_record"):
record = session.query(AppConfigRecord).filter(AppConfigRecord.id == "global").first()
logger.reason("Resolved app config record", extra={"exists": record is not None})
record = (
session.query(AppConfigRecord)
.filter(AppConfigRecord.id == "global")
.first()
)
logger.reason(
"Resolved app config record", extra={"exists": record is not None}
)
return record
# [/DEF:_get_record:Function]
# [DEF:_load_config:Function]
@@ -139,7 +164,10 @@ class ConfigManager:
try:
record = self._get_record(session)
if record and isinstance(record.payload, dict):
logger.reason("Loading configuration from database", extra={"record_id": record.id})
logger.reason(
"Loading configuration from database",
extra={"record_id": record.id},
)
self.raw_payload = dict(record.payload)
config = AppConfig.model_validate(
{
@@ -182,7 +210,9 @@ class ConfigManager:
self._save_config_to_db(config, session=session)
return config
logger.reason("No persisted config found; falling back to default configuration")
logger.reason(
"No persisted config found; falling back to default configuration"
)
config = self._default_config()
self.raw_payload = config.model_dump()
self._save_config_to_db(config, session=session)
@@ -203,6 +233,7 @@ class ConfigManager:
raise
finally:
session.close()
# [/DEF:_load_config:Function]
# [DEF:_sync_environment_records:Function]
@@ -210,29 +241,32 @@ class ConfigManager:
def _sync_environment_records(self, session: Session, config: AppConfig) -> None:
with belief_scope("ConfigManager._sync_environment_records"):
configured_envs = list(config.environments or [])
configured_ids = {
str(environment.id or "").strip()
for environment in configured_envs
if str(environment.id or "").strip()
}
persisted_records = session.query(EnvironmentRecord).all()
persisted_by_id = {str(record.id or "").strip(): record for record in persisted_records}
persisted_by_id = {
str(record.id or "").strip(): record for record in persisted_records
}
for environment in configured_envs:
normalized_id = str(environment.id or "").strip()
if not normalized_id:
continue
display_name = str(environment.name or normalized_id).strip() or normalized_id
display_name = (
str(environment.name or normalized_id).strip() or normalized_id
)
normalized_url = str(environment.url or "").strip()
credentials_id = str(environment.username or "").strip() or normalized_id
credentials_id = (
str(environment.username or "").strip() or normalized_id
)
record = persisted_by_id.get(normalized_id)
if record is None:
logger.reason(
"Creating relational environment record from typed config",
extra={"environment_id": normalized_id, "environment_name": display_name},
extra={
"environment_id": normalized_id,
"environment_name": display_name,
},
)
session.add(
EnvironmentRecord(
@@ -248,20 +282,13 @@ class ConfigManager:
record.url = normalized_url
record.credentials_id = credentials_id
for record in persisted_records:
normalized_id = str(record.id or "").strip()
if normalized_id and normalized_id not in configured_ids:
logger.reason(
"Removing stale relational environment record absent from typed config",
extra={"environment_id": normalized_id},
)
session.delete(record)
# [/DEF:_sync_environment_records:Function]
# [DEF:_save_config_to_db:Function]
# @PURPOSE: Persist provided AppConfig into the global DB configuration record.
def _save_config_to_db(self, config: AppConfig, session: Optional[Session] = None) -> None:
def _save_config_to_db(
self, config: AppConfig, session: Optional[Session] = None
) -> None:
with belief_scope("ConfigManager._save_config_to_db"):
owns_session = session is None
db = session or SessionLocal()
@@ -274,7 +301,10 @@ class ConfigManager:
record = AppConfigRecord(id="global", payload=payload)
db.add(record)
else:
logger.reason("Updating existing global app config record", extra={"record_id": record.id})
logger.reason(
"Updating existing global app config record",
extra={"record_id": record.id},
)
record.payload = payload
self._sync_environment_records(db, config)
@@ -283,7 +313,9 @@ class ConfigManager:
logger.reason(
"Configuration persisted to database",
extra={
"environments_count": len(payload.get("environments", []) or []),
"environments_count": len(
payload.get("environments", []) or []
),
"payload_keys": sorted(payload.keys()),
},
)
@@ -294,6 +326,7 @@ class ConfigManager:
finally:
if owns_session:
db.close()
# [/DEF:_save_config_to_db:Function]
# [DEF:save:Function]
@@ -302,6 +335,7 @@ class ConfigManager:
with belief_scope("ConfigManager.save"):
logger.reason("Persisting current in-memory configuration")
self._save_config_to_db(self.config)
# [/DEF:save:Function]
# [DEF:get_config:Function]
@@ -309,6 +343,7 @@ class ConfigManager:
def get_config(self) -> AppConfig:
with belief_scope("ConfigManager.get_config"):
return self.config
# [/DEF:get_config:Function]
# [DEF:get_payload:Function]
@@ -316,6 +351,7 @@ class ConfigManager:
def get_payload(self) -> dict[str, Any]:
with belief_scope("ConfigManager.get_payload"):
return self._sync_raw_payload_from_config()
# [/DEF:get_payload:Function]
# [DEF:save_config:Function]
@@ -345,8 +381,12 @@ class ConfigManager:
self._save_config_to_db(typed_config)
return self.config
logger.explore("Unsupported config type supplied to save_config", extra={"type": type(config).__name__})
logger.explore(
"Unsupported config type supplied to save_config",
extra={"type": type(config).__name__},
)
raise TypeError("config must be AppConfig or dict")
# [/DEF:save_config:Function]
# [DEF:update_global_settings:Function]
@@ -357,6 +397,7 @@ class ConfigManager:
self.config.settings = settings
self.save()
return self.config
# [/DEF:update_global_settings:Function]
# [DEF:validate_path:Function]
@@ -381,8 +422,11 @@ class ConfigManager:
logger.reason("Path validation succeeded", extra={"path": str(target)})
return True, "OK"
except Exception as exc:
logger.explore("Path validation failed", extra={"path": path, "error": str(exc)})
logger.explore(
"Path validation failed", extra={"path": path, "error": str(exc)}
)
return False, str(exc)
# [/DEF:validate_path:Function]
# [DEF:get_environments:Function]
@@ -390,6 +434,7 @@ class ConfigManager:
def get_environments(self) -> List[Environment]:
with belief_scope("ConfigManager.get_environments"):
return list(self.config.environments)
# [/DEF:get_environments:Function]
# [DEF:has_environments:Function]
@@ -397,6 +442,7 @@ class ConfigManager:
def has_environments(self) -> bool:
with belief_scope("ConfigManager.has_environments"):
return len(self.config.environments) > 0
# [/DEF:has_environments:Function]
# [DEF:get_environment:Function]
@@ -411,13 +457,21 @@ class ConfigManager:
if env.id == normalized or env.name == normalized:
return env
return None
# [/DEF:get_environment:Function]
# [DEF:add_environment:Function]
# @PURPOSE: Upsert environment by id into configuration and persist.
def add_environment(self, env: Environment) -> AppConfig:
with belief_scope("ConfigManager.add_environment", f"env_id={env.id}"):
existing_index = next((i for i, item in enumerate(self.config.environments) if item.id == env.id), None)
existing_index = next(
(
i
for i, item in enumerate(self.config.environments)
if item.id == env.id
),
None,
)
if env.is_default:
for item in self.config.environments:
item.is_default = False
@@ -426,14 +480,20 @@ class ConfigManager:
logger.reason("Appending new environment", extra={"env_id": env.id})
self.config.environments.append(env)
else:
logger.reason("Replacing existing environment during add", extra={"env_id": env.id})
logger.reason(
"Replacing existing environment during add",
extra={"env_id": env.id},
)
self.config.environments[existing_index] = env
if len(self.config.environments) == 1 and not any(item.is_default for item in self.config.environments):
if len(self.config.environments) == 1 and not any(
item.is_default for item in self.config.environments
):
self.config.environments[0].is_default = True
self.save()
return self.config
# [/DEF:add_environment:Function]
# [DEF:update_environment:Function]
@@ -461,8 +521,11 @@ class ConfigManager:
self.save()
return True
logger.explore("Environment update skipped; env not found", extra={"env_id": env_id})
logger.explore(
"Environment update skipped; env not found", extra={"env_id": env_id}
)
return False
# [/DEF:update_environment:Function]
# [DEF:delete_environment:Function]
@@ -471,22 +534,35 @@ class ConfigManager:
with belief_scope("ConfigManager.delete_environment", f"env_id={env_id}"):
before = len(self.config.environments)
removed = [env for env in self.config.environments if env.id == env_id]
self.config.environments = [env for env in self.config.environments if env.id != env_id]
self.config.environments = [
env for env in self.config.environments if env.id != env_id
]
if len(self.config.environments) == before:
logger.explore("Environment delete skipped; env not found", extra={"env_id": env_id})
logger.explore(
"Environment delete skipped; env not found",
extra={"env_id": env_id},
)
return False
if removed and removed[0].is_default and self.config.environments:
self.config.environments[0].is_default = True
if self.config.settings.default_environment_id == env_id:
replacement = next((env.id for env in self.config.environments if env.is_default), None)
replacement = next(
(env.id for env in self.config.environments if env.is_default), None
)
self.config.settings.default_environment_id = replacement
logger.reason("Environment deleted", extra={"env_id": env_id, "remaining": len(self.config.environments)})
logger.reason(
"Environment deleted",
extra={"env_id": env_id, "remaining": len(self.config.environments)},
)
self.save()
return True
# [/DEF:delete_environment:Function]
# [/DEF:ConfigManager:Class]
# [/DEF:ConfigManager:Module]

10
backend/src/core/logger/__tests__/test_logger.py
View File

@@ -44,6 +44,7 @@ def reset_logger_state():
# [DEF:test_belief_scope_logs_entry_action_exit_at_debug:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test that belief_scope generates [ID][Entry], [ID][Action], and [ID][Exit] logs at DEBUG level.
# @PRE: belief_scope is available. caplog fixture is used. Logger configured to DEBUG.
# @POST: Logs are verified to contain Entry, Action, and Exit tags at DEBUG level.
@@ -76,6 +77,7 @@ def test_belief_scope_logs_entry_action_exit_at_debug(caplog):
# [DEF:test_belief_scope_error_handling:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test that belief_scope logs Coherence:Failed on exception.
# @PRE: belief_scope is available. caplog fixture is used. Logger configured to DEBUG.
# @POST: Logs are verified to contain Coherence:Failed tag.
@@ -108,6 +110,7 @@ def test_belief_scope_error_handling(caplog):
# [DEF:test_belief_scope_success_coherence:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test that belief_scope logs Coherence:OK on success.
# @PRE: belief_scope is available. caplog fixture is used. Logger configured to DEBUG.
# @POST: Logs are verified to contain Coherence:OK tag.
@@ -135,6 +138,7 @@ def test_belief_scope_success_coherence(caplog):
# [DEF:test_belief_scope_not_visible_at_info:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test that belief_scope Entry/Exit/Coherence logs are NOT visible at INFO level.
# @PRE: belief_scope is available. caplog fixture is used.
# @POST: Entry/Exit/Coherence logs are not captured at INFO level.
@@ -157,6 +161,7 @@ def test_belief_scope_not_visible_at_info(caplog):
# [DEF:test_task_log_level_default:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test that default task log level is INFO.
# @PRE: None.
# @POST: Default level is INFO.
@@ -168,6 +173,7 @@ def test_task_log_level_default():
# [DEF:test_should_log_task_level:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test that should_log_task_level correctly filters log levels.
# @PRE: None.
# @POST: Filtering works correctly for all level combinations.
@@ -182,6 +188,7 @@ def test_should_log_task_level():
# [DEF:test_configure_logger_task_log_level:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test that configure_logger updates task_log_level.
# @PRE: LoggingConfig is available.
# @POST: task_log_level is updated correctly.
@@ -200,6 +207,7 @@ def test_configure_logger_task_log_level():
# [DEF:test_enable_belief_state_flag:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test that enable_belief_state flag controls belief_scope logging.
# @PRE: LoggingConfig is available. caplog fixture is used.
# @POST: belief_scope logs are controlled by the flag.
@@ -229,6 +237,7 @@ def test_enable_belief_state_flag(caplog):
# [DEF:test_belief_scope_missing_anchor:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test @PRE condition: anchor_id must be provided
def test_belief_scope_missing_anchor():
"""Test that belief_scope enforces anchor_id to be provided."""
@@ -241,6 +250,7 @@ def test_belief_scope_missing_anchor():
# [/DEF:test_belief_scope_missing_anchor:Function]
# [DEF:test_configure_logger_post_conditions:Function]
# @RELATION: BINDS_TO -> test_logger
# @PURPOSE: Test @POST condition: Logger level, handlers, belief state flag, and task log level are updated.
def test_configure_logger_post_conditions(tmp_path):
"""Test that configure_logger satisfies all @POST conditions."""

29
backend/src/core/migration/archive_parser.py
View File

@@ -19,13 +19,17 @@ from ..logger import logger, belief_scope
# [DEF:MigrationArchiveParser:Class]
# @PURPOSE: Extract normalized dashboards/charts/datasets metadata from ZIP archives.
# @RELATION: CONTAINS -> [extract_objects_from_zip, _collect_yaml_objects, _normalize_object_payload]
class MigrationArchiveParser:
# [DEF:extract_objects_from_zip:Function]
# @PURPOSE: Extract object catalogs from Superset archive.
# @RELATION: DEPENDS_ON -> _collect_yaml_objects
# @PRE: zip_path points to a valid readable ZIP.
# @POST: Returns object lists grouped by resource type.
# @RETURN: Dict[str, List[Dict[str, Any]]]
def extract_objects_from_zip(self, zip_path: str) -> Dict[str, List[Dict[str, Any]]]:
def extract_objects_from_zip(
self, zip_path: str
) -> Dict[str, List[Dict[str, Any]]]:
with belief_scope("MigrationArchiveParser.extract_objects_from_zip"):
result: Dict[str, List[Dict[str, Any]]] = {
"dashboards": [],
@@ -37,20 +41,28 @@ class MigrationArchiveParser:
with zipfile.ZipFile(zip_path, "r") as zip_file:
zip_file.extractall(temp_dir)
result["dashboards"] = self._collect_yaml_objects(temp_dir, "dashboards")
result["dashboards"] = self._collect_yaml_objects(
temp_dir, "dashboards"
)
result["charts"] = self._collect_yaml_objects(temp_dir, "charts")
result["datasets"] = self._collect_yaml_objects(temp_dir, "datasets")
return result
# [/DEF:extract_objects_from_zip:Function]
# [DEF:_collect_yaml_objects:Function]
# @PURPOSE: Read and normalize YAML manifests for one object type.
# @RELATION: DEPENDS_ON -> _normalize_object_payload
# @PRE: object_type is one of dashboards/charts/datasets.
# @POST: Returns only valid normalized objects.
def _collect_yaml_objects(self, root_dir: Path, object_type: str) -> List[Dict[str, Any]]:
def _collect_yaml_objects(
self, root_dir: Path, object_type: str
) -> List[Dict[str, Any]]:
with belief_scope("MigrationArchiveParser._collect_yaml_objects"):
files = list(root_dir.glob(f"**/{object_type}/**/*.yaml")) + list(root_dir.glob(f"**/{object_type}/*.yaml"))
files = list(root_dir.glob(f"**/{object_type}/**/*.yaml")) + list(
root_dir.glob(f"**/{object_type}/*.yaml")
)
objects: List[Dict[str, Any]] = []
for file_path in set(files):
try:
@@ -66,13 +78,16 @@ class MigrationArchiveParser:
exc,
)
return objects
# [/DEF:_collect_yaml_objects:Function]
# [DEF:_normalize_object_payload:Function]
# @PURPOSE: Convert raw YAML payload to stable diff signature shape.
# @PRE: payload is parsed YAML mapping.
# @POST: Returns normalized descriptor with `uuid`, `title`, and `signature`.
def _normalize_object_payload(self, payload: Dict[str, Any], object_type: str) -> Optional[Dict[str, Any]]:
def _normalize_object_payload(
self, payload: Dict[str, Any], object_type: str
) -> Optional[Dict[str, Any]]:
with belief_scope("MigrationArchiveParser._normalize_object_payload"):
if not isinstance(payload, dict):
return None
@@ -111,7 +126,8 @@ class MigrationArchiveParser:
"uuid": str(uuid),
"title": title or f"Chart {uuid}",
"signature": json.dumps(signature, sort_keys=True, default=str),
"dataset_uuid": payload.get("datasource_uuid") or payload.get("dataset_uuid"),
"dataset_uuid": payload.get("datasource_uuid")
or payload.get("dataset_uuid"),
}
if object_type == "datasets":
@@ -132,6 +148,7 @@ class MigrationArchiveParser:
}
return None
# [/DEF:_normalize_object_payload:Function]

207
backend/src/core/migration/dry_run_orchestrator.py
View File

@@ -27,6 +27,7 @@ from ..utils.fileio import create_temp_file
# [DEF:MigrationDryRunService:Class]
# @PURPOSE: Build deterministic diff/risk payload for migration pre-flight.
# @RELATION: CONTAINS -> [__init__, run, _load_db_mapping, _accumulate_objects, _index_by_uuid, _build_object_diff, _build_target_signatures, _build_risks]
class MigrationDryRunService:
# [DEF:__init__:Function]
# @PURPOSE: Wire parser dependency for archive object extraction.
@@ -34,10 +35,12 @@ class MigrationDryRunService:
# @POST: Service is ready to calculate dry-run payload.
def __init__(self, parser: MigrationArchiveParser | None = None):
self.parser = parser or MigrationArchiveParser()
# [/DEF:__init__:Function]
# [DEF:run:Function]
# @PURPOSE: Execute full dry-run computation for selected dashboards.
# @RELATION: DEPENDS_ON -> [_load_db_mapping, _accumulate_objects, _build_target_signatures, _build_object_diff, _build_risks]
# @PRE: source/target clients are authenticated and selection validated by caller.
# @POST: Returns JSON-serializable pre-flight payload with summary, diff and risk.
# @SIDE_EFFECT: Reads source export archives and target metadata via network.
@@ -49,9 +52,15 @@ class MigrationDryRunService:
db: Session,
) -> Dict[str, Any]:
with belief_scope("MigrationDryRunService.run"):
logger.explore("[MigrationDryRunService.run][EXPLORE] starting dry-run pipeline")
logger.explore(
"[MigrationDryRunService.run][EXPLORE] starting dry-run pipeline"
)
engine = MigrationEngine()
db_mapping = self._load_db_mapping(db, selection) if selection.replace_db_config else {}
db_mapping = (
self._load_db_mapping(db, selection)
if selection.replace_db_config
else {}
)
transformed = {"dashboards": {}, "charts": {}, "datasets": {}}
dashboards_preview = source_client.get_dashboards_summary()
@@ -63,7 +72,9 @@ class MigrationDryRunService:
for dashboard_id in selection.selected_ids:
exported_content, _ = source_client.export_dashboard(int(dashboard_id))
with create_temp_file(content=exported_content, suffix=".zip") as source_zip:
with create_temp_file(
content=exported_content, suffix=".zip"
) as source_zip:
with create_temp_file(suffix=".zip") as transformed_zip:
success = engine.transform_zip(
str(source_zip),
@@ -74,23 +85,46 @@ class MigrationDryRunService:
fix_cross_filters=selection.fix_cross_filters,
)
if not success:
raise ValueError(f"Failed to transform export archive for dashboard {dashboard_id}")
extracted = self.parser.extract_objects_from_zip(str(transformed_zip))
raise ValueError(
f"Failed to transform export archive for dashboard {dashboard_id}"
)
extracted = self.parser.extract_objects_from_zip(
str(transformed_zip)
)
self._accumulate_objects(transformed, extracted)
source_objects = {key: list(value.values()) for key, value in transformed.items()}
source_objects = {
key: list(value.values()) for key, value in transformed.items()
}
target_objects = self._build_target_signatures(target_client)
diff = {
"dashboards": self._build_object_diff(source_objects["dashboards"], target_objects["dashboards"]),
"charts": self._build_object_diff(source_objects["charts"], target_objects["charts"]),
"datasets": self._build_object_diff(source_objects["datasets"], target_objects["datasets"]),
"dashboards": self._build_object_diff(
source_objects["dashboards"], target_objects["dashboards"]
),
"charts": self._build_object_diff(
source_objects["charts"], target_objects["charts"]
),
"datasets": self._build_object_diff(
source_objects["datasets"], target_objects["datasets"]
),
}
risk = self._build_risks(source_objects, target_objects, diff, target_client)
risk = self._build_risks(
source_objects, target_objects, diff, target_client
)
summary = {
"dashboards": {action: len(diff["dashboards"][action]) for action in ("create", "update", "delete")},
"charts": {action: len(diff["charts"][action]) for action in ("create", "update", "delete")},
"datasets": {action: len(diff["datasets"][action]) for action in ("create", "update", "delete")},
"dashboards": {
action: len(diff["dashboards"][action])
for action in ("create", "update", "delete")
},
"charts": {
action: len(diff["charts"][action])
for action in ("create", "update", "delete")
},
"datasets": {
action: len(diff["datasets"][action])
for action in ("create", "update", "delete")
},
"selected_dashboards": len(selection.selected_ids),
}
selected_titles = [
@@ -99,7 +133,9 @@ class MigrationDryRunService:
if dash_id in selected_preview
]
logger.reason("[MigrationDryRunService.run][REASON] dry-run payload assembled")
logger.reason(
"[MigrationDryRunService.run][REASON] dry-run payload assembled"
)
return {
"generated_at": datetime.now(timezone.utc).isoformat(),
"selection": selection.model_dump(),
@@ -108,42 +144,61 @@ class MigrationDryRunService:
"summary": summary,
"risk": score_risks(risk),
}
# [/DEF:run:Function]
# [DEF:_load_db_mapping:Function]
# @PURPOSE: Resolve UUID mapping for optional DB config replacement.
def _load_db_mapping(self, db: Session, selection: DashboardSelection) -> Dict[str, str]:
rows = db.query(DatabaseMapping).filter(
def _load_db_mapping(
self, db: Session, selection: DashboardSelection
) -> Dict[str, str]:
rows = (
db.query(DatabaseMapping)
.filter(
DatabaseMapping.source_env_id == selection.source_env_id,
DatabaseMapping.target_env_id == selection.target_env_id,
).all()
)
.all()
)
return {row.source_db_uuid: row.target_db_uuid for row in rows}
# [/DEF:_load_db_mapping:Function]
# [DEF:_accumulate_objects:Function]
# @PURPOSE: Merge extracted resources by UUID to avoid duplicates.
def _accumulate_objects(self, target: Dict[str, Dict[str, Dict[str, Any]]], source: Dict[str, List[Dict[str, Any]]]) -> None:
def _accumulate_objects(
self,
target: Dict[str, Dict[str, Dict[str, Any]]],
source: Dict[str, List[Dict[str, Any]]],
) -> None:
for object_type in ("dashboards", "charts", "datasets"):
for item in source.get(object_type, []):
uuid = item.get("uuid")
if uuid:
target[object_type][str(uuid)] = item
# [/DEF:_accumulate_objects:Function]
# [DEF:_index_by_uuid:Function]
# @PURPOSE: Build UUID-index map for normalized resources.
def _index_by_uuid(self, objects: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
def _index_by_uuid(
self, objects: List[Dict[str, Any]]
) -> Dict[str, Dict[str, Any]]:
indexed: Dict[str, Dict[str, Any]] = {}
for obj in objects:
uuid = obj.get("uuid")
if uuid:
indexed[str(uuid)] = obj
return indexed
# [/DEF:_index_by_uuid:Function]
# [DEF:_build_object_diff:Function]
# @PURPOSE: Compute create/update/delete buckets by UUID+signature.
def _build_object_diff(self, source_objects: List[Dict[str, Any]], target_objects: List[Dict[str, Any]]) -> Dict[str, List[Dict[str, Any]]]:
# @RELATION: DEPENDS_ON -> _index_by_uuid
def _build_object_diff(
self, source_objects: List[Dict[str, Any]], target_objects: List[Dict[str, Any]]
) -> Dict[str, List[Dict[str, Any]]]:
target_index = self._index_by_uuid(target_objects)
created: List[Dict[str, Any]] = []
updated: List[Dict[str, Any]] = []
@@ -155,67 +210,128 @@ class MigrationDryRunService:
created.append({"uuid": source_uuid, "title": source_obj.get("title")})
continue
if source_obj.get("signature") != target_obj.get("signature"):
updated.append({
updated.append(
{
"uuid": source_uuid,
"title": source_obj.get("title"),
"target_title": target_obj.get("title"),
})
}
)
return {"create": created, "update": updated, "delete": deleted}
# [/DEF:_build_object_diff:Function]
# [DEF:_build_target_signatures:Function]
# @PURPOSE: Pull target metadata and normalize it into comparable signatures.
def _build_target_signatures(self, client: SupersetClient) -> Dict[str, List[Dict[str, Any]]]:
_, dashboards = client.get_dashboards(query={
"columns": ["uuid", "dashboard_title", "slug", "position_json", "json_metadata", "description", "owners"],
})
_, datasets = client.get_datasets(query={
"columns": ["uuid", "table_name", "schema", "database_uuid", "sql", "columns", "metrics"],
})
_, charts = client.get_charts(query={
"columns": ["uuid", "slice_name", "viz_type", "params", "query_context", "datasource_uuid", "dataset_uuid"],
})
def _build_target_signatures(
self, client: SupersetClient
) -> Dict[str, List[Dict[str, Any]]]:
_, dashboards = client.get_dashboards(
query={
"columns": [
"uuid",
"dashboard_title",
"slug",
"position_json",
"json_metadata",
"description",
"owners",
],
}
)
_, datasets = client.get_datasets(
query={
"columns": [
"uuid",
"table_name",
"schema",
"database_uuid",
"sql",
"columns",
"metrics",
],
}
)
_, charts = client.get_charts(
query={
"columns": [
"uuid",
"slice_name",
"viz_type",
"params",
"query_context",
"datasource_uuid",
"dataset_uuid",
],
}
)
return {
"dashboards": [{
"dashboards": [
{
"uuid": str(item.get("uuid")),
"title": item.get("dashboard_title"),
"owners": item.get("owners") or [],
"signature": json.dumps({
"signature": json.dumps(
{
"title": item.get("dashboard_title"),
"slug": item.get("slug"),
"position_json": item.get("position_json"),
"json_metadata": item.get("json_metadata"),
"description": item.get("description"),
"owners": item.get("owners"),
}, sort_keys=True, default=str),
} for item in dashboards if item.get("uuid")],
"datasets": [{
},
sort_keys=True,
default=str,
),
}
for item in dashboards
if item.get("uuid")
],
"datasets": [
{
"uuid": str(item.get("uuid")),
"title": item.get("table_name"),
"database_uuid": item.get("database_uuid"),
"signature": json.dumps({
"signature": json.dumps(
{
"title": item.get("table_name"),
"schema": item.get("schema"),
"database_uuid": item.get("database_uuid"),
"sql": item.get("sql"),
"columns": item.get("columns"),
"metrics": item.get("metrics"),
}, sort_keys=True, default=str),
} for item in datasets if item.get("uuid")],
"charts": [{
},
sort_keys=True,
default=str,
),
}
for item in datasets
if item.get("uuid")
],
"charts": [
{
"uuid": str(item.get("uuid")),
"title": item.get("slice_name") or item.get("name"),
"dataset_uuid": item.get("datasource_uuid") or item.get("dataset_uuid"),
"signature": json.dumps({
"dataset_uuid": item.get("datasource_uuid")
or item.get("dataset_uuid"),
"signature": json.dumps(
{
"title": item.get("slice_name") or item.get("name"),
"viz_type": item.get("viz_type"),
"params": item.get("params"),
"query_context": item.get("query_context"),
"datasource_uuid": item.get("datasource_uuid"),
"dataset_uuid": item.get("dataset_uuid"),
}, sort_keys=True, default=str),
} for item in charts if item.get("uuid")],
},
sort_keys=True,
default=str,
),
}
for item in charts
if item.get("uuid")
],
}
# [/DEF:_build_target_signatures:Function]
# [DEF:_build_risks:Function]
@@ -228,6 +344,7 @@ class MigrationDryRunService:
target_client: SupersetClient,
) -> List[Dict[str, Any]]:
return build_risks(source_objects, target_objects, diff, target_client)
# [/DEF:_build_risks:Function]

50
backend/src/core/migration/risk_assessor.py
View File

@@ -3,8 +3,9 @@
# @SEMANTICS: migration, dry_run, risk, scoring, preflight
# @PURPOSE: Compute deterministic migration risk items and aggregate score for dry-run reporting.
# @LAYER: Domain
# @RELATION: [DEPENDS_ON] ->[backend.src.core.superset_client.SupersetClient]
# @RELATION: [DISPATCHES] ->[backend.src.core.migration.dry_run_orchestrator.MigrationDryRunService.run]
# @RELATION: DEPENDS_ON -> [backend.src.core.superset_client.SupersetClient]
# @RELATION: DISPATCHED_BY -> [backend.src.core.migration.dry_run_orchestrator.MigrationDryRunService.run]
# @RELATION: CONTAINS -> [index_by_uuid, extract_owner_identifiers, build_risks, score_risks]
# @INVARIANT: Risk scoring must remain bounded to [0,100] and preserve severity-to-weight mapping.
# @TEST_CONTRACT: [source_objects,target_objects,diff,target_client] -> [List[RiskItem]]
# @TEST_SCENARIO: [overwrite_update_objects] -> [medium overwrite_existing risk is emitted for each update diff item]
@@ -41,6 +42,8 @@ def index_by_uuid(objects: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
indexed[str(uuid)] = obj
logger.reflect("UUID index built", extra={"indexed_count": len(indexed)})
return indexed
# [/DEF:index_by_uuid:Function]
@@ -66,13 +69,18 @@ def extract_owner_identifiers(owners: Any) -> List[str]:
elif owner is not None:
ids.append(str(owner))
normalized_ids = sorted(set(ids))
logger.reflect("Owner identifiers normalized", extra={"owner_count": len(normalized_ids)})
logger.reflect(
"Owner identifiers normalized", extra={"owner_count": len(normalized_ids)}
)
return normalized_ids
# [/DEF:extract_owner_identifiers:Function]
# [DEF:build_risks:Function]
# @PURPOSE: Build risk list from computed diffs and target catalog state.
# @RELATION: DEPENDS_ON -> [index_by_uuid, extract_owner_identifiers]
# @PRE: source_objects/target_objects/diff contain dashboards/charts/datasets keys with expected list structures.
# @PRE: target_client is authenticated/usable for database list retrieval.
# @POST: Returns list of deterministic risk items derived from overwrite, missing datasource, reference, and owner mismatch checks.
@@ -94,39 +102,47 @@ def build_risks(
risks: List[Dict[str, Any]] = []
for object_type in ("dashboards", "charts", "datasets"):
for item in diff[object_type]["update"]:
risks.append({
risks.append(
{
"code": "overwrite_existing",
"severity": "medium",
"object_type": object_type[:-1],
"object_uuid": item["uuid"],
"message": f"Object will be updated in target: {item.get('title') or item['uuid']}",
})
}
)
target_dataset_uuids = set(index_by_uuid(target_objects["datasets"]).keys())
_, target_databases = target_client.get_databases(query={"columns": ["uuid"]})
target_database_uuids = {str(item.get("uuid")) for item in target_databases if item.get("uuid")}
target_database_uuids = {
str(item.get("uuid")) for item in target_databases if item.get("uuid")
}
for dataset in source_objects["datasets"]:
db_uuid = dataset.get("database_uuid")
if db_uuid and str(db_uuid) not in target_database_uuids:
risks.append({
risks.append(
{
"code": "missing_datasource",
"severity": "high",
"object_type": "dataset",
"object_uuid": dataset.get("uuid"),
"message": f"Target datasource is missing for dataset {dataset.get('title') or dataset.get('uuid')}",
})
}
)
for chart in source_objects["charts"]:
ds_uuid = chart.get("dataset_uuid")
if ds_uuid and str(ds_uuid) not in target_dataset_uuids:
risks.append({
risks.append(
{
"code": "breaking_reference",
"severity": "high",
"object_type": "chart",
"object_uuid": chart.get("uuid"),
"message": f"Chart references dataset not found on target: {ds_uuid}",
})
}
)
source_dash = index_by_uuid(source_objects["dashboards"])
target_dash = index_by_uuid(target_objects["dashboards"])
@@ -138,15 +154,19 @@ def build_risks(
source_owners = extract_owner_identifiers(source_obj.get("owners"))
target_owners = extract_owner_identifiers(target_obj.get("owners"))
if source_owners and target_owners and source_owners != target_owners:
risks.append({
risks.append(
{
"code": "owner_mismatch",
"severity": "low",
"object_type": "dashboard",
"object_uuid": item["uuid"],
"message": f"Owner mismatch for dashboard {item.get('title') or item['uuid']}",
})
}
)
logger.reflect("Risk list assembled", extra={"risk_count": len(risks)})
return risks
# [/DEF:build_risks:Function]
@@ -160,11 +180,15 @@ def score_risks(risk_items: List[Dict[str, Any]]) -> Dict[str, Any]:
with belief_scope("risk_assessor.score_risks"):
logger.reason("Scoring risk items", extra={"risk_items_count": len(risk_items)})
weights = {"high": 25, "medium": 10, "low": 5}
score = min(100, sum(weights.get(item.get("severity", "low"), 5) for item in risk_items))
score = min(
100, sum(weights.get(item.get("severity", "low"), 5) for item in risk_items)
)
level = "low" if score < 25 else "medium" if score < 60 else "high"
result = {"score": score, "level": level, "items": risk_items}
logger.reflect("Risk score computed", extra={"score": score, "level": level})
return result
# [/DEF:score_risks:Function]

123
backend/src/core/migration_engine.py
View File

@@ -25,10 +25,11 @@ from src.core.mapping_service import IdMappingService
from src.models.mapping import ResourceType
# [/SECTION]
# [DEF:MigrationEngine:Class]
# @PURPOSE: Engine for transforming Superset export ZIPs.
# @RELATION: CONTAINS -> [__init__, transform_zip, _transform_yaml, _extract_chart_uuids_from_archive, _patch_dashboard_metadata]
class MigrationEngine:
# [DEF:__init__:Function]
# @PURPOSE: Initializes migration orchestration dependencies for ZIP/YAML metadata transformations.
# @PRE: mapping_service is None or implements batch remote ID lookup for ResourceType.CHART.
@@ -41,10 +42,12 @@ class MigrationEngine:
logger.reason("Initializing MigrationEngine")
self.mapping_service = mapping_service
logger.reflect("MigrationEngine initialized")
# [/DEF:__init__:Function]
# [DEF:transform_zip:Function]
# @PURPOSE: Extracts ZIP, replaces database UUIDs in YAMLs, patches cross-filters, and re-packages.
# @RELATION: DEPENDS_ON -> [_transform_yaml, _extract_chart_uuids_from_archive, _patch_dashboard_metadata]
# @PARAM: zip_path (str) - Path to the source ZIP file.
# @PARAM: output_path (str) - Path where the transformed ZIP will be saved.
# @PARAM: db_mapping (Dict[str, str]) - Mapping of source UUID to target UUID.
@@ -56,7 +59,15 @@ class MigrationEngine:
# @SIDE_EFFECT: Reads/writes filesystem archives, creates temporary directory, emits structured logs.
# @DATA_CONTRACT: Input[(str zip_path, str output_path, Dict[str,str] db_mapping, bool strip_databases, Optional[str] target_env_id, bool fix_cross_filters)] -> Output[bool]
# @RETURN: bool - True if successful.
def transform_zip(self, zip_path: str, output_path: str, db_mapping: Dict[str, str], strip_databases: bool = True, target_env_id: Optional[str] = None, fix_cross_filters: bool = False) -> bool:
def transform_zip(
self,
zip_path: str,
output_path: str,
db_mapping: Dict[str, str],
strip_databases: bool = True,
target_env_id: Optional[str] = None,
fix_cross_filters: bool = False,
) -> bool:
"""
Transform a Superset export ZIP by replacing database UUIDs and optionally fixing cross-filters.
"""
@@ -69,36 +80,52 @@ class MigrationEngine:
try:
# 1. Extract
logger.reason(f"Extracting source archive to {temp_dir}")
with zipfile.ZipFile(zip_path, 'r') as zf:
with zipfile.ZipFile(zip_path, "r") as zf:
zf.extractall(temp_dir)
# 2. Transform YAMLs (Databases)
dataset_files = list(temp_dir.glob("**/datasets/**/*.yaml")) + list(temp_dir.glob("**/datasets/*.yaml"))
dataset_files = list(temp_dir.glob("**/datasets/**/*.yaml")) + list(
temp_dir.glob("**/datasets/*.yaml")
)
dataset_files = list(set(dataset_files))
logger.reason(f"Transforming {len(dataset_files)} dataset YAML files")
logger.reason(
f"Transforming {len(dataset_files)} dataset YAML files"
)
for ds_file in dataset_files:
self._transform_yaml(ds_file, db_mapping)
# 2.5 Patch Cross-Filters (Dashboards)
if fix_cross_filters:
if self.mapping_service and target_env_id:
dash_files = list(temp_dir.glob("**/dashboards/**/*.yaml")) + list(temp_dir.glob("**/dashboards/*.yaml"))
dash_files = list(
temp_dir.glob("**/dashboards/**/*.yaml")
) + list(temp_dir.glob("**/dashboards/*.yaml"))
dash_files = list(set(dash_files))
logger.reason(f"Patching cross-filters for {len(dash_files)} dashboards")
logger.reason(
f"Patching cross-filters for {len(dash_files)} dashboards"
)
# Gather all source UUID-to-ID mappings from the archive first
source_id_to_uuid_map = self._extract_chart_uuids_from_archive(temp_dir)
source_id_to_uuid_map = (
self._extract_chart_uuids_from_archive(temp_dir)
)
for dash_file in dash_files:
self._patch_dashboard_metadata(dash_file, target_env_id, source_id_to_uuid_map)
self._patch_dashboard_metadata(
dash_file, target_env_id, source_id_to_uuid_map
)
else:
logger.explore("Cross-filter patching requested but mapping service or target_env_id is missing")
logger.explore(
"Cross-filter patching requested but mapping service or target_env_id is missing"
)
# 3. Re-package
logger.reason(f"Re-packaging transformed archive (strip_databases={strip_databases})")
with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zf:
logger.reason(
f"Re-packaging transformed archive (strip_databases={strip_databases})"
)
with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
for root, dirs, files in os.walk(temp_dir):
rel_root = Path(root).relative_to(temp_dir)
@@ -115,6 +142,7 @@ class MigrationEngine:
except Exception as e:
logger.explore(f"Error transforming ZIP: {e}")
return False
# [/DEF:transform_zip:Function]
# [DEF:_transform_yaml:Function]
@@ -131,19 +159,20 @@ class MigrationEngine:
logger.explore(f"YAML file not found: {file_path}")
raise FileNotFoundError(str(file_path))
with open(file_path, 'r') as f:
with open(file_path, "r") as f:
data = yaml.safe_load(f)
if not data:
return
source_uuid = data.get('database_uuid')
source_uuid = data.get("database_uuid")
if source_uuid in db_mapping:
logger.reason(f"Replacing database UUID in {file_path.name}")
data['database_uuid'] = db_mapping[source_uuid]
with open(file_path, 'w') as f:
data["database_uuid"] = db_mapping[source_uuid]
with open(file_path, "w") as f:
yaml.dump(data, f)
logger.reflect(f"Database UUID patched in {file_path.name}")
# [/DEF:_transform_yaml:Function]
# [DEF:_extract_chart_uuids_from_archive:Function]
@@ -161,16 +190,19 @@ class MigrationEngine:
# or manifesting the export metadata structure where source IDs are stored.
# For simplicity in US1 MVP, we assume it's read from chart files if present.
mapping = {}
chart_files = list(temp_dir.glob("**/charts/**/*.yaml")) + list(temp_dir.glob("**/charts/*.yaml"))
chart_files = list(temp_dir.glob("**/charts/**/*.yaml")) + list(
temp_dir.glob("**/charts/*.yaml")
)
for cf in set(chart_files):
try:
with open(cf, 'r') as f:
with open(cf, "r") as f:
cdata = yaml.safe_load(f)
if cdata and 'id' in cdata and 'uuid' in cdata:
mapping[cdata['id']] = cdata['uuid']
if cdata and "id" in cdata and "uuid" in cdata:
mapping[cdata["id"]] = cdata["uuid"]
except Exception:
pass
return mapping
# [/DEF:_extract_chart_uuids_from_archive:Function]
# [DEF:_patch_dashboard_metadata:Function]
@@ -182,29 +214,37 @@ class MigrationEngine:
# @PARAM: file_path (Path)
# @PARAM: target_env_id (str)
# @PARAM: source_map (Dict[int, str])
def _patch_dashboard_metadata(self, file_path: Path, target_env_id: str, source_map: Dict[int, str]):
def _patch_dashboard_metadata(
self, file_path: Path, target_env_id: str, source_map: Dict[int, str]
):
with belief_scope("MigrationEngine._patch_dashboard_metadata"):
try:
if not file_path.exists():
return
with open(file_path, 'r') as f:
with open(file_path, "r") as f:
data = yaml.safe_load(f)
if not data or 'json_metadata' not in data:
if not data or "json_metadata" not in data:
return
metadata_str = data['json_metadata']
metadata_str = data["json_metadata"]
if not metadata_str:
return
# Fetch target UUIDs for everything we know:
uuids_needed = list(source_map.values())
logger.reason(f"Resolving {len(uuids_needed)} remote IDs for dashboard metadata patching")
target_ids = self.mapping_service.get_remote_ids_batch(target_env_id, ResourceType.CHART, uuids_needed)
logger.reason(
f"Resolving {len(uuids_needed)} remote IDs for dashboard metadata patching"
)
target_ids = self.mapping_service.get_remote_ids_batch(
target_env_id, ResourceType.CHART, uuids_needed
)
if not target_ids:
logger.reflect("No remote target IDs found in mapping database for this dashboard.")
logger.reflect(
"No remote target IDs found in mapping database for this dashboard."
)
return
# Map Source Int -> Target Int
@@ -217,31 +257,46 @@ class MigrationEngine:
missing_targets.append(s_id)
if missing_targets:
logger.explore(f"Missing target IDs for source IDs: {missing_targets}. Cross-filters might break.")
logger.explore(
f"Missing target IDs for source IDs: {missing_targets}. Cross-filters might break."
)
if not source_to_target:
logger.reflect("No source IDs matched remotely. Skipping patch.")
return
logger.reason(f"Patching {len(source_to_target)} ID references in json_metadata")
logger.reason(
f"Patching {len(source_to_target)} ID references in json_metadata"
)
new_metadata_str = metadata_str
for s_id, t_id in source_to_target.items():
new_metadata_str = re.sub(r'("datasetId"\s*:\s*)' + str(s_id) + r'(\b)', r'\g<1>' + str(t_id) + r'\g<2>', new_metadata_str)
new_metadata_str = re.sub(r'("chartId"\s*:\s*)' + str(s_id) + r'(\b)', r'\g<1>' + str(t_id) + r'\g<2>', new_metadata_str)
new_metadata_str = re.sub(
r'("datasetId"\s*:\s*)' + str(s_id) + r"(\b)",
r"\g<1>" + str(t_id) + r"\g<2>",
new_metadata_str,
)
new_metadata_str = re.sub(
r'("chartId"\s*:\s*)' + str(s_id) + r"(\b)",
r"\g<1>" + str(t_id) + r"\g<2>",
new_metadata_str,
)
# Re-parse to validate valid JSON
data['json_metadata'] = json.dumps(json.loads(new_metadata_str))
data["json_metadata"] = json.dumps(json.loads(new_metadata_str))
with open(file_path, 'w') as f:
with open(file_path, "w") as f:
yaml.dump(data, f)
logger.reflect(f"Dashboard metadata patched and saved: {file_path.name}")
logger.reflect(
f"Dashboard metadata patched and saved: {file_path.name}"
)
except Exception as e:
logger.explore(f"Metadata patch failed for {file_path.name}: {e}")
# [/DEF:_patch_dashboard_metadata:Function]
# [/DEF:MigrationEngine:Class]
# [/DEF:backend.src.core.migration_engine:Module]

4
backend/src/core/superset_client.py
View File

@@ -694,7 +694,7 @@ class SupersetClient:
# @PRE: Client is authenticated and chart_id exists.
# @POST: Returns chart payload from Superset API.
# @DATA_CONTRACT: Input[chart_id: int] -> Output[Dict]
# @RELATION: [CALLS] ->[APIClient.request]
# @RELATION: [CALLS] ->[request]
def get_chart(self, chart_id: int) -> Dict:
with belief_scope("SupersetClient.get_chart", f"id={chart_id}"):
response = self.network.request(method="GET", endpoint=f"/chart/{chart_id}")
@@ -996,7 +996,7 @@ class SupersetClient:
# @PRE: Client is authenticated.
# @POST: Returns total count and charts list.
# @DATA_CONTRACT: Input[query: Optional[Dict]] -> Output[Tuple[int, List[Dict]]]
# @RELATION: [CALLS] ->[SupersetClient._fetch_all_pages]
# @RELATION: [CALLS] ->[_fetch_all_pages]
def get_charts(self, query: Optional[Dict] = None) -> Tuple[int, List[Dict]]:
with belief_scope("get_charts"):
validated_query = self._validate_query_params(query or {})

6
backend/src/core/task_manager/__tests__/test_context.py
View File

@@ -1,4 +1,5 @@
# [DEF:backend.src.core.task_manager.__tests__.test_context:Module]
# [DEF:TestContext:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, task-context, background-tasks, sub-context
# @PURPOSE: Verify TaskContext preserves optional background task scheduler across sub-context creation.
@@ -9,6 +10,7 @@ from src.core.task_manager.context import TaskContext
# [DEF:test_task_context_preserves_background_tasks_across_sub_context:Function]
# @RELATION: BINDS_TO -> TestContext
# @PURPOSE: Plugins must be able to access background_tasks from both root and sub-context loggers.
# @PRE: TaskContext is initialized with a BackgroundTasks-like object.
# @POST: background_tasks remains available on root and derived sub-contexts.
@@ -26,4 +28,4 @@ def test_task_context_preserves_background_tasks_across_sub_context():
assert context.background_tasks is background_tasks
assert sub_context.background_tasks is background_tasks
# [/DEF:test_task_context_preserves_background_tasks_across_sub_context:Function]
# [/DEF:backend.src.core.task_manager.__tests__.test_context:Module]
# [/DEF:TestContext:Module]

23
backend/src/core/task_manager/__tests__/test_task_logger.py
View File

@@ -17,12 +17,18 @@ def task_logger(mock_add_log):
return TaskLogger(task_id="test_123", add_log_fn=mock_add_log, source="test_plugin")
# @TEST_CONTRACT: TaskLoggerModel -> Invariants
# [DEF:test_task_logger_initialization:Function]
# @RELATION: BINDS_TO -> __tests__/test_task_logger
def test_task_logger_initialization(task_logger):
"""Verify TaskLogger is bound to specific task_id and source."""
assert task_logger._task_id == "test_123"
assert task_logger._default_source == "test_plugin"
# @TEST_CONTRACT: invariants -> "All specific log methods (info, error) delegate to _log"
# [/DEF:test_task_logger_initialization:Function]
# [DEF:test_log_methods_delegation:Function]
# @RELATION: BINDS_TO -> __tests__/test_task_logger
def test_log_methods_delegation(task_logger, mock_add_log):
"""Verify info, error, warning, debug delegate to internal _log."""
task_logger.info("info message", metadata={"k": "v"})
@@ -62,6 +68,10 @@ def test_log_methods_delegation(task_logger, mock_add_log):
)
# @TEST_CONTRACT: invariants -> "with_source creates a new logger with the same task_id"
# [/DEF:test_log_methods_delegation:Function]
# [DEF:test_with_source:Function]
# @RELATION: BINDS_TO -> __tests__/test_task_logger
def test_with_source(task_logger):
"""Verify with_source returns a new instance with updated default source."""
new_logger = task_logger.with_source("new_source")
@@ -71,18 +81,30 @@ def test_with_source(task_logger):
assert new_logger is not task_logger
# @TEST_EDGE: missing_task_id -> raises TypeError
# [/DEF:test_with_source:Function]
# [DEF:test_missing_task_id:Function]
# @RELATION: BINDS_TO -> __tests__/test_task_logger
def test_missing_task_id():
with pytest.raises(TypeError):
TaskLogger(add_log_fn=lambda x: x)
# @TEST_EDGE: invalid_add_log_fn -> raises TypeError
# (Python doesn't strictly enforce this at init, but let's verify it fails on call if not callable)
# [/DEF:test_missing_task_id:Function]
# [DEF:test_invalid_add_log_fn:Function]
# @RELATION: BINDS_TO -> __tests__/test_task_logger
def test_invalid_add_log_fn():
logger = TaskLogger(task_id="msg", add_log_fn=None)
with pytest.raises(TypeError):
logger.info("test")
# @TEST_INVARIANT: consistent_delegation
# [/DEF:test_invalid_add_log_fn:Function]
# [DEF:test_progress_log:Function]
# @RELATION: BINDS_TO -> __tests__/test_task_logger
def test_progress_log(task_logger, mock_add_log):
"""Verify progress method correctly formats metadata."""
task_logger.progress("Step 1", 45.5)
@@ -100,3 +122,4 @@ def test_progress_log(task_logger, mock_add_log):
task_logger.progress("Step low", -10)
assert mock_add_log.call_args[1]["metadata"]["progress"] == 0
# [/DEF:test_progress_log:Function]

2
backend/src/core/utils/network.py
View File

@@ -309,7 +309,7 @@ class APIClient:
except (requests.exceptions.RequestException, KeyError) as e:
SupersetAuthCache.invalidate(self._auth_cache_key)
raise NetworkError(f"Network or parsing error during authentication: {e}") from e
# [/DEF:authenticate:Function]
# [/DEF:APIClient.authenticate:Function]
@property
# [DEF:headers:Function]

178
backend/src/core/utils/superset_compilation_adapter.py
View File

@@ -34,6 +34,8 @@ class PreviewCompilationPayload:
preview_fingerprint: str
template_params: Dict[str, Any]
effective_filters: List[Dict[str, Any]]
# [/DEF:PreviewCompilationPayload:Class]
@@ -47,6 +49,8 @@ class SqlLabLaunchPayload:
preview_id: str
compiled_sql: str
template_params: Dict[str, Any]
# [/DEF:SqlLabLaunchPayload:Class]
@@ -61,11 +65,25 @@ class SupersetCompilationAdapter:
# [DEF:SupersetCompilationAdapter.__init__:Function]
# @COMPLEXITY: 2
# @PURPOSE: Bind adapter to one Superset environment and client instance.
def __init__(self, environment: Environment, client: Optional[SupersetClient] = None) -> None:
def __init__(
self, environment: Environment, client: Optional[SupersetClient] = None
) -> None:
self.environment = environment
self.client = client or SupersetClient(environment)
# [/DEF:SupersetCompilationAdapter.__init__:Function]
# [DEF:SupersetCompilationAdapter._supports_client_method:Function]
# @COMPLEXITY: 2
# @PURPOSE: Detect explicitly implemented client capabilities without treating loose mocks as real methods.
def _supports_client_method(self, method_name: str) -> bool:
client_dict = getattr(self.client, "__dict__", {})
if method_name in client_dict:
return callable(client_dict[method_name])
return callable(getattr(type(self.client), method_name, None))
# [/DEF:SupersetCompilationAdapter._supports_client_method:Function]
# [DEF:SupersetCompilationAdapter.compile_preview:Function]
# @COMPLEXITY: 4
# @PURPOSE: Request Superset-side compiled SQL preview for the current effective inputs.
@@ -79,7 +97,10 @@ class SupersetCompilationAdapter:
if payload.dataset_id <= 0:
logger.explore(
"Preview compilation rejected because dataset identifier is invalid",
extra={"dataset_id": payload.dataset_id, "session_id": payload.session_id},
extra={
"dataset_id": payload.dataset_id,
"session_id": payload.session_id,
},
)
raise ValueError("dataset_id must be a positive integer")
@@ -155,6 +176,7 @@ class SupersetCompilationAdapter:
},
)
return preview
# [/DEF:SupersetCompilationAdapter.compile_preview:Function]
# [DEF:SupersetCompilationAdapter.mark_preview_stale:Function]
@@ -165,6 +187,7 @@ class SupersetCompilationAdapter:
def mark_preview_stale(self, preview: CompiledPreview) -> CompiledPreview:
preview.preview_status = PreviewStatus.STALE
return preview
# [/DEF:SupersetCompilationAdapter.mark_preview_stale:Function]
# [DEF:SupersetCompilationAdapter.create_sql_lab_session:Function]
@@ -181,7 +204,10 @@ class SupersetCompilationAdapter:
if not compiled_sql:
logger.explore(
"SQL Lab launch rejected because compiled SQL is empty",
extra={"session_id": payload.session_id, "preview_id": payload.preview_id},
extra={
"session_id": payload.session_id,
"preview_id": payload.preview_id,
},
)
raise ValueError("compiled_sql must be non-empty")
@@ -204,9 +230,14 @@ class SupersetCompilationAdapter:
if not sql_lab_session_ref:
logger.explore(
"Superset SQL Lab launch response did not include a stable session reference",
extra={"session_id": payload.session_id, "preview_id": payload.preview_id},
extra={
"session_id": payload.session_id,
"preview_id": payload.preview_id,
},
)
raise RuntimeError(
"Superset SQL Lab launch response did not include a session reference"
)
raise RuntimeError("Superset SQL Lab launch response did not include a session reference")
logger.reflect(
"Canonical SQL Lab session created successfully",
@@ -217,6 +248,7 @@ class SupersetCompilationAdapter:
},
)
return sql_lab_session_ref
# [/DEF:SupersetCompilationAdapter.create_sql_lab_session:Function]
# [DEF:SupersetCompilationAdapter._request_superset_preview:Function]
@@ -227,7 +259,48 @@ class SupersetCompilationAdapter:
# @POST: returns one normalized upstream compilation response including the chosen strategy metadata.
# @SIDE_EFFECT: issues one or more Superset preview requests through the client fallback chain.
# @DATA_CONTRACT: Input[PreviewCompilationPayload] -> Output[Dict[str,Any]]
def _request_superset_preview(self, payload: PreviewCompilationPayload) -> Dict[str, Any]:
def _request_superset_preview(
self, payload: PreviewCompilationPayload
) -> Dict[str, Any]:
direct_compile_preview = getattr(self.client, "compile_preview", None)
if self._supports_client_method("compile_preview") and callable(
direct_compile_preview
):
try:
logger.reason(
"Attempting preview compilation via direct client capability",
extra={
"dataset_id": payload.dataset_id,
"session_id": payload.session_id,
},
)
response = direct_compile_preview(payload)
except TypeError:
response = direct_compile_preview(
payload.dataset_id,
template_params=payload.template_params,
effective_filters=payload.effective_filters,
)
except Exception as exc:
logger.explore(
"Direct client preview capability failed; falling back to dataset preview strategies",
extra={
"dataset_id": payload.dataset_id,
"session_id": payload.session_id,
"error": str(exc),
},
)
else:
normalized = self._normalize_preview_response(response)
if normalized is not None:
return normalized
direct_compile_dataset_preview = getattr(
self.client, "compile_dataset_preview", None
)
if self._supports_client_method("compile_dataset_preview") and callable(
direct_compile_dataset_preview
):
try:
logger.reason(
"Attempting deterministic Superset preview compilation through supported endpoint strategies",
@@ -238,7 +311,7 @@ class SupersetCompilationAdapter:
"template_param_count": len(payload.template_params),
},
)
response = self.client.compile_dataset_preview(
response = direct_compile_dataset_preview(
dataset_id=payload.dataset_id,
template_params=payload.template_params,
effective_filters=payload.effective_filters,
@@ -256,8 +329,72 @@ class SupersetCompilationAdapter:
normalized = self._normalize_preview_response(response)
if normalized is None:
raise RuntimeError("Superset preview compilation response could not be normalized")
raise RuntimeError(
"Superset preview compilation response could not be normalized"
)
return normalized
try:
logger.reason(
"Attempting deterministic Superset preview compilation through supported endpoint strategies",
extra={
"dataset_id": payload.dataset_id,
"session_id": payload.session_id,
"filter_count": len(payload.effective_filters),
"template_param_count": len(payload.template_params),
},
)
if self._supports_client_method("compile_dataset_preview"):
response = self.client.compile_dataset_preview(
dataset_id=payload.dataset_id,
template_params=payload.template_params,
effective_filters=payload.effective_filters,
)
normalized = self._normalize_preview_response(response)
if normalized is None:
raise RuntimeError(
"Superset preview compilation response could not be normalized"
)
return normalized
errors: List[str] = []
for endpoint in (
f"/dataset/{payload.dataset_id}/preview",
f"/dataset/{payload.dataset_id}/sql",
):
try:
response = self.client.network.request(
method="POST",
endpoint=endpoint,
data=self._dump_json(
{
"template_params": payload.template_params,
"effective_filters": payload.effective_filters,
}
),
headers={"Content-Type": "application/json"},
)
normalized = self._normalize_preview_response(response)
if normalized is not None:
return normalized
errors.append(f"{endpoint}:unrecognized_response")
except Exception as exc:
errors.append(f"{endpoint}:{exc}")
raise RuntimeError(
"; ".join(errors) or "Superset preview compilation failed"
)
except Exception as exc:
logger.explore(
"Superset preview compilation failed across supported endpoint strategies",
extra={
"dataset_id": payload.dataset_id,
"session_id": payload.session_id,
"error": str(exc),
},
)
raise RuntimeError(str(exc)) from exc
# [/DEF:SupersetCompilationAdapter._request_superset_preview:Function]
# [DEF:SupersetCompilationAdapter._request_sql_lab_session:Function]
@@ -270,10 +407,20 @@ class SupersetCompilationAdapter:
# @DATA_CONTRACT: Input[SqlLabLaunchPayload] -> Output[Dict[str,Any]]
def _request_sql_lab_session(self, payload: SqlLabLaunchPayload) -> Dict[str, Any]:
dataset_raw = self.client.get_dataset(payload.dataset_id)
dataset_record = dataset_raw.get("result", dataset_raw) if isinstance(dataset_raw, dict) else {}
database_id = dataset_record.get("database", {}).get("id") if isinstance(dataset_record.get("database"), dict) else dataset_record.get("database_id")
dataset_record = (
dataset_raw.get("result", dataset_raw)
if isinstance(dataset_raw, dict)
else {}
)
database_id = (
dataset_record.get("database", {}).get("id")
if isinstance(dataset_record.get("database"), dict)
else dataset_record.get("database_id")
)
if database_id is None:
raise RuntimeError("Superset dataset does not expose a database identifier for SQL Lab launch")
raise RuntimeError(
"Superset dataset does not expose a database identifier for SQL Lab launch"
)
request_payload = {
"database_id": database_id,
@@ -305,7 +452,10 @@ class SupersetCompilationAdapter:
extra={"target": candidate["target"], "error": str(exc)},
)
raise RuntimeError("; ".join(errors) or "No Superset SQL Lab surface accepted the request")
raise RuntimeError(
"; ".join(errors) or "No Superset SQL Lab surface accepted the request"
)
# [/DEF:SupersetCompilationAdapter._request_sql_lab_session:Function]
# [DEF:SupersetCompilationAdapter._normalize_preview_response:Function]
@@ -339,6 +489,7 @@ class SupersetCompilationAdapter:
"raw_response": response,
}
return None
# [/DEF:SupersetCompilationAdapter._normalize_preview_response:Function]
# [DEF:SupersetCompilationAdapter._dump_json:Function]
@@ -348,7 +499,10 @@ class SupersetCompilationAdapter:
import json
return json.dumps(payload, sort_keys=True, default=str)
# [/DEF:SupersetCompilationAdapter._dump_json:Function]
# [/DEF:SupersetCompilationAdapter:Class]
# [/DEF:SupersetCompilationAdapter:Module]

112
backend/src/dependencies.py
View File

@@ -15,6 +15,7 @@
# @RELATION: CALLS ->[init_db]
from pathlib import Path
from typing import Optional
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError
@@ -25,10 +26,16 @@ from .core.scheduler import SchedulerService
from .services.resource_service import ResourceService
from .services.mapping_service import MappingService
from .services.clean_release.repositories import (
CandidateRepository, ArtifactRepository, ManifestRepository,
PolicyRepository, ComplianceRepository, ReportRepository,
ApprovalRepository, PublicationRepository, AuditRepository,
CleanReleaseAuditLog
CandidateRepository,
ArtifactRepository,
ManifestRepository,
PolicyRepository,
ComplianceRepository,
ReportRepository,
ApprovalRepository,
PublicationRepository,
AuditRepository,
CleanReleaseAuditLog,
)
from .services.clean_release.repository import CleanReleaseRepository
from .services.clean_release.facade import CleanReleaseFacade
@@ -39,14 +46,17 @@ from .core.auth.jwt import decode_token
from .core.auth.repository import AuthRepository
from .models.auth import User
# Initialize singletons
# Initialize singletons lazily to avoid import-time DB side effects during test collection.
# Use absolute path relative to this file to ensure plugins are found regardless of CWD
project_root = Path(__file__).parent.parent.parent
config_path = project_root / "config.json"
# Initialize database before services that use persisted configuration.
init_db()
config_manager = ConfigManager(config_path=str(config_path))
config_manager: Optional[ConfigManager] = None
plugin_loader: Optional[PluginLoader] = None
task_manager: Optional[TaskManager] = None
scheduler_service: Optional[SchedulerService] = None
resource_service: Optional[ResourceService] = None
# [DEF:get_config_manager:Function]
# @COMPLEXITY: 1
@@ -56,29 +66,23 @@ config_manager = ConfigManager(config_path=str(config_path))
# @RETURN: ConfigManager - The shared config manager instance.
def get_config_manager() -> ConfigManager:
"""Dependency injector for ConfigManager."""
global config_manager
if config_manager is None:
init_db()
config_manager = ConfigManager(config_path=str(config_path))
return config_manager
# [/DEF:get_config_manager:Function]
plugin_dir = Path(__file__).parent / "plugins"
plugin_loader = PluginLoader(plugin_dir=str(plugin_dir))
logger.info(f"PluginLoader initialized with directory: {plugin_dir}")
logger.info(f"Available plugins: {[config.name for config in plugin_loader.get_all_plugin_configs()]}")
task_manager = TaskManager(plugin_loader)
logger.info("TaskManager initialized")
scheduler_service = SchedulerService(task_manager, config_manager)
logger.info("SchedulerService initialized")
resource_service = ResourceService()
logger.info("ResourceService initialized")
# Clean Release Redesign Singletons
# Note: These use get_db() which is a generator, so we need a way to provide a session.
# For singletons in dependencies.py, we might need a different approach or
# initialize them inside the dependency functions.
# [DEF:get_plugin_loader:Function]
# @COMPLEXITY: 1
# @PURPOSE: Dependency injector for PluginLoader.
@@ -87,9 +91,19 @@ logger.info("ResourceService initialized")
# @RETURN: PluginLoader - The shared plugin loader instance.
def get_plugin_loader() -> PluginLoader:
"""Dependency injector for PluginLoader."""
global plugin_loader
if plugin_loader is None:
plugin_loader = PluginLoader(plugin_dir=str(plugin_dir))
logger.info(f"PluginLoader initialized with directory: {plugin_dir}")
logger.info(
f"Available plugins: {[config.name for config in plugin_loader.get_all_plugin_configs()]}"
)
return plugin_loader
# [/DEF:get_plugin_loader:Function]
# [DEF:get_task_manager:Function]
# @COMPLEXITY: 1
# @PURPOSE: Dependency injector for TaskManager.
@@ -98,9 +112,16 @@ def get_plugin_loader() -> PluginLoader:
# @RETURN: TaskManager - The shared task manager instance.
def get_task_manager() -> TaskManager:
"""Dependency injector for TaskManager."""
global task_manager
if task_manager is None:
task_manager = TaskManager(get_plugin_loader())
logger.info("TaskManager initialized")
return task_manager
# [/DEF:get_task_manager:Function]
# [DEF:get_scheduler_service:Function]
# @COMPLEXITY: 1
# @PURPOSE: Dependency injector for SchedulerService.
@@ -109,9 +130,16 @@ def get_task_manager() -> TaskManager:
# @RETURN: SchedulerService - The shared scheduler service instance.
def get_scheduler_service() -> SchedulerService:
"""Dependency injector for SchedulerService."""
global scheduler_service
if scheduler_service is None:
scheduler_service = SchedulerService(get_task_manager(), get_config_manager())
logger.info("SchedulerService initialized")
return scheduler_service
# [/DEF:get_scheduler_service:Function]
# [DEF:get_resource_service:Function]
# @COMPLEXITY: 1
# @PURPOSE: Dependency injector for ResourceService.
@@ -120,9 +148,16 @@ def get_scheduler_service() -> SchedulerService:
# @RETURN: ResourceService - The shared resource service instance.
def get_resource_service() -> ResourceService:
"""Dependency injector for ResourceService."""
global resource_service
if resource_service is None:
resource_service = ResourceService()
logger.info("ResourceService initialized")
return resource_service
# [/DEF:get_resource_service:Function]
# [DEF:get_mapping_service:Function]
# @COMPLEXITY: 1
# @PURPOSE: Dependency injector for MappingService.
@@ -131,12 +166,15 @@ def get_resource_service() -> ResourceService:
# @RETURN: MappingService - A new mapping service instance.
def get_mapping_service() -> MappingService:
"""Dependency injector for MappingService."""
return MappingService(config_manager)
return MappingService(get_config_manager())
# [/DEF:get_mapping_service:Function]
_clean_release_repository = CleanReleaseRepository()
# [DEF:get_clean_release_repository:Function]
# @COMPLEXITY: 1
# @PURPOSE: Legacy compatibility shim for CleanReleaseRepository.
@@ -144,6 +182,8 @@ _clean_release_repository = CleanReleaseRepository()
def get_clean_release_repository() -> CleanReleaseRepository:
"""Legacy compatibility shim for CleanReleaseRepository."""
return _clean_release_repository
# [/DEF:get_clean_release_repository:Function]
@@ -172,17 +212,22 @@ def get_clean_release_facade(db = Depends(get_db)) -> CleanReleaseFacade:
approval_repo=approval_repo,
publication_repo=publication_repo,
audit_repo=audit_repo,
config_manager=config_manager
config_manager=get_config_manager(),
)
# [/DEF:get_clean_release_facade:Function]
# [DEF:oauth2_scheme:Variable]
# @RELATION: DEPENDS_ON -> OAuth2PasswordBearer
# @COMPLEXITY: 1
# @PURPOSE: OAuth2 password bearer scheme for token extraction.
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
# [/DEF:oauth2_scheme:Variable]
# [DEF:get_current_user:Function]
# @RELATION: CALLS -> AuthRepository
# @COMPLEXITY: 3
# @PURPOSE: Dependency for retrieving currently authenticated user from a JWT.
# @PRE: JWT token provided in Authorization header.
@@ -199,9 +244,10 @@ def get_current_user(token: str = Depends(oauth2_scheme), db = Depends(get_auth_
)
try:
payload = decode_token(token)
username: str = payload.get("sub")
if username is None:
username_value = payload.get("sub")
if not isinstance(username_value, str) or not username_value:
raise credentials_exception
username = username_value
except JWTError:
raise credentials_exception
@@ -210,9 +256,13 @@ def get_current_user(token: str = Depends(oauth2_scheme), db = Depends(get_auth_
if user is None:
raise credentials_exception
return user
# [/DEF:get_current_user:Function]
# [DEF:has_permission:Function]
# @RELATION: CALLS -> AuthRepository
# @COMPLEXITY: 3
# @PURPOSE: Dependency for checking if the current user has a specific permission.
# @PRE: User is authenticated.
@@ -234,13 +284,21 @@ def has_permission(resource: str, action: str):
return current_user
from .core.auth.logger import log_security_event
log_security_event("PERMISSION_DENIED", current_user.username, {"resource": resource, "action": action})
log_security_event(
"PERMISSION_DENIED",
str(getattr(current_user, "username", "unknown")),
{"resource": resource, "action": action},
)
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail=f"Permission denied for {resource}:{action}"
detail=f"Permission denied for {resource}:{action}",
)
return permission_checker
# [/DEF:has_permission:Function]
# [/DEF:AppDependencies:Module]

39
backend/src/models/__tests__/test_clean_release.py
View File

@@ -36,17 +36,27 @@ def valid_candidate_data():
"source_snapshot_ref": "v1.0.0-snapshot"
}
# [DEF:test_release_candidate_valid:Function]
# @RELATION: BINDS_TO -> __tests__/test_clean_release
# @PURPOSE: Verify that a valid release candidate can be instantiated.
def test_release_candidate_valid(valid_candidate_data):
rc = ReleaseCandidate(**valid_candidate_data)
assert rc.candidate_id == "RC-001"
assert rc.status == ReleaseCandidateStatus.DRAFT
# [/DEF:test_release_candidate_valid:Function]
# [DEF:test_release_candidate_empty_id:Function]
# @RELATION: BINDS_TO -> __tests__/test_clean_release
# @PURPOSE: Verify that a release candidate with an empty ID is rejected.
def test_release_candidate_empty_id(valid_candidate_data):
valid_candidate_data["candidate_id"] = " "
with pytest.raises(ValueError, match="candidate_id must be non-empty"):
ReleaseCandidate(**valid_candidate_data)
# @TEST_FIXTURE: valid_enterprise_policy
# [/DEF:test_release_candidate_empty_id:Function]
@pytest.fixture
def valid_policy_data():
return {
@@ -61,17 +71,30 @@ def valid_policy_data():
}
# @TEST_INVARIANT: policy_purity
# [DEF:test_enterprise_policy_valid:Function]
# @RELATION: BINDS_TO -> __tests__/test_clean_release
# @PURPOSE: Verify that a valid enterprise policy is accepted.
def test_enterprise_policy_valid(valid_policy_data):
policy = CleanProfilePolicy(**valid_policy_data)
assert policy.external_source_forbidden is True
# @TEST_EDGE: enterprise_policy_missing_prohibited
# [/DEF:test_enterprise_policy_valid:Function]
# [DEF:test_enterprise_policy_missing_prohibited:Function]
# @RELATION: BINDS_TO -> __tests__/test_clean_release
# @PURPOSE: Verify that an enterprise policy without prohibited categories is rejected.
def test_enterprise_policy_missing_prohibited(valid_policy_data):
valid_policy_data["prohibited_artifact_categories"] = []
with pytest.raises(ValueError, match="enterprise-clean policy requires prohibited_artifact_categories"):
CleanProfilePolicy(**valid_policy_data)
# @TEST_EDGE: enterprise_policy_external_allowed
# [/DEF:test_enterprise_policy_missing_prohibited:Function]
# [DEF:test_enterprise_policy_external_allowed:Function]
# @RELATION: BINDS_TO -> __tests__/test_clean_release
# @PURPOSE: Verify that an enterprise policy allowing external sources is rejected.
def test_enterprise_policy_external_allowed(valid_policy_data):
valid_policy_data["external_source_forbidden"] = False
with pytest.raises(ValueError, match="enterprise-clean policy requires external_source_forbidden=true"):
@@ -79,6 +102,11 @@ def test_enterprise_policy_external_allowed(valid_policy_data):
# @TEST_INVARIANT: manifest_consistency
# @TEST_EDGE: manifest_count_mismatch
# [/DEF:test_enterprise_policy_external_allowed:Function]
# [DEF:test_manifest_count_mismatch:Function]
# @RELATION: BINDS_TO -> __tests__/test_clean_release
# @PURPOSE: Verify that a manifest with count mismatches is rejected.
def test_manifest_count_mismatch():
summary = ManifestSummary(included_count=1, excluded_count=0, prohibited_detected_count=0)
item = ManifestItem(path="p", category="c", classification=ClassificationType.ALLOWED, reason="r")
@@ -101,6 +129,11 @@ def test_manifest_count_mismatch():
# @TEST_INVARIANT: run_integrity
# @TEST_EDGE: compliant_run_stage_fail
# [/DEF:test_manifest_count_mismatch:Function]
# [DEF:test_compliant_run_validation:Function]
# @RELATION: BINDS_TO -> __tests__/test_clean_release
# @PURPOSE: Verify compliant run validation logic and mandatory stage checks.
def test_compliant_run_validation():
base_run = {
"check_run_id": "run1",
@@ -130,6 +163,11 @@ def test_compliant_run_validation():
with pytest.raises(ValueError, match="compliant run requires all mandatory stages"):
ComplianceCheckRun(**base_run)
# [/DEF:test_compliant_run_validation:Function]
# [DEF:test_report_validation:Function]
# @RELATION: BINDS_TO -> __tests__/test_clean_release
# @PURPOSE: Verify compliance report validation based on status and violation counts.
def test_report_validation():
# Valid blocked report
ComplianceReport(
@@ -147,3 +185,4 @@ def test_report_validation():
operator_summary="Blocked", structured_payload_ref="ref",
violations_count=2, blocking_violations_count=0
)
# [/DEF:test_report_validation:Function]

1
backend/src/models/__tests__/test_models.py
View File

@@ -15,6 +15,7 @@ from src.core.logger import belief_scope
# [DEF:test_environment_model:Function]
# @RELATION: BINDS_TO -> test_models
# @PURPOSE: Tests that Environment model correctly stores values.
# @PRE: Environment class is available.
# @POST: Values are verified.

2
backend/src/models/__tests__/test_report_models.py
View File

@@ -1,8 +1,8 @@
# [DEF:test_report_models:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @PURPOSE: Unit tests for report Pydantic models and their validators
# @LAYER: Domain
# @RELATION: TESTS -> backend.src.models.report
import sys
from pathlib import Path

15
backend/src/models/assistant.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.src.models.assistant:Module]
# [DEF:AssistantModels:Module]
# @COMPLEXITY: 3
# @SEMANTICS: assistant, audit, confirmation, chat
# @PURPOSE: SQLAlchemy models for assistant audit trail and confirmation tokens.
# @LAYER: Domain
# @RELATION: DEPENDS_ON -> backend.src.models.mapping
# @RELATION: DEPENDS_ON -> MappingModels
# @INVARIANT: Assistant records preserve immutable ids and creation timestamps.
from datetime import datetime
@@ -16,6 +16,7 @@ from .mapping import Base
# [DEF:AssistantAuditRecord:Class]
# @COMPLEXITY: 3
# @PURPOSE: Store audit decisions and outcomes produced by assistant command handling.
# @RELATION: INHERITS -> MappingModels
# @PRE: user_id must identify the actor for every record.
# @POST: Audit payload remains available for compliance and debugging.
class AssistantAuditRecord(Base):
@@ -29,12 +30,15 @@ class AssistantAuditRecord(Base):
message = Column(Text, nullable=True)
payload = Column(JSON, nullable=True)
created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
# [/DEF:AssistantAuditRecord:Class]
# [DEF:AssistantMessageRecord:Class]
# @COMPLEXITY: 3
# @PURPOSE: Persist chat history entries for assistant conversations.
# @RELATION: INHERITS -> MappingModels
# @PRE: user_id, conversation_id, role and text must be present.
# @POST: Message row can be queried in chronological order.
class AssistantMessageRecord(Base):
@@ -50,12 +54,15 @@ class AssistantMessageRecord(Base):
confirmation_id = Column(String, nullable=True)
payload = Column(JSON, nullable=True)
created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
# [/DEF:AssistantMessageRecord:Class]
# [DEF:AssistantConfirmationRecord:Class]
# @COMPLEXITY: 3
# @PURPOSE: Persist risky operation confirmation tokens with lifecycle state.
# @RELATION: INHERITS -> MappingModels
# @PRE: intent/dispatch and expiry timestamp must be provided.
# @POST: State transitions can be tracked and audited.
class AssistantConfirmationRecord(Base):
@@ -70,5 +77,7 @@ class AssistantConfirmationRecord(Base):
expires_at = Column(DateTime, nullable=False)
created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
consumed_at = Column(DateTime, nullable=True)
# [/DEF:AssistantConfirmationRecord:Class]
# [/DEF:backend.src.models.assistant:Module]
# [/DEF:AssistantModels:Module]

9
backend/src/models/auth.py
View File

@@ -5,7 +5,7 @@
# @SEMANTICS: auth, models, user, role, permission, sqlalchemy
# @PURPOSE: SQLAlchemy models for multi-user authentication and authorization.
# @LAYER: Domain
# @RELATION: INHERITS_FROM -> [Base]
# @RELATION: INHERITS_FROM -> [MappingModels:Base]
#
# @INVARIANT: Usernames and emails must be unique.
@@ -20,12 +20,16 @@ from .mapping import Base
# [DEF:generate_uuid:Function]
# @PURPOSE: Generates a unique UUID string.
# @POST: Returns a string representation of a new UUID.
# @RELATION: DEPENDS_ON -> uuid
def generate_uuid():
return str(uuid.uuid4())
# [/DEF:generate_uuid:Function]
# [DEF:user_roles:Table]
# @PURPOSE: Association table for many-to-many relationship between Users and Roles.
# @RELATION: DEPENDS_ON -> Base.metadata
# @RELATION: DEPENDS_ON -> User
# @RELATION: DEPENDS_ON -> Role
user_roles = Table(
"user_roles",
Base.metadata,
@@ -36,6 +40,9 @@ user_roles = Table(
# [DEF:role_permissions:Table]
# @PURPOSE: Association table for many-to-many relationship between Roles and Permissions.
# @RELATION: DEPENDS_ON -> Base.metadata
# @RELATION: DEPENDS_ON -> Role
# @RELATION: DEPENDS_ON -> Permission
role_permissions = Table(
"role_permissions",
Base.metadata,

7
backend/src/models/clean_release.py
View File

@@ -1,8 +1,9 @@
# [DEF:backend.src.models.clean_release:Module]
# @COMPLEXITY: 5
# [DEF:CleanReleaseModels:Module]
# @COMPLEXITY: 3
# @SEMANTICS: clean-release, models, lifecycle, compliance, evidence, immutability
# @PURPOSE: Define canonical clean release domain entities and lifecycle guards.
# @LAYER: Domain
# @RELATION: DEPENDS_ON -> MappingModels
# @PRE: Base mapping model and release enums are available.
# @POST: Provides SQLAlchemy and dataclass definitions for governance domain.
# @SIDE_EFFECT: None (schema definition).
@@ -695,4 +696,4 @@ class CleanReleaseAuditLog(Base):
details_json = Column(JSON, default=dict)
# [/DEF:CleanReleaseAuditLog:Class]
# [/DEF:backend.src.models.clean_release:Module]
# [/DEF:CleanReleaseModels:Module]

10
backend/src/models/config.py
View File

@@ -1,11 +1,11 @@
# [DEF:backend.src.models.config:Module]
# [DEF:ConfigModels:Module]
#
# @COMPLEXITY: 5
# @COMPLEXITY: 3
# @SEMANTICS: database, config, settings, sqlalchemy, notification
# @PURPOSE: Defines SQLAlchemy persistence models for application and notification configuration records.
# @LAYER: Domain
# @RELATION: [DEPENDS_ON] ->[sqlalchemy]
# @RELATION: [DEPENDS_ON] ->[backend.src.models.mapping:Base]
# @RELATION: [DEPENDS_ON] -> [MappingModels:Base]
# @INVARIANT: Configuration payload and notification credentials must remain persisted as non-null JSON documents.
from sqlalchemy import Column, String, DateTime, JSON, Boolean
@@ -50,4 +50,4 @@ class NotificationConfig(Base):
import uuid
# [/DEF:backend.src.models.config:Module]
# [/DEF:ConfigModels:Module]

4
backend/src/models/connection.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.models.connection:Module]
# [DEF:ConnectionModels:Module]
#
# @COMPLEXITY: 1
# @SEMANTICS: database, connection, configuration, sqlalchemy, sqlite
@@ -33,4 +33,4 @@ class ConnectionConfig(Base):
updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
# [/DEF:ConnectionConfig:Class]
# [/DEF:backend.src.models.connection:Module]
# [/DEF:ConnectionModels:Module]

6
backend/src/models/dashboard.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.src.models.dashboard:Module]
# [DEF:DashboardModels:Module]
# @COMPLEXITY: 3
# @SEMANTICS: dashboard, model, metadata, migration
# @PURPOSE: Defines data models for dashboard metadata and selection.
# @LAYER: Model
# @RELATION: USED_BY -> backend.src.api.routes.migration
# @RELATION: USED_BY -> MigrationApi
from pydantic import BaseModel
from typing import List
@@ -29,4 +29,4 @@ class DashboardSelection(BaseModel):
fix_cross_filters: bool = True
# [/DEF:DashboardSelection:Class]
# [/DEF:backend.src.models.dashboard:Module]
# [/DEF:DashboardModels:Module]

6
backend/src/models/llm.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.src.models.llm:Module]
# [DEF:LlmModels:Module]
# @COMPLEXITY: 3
# @SEMANTICS: llm, models, sqlalchemy, persistence
# @PURPOSE: SQLAlchemy models for LLM provider configuration and validation results.
# @LAYER: Domain
# @RELATION: INHERITS_FROM -> backend.src.models.mapping.Base
# @RELATION: INHERITS_FROM -> MappingModels:Base
from sqlalchemy import Column, String, Boolean, DateTime, JSON, Text, Time, ForeignKey
from datetime import datetime
@@ -65,4 +65,4 @@ class ValidationRecord(Base):
raw_response = Column(Text, nullable=True)
# [/DEF:ValidationRecord:Class]
# [/DEF:backend.src.models.llm:Module]
# [/DEF:LlmModels:Module]

5
backend/src/models/mapping.py
View File

@@ -5,7 +5,8 @@
# @SEMANTICS: database, mapping, environment, migration, sqlalchemy, sqlite
# @PURPOSE: Defines the database schema for environment metadata and database mappings using SQLAlchemy.
# @LAYER: Domain
# @RELATION: DEPENDS_ON -> [sqlalchemy]
# @RELATION: DEPENDS_ON -> sqlalchemy
#
# @INVARIANT: All primary keys are UUID strings.
# @CONSTRAINT: source_env_id and target_env_id must be valid environment IDs.
@@ -44,6 +45,7 @@ class MigrationStatus(enum.Enum):
# [DEF:Environment:Class]
# @COMPLEXITY: 3
# @PURPOSE: Represents a Superset instance environment.
# @RELATION: DEPENDS_ON -> MappingModels
class Environment(Base):
__tablename__ = "environments"
@@ -87,6 +89,7 @@ class MigrationJob(Base):
# @COMPLEXITY: 3
# @PURPOSE: Maps a universal UUID for a resource to its actual ID on a specific environment.
# @TEST_DATA: resource_mapping_record -> {'environment_id': 'prod-env-1', 'resource_type': 'chart', 'uuid': '123e4567-e89b-12d3-a456-426614174000', 'remote_integer_id': '42'}
# @RELATION: DEPENDS_ON -> MappingModels
class ResourceMapping(Base):
__tablename__ = "resource_mappings"

3
backend/src/models/profile.py
View File

@@ -6,7 +6,7 @@
# @PURPOSE: Defines persistent per-user profile settings for dashboard filter, Git identity/token, and UX preferences.
# @LAYER: Domain
# @RELATION: DEPENDS_ON -> [AuthModels]
# @RELATION: INHERITS_FROM -> [Base]
# @RELATION: INHERITS_FROM -> [MappingModels:Base]
#
# @INVARIANT: Exactly one preference row exists per user_id.
# @INVARIANT: Sensitive Git token is stored encrypted and never returned in plaintext.
@@ -23,6 +23,7 @@ from .mapping import Base
# [DEF:UserDashboardPreference:Class]
# @COMPLEXITY: 3
# @PURPOSE: Stores Superset username binding and default "my dashboards" toggle for one authenticated user.
# @RELATION: INHERITS -> MappingModels:Base
class UserDashboardPreference(Base):
__tablename__ = "user_dashboard_preferences"

37
backend/src/models/report.py
View File

@@ -1,5 +1,5 @@
# [DEF:backend.src.models.report:Module]
# @COMPLEXITY: 5
# [DEF:ReportModels:Module]
# @COMPLEXITY: 3
# @SEMANTICS: reports, models, pydantic, normalization, pagination
# @PURPOSE: Canonical report schemas for unified task reporting across heterogeneous task types.
# @LAYER: Domain
@@ -7,7 +7,7 @@
# @POST: Provides validated schemas for cross-plugin reporting and UI consumption.
# @SIDE_EFFECT: None (schema definition).
# @DATA_CONTRACT: Model[TaskReport, ReportCollection, ReportDetailView]
# @RELATION: [DEPENDS_ON] ->[backend.src.core.task_manager.models]
# @RELATION: [DEPENDS_ON] -> [TaskModels]
# @INVARIANT: Canonical report fields are always present for every report item.
# [SECTION: IMPORTS]
@@ -20,8 +20,9 @@ from pydantic import BaseModel, Field, field_validator, model_validator
# [DEF:TaskType:Class]
# @COMPLEXITY: 5
# @COMPLEXITY: 3
# @INVARIANT: Must contain valid generic task type mappings.
# @RELATION: DEPENDS_ON -> ReportModels
# @SEMANTICS: enum, type, task
# @PURPOSE: Supported normalized task report types.
class TaskType(str, Enum):
@@ -31,11 +32,13 @@ class TaskType(str, Enum):
DOCUMENTATION = "documentation"
CLEAN_RELEASE = "clean_release"
UNKNOWN = "unknown"
# [/DEF:TaskType:Class]
# [DEF:ReportStatus:Class]
# @COMPLEXITY: 5
# @COMPLEXITY: 3
# @INVARIANT: TaskStatus enum mapping logic holds.
# @SEMANTICS: enum, status, task
# @PURPOSE: Supported normalized report status values.
@@ -44,11 +47,13 @@ class ReportStatus(str, Enum):
FAILED = "failed"
IN_PROGRESS = "in_progress"
PARTIAL = "partial"
# [/DEF:ReportStatus:Class]
# [DEF:ErrorContext:Class]
# @COMPLEXITY: 5
# @COMPLEXITY: 3
# @INVARIANT: The properties accurately describe error state.
# @SEMANTICS: error, context, payload
# @PURPOSE: Error and recovery context for failed/partial reports.
@@ -69,11 +74,13 @@ class ErrorContext(BaseModel):
code: Optional[str] = None
message: str
next_actions: List[str] = Field(default_factory=list)
# [/DEF:ErrorContext:Class]
# [DEF:TaskReport:Class]
# @COMPLEXITY: 5
# @COMPLEXITY: 3
# @INVARIANT: Must represent canonical task record attributes.
# @SEMANTICS: report, model, summary
# @PURPOSE: Canonical normalized report envelope for one task execution.
@@ -126,11 +133,13 @@ class TaskReport(BaseModel):
if not isinstance(value, str) or not value.strip():
raise ValueError("Value must be a non-empty string")
return value.strip()
# [/DEF:TaskReport:Class]
# [DEF:ReportQuery:Class]
# @COMPLEXITY: 5
# @COMPLEXITY: 3
# @INVARIANT: Time and pagination queries are mutually consistent.
# @SEMANTICS: query, filter, search
# @PURPOSE: Query object for server-side report filtering, sorting, and pagination.
@@ -184,11 +193,13 @@ class ReportQuery(BaseModel):
if self.time_from and self.time_to and self.time_from > self.time_to:
raise ValueError("time_from must be less than or equal to time_to")
return self
# [/DEF:ReportQuery:Class]
# [DEF:ReportCollection:Class]
# @COMPLEXITY: 5
# @COMPLEXITY: 3
# @INVARIANT: Represents paginated data correctly.
# @SEMANTICS: collection, pagination
# @PURPOSE: Paginated collection of normalized task reports.
@@ -209,11 +220,13 @@ class ReportCollection(BaseModel):
page_size: int = Field(ge=1)
has_next: bool
applied_filters: ReportQuery
# [/DEF:ReportCollection:Class]
# [DEF:ReportDetailView:Class]
# @COMPLEXITY: 5
# @COMPLEXITY: 3
# @INVARIANT: Incorporates a report and logs correctly.
# @SEMANTICS: view, detail, logs
# @PURPOSE: Detailed report representation including diagnostics and recovery actions.
@@ -230,6 +243,8 @@ class ReportDetailView(BaseModel):
timeline: List[Dict[str, Any]] = Field(default_factory=list)
diagnostics: Optional[Dict[str, Any]] = None
next_actions: List[str] = Field(default_factory=list)
# [/DEF:ReportDetailView:Class]
# [/DEF:backend.src.models.report:Module]
# [/DEF:ReportModels:Module]

4
backend/src/models/storage.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.models.storage:Module]
# [DEF:StorageModels:Module]
# @COMPLEXITY: 1
# @SEMANTICS: storage, file, model, pydantic
# @PURPOSE: Data models for the storage system.
@@ -41,4 +41,4 @@ class StoredFile(BaseModel):
mime_type: Optional[str] = Field(None, description="MIME type of the file.")
# [/DEF:StoredFile:Class]
# [/DEF:backend.src.models.storage:Module]
# [/DEF:StorageModels:Module]

6
backend/src/models/task.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.models.task:Module]
# [DEF:TaskModels:Module]
#
# @COMPLEXITY: 1
# @SEMANTICS: database, task, record, sqlalchemy, sqlite
@@ -36,7 +36,7 @@ class TaskRecord(Base):
# [DEF:TaskLogRecord:Class]
# @PURPOSE: Represents a single persistent log entry for a task.
# @COMPLEXITY: 5
# @COMPLEXITY: 3
# @RELATION: DEPENDS_ON -> TaskRecord
# @INVARIANT: Each log entry belongs to exactly one task.
#
@@ -113,4 +113,4 @@ class TaskLogRecord(Base):
)
# [/DEF:TaskLogRecord:Class]
# [/DEF:backend.src.models.task:Module]
# [/DEF:TaskModels:Module]

6
backend/src/plugins/llm_analysis/__tests__/test_client_headers.py
View File

@@ -1,4 +1,5 @@
# [DEF:backend.src.plugins.llm_analysis.__tests__.test_client_headers:Module]
# [DEF:TestClientHeaders:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, llm-client, openrouter, headers
# @PURPOSE: Verify OpenRouter client initialization includes provider-specific headers.
@@ -8,6 +9,7 @@ from src.plugins.llm_analysis.service import LLMClient
# [DEF:test_openrouter_client_includes_referer_and_title_headers:Function]
# @RELATION: BINDS_TO -> TestClientHeaders
# @PURPOSE: OpenRouter requests should carry site/app attribution headers for compatibility.
# @PRE: Client is initialized for OPENROUTER provider.
# @POST: Async client headers include Authorization, HTTP-Referer, and X-Title.
@@ -27,4 +29,4 @@ def test_openrouter_client_includes_referer_and_title_headers(monkeypatch):
assert headers["HTTP-Referer"] == "http://localhost:8000"
assert headers["X-Title"] == "ss-tools-test"
# [/DEF:test_openrouter_client_includes_referer_and_title_headers:Function]
# [/DEF:backend.src.plugins.llm_analysis.__tests__.test_client_headers:Module]
# [/DEF:TestClientHeaders:Module]

7
backend/src/plugins/llm_analysis/__tests__/test_service.py
View File

@@ -1,4 +1,5 @@
# [DEF:backend.src.plugins.llm_analysis.__tests__.test_service:Module]
# [DEF:TestService:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, llm-analysis, fallback, provider-error, unknown-status
# @PURPOSE: Verify LLM analysis transport/provider failures do not masquerade as dashboard FAIL results.
@@ -10,6 +11,7 @@ from src.plugins.llm_analysis.service import LLMClient
# [DEF:test_test_runtime_connection_uses_json_completion_transport:Function]
# @RELATION: BINDS_TO -> TestService
# @PURPOSE: Provider self-test must exercise the same chat completion transport as runtime analysis.
# @PRE: get_json_completion is available on initialized client.
# @POST: Self-test forwards a lightweight user message into get_json_completion and returns its payload.
@@ -38,6 +40,7 @@ async def test_test_runtime_connection_uses_json_completion_transport(monkeypatc
# [DEF:test_analyze_dashboard_provider_error_maps_to_unknown:Function]
# @RELATION: BINDS_TO -> TestService
# @PURPOSE: Infrastructure/provider failures must produce UNKNOWN analysis status rather than FAIL.
# @PRE: LLMClient.get_json_completion raises provider/auth exception.
# @POST: Returned payload uses status=UNKNOWN and issue severity UNKNOWN.
@@ -64,4 +67,4 @@ async def test_analyze_dashboard_provider_error_maps_to_unknown(monkeypatch, tmp
assert "Failed to get response from LLM" in result["summary"]
assert result["issues"][0]["severity"] == "UNKNOWN"
# [/DEF:test_analyze_dashboard_provider_error_maps_to_unknown:Function]
# [/DEF:backend.src.plugins.llm_analysis.__tests__.test_service:Module]
# [/DEF:TestService:Module]

8
backend/src/schemas/__tests__/test_settings_and_health_schemas.py
View File

@@ -1,4 +1,5 @@
# [DEF:backend.src.schemas.__tests__.test_settings_and_health_schemas:Module]
# [DEF:TestSettingsAndHealthSchemas:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @PURPOSE: Regression tests for settings and health schema contracts updated in 026 fix batch.
@@ -10,6 +11,7 @@ from src.schemas.settings import ValidationPolicyCreate
# [DEF:test_validation_policy_create_accepts_structured_custom_channels:Function]
# @RELATION: BINDS_TO -> TestSettingsAndHealthSchemas
# @PURPOSE: Ensure policy schema accepts structured custom channel objects with type/target fields.
def test_validation_policy_create_accepts_structured_custom_channels():
payload = {
@@ -34,6 +36,7 @@ def test_validation_policy_create_accepts_structured_custom_channels():
# [DEF:test_validation_policy_create_rejects_legacy_string_custom_channels:Function]
# @RELATION: BINDS_TO -> TestSettingsAndHealthSchemas
# @PURPOSE: Ensure legacy list[str] custom channel payload is rejected by typed channel contract.
def test_validation_policy_create_rejects_legacy_string_custom_channels():
payload = {
@@ -53,6 +56,7 @@ def test_validation_policy_create_rejects_legacy_string_custom_channels():
# [DEF:test_dashboard_health_item_status_accepts_only_whitelisted_values:Function]
# @RELATION: BINDS_TO -> TestSettingsAndHealthSchemas
# @PURPOSE: Verify strict grouped regex only accepts PASS/WARN/FAIL/UNKNOWN exact statuses.
def test_dashboard_health_item_status_accepts_only_whitelisted_values():
valid = DashboardHealthItem(
@@ -81,4 +85,4 @@ def test_dashboard_health_item_status_accepts_only_whitelisted_values():
# [/DEF:test_dashboard_health_item_status_accepts_only_whitelisted_values:Function]
# [/DEF:backend.src.schemas.__tests__.test_settings_and_health_schemas:Module]
# [/DEF:TestSettingsAndHealthSchemas:Module]

6
backend/src/services/__init__.py
View File

@@ -1,5 +1,5 @@
# [DEF:backend.src.services:Module]
# @COMPLEXITY: 3
# [DEF:services:Module]
# @COMPLEXITY: 2
# @SEMANTICS: services, package, init
# @PURPOSE: Package initialization for services module
# @LAYER: Core
@@ -18,4 +18,4 @@ def __getattr__(name):
from .resource_service import ResourceService
return ResourceService
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
# [/DEF:backend.src.services:Module]
# [/DEF:services:Module]

3
backend/src/services/__tests__/test_encryption_manager.py
View File

@@ -1,9 +1,9 @@
# [DEF:test_encryption_manager:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: encryption, security, fernet, api-keys, tests
# @PURPOSE: Unit tests for EncryptionManager encrypt/decrypt functionality.
# @LAYER: Domain
# @RELATION: TESTS -> backend.src.services.llm_provider.EncryptionManager
# @INVARIANT: Encrypt+decrypt roundtrip always returns original plaintext.
import sys
@@ -16,6 +16,7 @@ from cryptography.fernet import Fernet, InvalidToken
# [DEF:TestEncryptionManager:Class]
# @RELATION: BINDS_TO -> test_encryption_manager
# @PURPOSE: Validate EncryptionManager encrypt/decrypt roundtrip, uniqueness, and error handling.
# @PRE: cryptography package installed.
# @POST: All encrypt/decrypt invariants verified.

11
backend/src/services/__tests__/test_llm_plugin_persistence.py
View File

@@ -11,7 +11,9 @@ from src.plugins.llm_analysis import plugin as plugin_module
# [DEF:_DummyLogger:Class]
# @RELATION: BINDS_TO ->[test_llm_plugin_persistence]
# @COMPLEXITY: 1
# @PURPOSE: Minimal logger shim for TaskContext-like objects used in tests.
# @INVARIANT: Logging methods are no-ops and must not mutate test state.
class _DummyLogger:
def with_source(self, _source: str):
return self
@@ -34,7 +36,9 @@ class _DummyLogger:
# [DEF:_FakeDBSession:Class]
# @RELATION: BINDS_TO ->[test_llm_plugin_persistence]
# @COMPLEXITY: 2
# @PURPOSE: Captures persisted records for assertion and mimics SQLAlchemy session methods used by plugin.
# @INVARIANT: add/commit/close provide only persistence signals asserted by this test.
class _FakeDBSession:
def __init__(self):
self.added = None
@@ -90,6 +94,11 @@ async def test_dashboard_validation_plugin_persists_task_and_environment_ids(
async def capture_dashboard(self, _dashboard_id, _screenshot_path):
return None
# [DEF:_FakeLLMClient:Class]
# @RELATION: BINDS_TO ->[test_dashboard_validation_plugin_persists_task_and_environment_ids]
# @COMPLEXITY: 2
# @PURPOSE: Deterministic LLM client double returning canonical analysis payload for persistence-path assertions.
# @INVARIANT: analyze_dashboard is side-effect free and returns schema-compatible PASS result.
class _FakeLLMClient:
def __init__(self, **_kwargs):
return None
@@ -101,6 +110,8 @@ async def test_dashboard_validation_plugin_persists_task_and_environment_ids(
"issues": [],
}
# [/DEF:_FakeLLMClient:Class]
class _FakeNotificationService:
def __init__(self, *_args, **_kwargs):
return None

30
backend/src/services/__tests__/test_llm_prompt_templates.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.src.services.__tests__.test_llm_prompt_templates:Module]
# [DEF:test_llm_prompt_templates:Module]
# @COMPLEXITY: 3
# @SEMANTICS: tests, llm, prompts, templates, settings
# @PURPOSE: Validate normalization and rendering behavior for configurable LLM prompt templates.
# @LAYER: Domain Tests
# @RELATION: DEPENDS_ON -> backend.src.services.llm_prompt_templates
# @RELATION: DEPENDS_ON ->[backend.src.services.llm_prompt_templates:Function]
# @INVARIANT: All required prompt keys remain available after normalization.
from src.services.llm_prompt_templates import (
@@ -18,10 +18,13 @@ from src.services.llm_prompt_templates import (
# [DEF:test_normalize_llm_settings_adds_default_prompts:Function]
# @RELATION: BINDS_TO -> test_llm_prompt_templates
# @COMPLEXITY: 3
# @PURPOSE: Ensure legacy/partial llm settings are expanded with all prompt defaults.
# @PRE: Input llm settings do not contain complete prompts object.
# @POST: Returned structure includes required prompt templates with fallback defaults.
# [DEF:test_normalize_llm_settings_adds_default_prompts:Function]
# @RELATION: BINDS_TO -> test_llm_prompt_templates
def test_normalize_llm_settings_adds_default_prompts():
normalized = normalize_llm_settings({"default_provider": "x"})
@@ -39,10 +42,15 @@ def test_normalize_llm_settings_adds_default_prompts():
# [DEF:test_normalize_llm_settings_keeps_custom_prompt_values:Function]
# @RELATION: BINDS_TO -> test_llm_prompt_templates
# @COMPLEXITY: 3
# @PURPOSE: Ensure user-customized prompt values are preserved during normalization.
# @PRE: Input llm settings contain custom prompt override.
# @POST: Custom prompt value remains unchanged in normalized output.
# [/DEF:test_normalize_llm_settings_adds_default_prompts:Function]
# [DEF:test_normalize_llm_settings_keeps_custom_prompt_values:Function]
# @RELATION: BINDS_TO -> test_llm_prompt_templates
def test_normalize_llm_settings_keeps_custom_prompt_values():
custom = "Doc for {dataset_name} using {columns_json}"
normalized = normalize_llm_settings(
@@ -54,10 +62,15 @@ def test_normalize_llm_settings_keeps_custom_prompt_values():
# [DEF:test_render_prompt_replaces_known_placeholders:Function]
# @RELATION: BINDS_TO -> test_llm_prompt_templates
# @COMPLEXITY: 3
# @PURPOSE: Ensure template placeholders are deterministically replaced.
# @PRE: Template contains placeholders matching provided variables.
# @POST: Rendered prompt string contains substituted values.
# [/DEF:test_normalize_llm_settings_keeps_custom_prompt_values:Function]
# [DEF:test_render_prompt_replaces_known_placeholders:Function]
# @RELATION: BINDS_TO -> test_llm_prompt_templates
def test_render_prompt_replaces_known_placeholders():
rendered = render_prompt(
"Hello {name}, diff={diff}",
@@ -69,8 +82,11 @@ def test_render_prompt_replaces_known_placeholders():
# [DEF:test_is_multimodal_model_detects_known_vision_models:Function]
# @COMPLEXITY: 3
# @RELATION: BINDS_TO -> test_llm_prompt_templates
# @COMPLEXITY: 2
# @PURPOSE: Ensure multimodal model detection recognizes common vision-capable model names.
# [/DEF:test_render_prompt_replaces_known_placeholders:Function]
def test_is_multimodal_model_detects_known_vision_models():
assert is_multimodal_model("gpt-4o") is True
assert is_multimodal_model("claude-3-5-sonnet") is True
@@ -80,7 +96,8 @@ def test_is_multimodal_model_detects_known_vision_models():
# [DEF:test_resolve_bound_provider_id_prefers_binding_then_default:Function]
# @COMPLEXITY: 3
# @RELATION: BINDS_TO -> test_llm_prompt_templates
# @COMPLEXITY: 2
# @PURPOSE: Verify provider binding resolution priority.
def test_resolve_bound_provider_id_prefers_binding_then_default():
settings = {
@@ -93,7 +110,8 @@ def test_resolve_bound_provider_id_prefers_binding_then_default():
# [DEF:test_normalize_llm_settings_keeps_assistant_planner_settings:Function]
# @COMPLEXITY: 3
# @RELATION: BINDS_TO -> test_llm_prompt_templates
# @COMPLEXITY: 2
# @PURPOSE: Ensure assistant planner provider/model fields are preserved and normalized.
def test_normalize_llm_settings_keeps_assistant_planner_settings():
normalized = normalize_llm_settings(
@@ -107,4 +125,4 @@ def test_normalize_llm_settings_keeps_assistant_planner_settings():
# [/DEF:test_normalize_llm_settings_keeps_assistant_planner_settings:Function]
# [/DEF:backend.src.services.__tests__.test_llm_prompt_templates:Module]
# [/DEF:test_llm_prompt_templates:Module]

32
backend/src/services/__tests__/test_llm_provider.py
View File

@@ -14,11 +14,14 @@ from src.plugins.llm_analysis.models import LLMProviderConfig, LLMProviderType
# [DEF:_test_encryption_key_fixture:Global]
# @PURPOSE: Ensure encryption-dependent provider tests run with a valid Fernet key.
# @RELATION: DEPENDS_ON ->[pytest:Module]
os.environ.setdefault("ENCRYPTION_KEY", Fernet.generate_key().decode())
# [/DEF:_test_encryption_key_fixture:Global]
# @TEST_CONTRACT: EncryptionManagerModel -> Invariants
# @TEST_INVARIANT: symmetric_encryption
# [DEF:test_encryption_cycle:Function]
# @RELATION: BINDS_TO -> __tests__/test_llm_provider
def test_encryption_cycle():
"""Verify encrypted data can be decrypted back to original string."""
manager = EncryptionManager()
@@ -28,6 +31,10 @@ def test_encryption_cycle():
assert manager.decrypt(encrypted) == original
# @TEST_EDGE: empty_string_encryption
# [/DEF:test_encryption_cycle:Function]
# [DEF:test_empty_string_encryption:Function]
# @RELATION: BINDS_TO -> __tests__/test_llm_provider
def test_empty_string_encryption():
manager = EncryptionManager()
original = ""
@@ -35,12 +42,18 @@ def test_empty_string_encryption():
assert manager.decrypt(encrypted) == ""
# @TEST_EDGE: decrypt_invalid_data
# [/DEF:test_empty_string_encryption:Function]
# [DEF:test_decrypt_invalid_data:Function]
# @RELATION: BINDS_TO -> __tests__/test_llm_provider
def test_decrypt_invalid_data():
manager = EncryptionManager()
with pytest.raises(Exception):
manager.decrypt("not-encrypted-string")
# @TEST_FIXTURE: mock_db_session
# [/DEF:test_decrypt_invalid_data:Function]
@pytest.fixture
def mock_db():
return MagicMock(spec=Session)
@@ -49,11 +62,17 @@ def mock_db():
def service(mock_db):
return LLMProviderService(db=mock_db)
# [DEF:test_get_all_providers:Function]
# @RELATION: BINDS_TO -> __tests__/test_llm_provider
def test_get_all_providers(service, mock_db):
service.get_all_providers()
mock_db.query.assert_called()
mock_db.query().all.assert_called()
# [/DEF:test_get_all_providers:Function]
# [DEF:test_create_provider:Function]
# @RELATION: BINDS_TO -> __tests__/test_llm_provider
def test_create_provider(service, mock_db):
config = LLMProviderConfig(
provider_type=LLMProviderType.OPENAI,
@@ -73,6 +92,10 @@ def test_create_provider(service, mock_db):
# Decrypt to verify it matches
assert EncryptionManager().decrypt(provider.api_key) == "sk-test"
# [/DEF:test_create_provider:Function]
# [DEF:test_get_decrypted_api_key:Function]
# @RELATION: BINDS_TO -> __tests__/test_llm_provider
def test_get_decrypted_api_key(service, mock_db):
# Setup mock provider
encrypted_key = EncryptionManager().encrypt("secret-value")
@@ -82,10 +105,18 @@ def test_get_decrypted_api_key(service, mock_db):
key = service.get_decrypted_api_key("p1")
assert key == "secret-value"
# [/DEF:test_get_decrypted_api_key:Function]
# [DEF:test_get_decrypted_api_key_not_found:Function]
# @RELATION: BINDS_TO -> __tests__/test_llm_provider
def test_get_decrypted_api_key_not_found(service, mock_db):
mock_db.query().filter().first.return_value = None
assert service.get_decrypted_api_key("missing") is None
# [/DEF:test_get_decrypted_api_key_not_found:Function]
# [DEF:test_update_provider_ignores_masked_placeholder_api_key:Function]
# @RELATION: BINDS_TO -> __tests__/test_llm_provider
def test_update_provider_ignores_masked_placeholder_api_key(service, mock_db):
existing_encrypted = EncryptionManager().encrypt("secret-value")
mock_provider = LLMProvider(
@@ -114,3 +145,4 @@ def test_update_provider_ignores_masked_placeholder_api_key(service, mock_db):
assert updated.api_key == existing_encrypted
assert EncryptionManager().decrypt(updated.api_key) == "secret-value"
assert updated.is_active is False
# [/DEF:test_update_provider_ignores_masked_placeholder_api_key:Function]

10
backend/src/services/__tests__/test_rbac_permission_catalog.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.src.services.__tests__.test_rbac_permission_catalog:Module]
# [DEF:test_rbac_permission_catalog:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, rbac, permissions, catalog, discovery, sync
# @PURPOSE: Verifies RBAC permission catalog discovery and idempotent synchronization behavior.
# @LAYER: Service Tests
# @RELATION: TESTS -> backend.src.services.rbac_permission_catalog
# @INVARIANT: Synchronization adds only missing normalized permission pairs.
# [SECTION: IMPORTS]
@@ -15,6 +15,7 @@ import src.services.rbac_permission_catalog as catalog
# [DEF:test_discover_route_permissions_extracts_declared_pairs_and_ignores_tests:Function]
# @RELATION: BINDS_TO -> test_rbac_permission_catalog
# @PURPOSE: Ensures route-scanner extracts has_permission pairs from route files and skips __tests__.
# @PRE: Temporary route directory contains route and test files.
# @POST: Returned set includes production route permissions and excludes test-only declarations.
@@ -52,6 +53,7 @@ def test_discover_route_permissions_extracts_declared_pairs_and_ignores_tests(tm
# [DEF:test_discover_declared_permissions_unions_route_and_plugin_permissions:Function]
# @RELATION: BINDS_TO -> test_rbac_permission_catalog
# @PURPOSE: Ensures full catalog includes route-level permissions plus dynamic plugin EXECUTE rights.
# @PRE: Route discovery and plugin loader both return permission sources.
# @POST: Result set contains union of both sources.
@@ -78,6 +80,7 @@ def test_discover_declared_permissions_unions_route_and_plugin_permissions(monke
# [DEF:test_sync_permission_catalog_inserts_only_missing_normalized_pairs:Function]
# @RELATION: BINDS_TO -> test_rbac_permission_catalog
# @PURPOSE: Ensures synchronization inserts only missing pairs and normalizes action/resource tokens.
# @PRE: DB already contains subset of permissions.
# @POST: Only missing normalized pairs are inserted and commit is executed once.
@@ -111,6 +114,7 @@ def test_sync_permission_catalog_inserts_only_missing_normalized_pairs():
# [DEF:test_sync_permission_catalog_is_noop_when_all_permissions_exist:Function]
# @RELATION: BINDS_TO -> test_rbac_permission_catalog
# @PURPOSE: Ensures synchronization is idempotent when all declared pairs already exist.
# @PRE: DB contains full declared permission set.
# @POST: No inserts are added and commit is not called.
@@ -137,4 +141,4 @@ def test_sync_permission_catalog_is_noop_when_all_permissions_exist():
# [/DEF:test_sync_permission_catalog_is_noop_when_all_permissions_exist:Function]
# [/DEF:backend.src.services.__tests__.test_rbac_permission_catalog:Module]
# [/DEF:test_rbac_permission_catalog:Module]

20
backend/src/services/auth_service.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.services.auth_service:Module]
# [DEF:auth_service:Module]
# @COMPLEXITY: 5
# @SEMANTICS: auth, service, business-logic, login, jwt, adfs, jit-provisioning
# @PURPOSE: Orchestrates credential authentication and ADFS JIT user provisioning.
@@ -30,7 +30,7 @@ from ..core.logger import belief_scope
# @COMPLEXITY: 3
# @PURPOSE: Provides high-level authentication services.
class AuthService:
# [DEF:AuthService.__init__:Function]
# [DEF:AuthService_init:Function]
# @COMPLEXITY: 1
# @PURPOSE: Initializes the authentication service with repository access over an active DB session.
# @PRE: db is a valid SQLAlchemy Session instance bound to the auth persistence context.
@@ -41,9 +41,9 @@ class AuthService:
def __init__(self, db: Session):
self.db = db
self.repo = AuthRepository(db)
# [/DEF:AuthService.__init__:Function]
# [/DEF:AuthService_init:Function]
# [DEF:AuthService.authenticate_user:Function]
# [DEF:authenticate_user:Function]
# @COMPLEXITY: 3
# @PURPOSE: Validates credentials and account state for local username/password authentication.
# @PRE: username and password are non-empty credential inputs.
@@ -68,9 +68,9 @@ class AuthService:
self.db.refresh(user)
return user
# [/DEF:AuthService.authenticate_user:Function]
# [/DEF:authenticate_user:Function]
# [DEF:AuthService.create_session:Function]
# [DEF:create_session:Function]
# @COMPLEXITY: 3
# @PURPOSE: Issues an access token payload for an already authenticated user.
# @PRE: user is a valid User entity containing username and iterable roles with role.name values.
@@ -86,9 +86,9 @@ class AuthService:
data={"sub": user.username, "scopes": roles}
)
return {"access_token": access_token, "token_type": "bearer"}
# [/DEF:AuthService.create_session:Function]
# [/DEF:create_session:Function]
# [DEF:AuthService.provision_adfs_user:Function]
# [DEF:provision_adfs_user:Function]
# @COMPLEXITY: 3
# @PURPOSE: Performs ADFS Just-In-Time provisioning and role synchronization from AD group mappings.
# @PRE: user_info contains identity claims where at least one of 'upn' or 'email' is present; 'groups' may be absent.
@@ -125,7 +125,7 @@ class AuthService:
self.db.refresh(user)
return user
# [/DEF:AuthService.provision_adfs_user:Function]
# [/DEF:provision_adfs_user:Function]
# [/DEF:AuthService:Class]
# [/DEF:backend.src.services.auth_service:Module]
# [/DEF:auth_service:Module]

40
backend/src/services/clean_release/__tests__/test_audit_service.py
View File

@@ -1,27 +1,53 @@
# [DEF:backend.tests.services.clean_release.test_audit_service:Module]
# [DEF:TestAuditService:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, clean-release, audit, logging
# @PURPOSE: Validate audit hooks emit expected log patterns for clean release lifecycle.
# @LAYER: Infra
# @RELATION: TESTS -> backend.src.services.clean_release.audit_service
from unittest.mock import patch
from src.services.clean_release.audit_service import audit_preparation, audit_check_run, audit_report
from src.services.clean_release.audit_service import (
audit_preparation,
audit_check_run,
audit_report,
)
@patch("src.services.clean_release.audit_service.logger")
# [DEF:test_audit_preparation:Function]
# @RELATION: BINDS_TO -> TestAuditService
def test_audit_preparation(mock_logger):
audit_preparation("cand-1", "PREPARED")
mock_logger.info.assert_called_with("[REASON] clean-release preparation candidate=cand-1 status=PREPARED")
mock_logger.info.assert_called_with(
"[REASON] clean-release preparation candidate=cand-1 status=PREPARED"
)
# [/DEF:test_audit_preparation:Function]
@patch("src.services.clean_release.audit_service.logger")
# [DEF:test_audit_check_run:Function]
# @RELATION: BINDS_TO -> TestAuditService
def test_audit_check_run(mock_logger):
audit_check_run("check-1", "COMPLIANT")
mock_logger.info.assert_called_with("[REFLECT] clean-release check_run=check-1 final_status=COMPLIANT")
mock_logger.info.assert_called_with(
"[REFLECT] clean-release check_run=check-1 final_status=COMPLIANT"
)
# [/DEF:test_audit_check_run:Function]
@patch("src.services.clean_release.audit_service.logger")
# [DEF:test_audit_report:Function]
# @RELATION: BINDS_TO -> TestAuditService
def test_audit_report(mock_logger):
audit_report("rep-1", "cand-1")
mock_logger.info.assert_called_with("[EXPLORE] clean-release report_id=rep-1 candidate=cand-1")
mock_logger.info.assert_called_with(
"[EXPLORE] clean-release report_id=rep-1 candidate=cand-1"
)
# [/DEF:backend.tests.services.clean_release.test_audit_service:Module]
# [/DEF:test_audit_report:Function]
# [/DEF:TestAuditService:Module]

10
backend/src/services/clean_release/__tests__/test_compliance_orchestrator.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.tests.services.clean_release.test_compliance_orchestrator:Module]
# [DEF:TestComplianceOrchestrator:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, clean-release, orchestrator, stage-state-machine
# @PURPOSE: Validate compliance orchestrator stage transitions and final status derivation.
# @LAYER: Domain
# @RELATION: TESTS -> backend.src.services.clean_release.compliance_orchestrator
# @INVARIANT: Failed mandatory stage forces BLOCKED terminal status.
from unittest.mock import patch
@@ -22,6 +22,7 @@ from src.services.clean_release.repository import CleanReleaseRepository
# [DEF:test_orchestrator_stage_failure_blocks_release:Function]
# @RELATION: BINDS_TO -> TestComplianceOrchestrator
# @PURPOSE: Verify mandatory stage failure forces BLOCKED final status.
def test_orchestrator_stage_failure_blocks_release():
repository = CleanReleaseRepository()
@@ -49,6 +50,7 @@ def test_orchestrator_stage_failure_blocks_release():
# [DEF:test_orchestrator_compliant_candidate:Function]
# @RELATION: BINDS_TO -> TestComplianceOrchestrator
# @PURPOSE: Verify happy path where all mandatory stages pass yields COMPLIANT.
def test_orchestrator_compliant_candidate():
repository = CleanReleaseRepository()
@@ -76,6 +78,7 @@ def test_orchestrator_compliant_candidate():
# [DEF:test_orchestrator_missing_stage_result:Function]
# @RELATION: BINDS_TO -> TestComplianceOrchestrator
# @PURPOSE: Verify incomplete mandatory stage set cannot end as COMPLIANT and results in FAILED.
def test_orchestrator_missing_stage_result():
repository = CleanReleaseRepository()
@@ -93,6 +96,7 @@ def test_orchestrator_missing_stage_result():
# [DEF:test_orchestrator_report_generation_error:Function]
# @RELATION: BINDS_TO -> TestComplianceOrchestrator
# @PURPOSE: Verify downstream report errors do not mutate orchestrator final status.
def test_orchestrator_report_generation_error():
repository = CleanReleaseRepository()
@@ -109,4 +113,4 @@ def test_orchestrator_report_generation_error():
assert run.final_status == CheckFinalStatus.FAILED
# [/DEF:test_orchestrator_report_generation_error:Function]
# [/DEF:backend.tests.services.clean_release.test_compliance_orchestrator:Module]
# [/DEF:TestComplianceOrchestrator:Module]

5
backend/src/services/clean_release/__tests__/test_manifest_builder.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.tests.services.clean_release.test_manifest_builder:Module]
# [DEF:TestManifestBuilder:Module]
# @COMPLEXITY: 5
# @SEMANTICS: tests, clean-release, manifest, deterministic
# @PURPOSE: Validate deterministic manifest generation behavior for US1.
@@ -10,6 +10,7 @@ from src.services.clean_release.manifest_builder import build_distribution_manif
# [DEF:test_manifest_deterministic_hash_for_same_input:Function]
# @RELATION: BINDS_TO -> TestManifestBuilder
# @PURPOSE: Ensure hash is stable for same candidate/policy/artifact input.
# @PRE: Same input lists are passed twice.
# @POST: Hash and summary remain identical.
@@ -38,4 +39,4 @@ def test_manifest_deterministic_hash_for_same_input():
assert manifest1.summary.included_count == manifest2.summary.included_count
assert manifest1.summary.excluded_count == manifest2.summary.excluded_count
# [/DEF:test_manifest_deterministic_hash_for_same_input:Function]
# [/DEF:backend.tests.services.clean_release.test_manifest_builder:Module]
# [/DEF:TestManifestBuilder:Module]

23
backend/src/services/clean_release/__tests__/test_policy_engine.py
View File

@@ -40,6 +40,8 @@ def enterprise_clean_setup():
return policy, registry
# @TEST_SCENARIO: policy_valid
# [DEF:test_policy_valid:Function]
# @RELATION: BINDS_TO -> __tests__/test_policy_engine
def test_policy_valid(enterprise_clean_setup):
policy, registry = enterprise_clean_setup
engine = CleanPolicyEngine(policy, registry)
@@ -48,6 +50,10 @@ def test_policy_valid(enterprise_clean_setup):
assert not result.blocking_reasons
# @TEST_EDGE: missing_registry_ref
# [/DEF:test_policy_valid:Function]
# [DEF:test_missing_registry_ref:Function]
# @RELATION: BINDS_TO -> __tests__/test_policy_engine
def test_missing_registry_ref(enterprise_clean_setup):
policy, registry = enterprise_clean_setup
policy.internal_source_registry_ref = " "
@@ -57,6 +63,10 @@ def test_missing_registry_ref(enterprise_clean_setup):
assert "Policy missing internal_source_registry_ref" in result.blocking_reasons
# @TEST_EDGE: conflicting_registry
# [/DEF:test_missing_registry_ref:Function]
# [DEF:test_conflicting_registry:Function]
# @RELATION: BINDS_TO -> __tests__/test_policy_engine
def test_conflicting_registry(enterprise_clean_setup):
policy, registry = enterprise_clean_setup
registry.registry_id = "WRONG-REG"
@@ -66,6 +76,10 @@ def test_conflicting_registry(enterprise_clean_setup):
assert "Policy registry ref does not match provided registry" in result.blocking_reasons
# @TEST_INVARIANT: deterministic_classification
# [/DEF:test_conflicting_registry:Function]
# [DEF:test_classify_artifact:Function]
# @RELATION: BINDS_TO -> __tests__/test_policy_engine
def test_classify_artifact(enterprise_clean_setup):
policy, registry = enterprise_clean_setup
engine = CleanPolicyEngine(policy, registry)
@@ -78,6 +92,10 @@ def test_classify_artifact(enterprise_clean_setup):
assert engine.classify_artifact({"category": "others", "path": "p3"}) == "allowed"
# @TEST_EDGE: external_endpoint
# [/DEF:test_classify_artifact:Function]
# [DEF:test_validate_resource_source:Function]
# @RELATION: BINDS_TO -> __tests__/test_policy_engine
def test_validate_resource_source(enterprise_clean_setup):
policy, registry = enterprise_clean_setup
engine = CleanPolicyEngine(policy, registry)
@@ -92,6 +110,10 @@ def test_validate_resource_source(enterprise_clean_setup):
assert res_fail.violation["category"] == "external-source"
assert res_fail.violation["blocked_release"] is True
# [/DEF:test_validate_resource_source:Function]
# [DEF:test_evaluate_candidate:Function]
# @RELATION: BINDS_TO -> __tests__/test_policy_engine
def test_evaluate_candidate(enterprise_clean_setup):
policy, registry = enterprise_clean_setup
engine = CleanPolicyEngine(policy, registry)
@@ -112,3 +134,4 @@ def test_evaluate_candidate(enterprise_clean_setup):
assert len(violations) == 2
assert violations[0]["category"] == "data-purity"
assert violations[1]["category"] == "external-source"
# [/DEF:test_evaluate_candidate:Function]

116
backend/src/services/clean_release/__tests__/test_preparation_service.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.tests.services.clean_release.test_preparation_service:Module]
# [DEF:TestPreparationService:Module]
# @COMPLEXITY: 3
# @SEMANTICS: tests, clean-release, preparation, flow
# @PURPOSE: Validate release candidate preparation flow, including policy evaluation and manifest persisting.
@@ -17,11 +17,13 @@ from src.models.clean_release import (
ReleaseCandidate,
ReleaseCandidateStatus,
ProfileType,
DistributionManifest
DistributionManifest,
)
from src.services.clean_release.preparation_service import prepare_candidate
# [DEF:backend.tests.services.clean_release.test_preparation_service._mock_policy:Function]
# [DEF:_mock_policy:Function]
# @RELATION: BINDS_TO -> TestPreparationService
# @PURPOSE: Build a valid clean profile policy fixture for preparation tests.
def _mock_policy() -> CleanProfilePolicy:
return CleanProfilePolicy(
@@ -35,21 +37,37 @@ def _mock_policy() -> CleanProfilePolicy:
effective_from=datetime.now(timezone.utc),
profile=ProfileType.ENTERPRISE_CLEAN,
)
# [/DEF:backend.tests.services.clean_release.test_preparation_service._mock_policy:Function]
# [DEF:backend.tests.services.clean_release.test_preparation_service._mock_registry:Function]
# [/DEF:_mock_policy:Function]
# [DEF:_mock_registry:Function]
# @RELATION: BINDS_TO -> TestPreparationService
# @PURPOSE: Build an internal-only source registry fixture for preparation tests.
def _mock_registry() -> ResourceSourceRegistry:
return ResourceSourceRegistry(
registry_id="reg-1",
name="Reg",
entries=[ResourceSourceEntry(source_id="s1", host="nexus.internal", protocol="https", purpose="pkg", enabled=True)],
updated_at=datetime.now(timezone.utc),
updated_by="tester"
entries=[
ResourceSourceEntry(
source_id="s1",
host="nexus.internal",
protocol="https",
purpose="pkg",
enabled=True,
)
],
updated_at=datetime.now(timezone.utc),
updated_by="tester",
)
# [/DEF:backend.tests.services.clean_release.test_preparation_service._mock_registry:Function]
# [DEF:backend.tests.services.clean_release.test_preparation_service._mock_candidate:Function]
# [/DEF:_mock_registry:Function]
# [DEF:_mock_candidate:Function]
# @RELATION: BINDS_TO -> TestPreparationService
# @PURPOSE: Build a draft release candidate fixture with provided identifier.
def _mock_candidate(candidate_id: str) -> ReleaseCandidate:
return ReleaseCandidate(
@@ -59,11 +77,15 @@ def _mock_candidate(candidate_id: str) -> ReleaseCandidate:
created_at=datetime.now(timezone.utc),
status=ReleaseCandidateStatus.DRAFT,
created_by="tester",
source_snapshot_ref="v1.0.0-snapshot"
source_snapshot_ref="v1.0.0-snapshot",
)
# [/DEF:backend.tests.services.clean_release.test_preparation_service._mock_candidate:Function]
# [DEF:backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_success:Function]
# [/DEF:_mock_candidate:Function]
# [DEF:test_prepare_candidate_success:Function]
# @RELATION: BINDS_TO -> TestPreparationService
# @PURPOSE: Verify candidate transitions to PREPARED when evaluation returns no violations.
# @TEST_CONTRACT: [valid_candidate + active_policy + internal_sources + no_violations] -> [status=PREPARED, manifest_persisted, candidate_saved]
# @TEST_SCENARIO: [prepare_success] -> [prepared status and persistence side effects are produced]
@@ -83,24 +105,39 @@ def test_prepare_candidate_success():
sources = ["nexus.internal"]
# Execute
with patch("src.services.clean_release.preparation_service.CleanPolicyEngine") as MockEngine:
with patch(
"src.services.clean_release.preparation_service.CleanPolicyEngine"
) as MockEngine:
mock_engine_instance = MockEngine.return_value
mock_engine_instance.validate_policy.return_value.ok = True
mock_engine_instance.evaluate_candidate.return_value = (
[{"path": "file1.txt", "category": "system", "classification": "required-system", "reason": "system-core"}],
[]
[
{
"path": "file1.txt",
"category": "system",
"classification": "required-system",
"reason": "system-core",
}
],
[],
)
result = prepare_candidate(repository, candidate_id, artifacts, sources, "operator-1")
result = prepare_candidate(
repository, candidate_id, artifacts, sources, "operator-1"
)
# Verify
assert result["status"] == ReleaseCandidateStatus.PREPARED.value
assert candidate.status == ReleaseCandidateStatus.PREPARED
repository.save_manifest.assert_called_once()
repository.save_candidate.assert_called_with(candidate)
# [/DEF:backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_success:Function]
# [DEF:backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_with_violations:Function]
# [/DEF:test_prepare_candidate_success:Function]
# [DEF:test_prepare_candidate_with_violations:Function]
# @RELATION: BINDS_TO -> TestPreparationService
# @PURPOSE: Verify candidate transitions to BLOCKED when evaluation returns blocking violations.
# @TEST_CONTRACT: [valid_candidate + active_policy + evaluation_with_violations] -> [status=BLOCKED, violations_exposed]
# @TEST_SCENARIO: [prepare_blocked_due_to_policy] -> [blocked status and violation list are produced]
@@ -120,23 +157,38 @@ def test_prepare_candidate_with_violations():
sources = []
# Execute
with patch("src.services.clean_release.preparation_service.CleanPolicyEngine") as MockEngine:
with patch(
"src.services.clean_release.preparation_service.CleanPolicyEngine"
) as MockEngine:
mock_engine_instance = MockEngine.return_value
mock_engine_instance.validate_policy.return_value.ok = True
mock_engine_instance.evaluate_candidate.return_value = (
[{"path": "bad.txt", "category": "prohibited", "classification": "excluded-prohibited", "reason": "test-data"}],
[{"category": "data-purity", "blocked_release": True}]
[
{
"path": "bad.txt",
"category": "prohibited",
"classification": "excluded-prohibited",
"reason": "test-data",
}
],
[{"category": "data-purity", "blocked_release": True}],
)
result = prepare_candidate(repository, candidate_id, artifacts, sources, "operator-1")
result = prepare_candidate(
repository, candidate_id, artifacts, sources, "operator-1"
)
# Verify
assert result["status"] == ReleaseCandidateStatus.BLOCKED.value
assert candidate.status == ReleaseCandidateStatus.BLOCKED
assert len(result["violations"]) == 1
# [/DEF:backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_with_violations:Function]
# [DEF:backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_not_found:Function]
# [/DEF:test_prepare_candidate_with_violations:Function]
# [DEF:test_prepare_candidate_not_found:Function]
# @RELATION: BINDS_TO -> TestPreparationService
# @PURPOSE: Verify preparation raises ValueError when candidate does not exist.
# @TEST_CONTRACT: [missing_candidate] -> [ValueError('Candidate not found')]
# @TEST_SCENARIO: [prepare_missing_candidate] -> [raises candidate not found error]
@@ -149,9 +201,13 @@ def test_prepare_candidate_not_found():
with pytest.raises(ValueError, match="Candidate not found"):
prepare_candidate(repository, "non-existent", [], [], "op")
# [/DEF:backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_not_found:Function]
# [DEF:backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_no_active_policy:Function]
# [/DEF:test_prepare_candidate_not_found:Function]
# [DEF:test_prepare_candidate_no_active_policy:Function]
# @RELATION: BINDS_TO -> TestPreparationService
# @PURPOSE: Verify preparation raises ValueError when no active policy is available.
# @TEST_CONTRACT: [candidate_present + missing_active_policy] -> [ValueError('Active clean policy not found')]
# @TEST_SCENARIO: [prepare_missing_policy] -> [raises active policy missing error]
@@ -165,7 +221,9 @@ def test_prepare_candidate_no_active_policy():
with pytest.raises(ValueError, match="Active clean policy not found"):
prepare_candidate(repository, "cand-1", [], [], "op")
# [/DEF:backend.tests.services.clean_release.test_preparation_service.test_prepare_candidate_no_active_policy:Function]
# [/DEF:backend.tests.services.clean_release.test_preparation_service:Module]
# [/DEF:test_prepare_candidate_no_active_policy:Function]
# [/DEF:TestPreparationService:Module]

12
backend/src/services/clean_release/__tests__/test_report_builder.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.tests.services.clean_release.test_report_builder:Module]
# [DEF:TestReportBuilder:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, clean-release, report-builder, counters
# @PURPOSE: Validate compliance report builder counter integrity and blocked-run constraints.
# @LAYER: Domain
# @RELATION: TESTS -> backend.src.services.clean_release.report_builder
# @INVARIANT: blocked run requires at least one blocking violation.
from datetime import datetime, timezone
@@ -23,6 +23,7 @@ from src.services.clean_release.repository import CleanReleaseRepository
# [DEF:_terminal_run:Function]
# @RELATION: BINDS_TO -> TestReportBuilder
# @PURPOSE: Build terminal/non-terminal run fixtures for report builder tests.
def _terminal_run(status: CheckFinalStatus) -> ComplianceCheckRun:
return ComplianceCheckRun(
@@ -40,6 +41,7 @@ def _terminal_run(status: CheckFinalStatus) -> ComplianceCheckRun:
# [DEF:_blocking_violation:Function]
# @RELATION: BINDS_TO -> TestReportBuilder
# @PURPOSE: Build a blocking violation fixture for blocked report scenarios.
def _blocking_violation() -> ComplianceViolation:
return ComplianceViolation(
@@ -56,6 +58,7 @@ def _blocking_violation() -> ComplianceViolation:
# [DEF:test_report_builder_blocked_requires_blocking_violations:Function]
# @RELATION: BINDS_TO -> TestReportBuilder
# @PURPOSE: Verify BLOCKED run requires at least one blocking violation.
def test_report_builder_blocked_requires_blocking_violations():
builder = ComplianceReportBuilder(CleanReleaseRepository())
@@ -67,6 +70,7 @@ def test_report_builder_blocked_requires_blocking_violations():
# [DEF:test_report_builder_blocked_with_two_violations:Function]
# @RELATION: BINDS_TO -> TestReportBuilder
# @PURPOSE: Verify report builder generates conformant payload for a BLOCKED run with violations.
def test_report_builder_blocked_with_two_violations():
builder = ComplianceReportBuilder(CleanReleaseRepository())
@@ -87,6 +91,7 @@ def test_report_builder_blocked_with_two_violations():
# [DEF:test_report_builder_counter_consistency:Function]
# @RELATION: BINDS_TO -> TestReportBuilder
# @PURPOSE: Verify violations counters remain consistent for blocking payload.
def test_report_builder_counter_consistency():
builder = ComplianceReportBuilder(CleanReleaseRepository())
@@ -99,6 +104,7 @@ def test_report_builder_counter_consistency():
# [DEF:test_missing_operator_summary:Function]
# @RELATION: BINDS_TO -> TestReportBuilder
# @PURPOSE: Validate non-terminal run prevents operator summary/report generation.
def test_missing_operator_summary():
builder = ComplianceReportBuilder(CleanReleaseRepository())
@@ -109,4 +115,4 @@ def test_missing_operator_summary():
assert "Cannot build report for non-terminal run" in str(exc.value)
# [/DEF:test_missing_operator_summary:Function]
# [/DEF:backend.tests.services.clean_release.test_report_builder:Module]
# [/DEF:TestReportBuilder:Module]

20
backend/src/services/clean_release/__tests__/test_source_isolation.py
View File

@@ -1,9 +1,9 @@
# [DEF:backend.tests.services.clean_release.test_source_isolation:Module]
# [DEF:TestSourceIsolation:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, clean-release, source-isolation, internal-only
# @PURPOSE: Verify internal source registry validation behavior.
# @LAYER: Domain
# @RELATION: TESTS -> backend.src.services.clean_release.source_isolation
# @INVARIANT: External endpoints always produce blocking violations.
from datetime import datetime, timezone
@@ -12,6 +12,8 @@ from src.models.clean_release import ResourceSourceEntry, ResourceSourceRegistry
from src.services.clean_release.source_isolation import validate_internal_sources
# [DEF:_registry:Function]
# @RELATION: BINDS_TO -> TestSourceIsolation
def _registry() -> ResourceSourceRegistry:
return ResourceSourceRegistry(
registry_id="registry-internal-v1",
@@ -38,6 +40,11 @@ def _registry() -> ResourceSourceRegistry:
)
# [/DEF:_registry:Function]
# [DEF:test_validate_internal_sources_all_internal_ok:Function]
# @RELATION: BINDS_TO -> TestSourceIsolation
def test_validate_internal_sources_all_internal_ok():
result = validate_internal_sources(
registry=_registry(),
@@ -47,6 +54,11 @@ def test_validate_internal_sources_all_internal_ok():
assert result["violations"] == []
# [/DEF:test_validate_internal_sources_all_internal_ok:Function]
# [DEF:test_validate_internal_sources_external_blocked:Function]
# @RELATION: BINDS_TO -> TestSourceIsolation
def test_validate_internal_sources_external_blocked():
result = validate_internal_sources(
registry=_registry(),
@@ -57,4 +69,6 @@ def test_validate_internal_sources_external_blocked():
assert result["violations"][0]["category"] == "external-source"
assert result["violations"][0]["blocked_release"] is True
# [/DEF:backend.tests.services.clean_release.test_source_isolation:Module]
# [/DEF:test_validate_internal_sources_external_blocked:Function]
# [/DEF:TestSourceIsolation:Module]

56
backend/src/services/clean_release/__tests__/test_stages.py
View File

@@ -1,30 +1,70 @@
# [DEF:backend.tests.services.clean_release.test_stages:Module]
# [DEF:TestStages:Module]
# @RELATION: BELONGS_TO -> SrcRoot
# @COMPLEXITY: 3
# @SEMANTICS: tests, clean-release, compliance, stages
# @PURPOSE: Validate final status derivation logic from stage results.
# @LAYER: Domain
# @RELATION: TESTS -> backend.src.services.clean_release.stages
from src.models.clean_release import CheckFinalStatus, CheckStageName, CheckStageResult, CheckStageStatus
from src.models.clean_release import (
CheckFinalStatus,
CheckStageName,
CheckStageResult,
CheckStageStatus,
)
from src.services.clean_release.stages import derive_final_status, MANDATORY_STAGE_ORDER
# [DEF:test_derive_final_status_compliant:Function]
# @RELATION: BINDS_TO -> TestStages
def test_derive_final_status_compliant():
results = [CheckStageResult(stage=s, status=CheckStageStatus.PASS, details="ok") for s in MANDATORY_STAGE_ORDER]
results = [
CheckStageResult(stage=s, status=CheckStageStatus.PASS, details="ok")
for s in MANDATORY_STAGE_ORDER
]
assert derive_final_status(results) == CheckFinalStatus.COMPLIANT
# [/DEF:test_derive_final_status_compliant:Function]
# [DEF:test_derive_final_status_blocked:Function]
# @RELATION: BINDS_TO -> TestStages
def test_derive_final_status_blocked():
results = [CheckStageResult(stage=s, status=CheckStageStatus.PASS, details="ok") for s in MANDATORY_STAGE_ORDER]
results = [
CheckStageResult(stage=s, status=CheckStageStatus.PASS, details="ok")
for s in MANDATORY_STAGE_ORDER
]
results[1].status = CheckStageStatus.FAIL
assert derive_final_status(results) == CheckFinalStatus.BLOCKED
# [/DEF:test_derive_final_status_blocked:Function]
# [DEF:test_derive_final_status_failed_missing:Function]
# @RELATION: BINDS_TO -> TestStages
def test_derive_final_status_failed_missing():
results = [CheckStageResult(stage=MANDATORY_STAGE_ORDER[0], status=CheckStageStatus.PASS, details="ok")]
results = [
CheckStageResult(
stage=MANDATORY_STAGE_ORDER[0], status=CheckStageStatus.PASS, details="ok"
)
]
assert derive_final_status(results) == CheckFinalStatus.FAILED
# [/DEF:test_derive_final_status_failed_missing:Function]
# [DEF:test_derive_final_status_failed_skipped:Function]
# @RELATION: BINDS_TO -> TestStages
def test_derive_final_status_failed_skipped():
results = [CheckStageResult(stage=s, status=CheckStageStatus.PASS, details="ok") for s in MANDATORY_STAGE_ORDER]
results = [
CheckStageResult(stage=s, status=CheckStageStatus.PASS, details="ok")
for s in MANDATORY_STAGE_ORDER
]
results[2].status = CheckStageStatus.SKIPPED
assert derive_final_status(results) == CheckFinalStatus.FAILED
# [/DEF:backend.tests.services.clean_release.test_stages:Module]
# [/DEF:test_derive_final_status_failed_skipped:Function]
# [/DEF:TestStages:Module]

2
backend/src/services/clean_release/approval_service.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.services.clean_release.approval_service:Module]
# [DEF:approval_service:Module]
# @COMPLEXITY: 5
# @SEMANTICS: clean-release, approval, decision, lifecycle, gate
# @PURPOSE: Enforce approval/rejection gates over immutable compliance reports.

2
backend/src/services/clean_release/artifact_catalog_loader.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.services.clean_release.artifact_catalog_loader:Module]
# [DEF:artifact_catalog_loader:Module]
# @COMPLEXITY: 3
# @SEMANTICS: clean-release, artifacts, bootstrap, json, tui
# @PURPOSE: Load bootstrap artifact catalogs for clean release real-mode flows.

2
backend/src/services/clean_release/audit_service.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.services.clean_release.audit_service:Module]
# [DEF:audit_service:Module]
# @COMPLEXITY: 3
# @SEMANTICS: clean-release, audit, lifecycle, logging
# @PURPOSE: Provide lightweight audit hooks for clean release preparation/check/report lifecycle.

2
backend/src/services/clean_release/candidate_service.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.services.clean_release.candidate_service:Module]
# [DEF:candidate_service:Module]
# @COMPLEXITY: 5
# @SEMANTICS: clean-release, candidate, artifacts, lifecycle, validation
# @PURPOSE: Register release candidates with validated artifacts and advance lifecycle through legal transitions.

2
backend/src/services/clean_release/compliance_execution_service.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.services.clean_release.compliance_execution_service:Module]
# [DEF:compliance_execution_service:Module]
# @COMPLEXITY: 5
# @SEMANTICS: clean-release, compliance, execution, stages, immutable-evidence
# @PURPOSE: Create and execute compliance runs with trusted snapshots, deterministic stages, violations and immutable report persistence.

4
backend/src/services/clean_release/compliance_orchestrator.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.services.clean_release.compliance_orchestrator:Module]
# [DEF:compliance_orchestrator:Module]
# @COMPLEXITY: 5
# @SEMANTICS: clean-release, orchestrator, compliance-gate, stages
# @PURPOSE: Execute mandatory clean compliance stages and produce final COMPLIANT/BLOCKED/FAILED outcome.
@@ -42,7 +42,7 @@ from ...core.logger import belief_scope, logger
# [DEF:CleanComplianceOrchestrator:Class]
# @PURPOSE: Coordinate clean-release compliance verification stages.
class CleanComplianceOrchestrator:
# [DEF:CleanComplianceOrchestrator.__init__:Function]
# [DEF:__init__:Function]
# @PURPOSE: Bind repository dependency used for orchestrator persistence and lookups.
# @PRE: repository is a valid CleanReleaseRepository instance with required methods.
# @POST: self.repository is assigned and used by all orchestration steps.

2
backend/src/services/clean_release/demo_data_service.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.services.clean_release.demo_data_service:Module]
# [DEF:demo_data_service:Module]
# @COMPLEXITY: 3
# @SEMANTICS: clean-release, demo-mode, namespace, isolation, repository
# @PURPOSE: Provide deterministic namespace helpers and isolated in-memory repository creation for demo and real modes.

2
backend/src/services/clean_release/manifest_builder.py
View File

@@ -1,4 +1,4 @@
# [DEF:backend.src.services.clean_release.manifest_builder:Module]
# [DEF:manifest_builder:Module]
# @COMPLEXITY: 3
# @SEMANTICS: clean-release, manifest, deterministic-hash, summary
# @PURPOSE: Build deterministic distribution manifest from classified artifact input.

Some files were not shown because too many files have changed in this diff Show More