feat: complete governed documentation sources
This commit is contained in:
@@ -9,6 +9,13 @@ from fastapi import HTTPException
|
||||
|
||||
from govoplan_access.backend.manifest import get_manifest as get_access_manifest
|
||||
from govoplan_core.core.modules import DocumentationCondition, DocumentationLink, DocumentationTopic, ModuleManifest, NavItem
|
||||
from govoplan_core.core.modules import (
|
||||
DocumentationConfigurationDecision,
|
||||
DocumentationConfigurationProviderRegistration,
|
||||
DocumentationSourceDefinition,
|
||||
FrontendModule,
|
||||
FrontendRoute,
|
||||
)
|
||||
from govoplan_core.core.registry import PlatformRegistry
|
||||
from govoplan_tenancy.backend.manifest import get_manifest as get_tenancy_manifest
|
||||
from govoplan_docs.backend.api.v1.routes import (
|
||||
@@ -16,9 +23,11 @@ from govoplan_docs.backend.api.v1.routes import (
|
||||
_condition_visibility,
|
||||
_documentation_topic_anchor,
|
||||
_documentation_topic_groups,
|
||||
_visible_documentation_sources,
|
||||
docs_context,
|
||||
)
|
||||
from govoplan_docs.backend.manifest import get_manifest as get_docs_manifest
|
||||
from govoplan_docs.backend.sources import build_documentation_source_registry
|
||||
|
||||
|
||||
class FakePrincipal:
|
||||
@@ -208,7 +217,12 @@ class DocsContextTests(unittest.TestCase):
|
||||
)
|
||||
self.assertEqual(topic["conditions"], [])
|
||||
self.assertEqual(topic["configuration_keys"], [])
|
||||
self.assertEqual(topic["blockers"], {"modules": [], "capabilities": [], "scopes": []})
|
||||
self.assertEqual(topic["blockers"], {
|
||||
"modules": [],
|
||||
"capabilities": [],
|
||||
"scopes": [],
|
||||
"configuration": [],
|
||||
})
|
||||
self.assertNotIn("raw_policy", topic["metadata"])
|
||||
self.assertNotIn("api_path", topic["metadata"])
|
||||
self.assertEqual(topic["metadata"]["help_contexts"], ["example.list"])
|
||||
@@ -327,6 +341,7 @@ class DocsContextTests(unittest.TestCase):
|
||||
self.assertEqual(blockers["modules"], ["mail", "files", "campaigns", "legacy"])
|
||||
self.assertEqual(blockers["capabilities"], ["mail.delivery"])
|
||||
self.assertEqual(blockers["scopes"], ["mail:profile:read", "admin:policies:read"])
|
||||
self.assertEqual(blockers["configuration"], [])
|
||||
|
||||
def test_condition_visibility_accepts_any_module_scope_and_capability(self) -> None:
|
||||
registry = PlatformRegistry()
|
||||
@@ -342,7 +357,213 @@ class DocsContextTests(unittest.TestCase):
|
||||
|
||||
self.assertTrue(active)
|
||||
self.assertEqual(reason, "conditions satisfied")
|
||||
self.assertEqual(blockers, {"modules": [], "capabilities": [], "scopes": []})
|
||||
self.assertEqual(blockers, {
|
||||
"modules": [],
|
||||
"capabilities": [],
|
||||
"scopes": [],
|
||||
"configuration": [],
|
||||
})
|
||||
|
||||
def test_configuration_states_gate_conditions_without_disclosing_values(self) -> None:
|
||||
states = {
|
||||
"feature.enabled": "enabled",
|
||||
"feature.inherited": "inherited",
|
||||
"feature.disabled": "disabled",
|
||||
"feature.unavailable": "unavailable",
|
||||
}
|
||||
|
||||
def resolve(_context, keys):
|
||||
return {
|
||||
key: DocumentationConfigurationDecision(
|
||||
key=key,
|
||||
state=states[key], # type: ignore[arg-type]
|
||||
source="tenant" if states[key] == "enabled" else "system",
|
||||
reason="State metadata only.",
|
||||
)
|
||||
for key in keys
|
||||
}
|
||||
|
||||
topics = tuple(
|
||||
DocumentationTopic(
|
||||
id=f"example.{key}",
|
||||
title=key,
|
||||
summary="Configuration-aware topic.",
|
||||
conditions=(
|
||||
DocumentationCondition(
|
||||
required_scopes=("docs:documentation:read",),
|
||||
configuration_keys=(key,),
|
||||
),
|
||||
),
|
||||
configuration_keys=(key,),
|
||||
)
|
||||
for key in states
|
||||
)
|
||||
registry = PlatformRegistry()
|
||||
registry.register(ModuleManifest(
|
||||
id="example",
|
||||
name="Example",
|
||||
version="1.0.0",
|
||||
documentation=topics,
|
||||
documentation_configuration_providers=(
|
||||
DocumentationConfigurationProviderRegistration(
|
||||
keys=tuple(states),
|
||||
resolve=resolve,
|
||||
),
|
||||
),
|
||||
))
|
||||
|
||||
layers = _classify_documentation(
|
||||
registry,
|
||||
FakePrincipal({"docs:documentation:read"}),
|
||||
settings=None,
|
||||
session=None,
|
||||
documentation_type="admin",
|
||||
locale="en",
|
||||
)
|
||||
|
||||
self.assertEqual(
|
||||
{topic["id"] for topic in layers["configured"]},
|
||||
{"example.feature.enabled", "example.feature.inherited"},
|
||||
)
|
||||
self.assertEqual(
|
||||
[topic["id"] for topic in layers["available"]],
|
||||
["example.feature.disabled"],
|
||||
)
|
||||
self.assertEqual(
|
||||
[topic["id"] for topic in layers["evidence"]],
|
||||
["example.feature.unavailable"],
|
||||
)
|
||||
rendered = repr(layers)
|
||||
self.assertNotIn("raw value", rendered.casefold())
|
||||
self.assertNotIn("password", rendered.casefold())
|
||||
|
||||
def test_source_registry_covers_every_kind_and_redacts_explicit_payloads(self) -> None:
|
||||
manifest = ModuleManifest(
|
||||
id="example",
|
||||
name="Example",
|
||||
version="1.2.3",
|
||||
capability_factories={
|
||||
"example.lookup": lambda _context: object(),
|
||||
"policy.example": lambda _context: object(),
|
||||
},
|
||||
frontend=FrontendModule(
|
||||
module_id="example",
|
||||
routes=(
|
||||
FrontendRoute(
|
||||
path="/example",
|
||||
component="ExamplePage",
|
||||
required_all=("example:item:read",),
|
||||
),
|
||||
),
|
||||
),
|
||||
documentation_sources=(
|
||||
DocumentationSourceDefinition(
|
||||
id="example.configuration.package",
|
||||
kind="configuration_package",
|
||||
label="Example package",
|
||||
inspection={
|
||||
"package_id": "example.package",
|
||||
"schema_version": "2",
|
||||
"password": "must-not-leak",
|
||||
},
|
||||
),
|
||||
DocumentationSourceDefinition(
|
||||
id="example.project.wiki",
|
||||
kind="wiki",
|
||||
label="Example wiki",
|
||||
link=DocumentationLink(
|
||||
label="Wiki",
|
||||
href="https://example.invalid/wiki",
|
||||
kind="wiki",
|
||||
),
|
||||
),
|
||||
DocumentationSourceDefinition(
|
||||
id="example.repository.handbook",
|
||||
kind="repository",
|
||||
label="Example handbook",
|
||||
link=DocumentationLink(
|
||||
label="Handbook",
|
||||
href="example/docs/HANDBOOK.md",
|
||||
kind="repository",
|
||||
),
|
||||
),
|
||||
),
|
||||
)
|
||||
|
||||
sources = build_documentation_source_registry((manifest,)).sources()
|
||||
|
||||
self.assertEqual(
|
||||
{source.item.kind for source in sources},
|
||||
{
|
||||
"manifest",
|
||||
"route",
|
||||
"capability",
|
||||
"policy",
|
||||
"configuration_package",
|
||||
"wiki",
|
||||
"repository",
|
||||
},
|
||||
)
|
||||
self.assertNotIn("must-not-leak", repr(sources))
|
||||
for source in sources:
|
||||
self.assertTrue(source.item.id.startswith("example."))
|
||||
self.assertEqual("example", source.item.owner_module_id)
|
||||
self.assertEqual(
|
||||
f"/api/v1/docs/sources/{source.item.id}",
|
||||
source.item.inspection_url,
|
||||
)
|
||||
|
||||
def test_source_visibility_hides_unauthorized_ids(self) -> None:
|
||||
manifest = ModuleManifest(
|
||||
id="example",
|
||||
name="Example",
|
||||
version="1.0.0",
|
||||
documentation_sources=(
|
||||
DocumentationSourceDefinition(
|
||||
id="example.protected.handbook",
|
||||
kind="repository",
|
||||
label="Protected handbook",
|
||||
condition=DocumentationCondition(
|
||||
required_scopes=("example:handbook:read",),
|
||||
),
|
||||
link=DocumentationLink(
|
||||
label="Protected",
|
||||
href="example/docs/PROTECTED.md",
|
||||
kind="repository",
|
||||
),
|
||||
),
|
||||
),
|
||||
)
|
||||
registry = PlatformRegistry()
|
||||
registry.register(manifest)
|
||||
sources = build_documentation_source_registry((manifest,)).sources()
|
||||
|
||||
denied = _visible_documentation_sources(
|
||||
sources,
|
||||
registry,
|
||||
FakePrincipal({"docs:documentation:admin"}),
|
||||
settings=None,
|
||||
session=None,
|
||||
documentation_type="admin",
|
||||
locale="en",
|
||||
)
|
||||
allowed = _visible_documentation_sources(
|
||||
sources,
|
||||
registry,
|
||||
FakePrincipal({
|
||||
"docs:documentation:admin",
|
||||
"example:handbook:read",
|
||||
}),
|
||||
settings=None,
|
||||
session=None,
|
||||
documentation_type="admin",
|
||||
locale="en",
|
||||
)
|
||||
|
||||
denied_ids = {source.item.id for source in denied}
|
||||
allowed_ids = {source.item.id for source in allowed}
|
||||
self.assertNotIn("example.protected.handbook", denied_ids)
|
||||
self.assertIn("example.protected.handbook", allowed_ids)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
Reference in New Issue
Block a user