Files
MoviePilot/tests/test_architecture_dependencies.py

1661 lines
62 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import ast
import json
from functools import lru_cache
from pathlib import Path
from app.runtime.compat.manifest import SYMBOL_ALIASES
from scripts.architecture.baseline import (
collect_current_event_facts as _collect_current_event_facts,
)
from scripts.architecture.baseline import (
discover_modules as _discover_modules,
)
from scripts.architecture.baseline import (
resolve_imports as _resolve_imports,
)
from scripts.architecture.baseline import (
strongly_connected_components as _strongly_connected_components,
)
PROJECT_ROOT = Path(__file__).parents[1]
APP_ROOT = PROJECT_ROOT / "app"
DEPENDENCY_POLICY_PATH = (
PROJECT_ROOT / "tests" / "fixtures" / "architecture" / "dependency-policy.json"
)
LEGACY_ROOTS = ("app.core", "app.helper", "app.utils")
LEGACY_MODULES = {"app.log"}
IMPLEMENTATION_ROOTS = (
"app.agent.skills",
"app.adapters",
"app.application",
"app.db.adapters",
"app.domain",
"app.foundation",
"app.runtime",
)
CYCLE_ROOTS = (*IMPLEMENTATION_ROOTS, "app.runtime.compat", "app.sdk")
RETIRED_CANONICAL_ROOTS = (
"compat",
"extensions",
"infrastructure",
"integrations",
"messaging",
"platform",
"security",
"services",
)
RETIRED_CANONICAL_FILES = (
"app/infrastructure/package_installer.py",
"app/infrastructure/resource_updater.py",
"app/infrastructure/rust_accel.py",
"app/messaging/agent_bridge.py",
"app/platform/config_reload.py",
"app/platform/rate_limit.py",
"app/platform/thread_pool.py",
"app/services/filter_rules.py",
"app/services/transfer_history.py",
"app/extensions/module_loader.py",
"app/extensions/plugin_market.py",
"app/extensions/plugin_repository.py",
"app/infrastructure/http.py",
"app/integrations/rss.py",
"app/security/two_factor.py",
"app/infrastructure/gc.py",
"app/infrastructure/web.py",
"app/security/url_safety.py",
"app/domain/mediaserver.py",
"app/domain/nfo.py",
"app/domain/string.py",
"app/log.py",
"app/foundation/diagnostics.py",
"app/infrastructure/log.py",
"app/startup/diagnostics_initializer.py",
"app/startup/log_initializer.py",
"app/messaging/notification.py",
"app/messaging/webpush.py",
"app/foundation/jieba.py",
"app/foundation/module.py",
"app/foundation/object.py",
"app/foundation/structures.py",
"app/foundation/zhconv.py",
"app/runtime/runtime.py",
"app/adapters/network/rss.py",
"app/adapters/network/sites.pyi",
"app/application/plugins.py",
"app/application/subscribe.py",
"app/application/chain/durable_events.py",
"app/application/transfer.py",
"app/application/transfer_execution.py",
"app/db/adapters/transfer.py",
"app/db/adapters/transfer_execution.py",
"app/runtime/extensions/managed_resource_adapter.py",
"app/runtime/managed_resources.py",
"app/startup/agent_initializer.py",
"app/startup/cache_initializer.py",
"app/startup/chain_events.py",
"app/startup/command_initializer.py",
"app/startup/configuration.py",
"app/startup/context.py",
"app/startup/database.py",
"app/startup/database_initializer.py",
"app/startup/domain_initializer.py",
"app/startup/download_failure.py",
"app/startup/managed_resources_initializer.py",
"app/startup/initializers/managed_resources.py",
"app/startup/modules_initializer.py",
"app/startup/monitor_initializer.py",
"app/startup/outbox.py",
"app/startup/plugins_initializer.py",
"app/startup/routers_initializer.py",
"app/startup/scheduler_initializer.py",
"app/startup/site.py",
"app/startup/subscription.py",
"app/startup/transaction.py",
"app/startup/transfer_initializer.py",
"app/startup/workflow.py",
"app/startup/workflow_initializer.py",
)
PLUGIN_COMPONENT_ROOTS = (
"app/adapters/external/plugin",
"app/adapters/system/plugin",
"app/application/plugin",
"app/runtime/extensions/plugin",
)
PLUGIN_LEGACY_ABI_NAMES = {
"MoviePilotServerHelper",
"PluginHelper",
"PluginManager",
}
FORBIDDEN_IMPORT_PREFIXES = {
"app.foundation": (
"app.adapters",
"app.application",
"app.db",
"app.domain",
"app.runtime",
"app.sdk",
),
"app.domain": (
"app.adapters",
"app.application",
"app.db",
"app.runtime",
"app.sdk",
),
"app.adapters": (
"app.application",
"app.runtime.compat",
"app.runtime.extensions",
"app.sdk",
),
"app.runtime": (
"app.adapters",
"app.application",
"app.sdk",
),
"app.application": (
"app.runtime.extensions",
"app.runtime.compat",
"app.sdk",
),
"app.api": (
"app.runtime.extensions.plugin_manager",
"app.runtime.extensions.module_manager",
"app.scheduler",
),
"app.agent": (
"app.runtime.extensions.plugin_manager",
"app.runtime.extensions.module_manager",
),
"app.chain": (
"app.runtime.extensions.plugin_manager",
"app.runtime.extensions.module_manager",
"app.runtime.extensions.module.dispatcher",
),
"app.workflow": (
"app.runtime.extensions.plugin_manager",
"app.runtime.extensions.module_manager",
),
}
def _legacy_imports(path: Path) -> set[str]:
"""提取源码中的静态和常量动态旧路径导入。"""
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
imports: set[str] = set()
for node in ast.walk(tree):
candidates: list[str] = []
if isinstance(node, ast.Import):
candidates.extend(alias.name for alias in node.names)
elif isinstance(node, ast.ImportFrom) and node.module:
candidates.append(node.module)
elif isinstance(node, ast.Call) and node.args:
argument = node.args[0]
if isinstance(argument, ast.Constant) and isinstance(argument.value, str):
candidates.append(argument.value)
imports.update(
candidate
for candidate in candidates
if candidate in LEGACY_MODULES or candidate.startswith(LEGACY_ROOTS)
)
return imports
def _attribute_parts(node: ast.Attribute) -> list[str]:
"""将静态属性访问还原为从根名称开始的完整路径片段。"""
parts = [node.attr]
value = node.value
while isinstance(value, ast.Attribute):
parts.append(value.attr)
value = value.value
if not isinstance(value, ast.Name):
return []
parts.append(value.id)
return list(reversed(parts))
def _compat_symbol_references(tree: ast.AST) -> set[tuple[int, str]]:
"""收集显式导入或静态属性访问命中的兼容符号。"""
compatibility_symbols = {
(module_name, symbol_name)
for module_name, symbols in SYMBOL_ALIASES.items()
for symbol_name in symbols
}
module_bindings: dict[str, str] = {}
references: set[tuple[int, str]] = set()
for node in ast.walk(tree):
if isinstance(node, ast.Import):
for alias in node.names:
binding = alias.asname or alias.name.split(".", maxsplit=1)[0]
module_bindings[binding] = alias.name if alias.asname else binding
elif isinstance(node, ast.ImportFrom) and node.module:
for alias in node.names:
if (node.module, alias.name) in compatibility_symbols:
references.add((node.lineno, f"{node.module}.{alias.name}"))
continue
binding = alias.asname or alias.name
module_bindings[binding] = f"{node.module}.{alias.name}"
for node in ast.walk(tree):
if not isinstance(node, ast.Attribute):
continue
parts = _attribute_parts(node)
if len(parts) < 2:
continue
resolved_root = module_bindings.get(parts[0], parts[0])
resolved = [*resolved_root.split("."), *parts[1:]]
module_name = ".".join(resolved[:-1])
symbol_name = resolved[-1]
if (module_name, symbol_name) in compatibility_symbols:
references.add((node.lineno, f"{module_name}.{symbol_name}"))
return references
def test_legacy_roots_contain_no_python_sources():
"""旧目录只能作为运行时虚拟包存在,仓库中不得重新出现源码。"""
leftovers = sorted(
str(path.relative_to(PROJECT_ROOT))
for root_name in ("core", "helper", "utils")
for path in (APP_ROOT / root_name).rglob("*.py")
)
assert leftovers == []
def test_legacy_source_directories_do_not_exist():
"""core/helper/utils 物理目录应完全退役,旧导入只由虚拟兼容包解析。"""
leftovers = [
root_name
for root_name in ("core", "helper", "utils")
if (APP_ROOT / root_name).exists()
]
assert leftovers == []
def test_retired_canonical_filenames_do_not_return():
"""能力包应使用包内语境明确的短文件名,避免再次出现冗余角色后缀。"""
leftovers = [
relative_path
for relative_path in RETIRED_CANONICAL_FILES
if (PROJECT_ROOT / relative_path).exists()
]
assert leftovers == []
def test_startup_root_contains_only_composition_packages():
"""组合根顶层只保留稳定分区,禁止再次堆叠扁平实现文件。"""
startup_root = APP_ROOT / "startup"
root_modules = sorted(path.name for path in startup_root.glob("*.py"))
python_packages = sorted(
path.name
for path in startup_root.iterdir()
if path.is_dir() and any(path.rglob("*.py"))
)
assert root_modules == ["__init__.py"]
assert python_packages == ["composition", "initializers", "lifecycle"]
def test_retired_canonical_roots_contain_no_python_sources():
"""已收敛的新增目录不得再次以顶级 Python 包形式出现。"""
leftovers = sorted(
str(path.relative_to(PROJECT_ROOT))
for root_name in RETIRED_CANONICAL_ROOTS
for path in (APP_ROOT / root_name).rglob("*.py")
)
assert leftovers == []
def test_host_code_does_not_import_legacy_roots():
"""除插件和兼容层外,宿主代码必须使用 canonical 路径。"""
violations: dict[str, set[str]] = {}
for path in APP_ROOT.rglob("*.py"):
relative = path.relative_to(APP_ROOT)
if relative.parts[0] == "plugins" or relative.parts[:2] == (
"runtime",
"compat",
):
continue
imports = _legacy_imports(path)
if imports:
violations[str(relative)] = imports
assert violations == {}
def test_compat_symbol_scanner_covers_static_import_shapes() -> None:
"""兼容符号扫描必须覆盖显式导入、模块别名和完整属性链。"""
tree = ast.parse(
"""
from app.schemas import TransferTask
import app.schemas as schema_alias
schema_alias.TransferQueue
import app.schemas
app.schemas.TransferTask
from app.application import transfer as transfer_package
transfer_package.TransferQueue
"""
)
assert _compat_symbol_references(tree) == {
(2, "app.schemas.TransferTask"),
(4, "app.schemas.TransferQueue"),
(6, "app.schemas.TransferTask"),
(8, "app.application.transfer.TransferQueue"),
}
def test_host_code_does_not_use_compat_symbol_aliases() -> None:
"""宿主必须导入 canonical 符号,不得反向消费插件兼容覆盖。"""
violations: list[str] = []
for path in APP_ROOT.rglob("*.py"):
relative = path.relative_to(APP_ROOT)
if (
relative.parts[0] == "plugins"
or relative.parts[:2] == ("runtime", "compat")
or relative.parts[:2] == ("sdk", "_legacy")
):
continue
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
violations.extend(
f"{relative.as_posix()}:{line}:{symbol}"
for line, symbol in sorted(_compat_symbol_references(tree))
)
assert violations == []
def test_host_code_uses_explicit_runtime_facade_getters():
"""宿主消费者必须显式调用 getter,不得把兼容 Facade 当作新代码入口。"""
forbidden_imports = {
"app.application.module": {"ModuleManager"},
"app.application.scheduling": {"Scheduler"},
}
violations: list[str] = []
for path in APP_ROOT.rglob("*.py"):
relative = path.relative_to(APP_ROOT)
if relative.parts[0] == "plugins" or relative.parts[:2] == (
"runtime",
"compat",
):
continue
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if isinstance(node, ast.Assign) and isinstance(node.value, ast.Name):
target_names = {
target.id for target in node.targets if isinstance(target, ast.Name)
}
if (
"SystemConfigOper" in target_names
and node.value.id == "get_configured_system_config"
):
violations.append(
f"{relative.as_posix()}:{node.lineno}:SystemConfigOper"
)
continue
if not isinstance(node, ast.ImportFrom) or not node.module:
continue
forbidden_names = forbidden_imports.get(node.module, set())
for alias in node.names:
class_shaped_plugin_getter = (
node.module == "app.application.plugin.runtime"
and alias.name == "get_plugin_manager"
and alias.asname is not None
)
class_shaped_config_getter = (
node.module == "app.application.configuration"
and alias.name == "get_configured_system_config"
and alias.asname is not None
)
if (
alias.name in forbidden_names
or class_shaped_plugin_getter
or class_shaped_config_getter
):
imported_name = alias.asname or alias.name
violations.append(
f"{relative.as_posix()}:{node.lineno}:{imported_name}"
)
assert violations == []
def test_workflow_domain_uses_explicit_chain_data_port_getters():
"""工作流域不得重新使用迁移期 PortProxy 冒充数据库 Oper。"""
paths = [APP_ROOT / "chain" / "workflow.py"]
paths.extend((APP_ROOT / "workflow").rglob("*.py"))
violations: list[str] = []
for path in paths:
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if not isinstance(node, ast.ImportFrom):
continue
if node.module != "app.application.chain.data":
continue
for alias in node.names:
if alias.name.endswith("PortProxy"):
violations.append(
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}:{alias.name}"
)
assert violations == []
def test_user_and_messaging_chains_use_explicit_data_port_getters():
"""用户、交互和消息链不得把迁移期 UserPortProxy 伪装成 UserOper。"""
paths = [
APP_ROOT / "chain" / "user.py",
APP_ROOT / "chain" / "interaction.py",
APP_ROOT / "chain" / "_messaging.py",
]
violations: list[str] = []
for path in paths:
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if not isinstance(node, ast.ImportFrom):
continue
if node.module != "app.application.chain.data":
continue
for alias in node.names:
if alias.name == "UserPortProxy":
violations.append(
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}"
)
assert violations == []
def test_music_chain_uses_explicit_subscribe_data_port_getter():
"""音乐订阅链不得把 SubscribePortProxy 伪装成 SubscribeOper。"""
path = APP_ROOT / "chain" / "_music.py"
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
violations = [
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}"
for node in ast.walk(tree)
if isinstance(node, ast.ImportFrom)
and node.module == "app.application.chain.data"
and any(alias.name == "SubscribePortProxy" for alias in node.names)
]
assert violations == []
def test_site_chains_use_explicit_site_data_port_getter():
"""站点与种子链不得把 SitePortProxy 伪装成 SiteOper。"""
paths = [APP_ROOT / "chain" / "site.py", APP_ROOT / "chain" / "torrents.py"]
violations: list[str] = []
for path in paths:
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if not isinstance(node, ast.ImportFrom):
continue
if node.module != "app.application.chain.data":
continue
if any(alias.name == "SitePortProxy" for alias in node.names):
violations.append(
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}"
)
assert violations == []
def test_mediaserver_chain_uses_explicit_data_port_getter():
"""媒体服务器链不得把 MediaServerPortProxy 伪装成 MediaServerOper。"""
path = APP_ROOT / "chain" / "mediaserver.py"
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
violations = [
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}"
for node in ast.walk(tree)
if isinstance(node, ast.ImportFrom)
and node.module == "app.application.chain.data"
and any(alias.name == "MediaServerPortProxy" for alias in node.names)
]
assert violations == []
def test_download_chain_uses_explicit_data_port_getters():
"""下载链不得把三个迁移期 PortProxy 伪装成数据库 Oper。"""
path = APP_ROOT / "chain" / "download.py"
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
forbidden = {
"DownloadFailurePortProxy",
"DownloadHistoryPortProxy",
"MediaServerPortProxy",
}
violations = [
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}:{alias.name}"
for node in ast.walk(tree)
if isinstance(node, ast.ImportFrom)
and node.module == "app.application.chain.data"
for alias in node.names
if alias.name in forbidden
]
assert violations == []
def test_subscribe_chain_uses_explicit_data_port_getters():
"""订阅链不得把三个迁移期 PortProxy 伪装成数据库 Oper。"""
path = APP_ROOT / "chain" / "subscribe.py"
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
forbidden = {
"DownloadHistoryPortProxy",
"SitePortProxy",
"SubscribePortProxy",
}
violations = [
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}:{alias.name}"
for node in ast.walk(tree)
if isinstance(node, ast.ImportFrom)
and node.module == "app.application.chain.data"
for alias in node.names
if alias.name in forbidden
]
assert violations == []
def test_transfer_chains_use_explicit_data_port_getters():
"""整理主链与 mixin 不得把迁移期 PortProxy 伪装成数据库 Oper。"""
paths = [APP_ROOT / "chain" / "transfer.py", APP_ROOT / "chain" / "_transfer.py"]
forbidden = {
"DownloadHistoryPortProxy",
"TransferHistoryPortProxy",
"TransferPendingPortProxy",
}
violations: list[str] = []
for path in paths:
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if not isinstance(node, ast.ImportFrom):
continue
if node.module != "app.application.chain.data":
continue
for alias in node.names:
if alias.name in forbidden:
violations.append(
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}:{alias.name}"
)
assert violations == []
def test_transfer_pending_oper_import_is_confined_to_database_boundary():
"""宿主仅允许事务适配器和兼容导出直接导入整理待处理 Oper。"""
allowed_paths = {
"app/db/adapters/transfer/admission.py",
"app/db/adapters/chain.py",
"app/db/adapters/transfer/execution.py",
"app/db/oper/__init__.py",
}
violations: list[str] = []
for path in APP_ROOT.rglob("*.py"):
relative = path.relative_to(PROJECT_ROOT).as_posix()
if relative.startswith("app/plugins/") or relative in allowed_paths:
continue
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if isinstance(node, ast.Import):
if any(
alias.name == "app.db.oper.transferpending"
for alias in node.names
):
violations.append(f"{relative}:{node.lineno}")
elif isinstance(node, ast.ImportFrom) and (
node.module == "app.db.oper.transferpending"
or (
node.module == "app.db.oper"
and any(
alias.name in {"transferpending", "TransferPendingOper"}
for alias in node.names
)
)
):
violations.append(f"{relative}:{node.lineno}")
assert violations == []
def test_startup_injects_transactional_transfer_admission_repository():
"""启动组合根必须向 Chain 注入事务型整理准入仓储。"""
path = APP_ROOT / "startup" / "initializers" / "modules.py"
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
imports_repository = any(
isinstance(node, ast.ImportFrom)
and node.module == "app.db.adapters.transfer.admission"
and any(
alias.name == "TransactionalTransferAdmissionRepository"
for alias in node.names
)
for node in ast.walk(tree)
)
transfer_pending_factories = [
keyword.value
for node in ast.walk(tree)
if isinstance(node, ast.Call)
and isinstance(node.func, ast.Name)
and node.func.id == "configure_chain_data_ports"
for keyword in node.keywords
if keyword.arg == "transfer_pending"
]
assert imports_repository is True
assert len(transfer_pending_factories) == 1
assert any(
isinstance(node, ast.Call)
and isinstance(node.func, ast.Name)
and node.func.id == "TransactionalTransferAdmissionRepository"
for node in ast.walk(transfer_pending_factories[0])
)
def test_transfer_pending_chain_port_is_typed_without_legacy_proxy():
"""整理准入端口必须返回明确 Protocol,且旧 Proxy 不得重新出现。"""
path = APP_ROOT / "application" / "chain" / "data.py"
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
class_names = {
node.name
for node in tree.body
if isinstance(node, ast.ClassDef)
}
getters = [
node
for node in tree.body
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
and node.name == "get_chain_transfer_pending_port"
]
assert "TransferPendingPortProxy" not in class_names
assert len(getters) == 1
assert getters[0].returns is not None
assert ast.unparse(getters[0].returns) == "TransferAdmissionRepository"
def test_agent_consumers_use_explicit_data_port_getters():
"""Agent 生产模块不得把兼容数据端口代理重新伪装成数据库 Oper。"""
forbidden = {
"AgentChatPort",
"AgentTaskPort",
"DownloadHistoryPort",
"PluginDataPort",
"SitePort",
"SubscribeHistoryPort",
"SubscribePort",
"TransferHistoryPort",
"UserPort",
"WorkflowPort",
}
violations: list[str] = []
for path in (APP_ROOT / "agent").rglob("*.py"):
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if not isinstance(node, ast.ImportFrom):
continue
if node.module != "app.application.agentdata":
continue
for alias in node.names:
if alias.name in forbidden:
violations.append(
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}:{alias.name}"
)
assert violations == []
def test_scheduler_does_not_depend_on_database_implementation():
"""Scheduler 只能消费应用端口,不得重新直连 app.db 实现。"""
dependencies = _build_module_graph().get("app.scheduler", set())
assert {
dependency
for dependency in dependencies
if dependency == "app.db" or dependency.startswith("app.db.")
} == set()
def test_agent_task_async_execution_uses_application_service():
"""AgentTask async 执行不得经动态数据端口隐藏同步 Oper 调用。"""
path = APP_ROOT / "agent" / "orchestrator.py"
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
violations = [
node.lineno
for node in ast.walk(tree)
if isinstance(node, ast.ImportFrom)
and node.module == "app.application.agentdata"
and any(alias.name == "get_agent_task_port" for alias in node.names)
]
assert violations == []
def test_monitor_dispatcher_uses_explicit_history_port_getter():
"""监控分发器不得把兼容 TransferHistoryPort 伪装成数据库 Oper。"""
path = APP_ROOT / "monitor" / "dispatcher.py"
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
violations = [
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}"
for node in ast.walk(tree)
if isinstance(node, ast.ImportFrom)
and node.module == "app.application.history"
and any(alias.name == "TransferHistoryPort" for alias in node.names)
]
assert violations == []
def test_canonical_service_config_consumers_use_application_directory():
"""Chain、API、Scheduler 与 Agent 不得绕过命名应用目录读取服务配置。"""
paths = [
APP_ROOT / "chain" / "_messaging.py",
APP_ROOT / "chain" / "mediaserver.py",
APP_ROOT / "api" / "endpoints" / "message.py",
APP_ROOT / "scheduler.py",
APP_ROOT / "agent" / "llm" / "capability.py",
APP_ROOT / "agent" / "tools" / "base.py",
APP_ROOT / "agent" / "tools" / "impl" / "query_library_latest.py",
APP_ROOT / "api" / "endpoints" / "mediaserver.py",
]
violations: list[str] = []
for path in paths:
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if (
isinstance(node, ast.ImportFrom)
and node.module == "app.runtime.extensions.service_config"
):
violations.append(
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}"
)
if (
path.name == "mediaserver.py"
and isinstance(node, ast.ImportFrom)
and node.module == "app.application.mediaserver"
and any(alias.name == "MediaServerHelper" for alias in node.names)
):
violations.append(
f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}:MediaServerHelper"
)
assert violations == []
def test_plugin_components_do_not_reexport_legacy_abi_names():
"""新插件组件只提供 canonical 能力,不得复制旧 Helper、Manager 或 Oper 导出。"""
violations: list[str] = []
for root in PLUGIN_COMPONENT_ROOTS:
for path in (PROJECT_ROOT / root).rglob("*.py"):
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in tree.body:
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
if node.name == "__getattr__" or node.name in PLUGIN_LEGACY_ABI_NAMES:
violations.append(f"{path.relative_to(PROJECT_ROOT)}:{node.name}")
elif isinstance(node, ast.ClassDef):
if node.name in PLUGIN_LEGACY_ABI_NAMES or node.name.endswith("Oper"):
violations.append(f"{path.relative_to(PROJECT_ROOT)}:{node.name}")
elif isinstance(node, ast.ImportFrom):
for alias in node.names:
is_legacy_name = (
alias.name in PLUGIN_LEGACY_ABI_NAMES
or alias.name.endswith("Oper")
)
is_private = bool(alias.asname and alias.asname.startswith("_"))
if is_legacy_name and not is_private:
violations.append(
f"{path.relative_to(PROJECT_ROOT)}:{alias.name}"
)
elif isinstance(node, (ast.Assign, ast.AnnAssign)):
targets = node.targets if isinstance(node, ast.Assign) else [node.target]
names = {
target.id
for target in targets
if isinstance(target, ast.Name)
}
forbidden = {
name
for name in names
if name == "__all__"
or name in PLUGIN_LEGACY_ABI_NAMES
or name.endswith("Oper")
}
violations.extend(
f"{path.relative_to(PROJECT_ROOT)}:{name}"
for name in sorted(forbidden)
)
assert violations == []
def test_host_code_uses_precise_schema_modules():
"""宿主不得重新依赖 schema 聚合入口或星号导出。"""
violations: list[str] = []
for path in APP_ROOT.rglob("*.py"):
relative = path.relative_to(APP_ROOT)
if relative.parts[0] in {"plugins", "schemas"}:
continue
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if isinstance(node, ast.ImportFrom) and node.module == "app":
if any(alias.name == "schemas" for alias in node.names):
violations.append(str(relative))
break
if isinstance(node, ast.ImportFrom) and node.module == "app.schemas":
violations.append(str(relative))
break
assert violations == []
def test_database_internals_do_not_import_db_facades():
"""DB 子模块必须依赖具体实现文件,不得回流到包级兼容入口。"""
violations: list[str] = []
for path in (APP_ROOT / "db").rglob("*.py"):
if path.name == "__init__.py":
continue
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
if any(
isinstance(node, ast.ImportFrom)
and node.module in {"app.db", "app.db.models"}
for node in ast.walk(tree)
):
violations.append(str(path.relative_to(PROJECT_ROOT)))
assert violations == []
def test_database_opers_use_dboper_transaction_dispatchers():
"""Oper 不得绕过 DbOper 的统一 Session 类型分派直接调用事务 runner。"""
runner_names = {"run_sync_transaction", "run_async_transaction"}
violations: list[str] = []
for path in (APP_ROOT / "db" / "oper").rglob("*.py"):
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if not isinstance(node, ast.ImportFrom) or node.module != "app.db.uow":
continue
imported = {alias.name for alias in node.names} & runner_names
if imported:
relative = path.relative_to(PROJECT_ROOT).as_posix()
violations.append(f"{relative}:{node.lineno}:{','.join(sorted(imported))}")
assert violations == []
def test_models_and_base_require_explicit_database_sessions():
"""Model/Base 不得装饰事务,且所有 db 参数必须由调用方显式传入。"""
decorator_names = {
"db_query",
"db_update",
"async_db_query",
"async_db_update",
"legacy_db_query",
"legacy_db_update",
"legacy_async_db_query",
"legacy_async_db_update",
}
violations: list[str] = []
paths = [APP_ROOT / "db" / "base.py"]
paths.extend((APP_ROOT / "db" / "models").rglob("*.py"))
for path in paths:
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
relative = str(path.relative_to(PROJECT_ROOT))
nodes = list(ast.walk(tree))
for node in nodes:
if isinstance(node, ast.ImportFrom) and node.module == "app.db.decorators":
violations.append(f"{relative}:{node.lineno}:decorator-import")
if path.name == "base.py":
base_class = next(
node
for node in tree.body
if isinstance(node, ast.ClassDef) and node.name == "Base"
)
nodes = list(ast.walk(base_class))
for node in nodes:
if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
continue
for decorator in node.decorator_list:
name = (
decorator.id
if isinstance(decorator, ast.Name)
else decorator.attr
if isinstance(decorator, ast.Attribute)
else None
)
if name in decorator_names:
violations.append(f"{relative}:{node.lineno}:@{name}")
arguments = [*node.args.posonlyargs, *node.args.args]
defaults = [None] * (len(arguments) - len(node.args.defaults)) + list(
node.args.defaults
)
for argument, default in zip(arguments, defaults):
if argument.arg != "db":
continue
annotation = ast.unparse(argument.annotation) if argument.annotation else ""
if default is not None or "None" in annotation:
violations.append(
f"{relative}:{node.lineno}:{node.name}:optional-db"
)
assert violations == []
def test_plugin_sdk_does_not_import_or_export_host_models():
"""插件 SDK 不得暴露 ORM Model,只有精确旧 ABI 门面可在内部访问。"""
internal_compat_imports = {
("app/sdk/_legacy/transferpending.py", "app.db.models.transferpending"),
}
violations: list[str] = []
for path in (APP_ROOT / "sdk").rglob("*.py"):
relative = path.relative_to(PROJECT_ROOT).as_posix()
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if isinstance(node, ast.ImportFrom) and node.module and (
node.module == "app.db.models"
or node.module.startswith("app.db.models.")
) and (relative, node.module) not in internal_compat_imports:
violations.append(
f"{path.relative_to(PROJECT_ROOT)}:{node.lineno}:{node.module}"
)
assert violations == []
def test_entry_layers_do_not_import_database_implementations():
"""API、应用、编排、Agent、监控、模块和 Runtime 只能经端口访问持久化。"""
graph = _build_module_graph()
layer_roots = (
"app.api",
"app.application",
"app.agent",
"app.chain",
"app.monitor",
"app.modules",
"app.runtime",
"app.workflow",
"app.adapters",
)
violations = {
source: sorted(
dependency
for dependency in dependencies
if dependency.startswith("app.db")
)
for source, dependencies in graph.items()
if source.startswith(layer_roots)
and any(dependency.startswith("app.db") for dependency in dependencies)
}
assert violations == {}
def test_migrated_modules_are_not_in_import_cycles():
"""任何 canonical 迁移模块都不得进入完整应用依赖图的环。"""
modules = _discover_modules()
known_modules = set(modules)
graph = {
name: _resolve_imports(name, path, known_modules)
for name, path in modules.items()
}
relevant_cycles = [
sorted(component)
for component in _strongly_connected_components(graph)
if any(name.startswith(CYCLE_ROOTS) for name in component)
]
assert relevant_cycles == []
def test_canonical_layers_do_not_depend_on_sdk_or_compat():
"""canonical 实现层不得反向依赖面向插件的 SDK 或兼容层。"""
violations: dict[str, set[str]] = {}
modules = _discover_modules()
known_modules = set(modules)
for module_name, path in modules.items():
if not module_name.startswith(IMPLEMENTATION_ROOTS):
continue
if module_name.startswith("app.runtime.compat"):
continue
dependencies = _resolve_imports(module_name, path, known_modules)
forbidden = {
dependency
for dependency in dependencies
if dependency.startswith(("app.sdk", "app.runtime.compat"))
}
if forbidden:
violations[module_name] = forbidden
assert violations == {}
def test_capability_packages_do_not_import_forbidden_upper_layers():
"""新能力包只能依赖明确允许的下层或同层协作包。"""
modules = _discover_modules()
known_modules = set(modules)
violations: dict[str, set[str]] = {}
for module_name, path in modules.items():
source_root = next(
(
root
for root in FORBIDDEN_IMPORT_PREFIXES
if module_name == root or module_name.startswith(f"{root}.")
),
None,
)
if not source_root:
continue
dependencies = _resolve_imports(module_name, path, known_modules)
forbidden = {
dependency
for dependency in dependencies
if dependency.startswith(FORBIDDEN_IMPORT_PREFIXES[source_root])
}
if forbidden:
violations[module_name] = forbidden
assert violations == {}
def test_application_does_not_import_transport_frameworks():
"""应用层不得依赖 FastAPI、Starlette 或宿主 HTTP 适配器。"""
violations: dict[str, set[str]] = {}
for path in (APP_ROOT / "application").rglob("*.py"):
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
forbidden: set[str] = set()
for node in ast.walk(tree):
candidates: list[str] = []
if isinstance(node, ast.Import):
candidates.extend(alias.name for alias in node.names)
elif isinstance(node, ast.ImportFrom) and node.module:
candidates.append(node.module)
forbidden.update(
candidate
for candidate in candidates
if candidate.startswith(
("fastapi", "starlette", "app.api", "app.adapters.web")
)
)
if forbidden:
violations[str(path.relative_to(PROJECT_ROOT))] = forbidden
assert violations == {}
def test_site_domain_uses_foundation_dom_boundary():
"""站点领域规则应依赖 DOM 原语,不得重新耦合聚合字符串工具。"""
modules = _discover_modules()
dependencies = _resolve_imports(
"app.domain.site",
modules["app.domain.site"],
set(modules),
)
assert "app.foundation.dom" in dependencies
assert "app.domain.string" not in dependencies
def test_host_code_does_not_use_string_utils_facade():
"""聚合 StringUtils 只服务插件兼容,宿主实现必须使用拆分后的能力。"""
violations: list[str] = []
for path in APP_ROOT.rglob("*.py"):
relative = path.relative_to(APP_ROOT)
if relative.parts[0] in {"plugins", "sdk"}:
continue
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
if any(isinstance(node, ast.Name) and node.id == "StringUtils" for node in ast.walk(tree)):
violations.append(str(relative))
assert violations == []
def test_runtime_log_is_a_dependency_leaf():
"""底层可引用运行时日志,但日志模块本身不得反向导入应用模块。"""
modules = _discover_modules()
dependencies = _resolve_imports(
"app.runtime.log",
modules["app.runtime.log"],
set(modules),
)
assert {
dependency
for dependency in dependencies
if dependency.startswith("app.")
} == set()
def test_foundation_does_not_emit_runtime_logs():
"""基础机制不打印或初始化日志系统,运行期诊断由上层调用方负责。"""
violations: list[str] = []
for path in (APP_ROOT / "foundation").rglob("*.py"):
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if isinstance(node, ast.Import) and any(
alias.name == "logging" for alias in node.names
):
violations.append(str(path.relative_to(PROJECT_ROOT)))
break
if isinstance(node, ast.ImportFrom) and node.module in {
"logging",
"app.runtime.log",
}:
violations.append(str(path.relative_to(PROJECT_ROOT)))
break
if (
isinstance(node, ast.Call)
and isinstance(node.func, ast.Name)
and node.func.id == "print"
):
violations.append(str(path.relative_to(PROJECT_ROOT)))
break
assert violations == []
def test_cache_contract_does_not_import_concrete_adapters():
"""运行时缓存契约和内存机制不得反向导入具体缓存适配器。"""
modules = _discover_modules()
dependencies = _resolve_imports(
"app.runtime.cache",
modules["app.runtime.cache"],
set(modules),
)
assert {
dependency
for dependency in dependencies
if dependency.startswith("app.adapters.cache")
} == set()
def test_resource_adapter_does_not_restart_process():
"""资源下载安装适配器不得反向调用进程重启能力。"""
modules = _discover_modules()
dependencies = _resolve_imports(
"app.adapters.system.resource",
modules["app.adapters.system.resource"],
set(modules),
)
assert "app.runtime.state" not in dependencies
def test_modules_do_not_import_other_modules_or_chain():
"""模块之间以及模块对链层的直接依赖被禁止,跨模块编排归链层。
`app.modules._base` 是模块共享样板基类包(模块发现会跳过),不视为业务模块。
"""
modules = _discover_modules()
known_modules = set(modules)
violations: dict[str, set[str]] = {}
for module_name, path in modules.items():
if not module_name.startswith("app.modules."):
continue
own_package = module_name.split(".")[2]
dependencies = _resolve_imports(module_name, path, known_modules)
forbidden = {
dependency
for dependency in dependencies
if dependency.startswith("app.chain")
or (
dependency.startswith("app.modules.")
and dependency.split(".")[2] not in (own_package, "_base")
)
}
if forbidden:
violations[module_name] = forbidden
assert violations == {}
def test_entrypoints_do_not_import_module_internals():
"""入口层不得穿透导入具体模块实现,应经由链层或应用服务。"""
modules = _discover_modules()
known_modules = set(modules)
entrypoint_roots = ("app.api", "app.agent", "app.monitor", "app.workflow", "app.doctor")
violations: dict[str, set[str]] = {}
for module_name, path in modules.items():
if not module_name.startswith(entrypoint_roots):
continue
dependencies = _resolve_imports(module_name, path, known_modules)
forbidden = {
dependency
for dependency in dependencies
if dependency.startswith("app.modules.")
}
if forbidden:
violations[module_name] = forbidden
assert violations == {}
def test_chain_does_not_import_downloader_sdks():
"""链层不得引入下载器后端协议类型,避免后端细节泄漏到编排层。"""
forbidden_sdks = {"qbittorrentapi", "transmission_rpc"}
violations: list[str] = []
for path in (APP_ROOT / "chain").rglob("*.py"):
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
names: list[str] = []
if isinstance(node, ast.Import):
names.extend(alias.name for alias in node.names)
elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
names.append(node.module)
if any(name.split(".")[0] in forbidden_sdks for name in names):
violations.append(str(path.relative_to(PROJECT_ROOT)))
break
assert violations == []
def test_chain_does_not_import_module_internals():
"""链层与模块只能通过 run_module 方法名契约互联,禁止直接导入模块实现。
模块内容必须封闭在模块内部,链层不显式指定具体模块的类、异常或常量,
这样模块才是可插拔的。
"""
modules = _discover_modules()
known_modules = set(modules)
violations: dict[str, set[str]] = {}
for module_name, path in modules.items():
if not module_name.startswith("app.chain"):
continue
dependencies = _resolve_imports(module_name, path, known_modules)
forbidden = {
dependency
for dependency in dependencies
if dependency.startswith("app.modules.")
}
if forbidden:
violations[module_name] = forbidden
assert violations == {}
@lru_cache(maxsize=1)
def _build_module_graph() -> dict[str, set[str]]:
"""构建非插件模块的完整静态依赖图,供既有包治理断言复用。
纯静态 AST 分析无副作用,结果可安全缓存;多断言共享一次解析。
"""
modules = _discover_modules()
known_modules = set(modules)
return {
name: _resolve_imports(name, path, known_modules)
for name, path in modules.items()
}
def _load_dependency_policy() -> dict:
"""读取人工审查的依赖语义 policy;生成基线不得改写该文件。"""
return json.loads(DEPENDENCY_POLICY_PATH.read_text(encoding="utf-8"))
def _scc_policy_violations(
graph: dict[str, set[str]],
entries: list[dict],
) -> tuple[list[list[str]], list[list[str]]]:
"""返回未审查 SCC 与已经失效但未清理的 policy SCC。"""
actual = {
tuple(component)
for component in _strongly_connected_components(graph)
}
reviewed = {tuple(entry["modules"]) for entry in entries}
return (
[list(component) for component in sorted(actual - reviewed)],
[list(component) for component in sorted(reviewed - actual)],
)
def test_complete_host_sccs_match_reviewed_policy() -> None:
"""完整宿主图的每个 SCC 都必须精确匹配人工 policy,且不得保留陈旧项。"""
policy = _load_dependency_policy()
entries = policy["allowed_sccs"]
assert policy["schema_version"] == 3
assert policy["scope"] == {
"dependency_kind": "static_runtime_imports",
"excluded_roots": ["app/plugins"],
"include_parent_package_initialization": True,
"root": "app",
}
assert {entry["classification"] for entry in entries} == {
"contained_vendor",
"temporary_debt",
}
assert len({entry["id"] for entry in entries}) == len(entries)
assert all(entry["modules"] == sorted(set(entry["modules"])) for entry in entries)
assert all(entry["reason"] and entry["tracking"] for entry in entries)
all_members = [member for entry in entries for member in entry["modules"]]
assert len(all_members) == len(set(all_members))
temporary = next(
entry for entry in entries if entry["classification"] == "temporary_debt"
)
assert temporary["id"] == "chain-package-root"
assert temporary["tracking"] == "ARCH-107"
assert temporary["modules"] == [
"app.chain",
"app.chain._messaging",
"app.chain._recognition",
]
vendor = next(
entry for entry in entries if entry["classification"] == "contained_vendor"
)
assert vendor["id"] == "themoviedb-vendored-package"
assert vendor["tracking"] == "replace-or-upgrade-vendored-package"
assert len(vendor["modules"]) == 29
assert all(
member.startswith("app.modules.themoviedb")
for member in vendor["modules"]
)
unreviewed, stale = _scc_policy_violations(_build_module_graph(), entries)
assert unreviewed == []
assert stale == []
def test_scc_policy_rejects_unreviewed_cycles_in_every_host_root() -> None:
"""API、Chain、Module 与 Startup 内的新环都必须落入未审查集合。"""
for root in ("app.api", "app.chain", "app.modules", "app.startup"):
first = f"{root}.first"
second = f"{root}.second"
unreviewed, stale = _scc_policy_violations(
{first: {second}, second: {first}},
[],
)
assert unreviewed == [[first, second]]
assert stale == []
def test_scc_policy_rejects_changed_or_stale_membership() -> None:
"""已知 SCC 缩小、扩大或消失后必须同步审查 policy,不能静默放行。"""
entries = [{"modules": ["app.chain.first", "app.chain.second", "app.chain.third"]}]
unreviewed, stale = _scc_policy_violations(
{
"app.chain.first": {"app.chain.second"},
"app.chain.second": {"app.chain.first"},
"app.chain.third": set(),
},
entries,
)
assert unreviewed == [["app.chain.first", "app.chain.second"]]
assert stale == [["app.chain.first", "app.chain.second", "app.chain.third"]]
def test_contained_vendor_scc_may_have_one_way_outbound_dependency() -> None:
"""vendor SCC 的普通单向向下依赖不应把包外模块误纳入 containment。"""
first = "app.modules.themoviedb.first"
second = "app.modules.themoviedb.second"
domain = "app.domain.media"
entries = [{"modules": [first, second]}]
unreviewed, stale = _scc_policy_violations(
{first: {second, domain}, second: {first}, domain: set()},
entries,
)
assert unreviewed == []
assert stale == []
def test_host_dependency_graph_excludes_plugin_copies() -> None:
"""`app/plugins/**` 是运行时副本,不能进入宿主模块或 SCC 图。"""
assert all(
not module.startswith("app.plugins")
for module in _discover_modules()
)
def test_chain_does_not_import_agent_implementation():
"""编排层不得反向依赖 Agent 实现,跨域编排经 application 门面。"""
violations: dict[str, set[str]] = {}
for module_name, dependencies in _build_module_graph().items():
if not module_name.startswith("app.chain"):
continue
forbidden = {
dependency
for dependency in dependencies
if dependency.startswith("app.agent")
}
if forbidden:
violations[module_name] = forbidden
assert violations == {}
def test_agent_application_facade_does_not_import_agent_implementation():
"""Agent application 门面只能接收组合根注入,不能反向解析具体实现。"""
dependencies = _build_module_graph()["app.application.agent"]
assert {
dependency
for dependency in dependencies
if dependency.startswith("app.agent")
} == set()
def test_host_consumers_get_agent_manager_through_application_facade():
"""宿主消费者不得绕过 Application 门面直接定位 Agent manager。"""
forbidden = {"get_agent_manager", "get_running_agent_manager"}
violations: dict[str, set[str]] = {}
for module_name, path in _discover_modules().items():
if module_name.startswith(("app.agent", "app.startup")):
continue
tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
imported = {
alias.name
for node in ast.walk(tree)
if isinstance(node, ast.ImportFrom)
and node.module == "app.agent.runtime_loader"
for alias in node.names
if alias.name in forbidden
}
if imported:
violations[module_name] = imported
assert violations == {}
def test_host_consumers_resolve_llm_provider_runtime_through_gateway():
"""宿主不得绕过 gateway 或 LLM 公共导出穿透 provider 实现。"""
violations: dict[str, set[str]] = {}
graph = _build_module_graph()
for module_name, path in _discover_modules().items():
if module_name.startswith(("app.agent", "app.startup")):
continue
tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
imported = {
alias.name
for node in ast.walk(tree)
if isinstance(node, ast.ImportFrom)
and node.module in {"app.agent.llm", "app.agent.llm.provider"}
for alias in node.names
if alias.name == "LLMProviderManager"
}
forbidden = set(imported)
if "app.agent.llm.provider" in graph[module_name]:
forbidden.add("app.agent.llm.provider")
if forbidden:
violations[module_name] = forbidden
assert violations == {}
def test_host_consumers_use_agent_audio_capability_application_port():
"""宿主消费者不得绕过 Application 门面直连 Agent 音频实现。"""
violations: dict[str, set[str]] = {}
for module_name, path in _discover_modules().items():
if module_name.startswith(("app.agent", "app.startup")):
continue
tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
imported = {
alias.name
for node in ast.walk(tree)
if isinstance(node, ast.ImportFrom)
and node.module in {"app.agent.llm", "app.agent.llm.capability"}
for alias in node.names
if alias.name == "AgentCapabilityManager"
}
if imported:
violations[module_name] = imported
assert violations == {}
def test_application_services_do_not_resolve_event_manager_singleton():
"""Application 服务必须接收事件端口,不得自行定位进程级事件单例。"""
violations = {
module_name: dependencies & {"app.runtime.events"}
for module_name, dependencies in _build_module_graph().items()
if module_name.startswith("app.application")
and "app.runtime.events" in dependencies
}
assert violations == {}
def test_http_endpoints_do_not_register_process_event_listeners():
"""HTTP 端点不得拥有进程级事件监听器,监听装配必须留在 startup。"""
facts = _collect_current_event_facts()
callers = {item["caller"] for item in facts["consumers"]}
assert {caller for caller in callers if caller.startswith("app.api")} == set()
def test_agent_tools_do_not_import_entrypoint_internals():
"""Agent 工具不得穿透导入 HTTP 端点、调度器与命令注册表内部实现。
工具对进程级状态的读写必须收敛到 application 门面,
否则 agent 层与入口层互相穿透会形成不可测试的循环。
"""
violations: dict[str, set[str]] = {}
for module_name, dependencies in _build_module_graph().items():
if not module_name.startswith("app.agent.tools"):
continue
forbidden = {
dependency
for dependency in dependencies
if dependency.startswith(("app.api", "app.scheduler", "app.command"))
}
if forbidden:
violations[module_name] = forbidden
assert violations == {}
def test_modules_read_deployment_settings_through_runtime_port():
"""宿主 Module 不得绕过 runtime 配置端口直接依赖 Settings 实例。"""
violations: list[str] = []
for path in (APP_ROOT / "modules").rglob("*.py"):
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if not isinstance(node, ast.ImportFrom) or node.module != "app.runtime.config":
continue
if any(alias.name == "settings" for alias in node.names):
violations.append(path.relative_to(PROJECT_ROOT).as_posix())
break
assert violations == []
def test_runtime_implementation_does_not_use_legacy_settings_proxy():
"""runtime 实现只能使用只读配置端口,不得重新引入迁移期代理对象。"""
violations: list[str] = []
for path in (APP_ROOT / "runtime").rglob("*.py"):
if path == APP_ROOT / "runtime" / "settings.py":
continue
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
for node in ast.walk(tree):
if not isinstance(node, ast.ImportFrom):
continue
if node.module != "app.runtime.settings":
continue
if any(alias.name.lower().endswith("compat") for alias in node.names):
violations.append(path.relative_to(PROJECT_ROOT).as_posix())
break
assert violations == []
def test_deprecated_settings_proxy_imports_are_zero():
"""宿主代码不得导入已删除的 Settings 兼容代理。"""
limits = {
"adapters": 0,
"agent": 0,
"application": 0,
"cli.py": 0,
"doctor": 0,
"factory.py": 0,
"main.py": 0,
"modules": 0,
"startup": 0,
}
counts: dict[str, int] = {}
for path in APP_ROOT.rglob("*.py"):
if path == APP_ROOT / "runtime" / "settings.py":
continue
if path.is_relative_to(APP_ROOT / "plugins"):
continue
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
imports_compat = any(
isinstance(node, ast.ImportFrom)
and node.module == "app.runtime.settings"
and any(alias.name.lower().endswith("compat") for alias in node.names)
for node in ast.walk(tree)
)
if not imports_compat:
continue
relative = path.relative_to(APP_ROOT)
group = relative.parts[0] if len(relative.parts) > 1 else relative.as_posix()
counts[group] = counts.get(group, 0) + 1
unexpected = set(counts) - set(limits)
exceeded = {
group: count
for group, count in counts.items()
if group in limits and count > limits[group]
}
assert unexpected == set()
assert exceeded == {}
def test_global_settings_imports_stay_within_compatibility_baseline():
"""真实 Settings 对象只能保留在已知迁移点和插件 SDK,不得产生新宿主调用。"""
allowed = {
"app/sdk/config.py",
"app/startup/initializers/modules.py",
}
imports: set[str] = set()
for path in APP_ROOT.rglob("*.py"):
if path.is_relative_to(APP_ROOT / "plugins"):
continue
tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
if any(
isinstance(node, ast.ImportFrom)
and node.module == "app.runtime.config"
and any(alias.name == "settings" for alias in node.names)
for node in ast.walk(tree)
):
imports.add(path.relative_to(PROJECT_ROOT).as_posix())
assert imports <= allowed
def test_api_does_not_import_factory():
"""装配器(factory)只允许 app.main 使用,HTTP 端点不得回引。"""
violations: dict[str, set[str]] = {}
for module_name, dependencies in _build_module_graph().items():
if not module_name.startswith("app.api"):
continue
forbidden = {
dependency
for dependency in dependencies
if dependency.startswith("app.factory")
}
if forbidden:
violations[module_name] = forbidden
assert violations == {}
PROCESS_LEVEL_ROOTS = (
"app.api",
"app.chain",
"app.agent",
"app.scheduler",
"app.command",
"app.monitor",
"app.startup",
"app.factory",
)
def test_process_level_packages_are_not_mutually_cyclic():
"""进程级根包之间不得形成跨包强连通分量。
允许的环只存在于:单一包内部(modules 模块内、db 内、schemas 包内、
agent 子域内、doctor 内)。跨根包的环意味着入口层、编排层与 Agent 层
互相穿透,破坏可插拔性与可测试性。
"""
graph = _build_module_graph()
components = _strongly_connected_components(graph)
violations: list[list[str]] = []
for component in components:
roots = {
name.split(".")[1]
for name in component
if name.startswith("app.") and name.count(".") >= 1
}
involved = {root for root in roots if f"app.{root}" in PROCESS_LEVEL_ROOTS}
if len(involved) > 1:
violations.append(sorted(component))
assert violations == []