Search for a node to inspect its neighborhood.
Visualization disconnected
diff --git a/src/docforge/cli.py b/src/docforge/cli.py
index 9e5f507..35b55d2 100644
--- a/src/docforge/cli.py
+++ b/src/docforge/cli.py
@@ -13,11 +13,9 @@ from .client_config import CLIENT_NAMES, generate_client_configuration
from .context import compile_context
from .doctor import run_doctor
from .errors import DocForgeError
-from .graph_rendering import GraphRenderService
from .index import ProjectIndex
from .onboarding import assess_project, scaffold_project
from .project import Project, project_root_fingerprint
-from .projection_policy import compose_projection_policy
from .rendering import RenderService
from .telemetry import request
from .viewer_manager import ViewerManagerClient
@@ -31,18 +29,6 @@ def _parser() -> argparse.ArgumentParser:
action="store_true",
help="Attach bounded request-local stage timings and counters",
)
- parser.add_argument(
- "--manual-render-policy",
- choices=("auto", "explicit", "disabled"),
- )
- parser.add_argument(
- "--portable-graph-policy",
- choices=("explicit", "disabled"),
- )
- parser.add_argument(
- "--live-viewer-policy",
- choices=("on-demand", "disabled"),
- )
commands = parser.add_subparsers(dest="command", required=True)
configure = commands.add_parser("configure")
configure.add_argument("client", choices=CLIENT_NAMES)
@@ -56,21 +42,6 @@ def _parser() -> argparse.ArgumentParser:
configure.add_argument("--proposal-writer")
configure.add_argument("--canonical-applier")
configure.add_argument("--no-ast", action="store_true")
- configure.add_argument(
- "--manual-render-policy",
- choices=("auto", "explicit", "disabled"),
- default=argparse.SUPPRESS,
- )
- configure.add_argument(
- "--portable-graph-policy",
- choices=("explicit", "disabled"),
- default=argparse.SUPPRESS,
- )
- configure.add_argument(
- "--live-viewer-policy",
- choices=("on-demand", "disabled"),
- default=argparse.SUPPRESS,
- )
configure.add_argument("--startup-timeout", type=int, default=30)
configure.add_argument("--tool-timeout", type=int, default=300)
configure.add_argument("--output", type=Path)
@@ -124,12 +95,6 @@ def _parser() -> argparse.ArgumentParser:
render_status = commands.add_parser("render-status")
render_status.add_argument("view_id", nargs="?")
render_status.add_argument("--deep", action="store_true")
- graph_plan = commands.add_parser("graph-plan")
- graph_plan.add_argument("view_id")
- graph_render = commands.add_parser("graph-render")
- graph_render.add_argument("view_id")
- graph_render_status = commands.add_parser("graph-render-status")
- graph_render_status.add_argument("view_id", nargs="?")
preview = commands.add_parser("preview")
preview.add_argument("changeset_id")
preview.add_argument("view_id")
@@ -159,9 +124,6 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
proposal_writer=arguments.proposal_writer,
canonical_applier=arguments.canonical_applier,
no_ast=arguments.no_ast,
- manual_render_policy=arguments.manual_render_policy,
- portable_graph_policy=arguments.portable_graph_policy,
- live_viewer_policy=arguments.live_viewer_policy,
startup_timeout=arguments.startup_timeout,
tool_timeout=arguments.tool_timeout,
output=arguments.output,
@@ -190,39 +152,12 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
content_root=arguments.content_root,
)
project = Project.open(arguments.project_root)
- projection_policy = compose_projection_policy(
- manual=arguments.manual_render_policy,
- portable_graph=arguments.portable_graph_policy,
- live_viewer=arguments.live_viewer_policy,
- manual_configured=project.descriptor.render is not None,
- portable_graph_configured=project.descriptor.graph_render is not None,
- application_enabled=False,
- )
build = ProjectIndex(project).build()
- render = (
- {
- "status": "ok",
- "state": "skipped",
- "reason": "projection_policy_disabled",
- }
- if projection_policy.manual == "disabled"
- else RenderService(
- project,
- manual_policy=projection_policy.manual,
- ).render("manual")
- )
+ render = RenderService(project).render("manual")
return {**scaffold, "build": build, "render": render}
return assess_project(arguments.project_root, requested_languages=languages)
project = Project.open(arguments.project_root)
index = ProjectIndex(project)
- projection_policy = compose_projection_policy(
- manual=arguments.manual_render_policy,
- portable_graph=arguments.portable_graph_policy,
- live_viewer=arguments.live_viewer_policy,
- manual_configured=project.descriptor.render is not None,
- portable_graph_configured=project.descriptor.graph_render is not None,
- application_enabled=arguments.command == "apply",
- )
if arguments.command == "info":
snapshot = project.load()
return {
@@ -315,52 +250,24 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
cursor=arguments.cursor,
)
if arguments.command == "render":
- return RenderService(
- project,
- manual_policy=projection_policy.manual,
- ).render(arguments.view_id)
+ return RenderService(project).render(arguments.view_id)
if arguments.command == "render-status":
- rendering = RenderService(
- project,
- manual_policy=projection_policy.manual,
- )
+ rendering = RenderService(project)
return (
rendering.deep_status(arguments.view_id)
if arguments.deep
else rendering.status(arguments.view_id)
)
- if arguments.command == "graph-plan":
- return GraphRenderService(
- project,
- portable_graph_policy=projection_policy.portable_graph,
- ).plan(arguments.view_id)
- if arguments.command == "graph-render":
- return GraphRenderService(
- project,
- portable_graph_policy=projection_policy.portable_graph,
- ).render(arguments.view_id)
- if arguments.command == "graph-render-status":
- return GraphRenderService(
- project,
- portable_graph_policy=projection_policy.portable_graph,
- ).status(arguments.view_id)
if arguments.command == "preview":
- return RenderService(
- project,
- manual_policy=projection_policy.manual,
- ).preview(arguments.changeset_id, arguments.view_id)
+ return RenderService(project).preview(arguments.changeset_id, arguments.view_id)
if arguments.command == "apply":
return CanonicalApplicationService(
project,
applier_id=arguments.applier,
applier=GenericCanonicalApplier(project),
- manual_policy=projection_policy.manual,
).apply(arguments.changeset_id, arguments.changeset_hash)
if arguments.command == "visualize":
- visualization = ViewerManagerClient(
- index,
- live_viewer_policy=projection_policy.live_viewer,
- ).start(
+ visualization = ViewerManagerClient(index).start(
node_id=arguments.node,
query=arguments.query,
depth=arguments.depth,
@@ -377,15 +284,9 @@ def _run(arguments: argparse.Namespace) -> dict[str, object]:
"visualization": visualization,
}
if arguments.command == "visualization-status":
- return ViewerManagerClient(
- index,
- live_viewer_policy=projection_policy.live_viewer,
- ).status()
+ return ViewerManagerClient(index).status()
if arguments.command == "visualization-stop":
- return ViewerManagerClient(
- index,
- live_viewer_policy=projection_policy.live_viewer,
- ).stop()
+ return ViewerManagerClient(index).stop()
raise DocForgeError("invalid_command", "Unknown command")
diff --git a/src/docforge/client_config.py b/src/docforge/client_config.py
index 18c9de6..7b482d5 100644
--- a/src/docforge/client_config.py
+++ b/src/docforge/client_config.py
@@ -18,10 +18,9 @@ from typing import Literal, cast
from .changeset_contract import document_hash
from .errors import DocForgeError
-from .models import ProjectDescriptor, ProjectService
+from .models import ProjectService
from .policy import CapabilityMode, compose_effective_policy
-from .project import Project, project_root_fingerprint, validate_descriptor_binding
-from .projection_policy import compose_projection_policy
+from .project import project_root_fingerprint, validate_descriptor_binding
ClientName = Literal["codex", "claude", "openclaw"]
CLIENT_NAMES: tuple[ClientName, ...] = ("codex", "claude", "openclaw")
@@ -606,37 +605,11 @@ def _atomic_write(
os.close(directory_fd)
-def _validate_configuration_result(
- result: dict[str, object],
- *,
- trusted_descriptor: ProjectDescriptor | None = None,
-) -> None:
+def _validate_configuration_result(result: dict[str, object]) -> None:
artifact = cast(dict[str, object], result["artifact"])
binding = cast(dict[str, object], result["binding"])
policy = cast(dict[str, object], result["effective_policy"])
- projection_policy = cast(dict[str, object], result["projection_policy"])
- projection_availability = cast(
- dict[str, object],
- result["projection_availability"],
- )
project = cast(dict[str, object], result["project"])
- if trusted_descriptor is None:
- try:
- bound_descriptor = Project.open(cast(str, project["project_root"])).descriptor
- except (DocForgeError, KeyError, TypeError) as error:
- raise AssertionError(
- "Generated client project binding cannot be independently validated"
- ) from error
- else:
- bound_descriptor = trusted_descriptor
- if (
- project["project_id"] != bound_descriptor.project_id
- or project["project_root"] != str(bound_descriptor.root)
- or project["project_root_fingerprint"] != project_root_fingerprint(bound_descriptor.root)
- or project["adapter"] != bound_descriptor.adapter
- or project["descriptor_hash"] != bound_descriptor.descriptor_hash
- ):
- raise AssertionError("Generated client project binding drifted")
content = cast(str, artifact["content"])
if artifact["content_sha256"] != hashlib.sha256(content.encode("utf-8")).hexdigest():
raise AssertionError("Generated client content hash drifted")
@@ -671,29 +644,6 @@ def _validate_configuration_result(
if remaining[-1:] != ["--no-ast"] or arguments.count("--no-ast") != 1:
raise AssertionError("Generated no-AST argument layout drifted")
remaining = remaining[:-1]
- projection_arguments: dict[str, str] = {}
- authority_arguments: list[str] = []
- position = 0
- projection_options = {
- "--manual-render-policy": "manual",
- "--portable-graph-policy": "portable_graph",
- "--live-viewer-policy": "live_viewer",
- }
- while position < len(remaining):
- option = remaining[position]
- field = projection_options.get(option)
- if field is None:
- authority_arguments.append(option)
- position += 1
- continue
- if position + 1 >= len(remaining) or option in projection_arguments:
- raise AssertionError("Generated projection policy argument layout drifted")
- value = remaining[position + 1]
- projection_arguments[option] = value
- if projection_policy[field] != value:
- raise AssertionError("Generated projection policy argument drifted")
- position += 2
- remaining = authority_arguments
mode = binding["capability_mode"]
if (
(mode == "read" and remaining)
@@ -713,34 +663,6 @@ def _validate_configuration_result(
)
):
raise AssertionError("Generated authority argument layout drifted")
- expected_projection_policy = compose_projection_policy(
- manual=projection_arguments.get("--manual-render-policy"),
- portable_graph=projection_arguments.get("--portable-graph-policy"),
- live_viewer=projection_arguments.get("--live-viewer-policy"),
- manual_configured=cast(bool, projection_availability["manual_configured"]),
- portable_graph_configured=cast(
- bool,
- projection_availability["portable_graph_configured"],
- ),
- application_enabled=cast(
- bool,
- projection_availability["application_enabled"],
- ),
- live_viewer_available=cast(
- bool,
- projection_availability["live_viewer_available"],
- ),
- )
- if (
- projection_policy != expected_projection_policy.as_dict()
- or projection_availability["manual_configured"] != (render_policy["manual"] != "disabled")
- or projection_availability["manual_configured"] != (bound_descriptor.render is not None)
- or projection_availability["portable_graph_configured"]
- != (bound_descriptor.graph_render is not None)
- or projection_availability["application_enabled"] != (mode == "application")
- or projection_availability["live_viewer_available"] is not True
- ):
- raise AssertionError("Generated projection policy drifted from its availability")
composed_policy = compose_effective_policy(
selected_mode=cast(CapabilityMode, mode),
capability_source="explicit",
@@ -776,18 +698,6 @@ def _validate_configuration_result(
)
):
raise AssertionError("Generated client policy drifted from its binding")
- if (
- result["projection_policy_hash"]
- != hashlib.sha256(
- json.dumps(
- projection_policy,
- sort_keys=True,
- separators=(",", ":"),
- ensure_ascii=False,
- ).encode("utf-8")
- ).hexdigest()
- ):
- raise AssertionError("Generated projection policy hash drifted")
expected_hash = document_hash(
{
"schema_version": 1,
@@ -796,9 +706,6 @@ def _validate_configuration_result(
"project": project,
"binding": binding,
"effective_policy": policy,
- "projection_policy": projection_policy,
- "projection_policy_hash": result["projection_policy_hash"],
- "projection_availability": projection_availability,
"artifact_format": artifact["format"],
"artifact_content_sha256": artifact["content_sha256"],
}
@@ -816,9 +723,6 @@ def generate_client_configuration(
proposal_writer: str | None = None,
canonical_applier: str | None = None,
no_ast: bool = False,
- manual_render_policy: str | None = None,
- portable_graph_policy: str | None = None,
- live_viewer_policy: str | None = None,
startup_timeout: int = 30,
tool_timeout: int = 300,
output: Path | None = None,
@@ -935,6 +839,9 @@ def generate_client_configuration(
arguments.extend(("--proposal-writer", proposal_writer))
if canonical_applier is not None:
arguments.extend(("--canonical-applier", canonical_applier))
+ if no_ast:
+ arguments.append("--no-ast")
+
policy = compose_effective_policy(
selected_mode=selected_mode,
capability_source="explicit",
@@ -943,40 +850,6 @@ def generate_client_configuration(
render_configured=descriptor.render is not None,
application_enabled=canonical_applier is not None,
)
- projection_policy = compose_projection_policy(
- manual=manual_render_policy,
- portable_graph=portable_graph_policy,
- live_viewer=live_viewer_policy,
- manual_configured=descriptor.render is not None,
- portable_graph_configured=descriptor.graph_render is not None,
- application_enabled=canonical_applier is not None,
- )
- default_projection_policy = compose_projection_policy(
- manual_configured=descriptor.render is not None,
- portable_graph_configured=descriptor.graph_render is not None,
- application_enabled=canonical_applier is not None,
- )
- for option, selected, default in (
- (
- "--manual-render-policy",
- projection_policy.manual,
- default_projection_policy.manual,
- ),
- (
- "--portable-graph-policy",
- projection_policy.portable_graph,
- default_projection_policy.portable_graph,
- ),
- (
- "--live-viewer-policy",
- projection_policy.live_viewer,
- default_projection_policy.live_viewer,
- ),
- ):
- if selected != default:
- arguments.extend((option, selected))
- if no_ast:
- arguments.append("--no-ast")
artifact_format, content, warning = _artifact(
selected_client,
server_name=selected_name,
@@ -1029,7 +902,6 @@ def generate_client_configuration(
"project_root": str(descriptor.root),
"project_root_fingerprint": fingerprint,
"adapter": descriptor.adapter,
- "descriptor_hash": descriptor.descriptor_hash,
}
policy_payload = policy.as_dict()
plan_hash = document_hash(
@@ -1040,14 +912,6 @@ def generate_client_configuration(
"project": project_binding,
"binding": binding,
"effective_policy": policy_payload,
- "projection_policy": projection_policy.as_dict(),
- "projection_policy_hash": projection_policy.policy_hash,
- "projection_availability": {
- "manual_configured": descriptor.render is not None,
- "portable_graph_configured": descriptor.graph_render is not None,
- "application_enabled": canonical_applier is not None,
- "live_viewer_available": True,
- },
"artifact_format": artifact_format,
"artifact_content_sha256": artifact["content_sha256"],
}
@@ -1062,14 +926,6 @@ def generate_client_configuration(
"project": project_binding,
"binding": binding,
"effective_policy": policy_payload,
- "projection_policy": projection_policy.as_dict(),
- "projection_policy_hash": projection_policy.policy_hash,
- "projection_availability": {
- "manual_configured": descriptor.render is not None,
- "portable_graph_configured": descriptor.graph_render is not None,
- "application_enabled": canonical_applier is not None,
- "live_viewer_available": True,
- },
"artifact": artifact,
"configuration_hash": plan_hash,
"warnings": [
@@ -1077,5 +933,5 @@ def generate_client_configuration(
*([] if publication_warning is None else [{"code": publication_warning}]),
],
}
- _validate_configuration_result(result, trusted_descriptor=descriptor)
+ _validate_configuration_result(result)
return result
diff --git a/src/docforge/doctor.py b/src/docforge/doctor.py
index 89fd345..e79ed61 100644
--- a/src/docforge/doctor.py
+++ b/src/docforge/doctor.py
@@ -20,7 +20,6 @@ from .project import (
project_root_fingerprint,
validate_descriptor_binding,
)
-from .projection_policy import compose_projection_policy
MAX_CLIENT_CONFIG_BYTES = 1_000_000
MAX_CLIENT_SERVERS = 256
@@ -615,9 +614,6 @@ def _parse_binding(arguments: list[str]) -> dict[str, object]:
"--proposal-writer",
"--canonical-applier",
"--capability-mode",
- "--manual-render-policy",
- "--portable-graph-policy",
- "--live-viewer-policy",
}
flag_options = {"--no-ast", "--diagnostics"}
position = 0
@@ -666,9 +662,6 @@ def _parse_binding(arguments: list[str]) -> dict[str, object]:
"capability_mode_implicit": implicit,
"no_ast": "--no-ast" in flags,
"diagnostics": "--diagnostics" in flags,
- "manual_render_policy": values.get("--manual-render-policy"),
- "portable_graph_policy": values.get("--portable-graph-policy"),
- "live_viewer_policy": values.get("--live-viewer-policy"),
}
@@ -756,16 +749,6 @@ def _runtime_policy_check(
canonical_applier is not None and selected_mode in {"application", "operator"}
),
)
- compose_projection_policy(
- manual=cast(str | None, binding["manual_render_policy"]),
- portable_graph=cast(str | None, binding["portable_graph_policy"]),
- live_viewer=cast(str | None, binding["live_viewer_policy"]),
- manual_configured=project.descriptor.render is not None,
- portable_graph_configured=project.descriptor.graph_render is not None,
- application_enabled=(
- canonical_applier is not None and selected_mode in {"application", "operator"}
- ),
- )
if cast(bool, binding["capability_mode_implicit"]):
return (
"warning",
diff --git a/src/docforge/graph_projection.py b/src/docforge/graph_projection.py
deleted file mode 100644
index d716389..0000000
--- a/src/docforge/graph_projection.py
+++ /dev/null
@@ -1,525 +0,0 @@
-"""Pure, bounded portable-graph planning over one immutable graph generation."""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from typing import Literal, cast
-
-from .errors import DocForgeError
-from .models import Edge, Node, ProjectSnapshot
-from .project import project_root_fingerprint
-from .projection_contract import (
- MAX_GRAPH_VIEW_DEPTH,
- MAX_GRAPH_VIEW_EDGES,
- MAX_GRAPH_VIEW_FILTERS,
- MAX_GRAPH_VIEW_NODES,
- MAX_GRAPH_VIEW_QUERY_CHARS,
- MAX_GRAPH_VIEW_STRING_CHARS,
- MAX_GRAPH_VIEW_WORK,
- GraphViewPlanV1,
- ProjectionPackageV1,
-)
-
-GraphViewMode = Literal["nodes", "flow", "web", "logic"]
-
-_QUERY_TOKEN = re.compile(r"\w+", re.UNICODE)
-_DETAIL_FIELDS = (
- "node_id",
- "title",
- "family",
- "authority",
- "status",
- "tags",
- "summary",
- "content_hash",
-)
-
-
-@dataclass(frozen=True)
-class GraphViewRequestV1:
- """One closed, inert graph selection request."""
-
- view_id: str
- title: str
- root_node_id: str | None = None
- query: str | None = None
- initial_mode: GraphViewMode = "nodes"
- depth: int = 1
- max_nodes: int = 100
- max_edges: int = 400
- max_work: int = 100_000
- families: tuple[str, ...] = ()
- relations: tuple[str, ...] = ()
- authorities: tuple[str, ...] = ()
- statuses: tuple[str, ...] = ()
- tags: tuple[str, ...] = ()
- include_logic: bool = False
-
-
-@dataclass(frozen=True)
-class _ValidatedRequest:
- view_id: str
- title: str
- root_node_id: str | None
- query: str | None
- initial_mode: GraphViewMode
- depth: int
- max_nodes: int
- max_edges: int
- max_work: int
- families: tuple[str, ...]
- relations: tuple[str, ...]
- authorities: tuple[str, ...]
- statuses: tuple[str, ...]
- tags: tuple[str, ...]
- include_logic: bool
-
-
-def _invalid(message: str, **details: object) -> DocForgeError:
- return DocForgeError("invalid_graph_view_request", message, **details)
-
-
-def _string(value: object, *, field: str, maximum: int = MAX_GRAPH_VIEW_STRING_CHARS) -> str:
- if not isinstance(value, str) or not value.strip() or len(value) > maximum or "\0" in value:
- raise _invalid("Graph view request string is invalid", field=field)
- return value.strip()
-
-
-def _filter_values(values: object, *, field: str) -> tuple[str, ...]:
- if not isinstance(values, tuple):
- raise _invalid("Graph view filter is invalid", field=field)
- tuple_values = cast(tuple[object, ...], values)
- if not all(isinstance(value, str) for value in tuple_values):
- raise _invalid("Graph view filter is invalid", field=field)
- if len(tuple_values) > MAX_GRAPH_VIEW_FILTERS:
- raise _invalid("Graph view filter is invalid", field=field)
- normalized = tuple(_string(value, field=field) for value in cast(tuple[str, ...], tuple_values))
- if len(normalized) != len(set(normalized)):
- raise _invalid("Graph view filter contains duplicates", field=field)
- return tuple(sorted(normalized))
-
-
-def _validated_request(request: GraphViewRequestV1) -> _ValidatedRequest:
- view_id = _string(request.view_id, field="view_id")
- title = _string(request.title, field="title")
- if (request.root_node_id is None) == (request.query is None):
- raise _invalid("Choose exactly one exact root or lexical query")
- root_node_id = (
- None
- if request.root_node_id is None
- else _string(request.root_node_id, field="root_node_id")
- )
- query = (
- None
- if request.query is None
- else _string(
- request.query,
- field="query",
- maximum=MAX_GRAPH_VIEW_QUERY_CHARS,
- )
- )
- if request.initial_mode not in {"nodes", "flow", "web", "logic"}:
- raise _invalid("Graph view initial mode is unsupported")
- if type(request.depth) is not int or not 1 <= request.depth <= MAX_GRAPH_VIEW_DEPTH:
- raise _invalid(
- "Graph view depth is outside the fixed boundary",
- maximum=MAX_GRAPH_VIEW_DEPTH,
- )
- for field, value, minimum, maximum in (
- ("max_nodes", request.max_nodes, 1, MAX_GRAPH_VIEW_NODES),
- ("max_edges", request.max_edges, 0, MAX_GRAPH_VIEW_EDGES),
- ("max_work", request.max_work, 1, MAX_GRAPH_VIEW_WORK),
- ):
- if type(value) is not int or not minimum <= value <= maximum:
- raise _invalid(
- "Graph view bound is outside the fixed boundary",
- field=field,
- minimum=minimum,
- maximum=maximum,
- )
- if type(request.include_logic) is not bool:
- raise _invalid("Graph view Logic selection must be Boolean")
- return _ValidatedRequest(
- view_id=view_id,
- title=title,
- root_node_id=root_node_id,
- query=query,
- initial_mode=request.initial_mode,
- depth=request.depth,
- max_nodes=request.max_nodes,
- max_edges=request.max_edges,
- max_work=request.max_work,
- families=_filter_values(request.families, field="families"),
- relations=_filter_values(request.relations, field="relations"),
- authorities=_filter_values(request.authorities, field="authorities"),
- statuses=_filter_values(request.statuses, field="statuses"),
- tags=_filter_values(request.tags, field="tags"),
- include_logic=request.include_logic,
- )
-
-
-def _validated_graph(
- snapshot: ProjectSnapshot,
-) -> tuple[tuple[Node, ...], tuple[Edge, ...], dict[str, Node]]:
- nodes = tuple(sorted(snapshot.nodes, key=lambda node: node.node_id))
- node_by_id = {node.node_id: node for node in nodes}
- if len(node_by_id) != len(nodes):
- raise DocForgeError(
- "invalid_projection",
- "Graph view snapshot contains duplicate node identities",
- )
- edges = tuple(
- sorted(
- snapshot.edges,
- key=lambda edge: (edge.source_id, edge.relation, edge.target_id),
- )
- )
- edge_keys = {(edge.source_id, edge.relation, edge.target_id) for edge in edges}
- if len(edge_keys) != len(edges) or any(
- edge.source_id not in node_by_id or edge.target_id not in node_by_id for edge in edges
- ):
- raise DocForgeError(
- "invalid_projection",
- "Graph view snapshot contains invalid relationships",
- )
- return nodes, edges, node_by_id
-
-
-def _eligible(node: Node, request: _ValidatedRequest) -> bool:
- return (
- (not request.families or node.family in request.families)
- and (not request.authorities or node.authority in request.authorities)
- and (not request.statuses or node.status in request.statuses)
- and (not request.tags or set(request.tags).issubset(node.tags))
- )
-
-
-def _relation_allowed(edge: Edge, request: _ValidatedRequest) -> bool:
- return not request.relations or edge.relation in request.relations
-
-
-def _lexical_text(node: Node) -> str:
- return " ".join(
- (
- node.node_id,
- node.title,
- node.summary,
- node.family,
- node.authority,
- node.status,
- *node.tags,
- )
- ).casefold()
-
-
-def _lexical_nodes(
- nodes: tuple[Node, ...],
- request: _ValidatedRequest,
- omissions: list[dict[str, object]],
-) -> tuple[set[str], int, bool]:
- query = request.query
- maximum_nodes = request.max_nodes
- maximum_work = request.max_work
- assert query is not None
- terms = tuple(dict.fromkeys(_QUERY_TOKEN.findall(query.casefold())))
- if not terms:
- raise _invalid("Lexical graph scope contains no searchable text")
- selected: set[str] = set()
- work = 0
- work_limited = False
- for node in nodes:
- if work >= maximum_work:
- work_limited = True
- break
- work += 1
- if not _eligible(node, request) or not all(term in _lexical_text(node) for term in terms):
- continue
- if len(selected) >= maximum_nodes:
- omissions.append(
- {
- "code": "node_result_limit",
- "subject": "nodes",
- "limit": maximum_nodes,
- "minimum_omitted": 1,
- }
- )
- break
- selected.add(node.node_id)
- return selected, work, work_limited
-
-
-def _root_nodes(
- edges: tuple[Edge, ...],
- node_by_id: dict[str, Node],
- request: _ValidatedRequest,
- omissions: list[dict[str, object]],
-) -> tuple[set[str], int, bool]:
- root_node_id = request.root_node_id
- maximum_nodes = request.max_nodes
- maximum_work = request.max_work
- depth = request.depth
- assert root_node_id is not None
- root = node_by_id.get(root_node_id)
- if root is None:
- raise DocForgeError(
- "missing_node",
- "No node has the requested stable ID",
- node_id=root_node_id,
- )
- if not _eligible(root, request):
- raise _invalid("Exact graph root is excluded by the closed node filters")
-
- selected = {root_node_id}
- frontier = {root_node_id}
- work = 0
- work_limited = False
- node_limited = False
- for _ in range(depth):
- if not frontier:
- break
- next_frontier: set[str] = set()
- for edge in edges:
- if work >= maximum_work:
- work_limited = True
- break
- work += 1
- if not _relation_allowed(edge, request):
- continue
- candidate: str | None = None
- if edge.source_id in frontier:
- candidate = edge.target_id
- elif edge.target_id in frontier:
- candidate = edge.source_id
- if candidate is None or candidate in selected:
- continue
- node = node_by_id[candidate]
- if not _eligible(node, request):
- continue
- if len(selected) >= maximum_nodes:
- node_limited = True
- continue
- selected.add(candidate)
- next_frontier.add(candidate)
- if work_limited:
- break
- frontier = next_frontier
- if node_limited:
- omissions.append(
- {
- "code": "node_result_limit",
- "subject": "nodes",
- "limit": maximum_nodes,
- "minimum_omitted": 1,
- }
- )
- return selected, work, work_limited
-
-
-def _selected_edges(
- edges: tuple[Edge, ...],
- selected_ids: set[str],
- request: _ValidatedRequest,
- *,
- initial_work: int,
- omissions: list[dict[str, object]],
-) -> tuple[list[Edge], int, bool]:
- maximum_edges = request.max_edges
- maximum_work = request.max_work
- selected: list[Edge] = []
- work = initial_work
- work_limited = False
- edge_limited = False
- for edge in edges:
- if work >= maximum_work:
- work_limited = True
- break
- work += 1
- if (
- edge.source_id not in selected_ids
- or edge.target_id not in selected_ids
- or not _relation_allowed(edge, request)
- ):
- continue
- if len(selected) >= maximum_edges:
- edge_limited = True
- break
- selected.append(edge)
- if edge_limited:
- omissions.append(
- {
- "code": "edge_result_limit",
- "subject": "edges",
- "limit": maximum_edges,
- "minimum_omitted": 1,
- }
- )
- return selected, work, work_limited
-
-
-def _node_payload(node: Node) -> dict[str, object]:
- return {
- "node_id": node.node_id,
- "title": node.title,
- "family": node.family,
- "authority": node.authority,
- "status": node.status,
- "tags": sorted(node.tags),
- "summary": node.summary,
- "content_hash": node.content_hash,
- }
-
-
-def _edge_payload(edge: Edge) -> dict[str, str]:
- return {
- "source_id": edge.source_id,
- "relation": edge.relation,
- "target_id": edge.target_id,
- }
-
-
-def build_graph_view_plan(
- snapshot: ProjectSnapshot,
- request: GraphViewRequestV1,
- allow_logic: bool,
-) -> GraphViewPlanV1:
- """Build one deterministic, path-free graph plan without rendering or storage access."""
-
- if type(allow_logic) is not bool:
- raise _invalid("Graph view Logic policy must be Boolean")
- normalized = _validated_request(request)
- nodes, edges, node_by_id = _validated_graph(snapshot)
- omissions: list[dict[str, object]] = []
- if normalized.root_node_id is not None:
- selected_ids, work, work_limited = _root_nodes(
- edges,
- node_by_id,
- normalized,
- omissions,
- )
- scope: dict[str, object] = {
- "kind": "exact_root",
- "root_node_id": normalized.root_node_id,
- "depth": normalized.depth,
- }
- else:
- selected_ids, work, work_limited = _lexical_nodes(
- nodes,
- normalized,
- omissions,
- )
- scope = {
- "kind": "lexical",
- "query": normalized.query,
- }
- selected_edges, work, edge_work_limited = _selected_edges(
- edges,
- selected_ids,
- normalized,
- initial_work=work,
- omissions=omissions,
- )
- work_limited = work_limited or edge_work_limited
- if work_limited:
- omissions.append(
- {
- "code": "work_limit",
- "subject": "selection",
- "limit": normalized.max_work,
- "examined": work,
- "minimum_omitted": 1,
- }
- )
- logic_requested = normalized.include_logic
- if logic_requested and not allow_logic:
- omissions.append(
- {
- "code": "logic_forbidden",
- "subject": "logic",
- "minimum_omitted": 1,
- }
- )
- omissions.sort(key=lambda item: (str(item["code"]), str(item["subject"])))
- selected_nodes = [node_by_id[node_id] for node_id in sorted(selected_ids)]
- filters: dict[str, list[str]] = {
- "families": list(normalized.families),
- "relations": list(normalized.relations),
- "authorities": list(normalized.authorities),
- "statuses": list(normalized.statuses),
- "tags": list(normalized.tags),
- }
- return GraphViewPlanV1.create(
- {
- "project": {
- "project_id": snapshot.descriptor.project_id,
- "project_root_fingerprint": project_root_fingerprint(snapshot.descriptor.root),
- "adapter": snapshot.descriptor.adapter,
- "revision": snapshot.revision,
- "source_hash": snapshot.source_hash,
- },
- "view": {
- "view_id": normalized.view_id,
- "title": normalized.title,
- "initial_mode": normalized.initial_mode,
- "scope": scope,
- "filters": filters,
- "detail_fields": list(_DETAIL_FIELDS),
- },
- "bounds": {
- "depth": normalized.depth,
- "max_nodes": normalized.max_nodes,
- "max_edges": normalized.max_edges,
- "max_work": normalized.max_work,
- },
- "policy": {
- "visibility": "selected_graph_only",
- "source_paths": "excluded",
- "source_bodies": "excluded",
- "database_queries": "forbidden",
- "executable_content": "forbidden",
- "logic": "allowed" if allow_logic else "forbidden",
- "logic_requested": logic_requested,
- },
- "graph": {
- "root_node_id": normalized.root_node_id,
- "nodes": [_node_payload(node) for node in selected_nodes],
- "edges": [_edge_payload(edge) for edge in selected_edges],
- "logic_projections": [],
- },
- "omissions": omissions,
- "diagnostics": {
- "selection": scope["kind"],
- "returned_nodes": len(selected_nodes),
- "returned_edges": len(selected_edges),
- "examined_work_units": work,
- "truncated": bool(omissions),
- "ordering": "node_id;source_id,relation,target_id",
- },
- }
- )
-
-
-def build_graph_projection_package(
- plan: GraphViewPlanV1,
- *,
- renderer_id: str,
- renderer_version: str,
- max_output_bytes: int,
-) -> ProjectionPackageV1:
- """Bind a graph plan to the fixed portable renderer without adding runtime authority."""
-
- return ProjectionPackageV1.create(
- kind="graph",
- plan=plan,
- renderer={"renderer_id": renderer_id, "renderer_version": renderer_version},
- components=[
- {"component_id": "graph.portable-document@1"},
- {"component_id": "graph.accessible-list@1"},
- {"component_id": "graph.relationship-table@1"},
- ],
- assets=[],
- output_policy={
- "artifact_ids": ["portable-graph.html"],
- "max_total_bytes": max_output_bytes,
- },
- )
diff --git a/src/docforge/graph_render_config.py b/src/docforge/graph_render_config.py
deleted file mode 100644
index dfd3ade..0000000
--- a/src/docforge/graph_render_config.py
+++ /dev/null
@@ -1,285 +0,0 @@
-"""Strict parsing and confinement for optional portable graph artifacts."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Literal, cast
-
-from .config_validation import (
- ID_PATTERN,
- confined_path,
- positive_int,
- require_string,
- string_list,
-)
-from .errors import DocForgeError
-from .models import GraphRenderConfig, GraphRenderView, Limits, RenderConfig
-from .projection_contract import (
- MAX_GRAPH_VIEW_DEPTH,
- MAX_GRAPH_VIEW_EDGES,
- MAX_GRAPH_VIEW_FILTERS,
- MAX_GRAPH_VIEW_NODES,
- MAX_GRAPH_VIEW_QUERY_CHARS,
- MAX_GRAPH_VIEW_STRING_CHARS,
- MAX_GRAPH_VIEW_WORK,
-)
-
-_CONFIG_KEYS = frozenset({"output_root", "views"})
-_VIEW_KEYS = frozenset(
- {
- "id",
- "renderer",
- "output",
- "title",
- "root",
- "query",
- "initial_mode",
- "depth",
- "max_nodes",
- "max_edges",
- "max_work",
- "families",
- "relations",
- "authorities",
- "statuses",
- "tags",
- "include_logic",
- }
-)
-_MODES = frozenset({"nodes", "flow", "web"})
-
-
-def _overlaps(first: Path, second: Path) -> bool:
- return first == second or first.is_relative_to(second) or second.is_relative_to(first)
-
-
-def _optional_string(document: dict[str, object], key: str, source: Path) -> str | None:
- if key not in document:
- return None
- return require_string(document, key, source)
-
-
-def _bounded_string(
- document: dict[str, object],
- key: str,
- source: Path,
- *,
- maximum: int,
-) -> str:
- value = require_string(document, key, source)
- if len(value) > maximum:
- raise DocForgeError("invalid_config", f"{key} exceeds its fixed character limit")
- return value
-
-
-def _bounded_strings(
- value: object,
- *,
- key: str,
- source: Path,
-) -> tuple[str, ...]:
- values = string_list(value, key=key, source=source)
- if len(values) > MAX_GRAPH_VIEW_FILTERS or any(
- len(item) > MAX_GRAPH_VIEW_STRING_CHARS for item in values
- ):
- raise DocForgeError("invalid_config", f"{key} exceeds its fixed bounds")
- return values
-
-
-def load_graph_render_config(
- root: Path,
- document: object,
- *,
- descriptor_path: Path,
- content_roots: tuple[Path, ...],
- authority_files: tuple[Path, ...],
- cache_root: Path,
- index_path: Path,
- changeset_root: Path,
- manual_render: RenderConfig | None,
- limits: Limits,
-) -> GraphRenderConfig | None:
- if document is None:
- return None
- if not isinstance(document, dict):
- raise DocForgeError("invalid_config", "graph_render must be a table")
- document = cast(dict[str, object], document)
- unknown = sorted(set(document) - _CONFIG_KEYS)
- if unknown:
- raise DocForgeError("invalid_config", "graph_render has unknown fields", fields=unknown)
- output_root = confined_path(
- root,
- document.get("output_root"),
- field="graph_render.output_root",
- must_exist=False,
- )
- protected = [*content_roots, cache_root, changeset_root]
- if manual_render is not None:
- protected.extend((manual_render.template_root, manual_render.preview_root))
- protected.extend(view.output_path for view in manual_render.views)
- if any(_overlaps(output_root, path) for path in protected):
- raise DocForgeError(
- "invalid_config",
- "Portable graph output must not overlap canonical or other derived roots",
- )
- protected_files = (descriptor_path, index_path, *authority_files)
- if any(path == output_root or path.is_relative_to(output_root) for path in protected_files):
- raise DocForgeError(
- "invalid_config",
- "Portable graph output overlaps a protected project path",
- )
- view_values_value = document.get("views")
- if not isinstance(view_values_value, list) or not view_values_value:
- raise DocForgeError(
- "invalid_config",
- "graph_render.views must contain at least one view",
- )
- view_values = cast(list[object], view_values_value)
- if len(view_values) > limits.max_render_views:
- raise DocForgeError("invalid_config", "graph_render.views exceeds the configured limit")
- views: list[GraphRenderView] = []
- view_ids: set[str] = set()
- outputs: set[Path] = set()
- for value in view_values:
- if not isinstance(value, dict):
- raise DocForgeError("invalid_config", "Each portable graph view must be a table")
- view = cast(dict[str, object], value)
- unknown_view = sorted(set(view) - _VIEW_KEYS)
- if unknown_view:
- raise DocForgeError(
- "invalid_config",
- "Portable graph view has unknown fields",
- fields=unknown_view,
- )
- view_id = require_string(view, "id", descriptor_path)
- if ID_PATTERN.fullmatch(view_id) is None or view_id in view_ids:
- raise DocForgeError(
- "invalid_config",
- "Portable graph view ID is invalid or duplicated",
- id=view_id,
- )
- view_ids.add(view_id)
- renderer = require_string(view, "renderer", descriptor_path)
- if renderer != "portable_graph_html":
- raise DocForgeError(
- "unsupported_renderer",
- "Portable graph view names an unsupported built-in renderer",
- renderer=renderer,
- )
- output = confined_path(
- output_root,
- view.get("output"),
- field="graph_render.view.output",
- must_exist=False,
- )
- if output.suffix != ".html" or output in outputs:
- raise DocForgeError(
- "invalid_config",
- "Portable graph outputs must be unique HTML files",
- )
- outputs.add(output)
- root_node_id = _optional_string(view, "root", descriptor_path)
- query = _optional_string(view, "query", descriptor_path)
- if (root_node_id is None) == (query is None):
- raise DocForgeError(
- "invalid_config",
- "Portable graph view requires exactly one root or query",
- )
- if root_node_id is not None and len(root_node_id) > MAX_GRAPH_VIEW_STRING_CHARS:
- raise DocForgeError("invalid_config", "Portable graph root exceeds its fixed limit")
- if query is not None and len(query) > MAX_GRAPH_VIEW_QUERY_CHARS:
- raise DocForgeError("invalid_config", "Portable graph query exceeds its fixed limit")
- initial_mode_value = view.get("initial_mode", "nodes")
- if not isinstance(initial_mode_value, str):
- raise DocForgeError(
- "invalid_config",
- "Portable graph initial mode is unsupported",
- )
- initial_mode = cast(
- Literal["nodes", "flow", "web", "logic"],
- initial_mode_value,
- )
- if initial_mode not in _MODES:
- raise DocForgeError(
- "invalid_config",
- "Portable graph initial mode is unsupported",
- )
- depth = positive_int(view.get("depth", 1), "graph_render.view.depth")
- max_nodes = positive_int(view.get("max_nodes", 100), "graph_render.view.max_nodes")
- max_edges = positive_int(
- view.get("max_edges", 400),
- "graph_render.view.max_edges",
- allow_zero=True,
- )
- max_work = positive_int(view.get("max_work", 100_000), "graph_render.view.max_work")
- if (
- depth > min(limits.max_traversal_depth, MAX_GRAPH_VIEW_DEPTH)
- or max_nodes > min(limits.max_nodes, MAX_GRAPH_VIEW_NODES)
- or max_edges > MAX_GRAPH_VIEW_EDGES
- or max_work > MAX_GRAPH_VIEW_WORK
- ):
- raise DocForgeError(
- "invalid_config",
- "Portable graph view exceeds project or fixed safety limits",
- )
- include_logic = view.get("include_logic", False)
- if type(include_logic) is not bool:
- raise DocForgeError(
- "invalid_config",
- "Portable graph include_logic must be Boolean",
- )
- if include_logic:
- raise DocForgeError(
- "unsupported_renderer",
- "Portable graph renderer version 1 does not support Logic projections",
- )
- views.append(
- GraphRenderView(
- view_id=view_id,
- renderer=renderer,
- output_path=output,
- title=_bounded_string(
- view,
- "title",
- descriptor_path,
- maximum=MAX_GRAPH_VIEW_STRING_CHARS,
- ),
- root_node_id=root_node_id,
- query=query,
- initial_mode=initial_mode,
- depth=depth,
- max_nodes=max_nodes,
- max_edges=max_edges,
- max_work=max_work,
- families=_bounded_strings(
- view.get("families", []),
- key="graph_render.view.families",
- source=descriptor_path,
- ),
- relations=_bounded_strings(
- view.get("relations", []),
- key="graph_render.view.relations",
- source=descriptor_path,
- ),
- authorities=_bounded_strings(
- view.get("authorities", []),
- key="graph_render.view.authorities",
- source=descriptor_path,
- ),
- statuses=_bounded_strings(
- view.get("statuses", []),
- key="graph_render.view.statuses",
- source=descriptor_path,
- ),
- tags=_bounded_strings(
- view.get("tags", []),
- key="graph_render.view.tags",
- source=descriptor_path,
- ),
- include_logic=include_logic,
- )
- )
- return GraphRenderConfig(
- output_root=output_root,
- views=tuple(sorted(views, key=lambda item: item.view_id)),
- )
diff --git a/src/docforge/graph_rendering.py b/src/docforge/graph_rendering.py
deleted file mode 100644
index ee5c1a7..0000000
--- a/src/docforge/graph_rendering.py
+++ /dev/null
@@ -1,815 +0,0 @@
-"""Declared portable graph planning, publication, and receipt-only status."""
-
-from __future__ import annotations
-
-import fcntl
-import json
-import os
-from collections.abc import Callable, Generator
-from contextlib import contextmanager
-from pathlib import Path
-from typing import cast
-
-from ._fs_safety import (
- atomic_replace_bytes_at,
- open_confined_directory,
- read_bounded_file_at,
- require_bound_directory,
- safe_file_identity_at,
-)
-from .errors import DocForgeError
-from .graph_projection import (
- GraphViewRequestV1,
- build_graph_projection_package,
- build_graph_view_plan,
-)
-from .models import (
- GenerationRecordingProject,
- GraphRenderConfig,
- GraphRenderView,
- IncrementalStateProject,
- ProjectService,
- ProjectSnapshot,
- ProjectState,
-)
-from .project import project_root_fingerprint
-from .projection_contract import GraphViewPlanV1, ProjectionReceiptV1, projection_hash
-from .projection_policy import (
- PortableGraphProjectionMode,
- validate_portable_graph_projection_mode,
-)
-from .projection_worker import render_projection_in_worker
-
-GRAPH_RENDERER_ID = "portable_graph_html"
-GRAPH_RENDERER_VERSION = "1"
-GRAPH_PUBLICATION_MANIFEST_VERSION = 1
-GRAPH_PUBLICATION_CONTRACT = "docforge.graph-publication"
-MAX_GRAPH_PUBLICATION_BYTES = 256_000
-
-
-class GraphRenderService:
- """Publish one declared artifact while keeping planning and rendering independent."""
-
- def __init__(
- self,
- project: ProjectService,
- *,
- allow_logic: bool = False,
- portable_graph_policy: PortableGraphProjectionMode = "explicit",
- ) -> None:
- self.project = project
- self.allow_logic = allow_logic
- self.portable_graph_policy = validate_portable_graph_projection_mode(portable_graph_policy)
-
- def _require_rendering(self, operation: str) -> None:
- if self.portable_graph_policy == "disabled":
- raise DocForgeError(
- "projection_policy_forbids_operation",
- "Portable graph projection policy disables rendering work",
- projection="portable_graph",
- mode=self.portable_graph_policy,
- operation=operation,
- )
-
- def plan(self, view_id: str) -> dict[str, object]:
- self._require_rendering("plan")
- snapshot = self.project.load()
- view = self._view(self._config(snapshot), view_id)
- plan = self._plan(snapshot, view)
- return {
- "status": "ok",
- **self._identity(snapshot),
- "view_id": view.view_id,
- "plan": plan.as_dict(),
- }
-
- def status(self, view_id: str | None = None) -> dict[str, object]:
- config = self.project.descriptor.graph_render
- current = self._current_state()
- if config is None:
- return self._status_result(
- current,
- configured=False,
- state="not_configured",
- outputs=[],
- )
- views = config.views if view_id is None else (self._view(config, view_id),)
- first_outputs = [self._manifest_status(view, current) for view in views]
- outputs = [self._manifest_status(view, current) for view in views]
- if outputs != first_outputs:
- for output in outputs:
- if output["state"] == "current":
- output["state"] = "stale"
- output["reason"] = "publication_changed_during_status"
- final = self._current_state()
- if final != current:
- for output in outputs:
- if output["state"] == "current":
- output["state"] = "stale"
- output["reason"] = "source_changed_during_status"
- identity = final if final is not None else current
- return self._status_result(
- identity,
- configured=True,
- state="current" if all(item["state"] == "current" for item in outputs) else "stale",
- outputs=outputs,
- )
-
- def render(self, view_id: str) -> dict[str, object]:
- self._require_rendering("render")
- with self._lock():
- current_status = self.status(view_id)
- current_outputs = cast(list[dict[str, object]], current_status["outputs"])
- if current_status["state"] == "current" and current_outputs:
- return {
- **current_status,
- "publication": "unchanged",
- "output": current_outputs[0],
- }
- snapshot = self.project.load()
- view = self._view(self._config(snapshot), view_id)
- plan = self._plan(snapshot, view)
- package = build_graph_projection_package(
- plan,
- renderer_id=GRAPH_RENDERER_ID,
- renderer_version=GRAPH_RENDERER_VERSION,
- max_output_bytes=snapshot.descriptor.limits.max_render_bytes,
- )
- result = render_projection_in_worker(package)
- if len(result.artifacts) != 1:
- raise DocForgeError(
- "invalid_projection",
- "Portable graph renderer returned an unsupported artifact set",
- )
- artifact = result.artifacts[0]
-
- def verify() -> None:
- current = self.project.load()
- if (
- current.revision != snapshot.revision
- or current.source_hash != snapshot.source_hash
- ):
- raise DocForgeError(
- "render_input_changed",
- "Canonical input changed during portable graph rendering",
- )
-
- verify()
- if isinstance(self.project, GenerationRecordingProject):
- self.project.record_generation(snapshot)
- artifact_evidence = artifact.evidence()
- try:
- store_identity = self._publish_artifact(
- snapshot,
- artifact_evidence["sha256"],
- artifact.content,
- verify=verify,
- )
- except DocForgeError as error:
- if self._mutation_committed(error):
- return self._degraded_publication(
- snapshot,
- view,
- plan,
- package.package_id,
- result.receipt.as_dict(),
- artifact_evidence,
- stage="artifact_store",
- error=error,
- output_published=False,
- )
- raise
- try:
- output_identity = self._publish_output(
- snapshot,
- view,
- artifact.content,
- verify=verify,
- )
- except DocForgeError as error:
- if self._mutation_committed(error):
- return self._degraded_publication(
- snapshot,
- view,
- plan,
- package.package_id,
- result.receipt.as_dict(),
- artifact_evidence,
- stage="output",
- error=error,
- output_published=True,
- )
- raise
- manifest = self._manifest(
- snapshot,
- view,
- plan,
- package.package_id,
- result.receipt.as_dict(),
- artifact_evidence,
- store_identity,
- output_identity,
- )
- try:
- self._publish_manifest(snapshot, view, manifest, verify=verify)
- except DocForgeError as error:
- return self._degraded_publication(
- snapshot,
- view,
- plan,
- package.package_id,
- result.receipt.as_dict(),
- artifact_evidence,
- stage="manifest",
- error=error,
- output_published=True,
- )
- return {
- "status": "ok",
- **self._identity(snapshot),
- "view_id": view.view_id,
- "state": "current",
- "publication": "published",
- "plan_id": plan.plan_id,
- "package_id": package.package_id,
- "output": {
- **artifact.evidence(),
- "path": view.output_path.relative_to(snapshot.descriptor.root).as_posix(),
- },
- "receipt": result.receipt.as_dict(),
- "manifest": {
- "state": "current",
- "publication_id": manifest["publication_id"],
- },
- }
-
- @staticmethod
- def _mutation_committed(error: DocForgeError) -> bool:
- return error.details.get("mutation_committed") is True
-
- def _degraded_publication(
- self,
- snapshot: ProjectSnapshot,
- view: GraphRenderView,
- plan: GraphViewPlanV1,
- package_id: str,
- receipt: dict[str, object],
- artifact: dict[str, object],
- *,
- stage: str,
- error: DocForgeError,
- output_published: bool,
- ) -> dict[str, object]:
- return {
- "status": "ok",
- **self._identity(snapshot),
- "view_id": view.view_id,
- "state": "degraded",
- "publication": "published" if output_published else "partial",
- "committed_stage": stage,
- "plan_id": plan.plan_id,
- "package_id": package_id,
- "artifact": artifact,
- "output": {
- **artifact,
- "path": view.output_path.relative_to(snapshot.descriptor.root).as_posix(),
- "state": "unverified" if output_published else "not_published",
- },
- "receipt": receipt,
- "manifest": {
- "state": "failed",
- "error": error.as_dict(),
- },
- }
-
- def _manifest_status(
- self,
- view: GraphRenderView,
- current: ProjectState | None,
- ) -> dict[str, object]:
- manifest = self._read_manifest(view)
- base = {
- "view_id": view.view_id,
- "renderer": GRAPH_RENDERER_ID,
- "renderer_version": GRAPH_RENDERER_VERSION,
- "path": view.output_path.relative_to(self.project.descriptor.root).as_posix(),
- "verification": "manifest",
- }
- if manifest is None:
- return {**base, "state": "missing", "reason": "manifest_missing"}
- if not self._valid_manifest(view, manifest):
- return {**base, "state": "unverified", "reason": "manifest_invalid"}
- if current is None:
- reason = (
- "source_generation_changed"
- if isinstance(self.project, GenerationRecordingProject)
- else "source_generation_unavailable"
- )
- return {
- **base,
- "state": (
- "stale"
- if isinstance(self.project, GenerationRecordingProject)
- else "unverified"
- ),
- "reason": reason,
- "plan_id": manifest.get("plan_id"),
- "package_id": manifest.get("package_id"),
- }
- project = cast(dict[str, object], manifest["project"])
- if project["revision"] != current.revision or project["source_hash"] != current.source_hash:
- return {
- **base,
- "state": "stale",
- "reason": "source_generation_changed",
- "plan_id": manifest["plan_id"],
- "package_id": manifest["package_id"],
- }
- artifact = cast(dict[str, object], manifest["artifact"])
- store = cast(dict[str, object], manifest["store"])
- artifact_root = self.project.descriptor.cache_root / "projection-artifacts"
- if not artifact_root.exists():
- return {
- **base,
- "state": "stale",
- "reason": "artifact_store_missing",
- "plan_id": manifest["plan_id"],
- "package_id": manifest["package_id"],
- }
- if artifact_root.is_symlink() or not artifact_root.is_dir():
- return {
- **base,
- "state": "unsafe",
- "reason": "artifact_store_unsafe",
- "plan_id": manifest["plan_id"],
- "package_id": manifest["package_id"],
- }
- artifact_directory: int | None = None
- try:
- artifact_directory = open_confined_directory(
- self.project.descriptor.root,
- artifact_root,
- create=False,
- )
- artifact_identity = safe_file_identity_at(
- artifact_root,
- artifact_directory,
- f"{artifact['sha256']}.html",
- )
- except DocForgeError:
- return {
- **base,
- "state": "unsafe",
- "reason": "artifact_store_unsafe",
- "plan_id": manifest["plan_id"],
- "package_id": manifest["package_id"],
- }
- finally:
- if artifact_directory is not None:
- os.close(artifact_directory)
- if artifact_identity is None:
- return {
- **base,
- "state": "stale",
- "reason": "artifact_store_missing",
- "plan_id": manifest["plan_id"],
- "package_id": manifest["package_id"],
- }
- if artifact_identity != store:
- return {
- **base,
- "state": "stale",
- "reason": "artifact_store_changed",
- "plan_id": manifest["plan_id"],
- "package_id": manifest["package_id"],
- }
- try:
- directory = open_confined_directory(
- self.project.descriptor.root,
- view.output_path.parent,
- create=False,
- )
- except DocForgeError:
- return {**base, "state": "unsafe", "reason": "output_root_unsafe"}
- try:
- identity = safe_file_identity_at(
- view.output_path.parent, directory, view.output_path.name
- )
- except DocForgeError:
- return {**base, "state": "unsafe", "reason": "output_unsafe"}
- finally:
- os.close(directory)
- expected = cast(dict[str, object], manifest["output"])
- if identity != expected:
- return {
- **base,
- "state": "stale",
- "reason": "output_changed",
- "plan_id": manifest["plan_id"],
- "package_id": manifest["package_id"],
- }
- return {
- **base,
- "state": "current",
- "reason": None,
- "plan_id": manifest["plan_id"],
- "package_id": manifest["package_id"],
- "publication_id": manifest["publication_id"],
- "artifact": manifest["artifact"],
- }
-
- def _read_manifest(self, view: GraphRenderView) -> dict[str, object] | None:
- root = self._manifest_root()
- if not root.is_dir() or root.is_symlink():
- return None
- try:
- descriptor = open_confined_directory(
- self.project.descriptor.root,
- root,
- create=False,
- )
- except DocForgeError:
- return None
- try:
- raw = read_bounded_file_at(
- descriptor,
- f"{view.view_id}.json",
- MAX_GRAPH_PUBLICATION_BYTES,
- )
- except DocForgeError:
- return None
- finally:
- os.close(descriptor)
- if raw is None:
- return None
- try:
- value: object = json.loads(raw)
- except (UnicodeDecodeError, json.JSONDecodeError):
- return None
- return cast(dict[str, object], value) if isinstance(value, dict) else None
-
- def _valid_manifest(self, view: GraphRenderView, manifest: dict[str, object]) -> bool:
- required = {
- "schema_version",
- "contract",
- "publication_id",
- "project",
- "view_id",
- "view_config_hash",
- "plan_id",
- "package_id",
- "renderer",
- "receipt",
- "artifact",
- "store",
- "output",
- }
- try:
- if (
- set(manifest) != required
- or manifest.get("schema_version") != GRAPH_PUBLICATION_MANIFEST_VERSION
- or manifest.get("contract") != GRAPH_PUBLICATION_CONTRACT
- or manifest.get("view_id") != view.view_id
- or manifest.get("view_config_hash") != self._view_hash(view)
- or not self._hash(manifest.get("plan_id"))
- or not self._hash(manifest.get("package_id"))
- ):
- return False
- project = manifest.get("project")
- descriptor = self.project.descriptor
- if not isinstance(project, dict):
- return False
- project_document = cast(dict[str, object], project)
- if (
- set(project_document)
- != {
- "project_id",
- "project_root_fingerprint",
- "adapter",
- "revision",
- "source_hash",
- }
- or project_document.get("project_id") != descriptor.project_id
- or project_document.get("project_root_fingerprint")
- != project_root_fingerprint(descriptor.root)
- or project_document.get("adapter") != descriptor.adapter
- or not isinstance(project_document.get("revision"), str)
- or not project_document["revision"]
- or not self._hash(project_document.get("source_hash"))
- ):
- return False
- renderer = manifest.get("renderer")
- if renderer != {
- "renderer_id": GRAPH_RENDERER_ID,
- "renderer_version": GRAPH_RENDERER_VERSION,
- }:
- return False
- receipt_value = manifest.get("receipt")
- if not isinstance(receipt_value, dict):
- return False
- receipt = ProjectionReceiptV1.from_dict(
- dict(cast(dict[str, object], receipt_value))
- ).as_dict()
- artifacts = receipt.get("artifacts")
- if not isinstance(artifacts, list):
- return False
- artifact_values = cast(list[object], artifacts)
- if (
- receipt.get("kind") != "graph"
- or receipt.get("plan_id") != manifest["plan_id"]
- or receipt.get("package_id") != manifest["package_id"]
- or receipt.get("renderer") != renderer
- or len(artifact_values) != 1
- or manifest.get("artifact") != artifact_values[0]
- ):
- return False
- artifact = artifact_values[0]
- if not isinstance(artifact, dict):
- return False
- artifact_document = cast(dict[str, object], artifact)
- if (
- artifact_document.get("artifact_id") != "portable-graph.html"
- or artifact_document.get("media_type") != "text/html; charset=utf-8"
- ):
- return False
- artifact_hash = artifact_document.get("sha256")
- artifact_bytes = artifact_document.get("bytes")
- store = manifest.get("store")
- output = manifest.get("output")
- if (
- not self._file_identity(store, expected_name=f"{artifact_hash}.html")
- or not self._file_identity(output, expected_name=view.output_path.name)
- or type(artifact_bytes) is not int
- or cast(dict[str, object], store)["size"] != artifact_bytes
- or cast(dict[str, object], output)["size"] != artifact_bytes
- ):
- return False
- body = dict(manifest)
- publication_id = body.pop("publication_id", None)
- return self._hash(publication_id) and publication_id == projection_hash(body)
- except (DocForgeError, KeyError, TypeError, ValueError):
- return False
-
- @staticmethod
- def _hash(value: object) -> bool:
- return (
- isinstance(value, str)
- and len(value) == 64
- and all(character in "0123456789abcdef" for character in value)
- )
-
- @staticmethod
- def _file_identity(value: object, *, expected_name: str) -> bool:
- if not isinstance(value, dict):
- return False
- document = cast(dict[str, object], value)
- required = {"path", "device", "inode", "mode", "size", "mtime_ns", "ctime_ns"}
- return (
- set(document) == required
- and document.get("path") == expected_name
- and all(
- type(document.get(field)) is int and cast(int, document[field]) >= 0
- for field in required - {"path"}
- )
- )
-
- def _manifest(
- self,
- snapshot: ProjectSnapshot,
- view: GraphRenderView,
- plan: GraphViewPlanV1,
- package_id: str,
- receipt: dict[str, object],
- artifact: dict[str, object],
- store: dict[str, object],
- output: dict[str, object],
- ) -> dict[str, object]:
- body: dict[str, object] = {
- "schema_version": GRAPH_PUBLICATION_MANIFEST_VERSION,
- "contract": GRAPH_PUBLICATION_CONTRACT,
- "project": self._identity(snapshot),
- "view_id": view.view_id,
- "view_config_hash": self._view_hash(view),
- "plan_id": plan.plan_id,
- "package_id": package_id,
- "renderer": {
- "renderer_id": GRAPH_RENDERER_ID,
- "renderer_version": GRAPH_RENDERER_VERSION,
- },
- "receipt": receipt,
- "artifact": artifact,
- "store": store,
- "output": output,
- }
- return {**body, "publication_id": projection_hash(body)}
-
- def _publish_artifact(
- self,
- snapshot: ProjectSnapshot,
- artifact_hash: object,
- content: bytes,
- *,
- verify: Callable[[], None],
- ) -> dict[str, object]:
- if not isinstance(artifact_hash, str):
- raise DocForgeError("invalid_projection", "Artifact hash is invalid")
- root = snapshot.descriptor.cache_root / "projection-artifacts"
- descriptor = open_confined_directory(snapshot.descriptor.root, root, create=True)
- name = f"{artifact_hash}.html"
- try:
- try:
- existing = read_bounded_file_at(descriptor, name, len(content))
- except DocForgeError as error:
- if error.code != "invalid_projection":
- raise
- existing = None
- if existing == content:
- identity = safe_file_identity_at(root, descriptor, name)
- assert identity is not None
- return identity
- return atomic_replace_bytes_at(root, descriptor, name, content, verify=verify)
- finally:
- os.close(descriptor)
-
- def _publish_output(
- self,
- snapshot: ProjectSnapshot,
- view: GraphRenderView,
- content: bytes,
- *,
- verify: Callable[[], None],
- ) -> dict[str, object]:
- root = view.output_path.parent
- descriptor = open_confined_directory(snapshot.descriptor.root, root, create=True)
- try:
- try:
- existing = read_bounded_file_at(
- descriptor,
- view.output_path.name,
- len(content),
- )
- except DocForgeError as error:
- if error.code != "invalid_projection":
- raise
- existing = None
- if existing == content:
- identity = safe_file_identity_at(root, descriptor, view.output_path.name)
- assert identity is not None
- return identity
- return atomic_replace_bytes_at(
- root,
- descriptor,
- view.output_path.name,
- content,
- verify=verify,
- )
- finally:
- os.close(descriptor)
-
- def _publish_manifest(
- self,
- snapshot: ProjectSnapshot,
- view: GraphRenderView,
- manifest: dict[str, object],
- *,
- verify: Callable[[], None],
- ) -> None:
- raw = json.dumps(manifest, sort_keys=True, indent=2).encode() + b"\n"
- if len(raw) > MAX_GRAPH_PUBLICATION_BYTES:
- raise DocForgeError(
- "projection_too_large",
- "Portable graph publication manifest exceeds its fixed limit",
- )
- root = self._manifest_root()
- descriptor = open_confined_directory(snapshot.descriptor.root, root, create=True)
- try:
- atomic_replace_bytes_at(
- root,
- descriptor,
- f"{view.view_id}.json",
- raw,
- verify=verify,
- )
- finally:
- os.close(descriptor)
-
- @contextmanager
- def _lock(self) -> Generator[None]:
- root = self.project.descriptor.cache_root
- descriptor = open_confined_directory(self.project.descriptor.root, root, create=True)
- lock_descriptor: int | None = None
- try:
- lock_descriptor = os.open(
- "graph-render.lock",
- os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW,
- 0o600,
- dir_fd=descriptor,
- )
- fcntl.flock(lock_descriptor, fcntl.LOCK_EX)
- require_bound_directory(root, descriptor)
- yield
- except OSError as error:
- raise DocForgeError(
- "publication_failure",
- "Portable graph render lock is unavailable",
- ) from error
- finally:
- if lock_descriptor is not None:
- os.close(lock_descriptor)
- os.close(descriptor)
-
- def _plan(self, snapshot: ProjectSnapshot, view: GraphRenderView) -> GraphViewPlanV1:
- return build_graph_view_plan(
- snapshot,
- GraphViewRequestV1(
- view_id=view.view_id,
- title=view.title,
- root_node_id=view.root_node_id,
- query=view.query,
- initial_mode=view.initial_mode,
- depth=view.depth,
- max_nodes=view.max_nodes,
- max_edges=view.max_edges,
- max_work=view.max_work,
- families=view.families,
- relations=view.relations,
- authorities=view.authorities,
- statuses=view.statuses,
- tags=view.tags,
- include_logic=view.include_logic,
- ),
- self.allow_logic,
- )
-
- def _current_state(self) -> ProjectState | None:
- if isinstance(self.project, IncrementalStateProject):
- return self.project.incremental_state()
- return None
-
- def _config(self, snapshot: ProjectSnapshot) -> GraphRenderConfig:
- config = snapshot.descriptor.graph_render
- if config is None:
- raise DocForgeError(
- "graph_render_not_configured",
- "Project has no portable graph render configuration",
- )
- return config
-
- @staticmethod
- def _view(config: GraphRenderConfig, view_id: str) -> GraphRenderView:
- for view in config.views:
- if view.view_id == view_id:
- return view
- raise DocForgeError(
- "unknown_graph_render_view",
- "Portable graph view is not declared",
- view_id=view_id,
- )
-
- def _manifest_root(self) -> Path:
- return self.project.descriptor.cache_root / "projection-publications" / "graph"
-
- @staticmethod
- def _view_hash(view: GraphRenderView) -> str:
- return projection_hash(
- {
- "view_id": view.view_id,
- "renderer": view.renderer,
- "title": view.title,
- "root_node_id": view.root_node_id,
- "query": view.query,
- "initial_mode": view.initial_mode,
- "depth": view.depth,
- "max_nodes": view.max_nodes,
- "max_edges": view.max_edges,
- "max_work": view.max_work,
- "families": list(view.families),
- "relations": list(view.relations),
- "authorities": list(view.authorities),
- "statuses": list(view.statuses),
- "tags": list(view.tags),
- "include_logic": view.include_logic,
- }
- )
-
- def _status_result(self, current: ProjectState | None, **payload: object) -> dict[str, object]:
- descriptor = self.project.descriptor
- return {
- "status": "ok",
- "project_id": descriptor.project_id,
- "project_root_fingerprint": project_root_fingerprint(descriptor.root),
- "adapter": descriptor.adapter,
- "revision": current.revision if current is not None else "unknown",
- "source_hash": current.source_hash if current is not None else None,
- **payload,
- }
-
- @staticmethod
- def _identity(snapshot: ProjectSnapshot) -> dict[str, object]:
- return {
- "project_id": snapshot.descriptor.project_id,
- "project_root_fingerprint": project_root_fingerprint(snapshot.descriptor.root),
- "adapter": snapshot.descriptor.adapter,
- "revision": snapshot.revision,
- "source_hash": snapshot.source_hash,
- }
diff --git a/src/docforge/manual_projection.py b/src/docforge/manual_projection.py
deleted file mode 100644
index a249d38..0000000
--- a/src/docforge/manual_projection.py
+++ /dev/null
@@ -1,208 +0,0 @@
-"""Pure manual planning over one immutable validated graph generation."""
-
-from __future__ import annotations
-
-import hashlib
-from collections import defaultdict
-from collections.abc import Sequence
-
-from .errors import DocForgeError
-from .models import Edge, ProjectSnapshot, RenderView
-from .project import project_root_fingerprint
-from .projection_contract import ManualRenderPlanV1, ProjectionPackageV1
-
-
-def _edge_dict(edge: Edge) -> dict[str, str]:
- return {
- "source_id": edge.source_id,
- "relation": edge.relation,
- "target_id": edge.target_id,
- }
-
-
-def _cycles(node_ids: tuple[str, ...], edges: tuple[Edge, ...]) -> list[list[str]]:
- """Return deterministic strongly connected components that represent cycles."""
-
- adjacency: dict[str, list[str]] = {node_id: [] for node_id in node_ids}
- reverse_adjacency: dict[str, list[str]] = {node_id: [] for node_id in node_ids}
- for edge in edges:
- adjacency[edge.source_id].append(edge.target_id)
- reverse_adjacency[edge.target_id].append(edge.source_id)
- for targets in (*adjacency.values(), *reverse_adjacency.values()):
- targets.sort()
-
- visited: set[str] = set()
- finished: list[str] = []
- for node_id in node_ids:
- if node_id in visited:
- continue
- visited.add(node_id)
- traversal: list[tuple[str, int]] = [(node_id, 0)]
- while traversal:
- current, position = traversal[-1]
- targets = adjacency[current]
- if position < len(targets):
- target = targets[position]
- traversal[-1] = (current, position + 1)
- if target not in visited:
- visited.add(target)
- traversal.append((target, 0))
- continue
- finished.append(current)
- traversal.pop()
-
- assigned: set[str] = set()
- components: list[list[str]] = []
- for node_id in reversed(finished):
- if node_id in assigned:
- continue
- assigned.add(node_id)
- component: list[str] = []
- component_stack = [node_id]
- while component_stack:
- current = component_stack.pop()
- component.append(current)
- for target in reversed(reverse_adjacency[current]):
- if target not in assigned:
- assigned.add(target)
- component_stack.append(target)
- component.sort()
- if len(component) > 1 or component[0] in adjacency[component[0]]:
- components.append(component)
- return sorted(components)
-
-
-def build_manual_render_plan(
- snapshot: ProjectSnapshot,
- view: RenderView,
- *,
- changeset_hash: str | None,
-) -> ManualRenderPlanV1:
- """Select and describe a complete manual without rendering markup."""
-
- selected = tuple(
- node for node in snapshot.nodes if not view.families or node.family in view.families
- )
- selected_ids = {node.node_id for node in selected}
- edges = tuple(
- edge
- for edge in snapshot.edges
- if edge.source_id in selected_ids and edge.target_id in selected_ids
- )
- outgoing: dict[str, list[Edge]] = defaultdict(list)
- incoming: dict[str, list[Edge]] = defaultdict(list)
- for edge in edges:
- outgoing[edge.source_id].append(edge)
- incoming[edge.target_id].append(edge)
- for values in (*outgoing.values(), *incoming.values()):
- values.sort(key=lambda edge: (edge.source_id, edge.relation, edge.target_id))
-
- pages = [
- {
- "node_id": node.node_id,
- "title": node.title,
- "family": node.family,
- "authority": node.authority,
- "status": node.status,
- "tags": list(node.tags),
- "summary": node.summary,
- "content": node.content,
- "content_hash": node.content_hash,
- "components": [
- "manual.node-metadata@1",
- "manual.summary@1",
- "manual.commonmark@1",
- "manual.relationships@1",
- ],
- "breadcrumbs": [],
- "cross_references": [_edge_dict(edge) for edge in outgoing[node.node_id]],
- "backlinks": [_edge_dict(edge) for edge in incoming[node.node_id]],
- }
- for node in selected
- ]
- node_ids = tuple(node.node_id for node in selected)
- connected = {endpoint for edge in edges for endpoint in (edge.source_id, edge.target_id)}
- return ManualRenderPlanV1.create(
- {
- "project": {
- "project_id": snapshot.descriptor.project_id,
- "project_root_fingerprint": project_root_fingerprint(snapshot.descriptor.root),
- "adapter": snapshot.descriptor.adapter,
- "revision": snapshot.revision,
- "source_hash": snapshot.source_hash,
- },
- "view": {
- "view_id": view.view_id,
- "title": view.title,
- "families": list(view.families),
- "renderer": view.renderer,
- },
- "changeset_hash": changeset_hash,
- "pages": pages,
- "navigation": [{"node_id": node.node_id, "title": node.title} for node in selected],
- "search_documents": [
- {
- "node_id": node.node_id,
- "title": node.title,
- "summary": node.summary,
- "family": node.family,
- "status": node.status,
- "tags": list(node.tags),
- }
- for node in selected
- ],
- "diagnostics": {
- "orphans": [node_id for node_id in node_ids if node_id not in connected],
- "cycles": _cycles(node_ids, edges),
- },
- }
- )
-
-
-def build_manual_projection_package(
- plan: ManualRenderPlanV1,
- template_bytes: bytes,
- *,
- renderer_id: str,
- renderer_version: str,
- max_output_bytes: int,
- render_identity: str | None = None,
- fragment_records: Sequence[dict[str, object]] = (),
-) -> ProjectionPackageV1:
- """Bind one plan and inert template asset for a path-free manual renderer."""
-
- try:
- template = template_bytes.decode("utf-8")
- except UnicodeDecodeError as error:
- raise DocForgeError("invalid_template", "Render template is not valid UTF-8") from error
- template_asset: dict[str, object] = {
- "asset_id": "manual.template",
- "media_type": "text/html; charset=utf-8",
- "sha256": hashlib.sha256(template_bytes).hexdigest(),
- "text": template,
- }
- if render_identity is not None:
- template_asset["render_identity"] = render_identity
- assets = [template_asset]
- if fragment_records:
- assets.append(
- {
- "asset_id": "manual.fragments",
- "media_type": "application/vnd.docforge.projection-fragments.v1+json",
- "records": list(fragment_records),
- }
- )
- return ProjectionPackageV1.create(
- kind="manual",
- plan=plan,
- renderer={"renderer_id": renderer_id, "renderer_version": renderer_version},
- components=[
- {"component_id": "manual.document@1"},
- {"component_id": "manual.commonmark@1"},
- ],
- assets=assets,
- output_policy={
- "artifact_ids": ["manual.html"],
- "max_total_bytes": max_output_bytes,
- },
- )
diff --git a/src/docforge/mcp_server.py b/src/docforge/mcp_server.py
index 21e6544..d90e7b2 100644
--- a/src/docforge/mcp_server.py
+++ b/src/docforge/mcp_server.py
@@ -15,13 +15,11 @@ from .application import CanonicalApplicationService, CanonicalApplier, GenericC
from .changesets import ChangesetStore
from .context import compile_context
from .errors import DocForgeError
-from .graph_rendering import GraphRenderService
from .index import ProjectIndex
from .models import IncrementalStateProject, ProjectService, RuntimeValidatedProject
from .pagination import canonical_hash, decode_cursor, page_limit, page_receipt
from .policy import CapabilityMode, capability_mode, compose_effective_policy
from .project import Project, project_root_fingerprint
-from .projection_policy import compose_projection_policy
from .rendering import RenderService
from .retrieval import MAX_TASK_EVIDENCE, TaskKind, build_retrieval_plan
from .telemetry import request, stage
@@ -49,8 +47,6 @@ READ_TOOLS = (
"docforge_get_task_context",
"docforge_validate_project",
"docforge_render_status",
- "docforge_graph_plan",
- "docforge_graph_render_status",
"docforge_visualize",
"docforge_stop_visualization",
"docforge_visualization_status",
@@ -138,9 +134,6 @@ class DocForgeService:
no_ast: bool = False,
diagnostics: bool = False,
capability_mode_name: str | None = None,
- manual_projection_policy: str | None = None,
- portable_graph_policy: str | None = None,
- live_viewer_policy: str | None = None,
) -> None:
self.project = project
default_mode: CapabilityMode = (
@@ -160,40 +153,19 @@ class DocForgeService:
render_configured=project.descriptor.render is not None,
application_enabled=application_enabled,
)
- self.projection_policy = compose_projection_policy(
- manual=manual_projection_policy,
- portable_graph=portable_graph_policy,
- live_viewer=live_viewer_policy,
- manual_configured=project.descriptor.render is not None,
- portable_graph_configured=project.descriptor.graph_render is not None,
- application_enabled=application_enabled,
- )
self.index = ProjectIndex(self.project, allow_logic=not self.policy.no_ast)
self.changesets = ChangesetStore(
self.project,
proposal_writer if selected_mode != "read" else None,
)
- self.rendering = RenderService(
- self.project,
- self.changesets,
- manual_policy=self.projection_policy.manual,
- )
- self.graph_rendering = GraphRenderService(
- self.project,
- allow_logic=not self.policy.no_ast,
- portable_graph_policy=self.projection_policy.portable_graph,
- )
+ self.rendering = RenderService(self.project, self.changesets)
self.application = CanonicalApplicationService(
self.project,
applier_id=canonical_applier_id if application_enabled else None,
applier=canonical_applier if application_enabled else None,
index=self.index,
- manual_policy=self.projection_policy.manual,
- )
- self.visualization = ViewerManagerClient(
- self.index,
- live_viewer_policy=self.projection_policy.live_viewer,
)
+ self.visualization = ViewerManagerClient(self.index)
self.context_provider = context_provider
self.task_context_available = context_provider is compile_context
self.binding_metadata = dict(binding_metadata or {})
@@ -649,7 +621,6 @@ class DocForgeService:
}
capabilities = self.capabilities()
effective_policy = self.policy.as_dict()
- projection_policy = self.projection_policy.as_dict()
session_contract: dict[str, object] = {
"schema_version": 1,
"binding": binding,
@@ -659,8 +630,6 @@ class DocForgeService:
"freshness": "current",
},
"effective_policy": effective_policy,
- "projection_policy": projection_policy,
- "projection_policy_hash": self.projection_policy.policy_hash,
"capabilities": capabilities,
"render_policies": {
"manual": effective_policy["manual_render"],
@@ -683,8 +652,6 @@ class DocForgeService:
"canonical_paths": [str(path) for path in descriptor.content_roots],
"adapter_policy": self.adapter_policy(),
"effective_policy": effective_policy,
- "projection_policy": projection_policy,
- "projection_policy_hash": self.projection_policy.policy_hash,
"capabilities": capabilities,
"session_contract": session_contract,
"proposal_access": proposal_access,
@@ -747,8 +714,6 @@ class DocForgeService:
),
"adapter_policy": self.adapter_policy(),
"effective_policy": self.policy.as_dict(),
- "projection_policy": self.projection_policy.as_dict(),
- "projection_policy_hash": self.projection_policy.policy_hash,
"capabilities": self.capabilities(),
"canonical_paths": [
*(relative(path) for path in snapshot.descriptor.content_roots),
@@ -864,29 +829,6 @@ class DocForgeService:
operation_name="mcp.render_status",
)
- def graph_plan(self, view_id: str) -> dict[str, object]:
- """Plan one declared portable graph without publishing derived output."""
-
- return self.invoke(
- lambda: self.graph_rendering.plan(view_id),
- synchronize=False,
- load_error_identity=False,
- operation_name="mcp.graph_plan",
- )
-
- def graph_render_status(
- self,
- view_id: str | None = None,
- ) -> dict[str, object]:
- """Report portable-graph publication state without planning or rendering."""
-
- return self.invoke(
- lambda: self.graph_rendering.status(view_id),
- synchronize=False,
- load_error_identity=False,
- operation_name="mcp.graph_render_status",
- )
-
def context(
self,
profile: str,
@@ -1633,18 +1575,6 @@ def _create_bound_server(service: DocForgeService, *, read_only: bool) -> FastMC
return service.render_status(view_id, deep=deep)
- @server.tool(name="docforge_graph_plan")
- def graph_plan(view_id: str) -> dict[str, Any]:
- """Plan one declared portable graph without publishing derived output."""
-
- return service.graph_plan(view_id)
-
- @server.tool(name="docforge_graph_render_status")
- def graph_render_status(view_id: str | None = None) -> dict[str, Any]:
- """Report portable-graph publication state without rendering."""
-
- return service.graph_render_status(view_id)
-
@server.tool(name="docforge_visualize")
def visualize(
node_id: str | None = None,
@@ -1692,8 +1622,6 @@ def _create_bound_server(service: DocForgeService, *, read_only: bool) -> FastMC
get_task_context,
validate_project,
render_status,
- graph_plan,
- graph_render_status,
visualize,
stop_visualization,
visualization_status,
@@ -2076,9 +2004,6 @@ def create_server(
no_ast: bool = False,
diagnostics: bool = False,
capability_mode: str | None = None,
- manual_projection_policy: str | None = None,
- portable_graph_policy: str | None = None,
- live_viewer_policy: str | None = None,
) -> FastMCP:
project = Project.open(project_root)
return create_project_server(
@@ -2095,9 +2020,6 @@ def create_server(
no_ast=no_ast,
diagnostics=diagnostics,
capability_mode=capability_mode,
- manual_projection_policy=manual_projection_policy,
- portable_graph_policy=portable_graph_policy,
- live_viewer_policy=live_viewer_policy,
)
@@ -2112,9 +2034,6 @@ def create_project_server(
no_ast: bool = False,
diagnostics: bool = False,
capability_mode: str | None = None,
- manual_projection_policy: str | None = None,
- portable_graph_policy: str | None = None,
- live_viewer_policy: str | None = None,
) -> FastMCP:
"""Create the full fixed MCP surface for one explicitly configured project service."""
@@ -2128,9 +2047,6 @@ def create_project_server(
no_ast=no_ast,
diagnostics=diagnostics,
capability_mode_name=capability_mode,
- manual_projection_policy=manual_projection_policy,
- portable_graph_policy=portable_graph_policy,
- live_viewer_policy=live_viewer_policy,
)
return _create_bound_server(
service,
@@ -2146,9 +2062,6 @@ def create_read_only_server(
no_ast: bool = False,
diagnostics: bool = False,
capability_mode: str | None = None,
- manual_projection_policy: str | None = None,
- portable_graph_policy: str | None = None,
- live_viewer_policy: str | None = None,
) -> FastMCP:
"""Create an adapter-capable MCP server exposing only the fixed read tool surface."""
@@ -2160,9 +2073,6 @@ def create_read_only_server(
no_ast=no_ast,
diagnostics=diagnostics,
capability_mode_name="read" if capability_mode is None else capability_mode,
- manual_projection_policy=manual_projection_policy,
- portable_graph_policy=portable_graph_policy,
- live_viewer_policy=live_viewer_policy,
)
if service.policy.capability_mode != "read":
raise DocForgeError(
@@ -2196,18 +2106,6 @@ def main() -> None:
choices=("read", "proposal", "application", "operator"),
help="Expose the versioned project-bound capability surface",
)
- parser.add_argument(
- "--manual-render-policy",
- choices=("auto", "explicit", "disabled"),
- )
- parser.add_argument(
- "--portable-graph-policy",
- choices=("explicit", "disabled"),
- )
- parser.add_argument(
- "--live-viewer-policy",
- choices=("on-demand", "disabled"),
- )
arguments = parser.parse_args()
create_server(
arguments.project_root,
@@ -2216,9 +2114,6 @@ def main() -> None:
no_ast=arguments.no_ast,
diagnostics=arguments.diagnostics,
capability_mode=arguments.capability_mode,
- manual_projection_policy=arguments.manual_render_policy,
- portable_graph_policy=arguments.portable_graph_policy,
- live_viewer_policy=arguments.live_viewer_policy,
).run(transport="stdio")
diff --git a/src/docforge/models.py b/src/docforge/models.py
index efcd71f..47d5339 100644
--- a/src/docforge/models.py
+++ b/src/docforge/models.py
@@ -5,7 +5,7 @@ from __future__ import annotations
from collections.abc import Mapping
from dataclasses import asdict, dataclass
from pathlib import Path
-from typing import Literal, Protocol, runtime_checkable
+from typing import Protocol, runtime_checkable
@dataclass(frozen=True)
@@ -49,33 +49,6 @@ class RenderConfig:
views: tuple[RenderView, ...]
-@dataclass(frozen=True)
-class GraphRenderView:
- view_id: str
- renderer: str
- output_path: Path
- title: str
- root_node_id: str | None
- query: str | None
- initial_mode: Literal["nodes", "flow", "web", "logic"]
- depth: int
- max_nodes: int
- max_edges: int
- max_work: int
- families: tuple[str, ...]
- relations: tuple[str, ...]
- authorities: tuple[str, ...]
- statuses: tuple[str, ...]
- tags: tuple[str, ...]
- include_logic: bool
-
-
-@dataclass(frozen=True)
-class GraphRenderConfig:
- output_root: Path
- views: tuple[GraphRenderView, ...]
-
-
@dataclass(frozen=True)
class ContextProfile:
profile_id: str
@@ -105,7 +78,6 @@ class ProjectDescriptor:
allowed_relations: tuple[str, ...]
profiles: tuple[ContextProfile, ...]
limits: Limits
- graph_render: GraphRenderConfig | None = None
@dataclass(frozen=True)
diff --git a/src/docforge/project.py b/src/docforge/project.py
index 17052b3..3d689bd 100644
--- a/src/docforge/project.py
+++ b/src/docforge/project.py
@@ -25,7 +25,6 @@ from .config_validation import (
string_list,
)
from .errors import DocForgeError
-from .graph_render_config import load_graph_render_config
from .models import (
ContextProfile,
Edge,
@@ -67,7 +66,6 @@ _DESCRIPTOR_KEYS = frozenset(
"derived",
"changesets",
"render",
- "graph_render",
"graph",
"limits",
"profiles",
@@ -550,6 +548,7 @@ def _load_descriptor(root: Path) -> ProjectDescriptor:
for field in defaults.__dataclass_fields__
}
)
+
render = load_render_config(
root,
document.get("render"),
@@ -561,18 +560,6 @@ def _load_descriptor(root: Path) -> ProjectDescriptor:
changeset_root=changeset_root,
limits=limits,
)
- graph_render = load_graph_render_config(
- root,
- document.get("graph_render"),
- descriptor_path=descriptor_path,
- content_roots=content_roots,
- authority_files=authority_files,
- cache_root=cache_root,
- index_path=index_path,
- changeset_root=changeset_root,
- manual_render=render,
- limits=limits,
- )
profile_documents = document.get("profiles", [])
if not isinstance(profile_documents, list):
@@ -636,7 +623,6 @@ def _load_descriptor(root: Path) -> ProjectDescriptor:
changeset_root=changeset_root,
proposal_writers=tuple(sorted(proposal_writers, key=lambda writer: writer.writer_id)),
render=render,
- graph_render=graph_render,
allowed_relations=allowed_relations,
profiles=tuple(profiles),
limits=limits,
diff --git a/src/docforge/projection_contract.py b/src/docforge/projection_contract.py
deleted file mode 100644
index 937d84d..0000000
--- a/src/docforge/projection_contract.py
+++ /dev/null
@@ -1,536 +0,0 @@
-"""Versioned, canonical contracts shared by independent projection renderers."""
-
-from __future__ import annotations
-
-import hashlib
-import json
-from dataclasses import dataclass
-from typing import Literal, cast
-
-from .errors import DocForgeError
-
-MANUAL_RENDER_PLAN_CONTRACT = "docforge.manual-render-plan"
-GRAPH_VIEW_PLAN_CONTRACT = "docforge.graph-view-plan"
-PROJECTION_PACKAGE_CONTRACT = "docforge.projection-package"
-PROJECTION_RECEIPT_CONTRACT = "docforge.projection-receipt"
-
-PROJECTION_SCHEMA_VERSION = 1
-MAX_PLAN_BYTES = 16_000_000
-MAX_PACKAGE_BYTES = 24_000_000
-MAX_RECEIPT_BYTES = 128_000
-MAX_PROJECTION_ARTIFACTS = 32
-MAX_GRAPH_VIEW_DEPTH = 32
-MAX_GRAPH_VIEW_NODES = 1_000
-MAX_GRAPH_VIEW_EDGES = 4_000
-MAX_GRAPH_VIEW_WORK = 1_000_000
-MAX_GRAPH_VIEW_FILTERS = 64
-MAX_GRAPH_VIEW_STRING_CHARS = 1_024
-MAX_GRAPH_VIEW_QUERY_CHARS = 10_000
-
-ProjectionKind = Literal["manual", "graph"]
-
-
-def canonical_projection_bytes(value: object) -> bytes:
- """Return the one canonical UTF-8 representation used for projection identities."""
-
- return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
- "utf-8"
- )
-
-
-def projection_hash(value: object) -> str:
- return hashlib.sha256(canonical_projection_bytes(value)).hexdigest()
-
-
-def _is_hash(value: object) -> bool:
- return (
- isinstance(value, str)
- and len(value) == 64
- and all(character in "0123456789abcdef" for character in value)
- )
-
-
-def _bounded(document: dict[str, object], maximum: int, *, kind: str) -> None:
- size = len(canonical_projection_bytes(document))
- if size > maximum:
- raise DocForgeError(
- "projection_too_large",
- f"{kind} exceeds its fixed serialized-size limit",
- maximum_bytes=maximum,
- actual_bytes=size,
- )
-
-
-def _validated_identity(
- document: dict[str, object],
- *,
- identity_field: str,
- maximum: int,
- kind: str,
-) -> dict[str, object]:
- _bounded(document, maximum, kind=kind)
- identity = document.get(identity_field)
- if not _is_hash(identity):
- raise DocForgeError("invalid_projection", f"{kind} identity is invalid")
- body = dict(document)
- body.pop(identity_field)
- if projection_hash(body) != identity:
- raise DocForgeError("invalid_projection", f"{kind} identity does not match its content")
- return document
-
-
-def _reject_runtime_authority(value: object) -> None:
- """Reject structural capabilities while treating selected content as inert data."""
-
- forbidden_keys = {
- "command",
- "database",
- "database_path",
- "index_path",
- "project_root",
- "project_path",
- "sql",
- }
- if isinstance(value, dict):
- payload = cast(dict[object, object], value)
- for key, item in payload.items():
- if isinstance(key, str) and key in forbidden_keys:
- raise DocForgeError(
- "invalid_projection",
- "Projection package contains forbidden runtime authority",
- field=key,
- )
- if (
- isinstance(key, str)
- and (key == "path" or key.endswith("_path"))
- and isinstance(item, str)
- and item.startswith("/")
- ):
- raise DocForgeError(
- "invalid_projection",
- "Projection package contains an absolute runtime path",
- field=key,
- )
- _reject_runtime_authority(item)
- elif isinstance(value, list):
- for item in cast(list[object], value):
- _reject_runtime_authority(item)
-
-
-@dataclass(frozen=True)
-class ManualRenderPlanV1:
- """One immutable, bounded manual plan prepared from a validated graph generation."""
-
- document: dict[str, object]
-
- @property
- def plan_id(self) -> str:
- return cast(str, self.document["plan_id"])
-
- def as_dict(self) -> dict[str, object]:
- return dict(self.document)
-
- @classmethod
- def create(cls, payload: dict[str, object]) -> ManualRenderPlanV1:
- body = {
- "schema_version": PROJECTION_SCHEMA_VERSION,
- "contract": MANUAL_RENDER_PLAN_CONTRACT,
- **payload,
- }
- document = {**body, "plan_id": projection_hash(body)}
- return cls(validate_manual_render_plan(document))
-
- @classmethod
- def from_dict(cls, document: dict[str, object]) -> ManualRenderPlanV1:
- return cls(validate_manual_render_plan(dict(document)))
-
-
-@dataclass(frozen=True)
-class GraphViewPlanV1:
- """One immutable, bounded portable-graph plan."""
-
- document: dict[str, object]
-
- @property
- def plan_id(self) -> str:
- return cast(str, self.document["plan_id"])
-
- def as_dict(self) -> dict[str, object]:
- return dict(self.document)
-
- @classmethod
- def create(cls, payload: dict[str, object]) -> GraphViewPlanV1:
- body = {
- "schema_version": PROJECTION_SCHEMA_VERSION,
- "contract": GRAPH_VIEW_PLAN_CONTRACT,
- **payload,
- }
- document = {**body, "plan_id": projection_hash(body)}
- return cls(validate_graph_view_plan(document))
-
- @classmethod
- def from_dict(cls, document: dict[str, object]) -> GraphViewPlanV1:
- return cls(validate_graph_view_plan(dict(document)))
-
-
-@dataclass(frozen=True)
-class ProjectionPackageV1:
- """Path-free package supplied to one capability-isolated renderer."""
-
- document: dict[str, object]
-
- @property
- def package_id(self) -> str:
- return cast(str, self.document["package_id"])
-
- @property
- def kind(self) -> ProjectionKind:
- return cast(ProjectionKind, self.document["kind"])
-
- def as_dict(self) -> dict[str, object]:
- return dict(self.document)
-
- @classmethod
- def create(
- cls,
- *,
- kind: ProjectionKind,
- plan: ManualRenderPlanV1 | GraphViewPlanV1,
- renderer: dict[str, object],
- components: list[dict[str, object]],
- assets: list[dict[str, object]],
- output_policy: dict[str, object],
- ) -> ProjectionPackageV1:
- body: dict[str, object] = {
- "schema_version": PROJECTION_SCHEMA_VERSION,
- "contract": PROJECTION_PACKAGE_CONTRACT,
- "kind": kind,
- "plan_id": plan.plan_id,
- "plan": plan.as_dict(),
- "renderer": renderer,
- "components": components,
- "assets": assets,
- "output_policy": output_policy,
- }
- document = {**body, "package_id": projection_hash(body)}
- return cls(validate_projection_package(document))
-
- @classmethod
- def from_dict(cls, document: dict[str, object]) -> ProjectionPackageV1:
- return cls(validate_projection_package(dict(document)))
-
-
-@dataclass(frozen=True)
-class ProjectionReceiptV1:
- """Renderer evidence that contains identities and sizes, never artifact bytes."""
-
- document: dict[str, object]
-
- @property
- def receipt_id(self) -> str:
- return cast(str, self.document["receipt_id"])
-
- def as_dict(self) -> dict[str, object]:
- return dict(self.document)
-
- @classmethod
- def create(
- cls,
- *,
- kind: ProjectionKind,
- package_id: str,
- plan_id: str,
- renderer: dict[str, object],
- artifacts: list[dict[str, object]],
- diagnostics: dict[str, object],
- timing: dict[str, object],
- peak_memory_bytes: int | None,
- ) -> ProjectionReceiptV1:
- body: dict[str, object] = {
- "schema_version": PROJECTION_SCHEMA_VERSION,
- "contract": PROJECTION_RECEIPT_CONTRACT,
- "kind": kind,
- "package_id": package_id,
- "plan_id": plan_id,
- "renderer": renderer,
- "artifacts": artifacts,
- "diagnostics": diagnostics,
- "timing": timing,
- "peak_memory_bytes": peak_memory_bytes,
- }
- document = {**body, "receipt_id": projection_hash(body)}
- return cls(validate_projection_receipt(document))
-
- @classmethod
- def from_dict(cls, document: dict[str, object]) -> ProjectionReceiptV1:
- return cls(validate_projection_receipt(dict(document)))
-
-
-@dataclass(frozen=True)
-class ProjectionArtifact:
- """One renderer-produced artifact addressed by a logical identifier."""
-
- artifact_id: str
- media_type: str
- content: bytes
-
- def evidence(self) -> dict[str, object]:
- return {
- "artifact_id": self.artifact_id,
- "media_type": self.media_type,
- "sha256": hashlib.sha256(self.content).hexdigest(),
- "bytes": len(self.content),
- }
-
-
-@dataclass(frozen=True)
-class ProjectionRenderResult:
- """Artifact bytes plus the bounded renderer receipt that attests them."""
-
- artifacts: tuple[ProjectionArtifact, ...]
- receipt: ProjectionReceiptV1
-
-
-def _validate_project_identity(value: object) -> None:
- if not isinstance(value, dict):
- raise DocForgeError("invalid_projection", "Projection project identity is invalid")
- project = cast(dict[str, object], value)
- if set(project) != {
- "project_id",
- "project_root_fingerprint",
- "adapter",
- "revision",
- "source_hash",
- }:
- raise DocForgeError("invalid_projection", "Projection project identity is invalid")
- if not all(
- isinstance(project.get(key), str) and bool(project[key])
- for key in ("project_id", "project_root_fingerprint", "adapter", "revision")
- ) or not _is_hash(project.get("source_hash")):
- raise DocForgeError("invalid_projection", "Projection project identity is invalid")
-
-
-def validate_manual_render_plan(document: dict[str, object]) -> dict[str, object]:
- required = {
- "schema_version",
- "contract",
- "plan_id",
- "project",
- "view",
- "changeset_hash",
- "pages",
- "navigation",
- "search_documents",
- "diagnostics",
- }
- if set(document) != required:
- raise DocForgeError("invalid_projection", "Manual render plan fields are invalid")
- if (
- document.get("schema_version") != PROJECTION_SCHEMA_VERSION
- or document.get("contract") != MANUAL_RENDER_PLAN_CONTRACT
- ):
- raise DocForgeError("invalid_projection", "Manual render plan version is unsupported")
- _validate_project_identity(document.get("project"))
- if not all(
- isinstance(document.get(key), expected)
- for key, expected in (
- ("view", dict),
- ("pages", list),
- ("navigation", list),
- ("search_documents", list),
- ("diagnostics", dict),
- )
- ):
- raise DocForgeError("invalid_projection", "Manual render plan structure is invalid")
- changeset_hash = document.get("changeset_hash")
- if changeset_hash is not None and not _is_hash(changeset_hash):
- raise DocForgeError("invalid_projection", "Manual render plan changeset hash is invalid")
- return _validated_identity(
- document,
- identity_field="plan_id",
- maximum=MAX_PLAN_BYTES,
- kind="Manual render plan",
- )
-
-
-def validate_graph_view_plan(document: dict[str, object]) -> dict[str, object]:
- required = {
- "schema_version",
- "contract",
- "plan_id",
- "project",
- "view",
- "bounds",
- "policy",
- "graph",
- "omissions",
- "diagnostics",
- }
- if set(document) != required:
- raise DocForgeError("invalid_projection", "Graph view plan fields are invalid")
- if (
- document.get("schema_version") != PROJECTION_SCHEMA_VERSION
- or document.get("contract") != GRAPH_VIEW_PLAN_CONTRACT
- ):
- raise DocForgeError("invalid_projection", "Graph view plan version is unsupported")
- _validate_project_identity(document.get("project"))
- if not all(
- isinstance(document.get(key), expected)
- for key, expected in (
- ("view", dict),
- ("bounds", dict),
- ("policy", dict),
- ("graph", dict),
- ("omissions", list),
- ("diagnostics", dict),
- )
- ):
- raise DocForgeError("invalid_projection", "Graph view plan structure is invalid")
- return _validated_identity(
- document,
- identity_field="plan_id",
- maximum=MAX_PLAN_BYTES,
- kind="Graph view plan",
- )
-
-
-def validate_projection_package(document: dict[str, object]) -> dict[str, object]:
- required = {
- "schema_version",
- "contract",
- "package_id",
- "kind",
- "plan_id",
- "plan",
- "renderer",
- "components",
- "assets",
- "output_policy",
- }
- if set(document) != required:
- raise DocForgeError("invalid_projection", "Projection package fields are invalid")
- kind = document.get("kind")
- if (
- document.get("schema_version") != PROJECTION_SCHEMA_VERSION
- or document.get("contract") != PROJECTION_PACKAGE_CONTRACT
- or kind not in {"manual", "graph"}
- ):
- raise DocForgeError("invalid_projection", "Projection package version or kind is invalid")
- plan = document.get("plan")
- if not isinstance(plan, dict):
- raise DocForgeError("invalid_projection", "Projection package plan is invalid")
- validated_plan = (
- validate_manual_render_plan(cast(dict[str, object], plan))
- if kind == "manual"
- else validate_graph_view_plan(cast(dict[str, object], plan))
- )
- if document.get("plan_id") != validated_plan.get("plan_id"):
- raise DocForgeError("invalid_projection", "Projection package plan identity is invalid")
- if not all(
- isinstance(document.get(key), expected)
- for key, expected in (
- ("renderer", dict),
- ("components", list),
- ("assets", list),
- ("output_policy", dict),
- )
- ):
- raise DocForgeError("invalid_projection", "Projection package structure is invalid")
- if len(cast(list[object], document["assets"])) > MAX_PROJECTION_ARTIFACTS:
- raise DocForgeError("projection_too_large", "Projection package has too many assets")
- _reject_runtime_authority(document)
- return _validated_identity(
- document,
- identity_field="package_id",
- maximum=MAX_PACKAGE_BYTES,
- kind="Projection package",
- )
-
-
-def validate_projection_receipt(document: dict[str, object]) -> dict[str, object]:
- required = {
- "schema_version",
- "contract",
- "receipt_id",
- "kind",
- "package_id",
- "plan_id",
- "renderer",
- "artifacts",
- "diagnostics",
- "timing",
- "peak_memory_bytes",
- }
- if set(document) != required:
- raise DocForgeError("invalid_projection", "Projection receipt fields are invalid")
- if (
- document.get("schema_version") != PROJECTION_SCHEMA_VERSION
- or document.get("contract") != PROJECTION_RECEIPT_CONTRACT
- or document.get("kind") not in {"manual", "graph"}
- or not _is_hash(document.get("package_id"))
- or not _is_hash(document.get("plan_id"))
- ):
- raise DocForgeError("invalid_projection", "Projection receipt identity is invalid")
- artifacts_value = document.get("artifacts")
- if not isinstance(artifacts_value, list):
- raise DocForgeError("invalid_projection", "Projection receipt structure is invalid")
- artifacts = cast(list[object], artifacts_value)
- renderer = document.get("renderer")
- diagnostics = document.get("diagnostics")
- timing = document.get("timing")
- if (
- not isinstance(renderer, dict)
- or not isinstance(diagnostics, dict)
- or not isinstance(timing, dict)
- ):
- raise DocForgeError("invalid_projection", "Projection receipt structure is invalid")
- renderer_document = cast(dict[str, object], renderer)
- diagnostics_document = cast(dict[str, object], diagnostics)
- timing_document = cast(dict[str, object], timing)
- warnings = diagnostics_document.get("warnings")
- if (
- len(artifacts) > MAX_PROJECTION_ARTIFACTS
- or set(renderer_document) != {"renderer_id", "renderer_version"}
- or not all(
- isinstance(renderer_document.get(field), str) and renderer_document[field]
- for field in ("renderer_id", "renderer_version")
- )
- or set(diagnostics_document) != {"warnings"}
- or not isinstance(warnings, list)
- or len(cast(list[object], warnings)) > 10_000
- or not all(isinstance(item, str) for item in cast(list[object], warnings))
- or set(timing_document) != {"elapsed_ns"}
- or type(timing_document.get("elapsed_ns")) is not int
- or cast(int, timing_document["elapsed_ns"]) < 0
- ):
- raise DocForgeError("invalid_projection", "Projection receipt structure is invalid")
- peak = document.get("peak_memory_bytes")
- if peak is not None and (type(peak) is not int or peak < 0):
- raise DocForgeError("invalid_projection", "Projection receipt memory value is invalid")
- artifact_ids: set[str] = set()
- for artifact in artifacts:
- if not isinstance(artifact, dict):
- raise DocForgeError("invalid_projection", "Projection receipt artifact is invalid")
- item = cast(dict[str, object], artifact)
- if (
- set(item) != {"artifact_id", "media_type", "sha256", "bytes"}
- or not isinstance(item.get("artifact_id"), str)
- or not item["artifact_id"]
- or "/" in cast(str, item["artifact_id"])
- or not isinstance(item.get("media_type"), str)
- or not item["media_type"]
- or not _is_hash(item.get("sha256"))
- or type(item.get("bytes")) is not int
- or cast(int, item["bytes"]) < 0
- ):
- raise DocForgeError("invalid_projection", "Projection receipt artifact is invalid")
- artifact_id = cast(str, item["artifact_id"])
- if artifact_id in artifact_ids:
- raise DocForgeError("invalid_projection", "Projection receipt artifacts are duplicated")
- artifact_ids.add(artifact_id)
- return _validated_identity(
- document,
- identity_field="receipt_id",
- maximum=MAX_RECEIPT_BYTES,
- kind="Projection receipt",
- )
diff --git a/src/docforge/projection_fragments.py b/src/docforge/projection_fragments.py
deleted file mode 100644
index b2fe3d2..0000000
--- a/src/docforge/projection_fragments.py
+++ /dev/null
@@ -1,489 +0,0 @@
-"""Bounded, path-free, disposable projection fragment caching."""
-
-from __future__ import annotations
-
-import base64
-import hashlib
-import json
-import os
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Literal, cast
-
-from ._fs_safety import (
- atomic_replace_bytes_at,
- open_confined_directory,
- read_bounded_file_at,
- require_bound_directory,
-)
-from .errors import DocForgeError
-from .projection_contract import canonical_projection_bytes, projection_hash
-
-FRAGMENT_SCHEMA_VERSION = 1
-FRAGMENT_KEY_CONTRACT = "docforge.projection-fragment-key"
-FRAGMENT_RECORD_CONTRACT = "docforge.projection-fragment-record"
-FRAGMENT_CACHE_DIRECTORY = "projection-fragments-v1"
-MAX_FRAGMENT_CONTENT_BYTES = 4_000_000
-MAX_FRAGMENT_ID_CHARS = 256
-MAX_FRAGMENT_CACHE_ENTRIES = 10_000
-MAX_FRAGMENT_CACHE_BYTES = 64_000_000
-_MAX_RECORD_OVERHEAD_BYTES = 8_192
-
-ProjectionKind = Literal["manual", "graph"]
-
-
-def _is_hash(value: object) -> bool:
- return (
- isinstance(value, str)
- and len(value) == 64
- and all(character in "0123456789abcdef" for character in value)
- )
-
-
-def _version_string(value: object, *, field: str) -> str:
- if (
- not isinstance(value, str)
- or not value
- or value != value.strip()
- or len(value) > MAX_FRAGMENT_ID_CHARS
- or any(ord(character) < 32 for character in value)
- ):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment identity is invalid",
- field=field,
- )
- return value
-
-
-def fragment_semantic_hash(value: object) -> str:
- """Hash one complete semantic input using the projection canonical JSON form."""
-
- try:
- return hashlib.sha256(canonical_projection_bytes(value)).hexdigest()
- except (TypeError, ValueError) as error:
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment semantic input is not canonical JSON",
- ) from error
-
-
-@dataclass(frozen=True)
-class FragmentKey:
- """Versioned identity for one renderer component's complete semantics."""
-
- projection_kind: ProjectionKind
- renderer_id: str
- renderer_version: str
- component_version: str
- semantic_input_hash: str
- key_id: str
-
- @classmethod
- def create(
- cls,
- *,
- projection_kind: ProjectionKind,
- renderer_id: str,
- renderer_version: str,
- component_version: str,
- semantic_input_hash: str,
- ) -> FragmentKey:
- body = cls._body(
- projection_kind=projection_kind,
- renderer_id=renderer_id,
- renderer_version=renderer_version,
- component_version=component_version,
- semantic_input_hash=semantic_input_hash,
- )
- return cls._from_validated({**body, "key_id": projection_hash(body)})
-
- @classmethod
- def from_dict(cls, value: object) -> FragmentKey:
- if not isinstance(value, dict):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment key is invalid",
- )
- return cls._from_validated(dict(cast(dict[str, object], value)))
-
- @staticmethod
- def _body(
- *,
- projection_kind: object,
- renderer_id: object,
- renderer_version: object,
- component_version: object,
- semantic_input_hash: object,
- ) -> dict[str, object]:
- if projection_kind not in {"manual", "graph"}:
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment kind is invalid",
- )
- if not _is_hash(semantic_input_hash):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment semantic input hash is invalid",
- )
- return {
- "schema_version": FRAGMENT_SCHEMA_VERSION,
- "contract": FRAGMENT_KEY_CONTRACT,
- "projection_kind": projection_kind,
- "renderer_id": _version_string(renderer_id, field="renderer_id"),
- "renderer_version": _version_string(
- renderer_version,
- field="renderer_version",
- ),
- "component_version": _version_string(
- component_version,
- field="component_version",
- ),
- "semantic_input_hash": semantic_input_hash,
- }
-
- @classmethod
- def _from_validated(cls, value: dict[str, object]) -> FragmentKey:
- required = {
- "schema_version",
- "contract",
- "projection_kind",
- "renderer_id",
- "renderer_version",
- "component_version",
- "semantic_input_hash",
- "key_id",
- }
- if (
- set(value) != required
- or value.get("schema_version") != FRAGMENT_SCHEMA_VERSION
- or value.get("contract") != FRAGMENT_KEY_CONTRACT
- ):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment key contract is incompatible",
- )
- body = cls._body(
- projection_kind=value.get("projection_kind"),
- renderer_id=value.get("renderer_id"),
- renderer_version=value.get("renderer_version"),
- component_version=value.get("component_version"),
- semantic_input_hash=value.get("semantic_input_hash"),
- )
- key_id = value.get("key_id")
- if not _is_hash(key_id) or key_id != projection_hash(body):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment key does not match its semantics",
- )
- return cls(
- projection_kind=cast(ProjectionKind, body["projection_kind"]),
- renderer_id=cast(str, body["renderer_id"]),
- renderer_version=cast(str, body["renderer_version"]),
- component_version=cast(str, body["component_version"]),
- semantic_input_hash=cast(str, body["semantic_input_hash"]),
- key_id=cast(str, key_id),
- )
-
- def as_dict(self) -> dict[str, object]:
- return {
- "schema_version": FRAGMENT_SCHEMA_VERSION,
- "contract": FRAGMENT_KEY_CONTRACT,
- "projection_kind": self.projection_kind,
- "renderer_id": self.renderer_id,
- "renderer_version": self.renderer_version,
- "component_version": self.component_version,
- "semantic_input_hash": self.semantic_input_hash,
- "key_id": self.key_id,
- }
-
-
-@dataclass(frozen=True)
-class FragmentRecord:
- """One path-free fragment payload with complete byte evidence."""
-
- key: FragmentKey
- content: bytes
- byte_count: int
- content_sha256: str
- record_id: str
-
- @classmethod
- def create(cls, key: FragmentKey, content: bytes) -> FragmentRecord:
- if len(content) > MAX_FRAGMENT_CONTENT_BYTES:
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment content is invalid or oversized",
- maximum_bytes=MAX_FRAGMENT_CONTENT_BYTES,
- )
- body = cls._body(key, content)
- return cls(
- key=key,
- content=content,
- byte_count=len(content),
- content_sha256=hashlib.sha256(content).hexdigest(),
- record_id=projection_hash(body),
- )
-
- @classmethod
- def from_dict(cls, value: object) -> FragmentRecord:
- if not isinstance(value, dict):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment record is invalid",
- )
- document = dict(cast(dict[str, object], value))
- required = {
- "schema_version",
- "contract",
- "record_id",
- "key",
- "content_encoding",
- "content",
- "byte_count",
- "content_sha256",
- }
- if (
- set(document) != required
- or document.get("schema_version") != FRAGMENT_SCHEMA_VERSION
- or document.get("contract") != FRAGMENT_RECORD_CONTRACT
- or document.get("content_encoding") != "base64"
- ):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment record contract is incompatible",
- )
- encoded = document.get("content")
- if not isinstance(encoded, str):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment content encoding is invalid",
- )
- try:
- content = base64.b64decode(encoded.encode("ascii"), validate=True)
- except (UnicodeEncodeError, ValueError) as error:
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment content encoding is invalid",
- ) from error
- if len(content) > MAX_FRAGMENT_CONTENT_BYTES:
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment content is oversized",
- maximum_bytes=MAX_FRAGMENT_CONTENT_BYTES,
- )
- key = FragmentKey.from_dict(document.get("key"))
- body = cls._body(key, content)
- record_id = document.get("record_id")
- if (
- type(document.get("byte_count")) is not int
- or document.get("byte_count") != len(content)
- or document.get("content_sha256") != hashlib.sha256(content).hexdigest()
- or not _is_hash(record_id)
- or record_id != projection_hash(body)
- ):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment byte evidence is invalid",
- )
- return cls(
- key=key,
- content=content,
- byte_count=len(content),
- content_sha256=hashlib.sha256(content).hexdigest(),
- record_id=cast(str, record_id),
- )
-
- @classmethod
- def from_bytes(cls, raw: bytes) -> FragmentRecord:
- try:
- value: object = json.loads(raw)
- except (UnicodeDecodeError, json.JSONDecodeError) as error:
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment record is not valid JSON",
- ) from error
- record = cls.from_dict(value)
- if record.to_bytes() != raw:
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment record is not canonically serialized",
- )
- return record
-
- @staticmethod
- def _body(key: FragmentKey, content: bytes) -> dict[str, object]:
- return {
- "schema_version": FRAGMENT_SCHEMA_VERSION,
- "contract": FRAGMENT_RECORD_CONTRACT,
- "key": key.as_dict(),
- "content_encoding": "base64",
- "content": base64.b64encode(content).decode("ascii"),
- "byte_count": len(content),
- "content_sha256": hashlib.sha256(content).hexdigest(),
- }
-
- def as_dict(self) -> dict[str, object]:
- return {
- **self._body(self.key, self.content),
- "record_id": self.record_id,
- }
-
- def to_bytes(self) -> bytes:
- return canonical_projection_bytes(self.as_dict())
-
-
-class ProjectionFragmentCache:
- """Confined best-effort storage for immutable projection fragments."""
-
- def __init__(
- self,
- project_root: Path,
- cache_root: Path,
- *,
- maximum_content_bytes: int = MAX_FRAGMENT_CONTENT_BYTES,
- ) -> None:
- if (
- type(maximum_content_bytes) is not int
- or not 1 <= maximum_content_bytes <= MAX_FRAGMENT_CONTENT_BYTES
- ):
- raise DocForgeError(
- "invalid_projection_fragment",
- "Projection fragment cache byte limit is invalid",
- maximum_bytes=MAX_FRAGMENT_CONTENT_BYTES,
- )
- self.project_root = project_root
- self.cache_root = cache_root
- self.fragment_root = cache_root / FRAGMENT_CACHE_DIRECTORY
- self.maximum_content_bytes = maximum_content_bytes
-
- @property
- def maximum_record_bytes(self) -> int:
- encoded = ((self.maximum_content_bytes + 2) // 3) * 4
- return encoded + _MAX_RECORD_OVERHEAD_BYTES
-
- def get(self, key: FragmentKey) -> FragmentRecord | None:
- """Return one exact compatible fragment, treating every cache defect as a miss."""
-
- descriptor: int | None = None
- try:
- descriptor = self._open(create=False)
- raw = read_bounded_file_at(
- descriptor,
- f"{key.key_id}.json",
- self.maximum_record_bytes,
- )
- if raw is None:
- return None
- record = FragmentRecord.from_bytes(raw)
- if record.key != key or record.byte_count > self.maximum_content_bytes:
- return None
- require_bound_directory(self.fragment_root, descriptor)
- return record
- except (DocForgeError, OSError):
- return None
- finally:
- if descriptor is not None:
- os.close(descriptor)
-
- def put(self, key: FragmentKey, content: bytes) -> FragmentRecord | None:
- """Durably publish one fragment, returning ``None`` on disposable cache failure."""
-
- if len(content) > self.maximum_content_bytes:
- return None
- try:
- record = FragmentRecord.create(key, content)
- except DocForgeError:
- return None
- raw = record.to_bytes()
- if len(raw) > self.maximum_record_bytes:
- return None
- descriptor: int | None = None
- try:
- descriptor = self._open(create=True)
- name = f"{key.key_id}.json"
- try:
- existing = read_bounded_file_at(
- descriptor,
- name,
- self.maximum_record_bytes,
- )
- except DocForgeError as error:
- if error.code == "path_escape":
- return None
- existing = None
- if existing == raw:
- require_bound_directory(self.fragment_root, descriptor)
- return record
- atomic_replace_bytes_at(
- self.fragment_root,
- descriptor,
- name,
- raw,
- verify=lambda: require_bound_directory(self.fragment_root, descriptor),
- )
- return record
- except (DocForgeError, OSError):
- return None
- finally:
- if descriptor is not None:
- os.close(descriptor)
-
- def prune(self, keep: tuple[FragmentKey, ...]) -> bool:
- """Remove every stale entry and prove the retained inventory is bounded."""
-
- keep_ids = {key.key_id for key in keep}
- if len(keep_ids) > MAX_FRAGMENT_CACHE_ENTRIES:
- return False
- descriptor: int | None = None
- try:
- descriptor = self._open(create=False)
- retained_entries = 0
- retained_bytes = 0
- with os.scandir(descriptor) as entries:
- for entry in entries:
- name = entry.name
- retained = (
- len(name) == 69
- and name.endswith(".json")
- and name[:-5] in keep_ids
- and all(character in "0123456789abcdef" for character in name[:-5])
- )
- if retained:
- identity = entry.stat(follow_symlinks=False)
- if not entry.is_file(follow_symlinks=False):
- return False
- retained_entries += 1
- retained_bytes += identity.st_size
- continue
- try:
- os.unlink(name, dir_fd=descriptor)
- except OSError:
- return False
- if (
- retained_entries > MAX_FRAGMENT_CACHE_ENTRIES
- or retained_bytes > MAX_FRAGMENT_CACHE_BYTES
- ):
- return False
- require_bound_directory(self.fragment_root, descriptor)
- os.fsync(descriptor)
- return True
- except (DocForgeError, OSError):
- return False
- finally:
- if descriptor is not None:
- os.close(descriptor)
-
- def _open(self, *, create: bool) -> int:
- if self.cache_root == self.project_root or not self.cache_root.is_relative_to(
- self.project_root
- ):
- raise DocForgeError(
- "path_escape",
- "Projection fragment cache is not confined to a derived project root",
- )
- return open_confined_directory(
- self.project_root,
- self.fragment_root,
- create=create,
- )
diff --git a/src/docforge/projection_policy.py b/src/docforge/projection_policy.py
deleted file mode 100644
index 5c7321d..0000000
--- a/src/docforge/projection_policy.py
+++ /dev/null
@@ -1,234 +0,0 @@
-"""Independent version-2 policy for manual, portable graph, and live projections."""
-
-from __future__ import annotations
-
-import hashlib
-import json
-from dataclasses import dataclass
-from typing import Literal, cast
-
-from .errors import DocForgeError
-
-ManualProjectionMode = Literal["auto", "explicit", "disabled"]
-PortableGraphProjectionMode = Literal["explicit", "disabled"]
-LiveViewerProjectionMode = Literal["on-demand", "disabled"]
-
-MANUAL_PROJECTION_MODES: tuple[ManualProjectionMode, ...] = (
- "auto",
- "explicit",
- "disabled",
-)
-PORTABLE_GRAPH_PROJECTION_MODES: tuple[PortableGraphProjectionMode, ...] = (
- "explicit",
- "disabled",
-)
-LIVE_VIEWER_PROJECTION_MODES: tuple[LiveViewerProjectionMode, ...] = (
- "on-demand",
- "disabled",
-)
-
-
-def _invalid_mode(field: str, value: object, allowed: tuple[str, ...]) -> DocForgeError:
- return DocForgeError(
- "invalid_projection_policy",
- "Projection policy mode is unsupported",
- projection=field,
- mode=value,
- allowed=list(allowed),
- )
-
-
-def _select_mode(
- value: object | None,
- *,
- field: str,
- default: str,
- allowed: tuple[str, ...],
-) -> str:
- selected: object = default if value is None else value
- if not isinstance(selected, str) or selected not in allowed:
- raise _invalid_mode(field, selected, allowed)
- return selected
-
-
-def _require_boolean(field: str, value: object) -> bool:
- if type(value) is not bool:
- raise DocForgeError(
- "invalid_projection_policy",
- "Projection policy availability must be Boolean",
- field=field,
- )
- return value
-
-
-def _unavailable(field: str, mode: str, required: str) -> DocForgeError:
- return DocForgeError(
- "projection_policy_unavailable",
- "Projection policy mode is unavailable",
- projection=field,
- mode=mode,
- required=required,
- )
-
-
-def validate_manual_projection_mode(value: object) -> ManualProjectionMode:
- """Validate one direct manual-service policy selection."""
-
- return cast(
- ManualProjectionMode,
- _select_mode(
- value,
- field="manual",
- default="explicit",
- allowed=MANUAL_PROJECTION_MODES,
- ),
- )
-
-
-def validate_portable_graph_projection_mode(
- value: object,
-) -> PortableGraphProjectionMode:
- """Validate one direct portable-graph service policy selection."""
-
- return cast(
- PortableGraphProjectionMode,
- _select_mode(
- value,
- field="portable_graph",
- default="explicit",
- allowed=PORTABLE_GRAPH_PROJECTION_MODES,
- ),
- )
-
-
-def validate_live_viewer_projection_mode(value: object) -> LiveViewerProjectionMode:
- """Validate one direct live-viewer service policy selection."""
-
- return cast(
- LiveViewerProjectionMode,
- _select_mode(
- value,
- field="live_viewer",
- default="on-demand",
- allowed=LIVE_VIEWER_PROJECTION_MODES,
- ),
- )
-
-
-@dataclass(frozen=True)
-class ProjectionPolicyV2:
- """One immutable policy for three independent projection consumers."""
-
- manual: ManualProjectionMode
- portable_graph: PortableGraphProjectionMode
- live_viewer: LiveViewerProjectionMode
-
- def __post_init__(self) -> None:
- if self.manual not in MANUAL_PROJECTION_MODES:
- raise _invalid_mode("manual", self.manual, MANUAL_PROJECTION_MODES)
- if self.portable_graph not in PORTABLE_GRAPH_PROJECTION_MODES:
- raise _invalid_mode(
- "portable_graph",
- self.portable_graph,
- PORTABLE_GRAPH_PROJECTION_MODES,
- )
- if self.live_viewer not in LIVE_VIEWER_PROJECTION_MODES:
- raise _invalid_mode(
- "live_viewer",
- self.live_viewer,
- LIVE_VIEWER_PROJECTION_MODES,
- )
-
- def as_dict(self) -> dict[str, object]:
- return {
- "schema_version": 2,
- "manual": self.manual,
- "portable_graph": self.portable_graph,
- "live_viewer": self.live_viewer,
- }
-
- @property
- def policy_hash(self) -> str:
- raw = json.dumps(
- self.as_dict(),
- sort_keys=True,
- separators=(",", ":"),
- ensure_ascii=False,
- ).encode("utf-8")
- return hashlib.sha256(raw).hexdigest()
-
-
-def compose_projection_policy(
- *,
- manual: str | None = None,
- portable_graph: str | None = None,
- live_viewer: str | None = None,
- manual_configured: bool,
- portable_graph_configured: bool,
- application_enabled: bool,
- live_viewer_available: bool = True,
-) -> ProjectionPolicyV2:
- """Compose compatible defaults with explicit availability-checked selections."""
-
- manual_available = _require_boolean("manual_configured", manual_configured)
- graph_available = _require_boolean(
- "portable_graph_configured",
- portable_graph_configured,
- )
- application_available = _require_boolean("application_enabled", application_enabled)
- viewer_available = _require_boolean("live_viewer_available", live_viewer_available)
-
- default_manual = (
- "auto"
- if manual_available and application_available
- else ("explicit" if manual_available else "disabled")
- )
- default_graph = "explicit" if graph_available else "disabled"
- default_viewer = "on-demand" if viewer_available else "disabled"
-
- manual_mode = cast(
- ManualProjectionMode,
- _select_mode(
- manual,
- field="manual",
- default=default_manual,
- allowed=MANUAL_PROJECTION_MODES,
- ),
- )
- graph_mode = cast(
- PortableGraphProjectionMode,
- _select_mode(
- portable_graph,
- field="portable_graph",
- default=default_graph,
- allowed=PORTABLE_GRAPH_PROJECTION_MODES,
- ),
- )
- viewer_mode = cast(
- LiveViewerProjectionMode,
- _select_mode(
- live_viewer,
- field="live_viewer",
- default=default_viewer,
- allowed=LIVE_VIEWER_PROJECTION_MODES,
- ),
- )
-
- if manual_mode != "disabled" and not manual_available:
- raise _unavailable("manual", manual_mode, "manual_render_config")
- if manual_mode == "auto" and not application_available:
- raise _unavailable("manual", manual_mode, "canonical_application")
- if graph_mode == "explicit" and not graph_available:
- raise _unavailable(
- "portable_graph",
- graph_mode,
- "portable_graph_render_config",
- )
- if viewer_mode == "on-demand" and not viewer_available:
- raise _unavailable("live_viewer", viewer_mode, "live_viewer_runtime")
-
- return ProjectionPolicyV2(
- manual=manual_mode,
- portable_graph=graph_mode,
- live_viewer=viewer_mode,
- )
diff --git a/src/docforge/projection_worker.py b/src/docforge/projection_worker.py
deleted file mode 100644
index dc6d48a..0000000
--- a/src/docforge/projection_worker.py
+++ /dev/null
@@ -1,436 +0,0 @@
-"""One-shot detached execution for the fixed built-in projection renderers."""
-
-from __future__ import annotations
-
-import base64
-import binascii
-import json
-import os
-import resource
-import subprocess
-import sys
-import tempfile
-from importlib.metadata import version
-from typing import cast
-
-from .errors import DocForgeError
-from .projection_contract import (
- MAX_PACKAGE_BYTES,
- MAX_PROJECTION_ARTIFACTS,
- MAX_RECEIPT_BYTES,
- ProjectionArtifact,
- ProjectionPackageV1,
- ProjectionReceiptV1,
- ProjectionRenderResult,
- canonical_projection_bytes,
-)
-
-WORKER_PROTOCOL_VERSION = 1
-MAX_WORKER_ARTIFACT_BYTES = 20_000_000
-MAX_WORKER_REQUEST_BYTES = MAX_PACKAGE_BYTES + 1
-MAX_WORKER_RESPONSE_BYTES = 4 * ((MAX_WORKER_ARTIFACT_BYTES + 2) // 3) + MAX_RECEIPT_BYTES + 256_000
-WORKER_TIMEOUT_SECONDS = 30
-
-_GENERIC_HTML_RENDERER_ID = "generic_html"
-_PORTABLE_GRAPH_RENDERER_ID = "portable_graph_html"
-_PORTABLE_GRAPH_RENDERER_VERSION = "1"
-
-
-def _generic_html_renderer_version() -> str:
- return f"1+markdown-it-py-{version('markdown-it-py')}"
-
-
-def _worker_failure(message: str, **details: object) -> DocForgeError:
- return DocForgeError("projection_worker_failure", message, **details)
-
-
-def _renderer_identity(package: ProjectionPackageV1) -> dict[str, object]:
- renderer_value = package.document.get("renderer")
- if not isinstance(renderer_value, dict):
- raise DocForgeError("unsupported_renderer", "Projection renderer identity is invalid")
- renderer = cast(dict[str, object], renderer_value)
- if set(renderer) != {"renderer_id", "renderer_version"}:
- raise DocForgeError("unsupported_renderer", "Projection renderer identity is invalid")
- renderer_id = renderer.get("renderer_id")
- renderer_version = renderer.get("renderer_version")
- if not isinstance(renderer_id, str) or not isinstance(renderer_version, str):
- raise DocForgeError("unsupported_renderer", "Projection renderer identity is invalid")
- supported = (
- package.kind == "manual"
- and renderer_id == _GENERIC_HTML_RENDERER_ID
- and renderer_version == _generic_html_renderer_version()
- ) or (
- package.kind == "graph"
- and renderer_id == _PORTABLE_GRAPH_RENDERER_ID
- and renderer_version == _PORTABLE_GRAPH_RENDERER_VERSION
- )
- if not supported:
- raise DocForgeError(
- "unsupported_renderer",
- "Projection worker supports only the fixed built-in renderer versions",
- )
- return dict(renderer)
-
-
-def _output_policy(package: ProjectionPackageV1) -> tuple[tuple[str, ...], int]:
- policy_value = package.document.get("output_policy")
- if not isinstance(policy_value, dict):
- raise DocForgeError("invalid_projection", "Projection output policy is invalid")
- policy = cast(dict[str, object], policy_value)
- if set(policy) != {"artifact_ids", "max_total_bytes"}:
- raise DocForgeError("invalid_projection", "Projection output policy is invalid")
- artifact_ids_value = policy.get("artifact_ids")
- maximum = policy.get("max_total_bytes")
- if not isinstance(artifact_ids_value, list):
- raise DocForgeError("invalid_projection", "Projection artifact inventory is invalid")
- artifact_ids_objects = cast(list[object], artifact_ids_value)
- if (
- not artifact_ids_objects
- or len(artifact_ids_objects) > MAX_PROJECTION_ARTIFACTS
- or not all(
- isinstance(artifact_id, str)
- and bool(artifact_id)
- and "/" not in artifact_id
- and artifact_id not in {".", ".."}
- for artifact_id in artifact_ids_objects
- )
- ):
- raise DocForgeError("invalid_projection", "Projection artifact inventory is invalid")
- artifact_ids = tuple(cast(list[str], artifact_ids_objects))
- if len(set(artifact_ids)) != len(artifact_ids):
- raise DocForgeError("invalid_projection", "Projection artifact inventory is duplicated")
- if type(maximum) is not int or maximum < 1:
- raise DocForgeError(
- "invalid_projection",
- "Projection output byte allowance is invalid",
- )
- return artifact_ids, maximum
-
-
-def _validated_package(package: object) -> ProjectionPackageV1:
- if not isinstance(package, ProjectionPackageV1):
- raise TypeError("Projection worker requires ProjectionPackageV1")
- validated = ProjectionPackageV1.from_dict(package.as_dict())
- _renderer_identity(validated)
- _output_policy(validated)
- return validated
-
-
-def _validate_result(
- package: ProjectionPackageV1,
- result: ProjectionRenderResult,
- *,
- require_peak_memory: bool,
-) -> ProjectionRenderResult:
- artifact_ids, maximum = _output_policy(package)
- if (
- len(result.artifacts) != len(artifact_ids)
- or tuple(artifact.artifact_id for artifact in result.artifacts) != artifact_ids
- ):
- raise _worker_failure("Projection worker returned an invalid artifact inventory")
- total_bytes = 0
- evidence: list[dict[str, object]] = []
- for artifact in result.artifacts:
- if not artifact.media_type or type(artifact.content) is not bytes:
- raise _worker_failure("Projection worker returned an invalid artifact")
- total_bytes += len(artifact.content)
- if total_bytes > maximum or total_bytes > MAX_WORKER_ARTIFACT_BYTES:
- raise _worker_failure("Projection worker artifact transfer exceeded its fixed boundary")
- evidence.append(artifact.evidence())
-
- try:
- receipt = ProjectionReceiptV1.from_dict(result.receipt.as_dict())
- except DocForgeError as error:
- raise _worker_failure("Projection worker receipt is invalid") from error
- receipt_document = receipt.document
- renderer = _renderer_identity(package)
- timing_value = receipt_document.get("timing")
- if not isinstance(timing_value, dict):
- raise _worker_failure("Projection worker receipt timing is invalid")
- timing = cast(dict[str, object], timing_value)
- elapsed = timing.get("elapsed_ns")
- peak_memory = receipt_document.get("peak_memory_bytes")
- if (
- receipt_document.get("kind") != package.kind
- or receipt_document.get("package_id") != package.package_id
- or receipt_document.get("plan_id") != package.document.get("plan_id")
- or receipt_document.get("renderer") != renderer
- or receipt_document.get("artifacts") != evidence
- or type(elapsed) is not int
- or elapsed < 0
- or (require_peak_memory and (type(peak_memory) is not int or peak_memory <= 0))
- ):
- raise _worker_failure("Projection worker receipt does not attest the requested package")
- return ProjectionRenderResult(tuple(result.artifacts), receipt)
-
-
-def _decode_canonical_line(raw: bytes, *, maximum: int, label: str) -> dict[str, object]:
- if type(raw) is not bytes or len(raw) > maximum:
- raise _worker_failure(f"{label} exceeded its fixed boundary", maximum_bytes=maximum)
- if not raw or not raw.endswith(b"\n") or raw.count(b"\n") != 1:
- raise _worker_failure(f"{label} framing is invalid")
- payload = raw[:-1]
- try:
- value: object = json.loads(payload)
- except (UnicodeDecodeError, json.JSONDecodeError) as error:
- raise _worker_failure(f"{label} is not valid JSON") from error
- if not isinstance(value, dict):
- raise _worker_failure(f"{label} must be one JSON object")
- document = cast(dict[str, object], value)
- if canonical_projection_bytes(document) != payload:
- raise _worker_failure(f"{label} is not canonical JSON")
- return document
-
-
-def _encode_request(package: ProjectionPackageV1) -> bytes:
- encoded = canonical_projection_bytes(package.as_dict()) + b"\n"
- if len(encoded) > MAX_WORKER_REQUEST_BYTES:
- raise DocForgeError(
- "projection_too_large",
- "Projection worker request exceeds its fixed boundary",
- maximum_bytes=MAX_WORKER_REQUEST_BYTES,
- )
- return encoded
-
-
-def _invoke_worker(request: bytes) -> subprocess.CompletedProcess[bytes]:
- environment = {key: os.environ[key] for key in ("SYSTEMROOT", "WINDIR") if key in os.environ}
- environment.update(
- {
- "PYTHONIOENCODING": "utf-8",
- "PYTHONUTF8": "1",
- }
- )
- command = [sys.executable, "-I", "-m", "docforge._projection_worker_main"]
- with tempfile.TemporaryFile() as output:
- completed = subprocess.run(
- command,
- input=request,
- stdout=output,
- stderr=subprocess.DEVNULL,
- check=False,
- timeout=WORKER_TIMEOUT_SECONDS,
- shell=False,
- cwd=sys.prefix,
- env=environment,
- )
- output.seek(0)
- stdout = output.read(MAX_WORKER_RESPONSE_BYTES + 1)
- return subprocess.CompletedProcess(
- command,
- completed.returncode,
- stdout=stdout,
- )
-
-
-def _decode_response(package: ProjectionPackageV1, raw: bytes) -> ProjectionRenderResult:
- document = _decode_canonical_line(
- raw,
- maximum=MAX_WORKER_RESPONSE_BYTES,
- label="Projection worker response",
- )
- if (
- set(document) != {"schema_version", "artifacts", "receipt"}
- or document.get("schema_version") != WORKER_PROTOCOL_VERSION
- ):
- raise _worker_failure("Projection worker response contract is invalid")
- artifact_values = document.get("artifacts")
- receipt_value = document.get("receipt")
- if not isinstance(artifact_values, list) or not isinstance(receipt_value, dict):
- raise _worker_failure("Projection worker response structure is invalid")
- artifacts: list[ProjectionArtifact] = []
- total_bytes = 0
- for value in cast(list[object], artifact_values):
- if not isinstance(value, dict):
- raise _worker_failure("Projection worker artifact envelope is invalid")
- artifact = cast(dict[str, object], value)
- if set(artifact) != {"artifact_id", "media_type", "content_base64"}:
- raise _worker_failure("Projection worker artifact envelope is invalid")
- artifact_id = artifact.get("artifact_id")
- media_type = artifact.get("media_type")
- encoded = artifact.get("content_base64")
- if (
- not isinstance(artifact_id, str)
- or not isinstance(media_type, str)
- or not isinstance(encoded, str)
- ):
- raise _worker_failure("Projection worker artifact envelope is invalid")
- try:
- content = base64.b64decode(encoded.encode("ascii"), validate=True)
- except (UnicodeEncodeError, binascii.Error, ValueError) as error:
- raise _worker_failure("Projection worker artifact encoding is invalid") from error
- total_bytes += len(content)
- if total_bytes > MAX_WORKER_ARTIFACT_BYTES:
- raise _worker_failure("Projection worker artifact transfer exceeded its fixed boundary")
- artifacts.append(ProjectionArtifact(artifact_id, media_type, content))
- try:
- receipt = ProjectionReceiptV1.from_dict(cast(dict[str, object], receipt_value))
- except DocForgeError as error:
- raise _worker_failure("Projection worker receipt is invalid") from error
- return _validate_result(
- package,
- ProjectionRenderResult(tuple(artifacts), receipt),
- require_peak_memory=True,
- )
-
-
-def render_projection_in_worker(package: ProjectionPackageV1) -> ProjectionRenderResult:
- """Render one validated path-free package in a fixed one-shot child process."""
-
- validated = _validated_package(package)
- request = _encode_request(validated)
- try:
- completed = _invoke_worker(request)
- except subprocess.TimeoutExpired as error:
- raise DocForgeError(
- "projection_worker_timeout",
- "Detached projection worker exceeded its fixed timeout",
- timeout_seconds=WORKER_TIMEOUT_SECONDS,
- ) from error
- except OSError as error:
- raise _worker_failure("Detached projection worker could not be launched") from error
- if completed.returncode != 0:
- if completed.returncode == 3 and completed.stdout:
- try:
- failure = _decode_canonical_line(
- completed.stdout,
- maximum=MAX_RECEIPT_BYTES,
- label="Projection worker error response",
- )
- error = failure.get("error")
- error_document = cast(dict[str, object], error) if isinstance(error, dict) else None
- if (
- set(failure) == {"schema_version", "error"}
- and failure.get("schema_version") == WORKER_PROTOCOL_VERSION
- and error_document is not None
- and set(error_document) == {"code", "message", "details"}
- and isinstance(error_document.get("code"), str)
- and bool(error_document["code"])
- and isinstance(error_document.get("message"), str)
- and bool(error_document["message"])
- and isinstance(error_document.get("details"), dict)
- ):
- raise DocForgeError(
- cast(str, error_document["code"]),
- cast(str, error_document["message"]),
- **cast(dict[str, object], error_document["details"]),
- )
- except DocForgeError as error:
- if error.code != "projection_worker_failure":
- raise
- if completed.returncode < 0:
- raise _worker_failure(
- "Detached projection worker terminated by signal",
- signal=-completed.returncode,
- )
- raise _worker_failure(
- "Detached projection worker exited unsuccessfully",
- exit_code=completed.returncode,
- )
- if type(completed.stdout) is not bytes:
- raise _worker_failure("Detached projection worker returned invalid output")
- return _decode_response(validated, completed.stdout)
-
-
-def _render_package(package: ProjectionPackageV1) -> ProjectionRenderResult:
- renderer = _renderer_identity(package)
- if renderer["renderer_id"] == _GENERIC_HTML_RENDERER_ID:
- from docforge_renderers.manual import ManualHtmlRenderer
-
- result = ManualHtmlRenderer(cast(str, renderer["renderer_version"])).render(package)
- else:
- from docforge_renderers.graph import PortableGraphHtmlRenderer
-
- result = PortableGraphHtmlRenderer().render(package)
- return _validate_result(package, result, require_peak_memory=False)
-
-
-def _peak_memory_bytes() -> int:
- peak = int(resource.getrusage(resource.RUSAGE_SELF).ru_maxrss)
- return max(1, peak if sys.platform == "darwin" else peak * 1024)
-
-
-def _child_response(package: ProjectionPackageV1) -> bytes:
- result = _render_package(package)
- original = result.receipt.document
- receipt = ProjectionReceiptV1.create(
- kind=package.kind,
- package_id=package.package_id,
- plan_id=cast(str, package.document["plan_id"]),
- renderer=cast(dict[str, object], original["renderer"]),
- artifacts=[artifact.evidence() for artifact in result.artifacts],
- diagnostics=cast(dict[str, object], original["diagnostics"]),
- timing=cast(dict[str, object], original["timing"]),
- peak_memory_bytes=_peak_memory_bytes(),
- )
- validated = _validate_result(
- package,
- ProjectionRenderResult(result.artifacts, receipt),
- require_peak_memory=True,
- )
- document: dict[str, object] = {
- "schema_version": WORKER_PROTOCOL_VERSION,
- "artifacts": [
- {
- "artifact_id": artifact.artifact_id,
- "media_type": artifact.media_type,
- "content_base64": base64.b64encode(artifact.content).decode("ascii"),
- }
- for artifact in validated.artifacts
- ],
- "receipt": validated.receipt.as_dict(),
- }
- encoded = canonical_projection_bytes(document) + b"\n"
- if len(encoded) > MAX_WORKER_RESPONSE_BYTES:
- raise _worker_failure(
- "Projection worker response exceeded its fixed boundary",
- maximum_bytes=MAX_WORKER_RESPONSE_BYTES,
- )
- return encoded
-
-
-def _read_child_request() -> ProjectionPackageV1:
- raw = sys.stdin.buffer.read(MAX_WORKER_REQUEST_BYTES + 1)
- document = _decode_canonical_line(
- raw,
- maximum=MAX_WORKER_REQUEST_BYTES,
- label="Projection worker request",
- )
- return _validated_package(ProjectionPackageV1.from_dict(document))
-
-
-def main(argv: list[str] | None = None) -> int:
- """Run the closed one-request child protocol."""
-
- arguments = sys.argv[1:] if argv is None else argv
- if arguments:
- return 2
- try:
- package = _read_child_request()
- except Exception:
- return 2
- try:
- response = _child_response(package)
- sys.stdout.buffer.write(response)
- sys.stdout.buffer.flush()
- except DocForgeError as error:
- response = (
- canonical_projection_bytes(
- {
- "schema_version": WORKER_PROTOCOL_VERSION,
- "error": error.as_dict(),
- }
- )
- + b"\n"
- )
- if len(response) <= MAX_RECEIPT_BYTES:
- sys.stdout.buffer.write(response)
- sys.stdout.buffer.flush()
- return 3
- except Exception:
- return 2
- return 0
-
-
-if __name__ == "__main__":
- raise SystemExit(main())
diff --git a/src/docforge/py.typed b/src/docforge/py.typed
deleted file mode 100644
index e4798ff..0000000
--- a/src/docforge/py.typed
+++ /dev/null
@@ -1 +0,0 @@
-# PEP 561 marker for the typed DocForge public package.
diff --git a/src/docforge/render_contract.py b/src/docforge/render_contract.py
index 430dc26..f24ee9b 100644
--- a/src/docforge/render_contract.py
+++ b/src/docforge/render_contract.py
@@ -1,30 +1,31 @@
-"""Compatibility shim over the versioned manual projection boundary."""
+"""Deterministic built-in renderer contract and safe template primitives."""
from __future__ import annotations
import hashlib
import html
import json
+import re
from dataclasses import dataclass
from importlib.metadata import version
from pathlib import Path
-from typing import Protocol, cast
+from typing import Protocol
+
+from markdown_it import MarkdownIt
from .errors import DocForgeError
-from .manual_projection import build_manual_projection_package, build_manual_render_plan
-from .models import ProjectSnapshot, RenderView
-from .projection_contract import (
- ManualRenderPlanV1,
- ProjectionPackageV1,
- ProjectionRenderResult,
+from .models import Edge, Node, ProjectSnapshot, RenderView
+
+_TEMPLATE_TOKEN = re.compile(r"{{\s*([a-z_][a-z0-9_]*)\s*}}")
+_ALLOWED_TOKENS = frozenset(
+ {
+ "docforge_content",
+ "docforge_project_id",
+ "docforge_render_identity",
+ "docforge_title",
+ "docforge_view_id",
+ }
)
-from .projection_fragments import (
- FragmentKey,
- FragmentRecord,
- ProjectionFragmentCache,
- fragment_semantic_hash,
-)
-from .projection_worker import render_projection_in_worker
@dataclass(frozen=True)
@@ -35,7 +36,6 @@ class PreparedRender:
renderer: str
renderer_version: str
template_hash: str
- projection_receipt: dict[str, object] | None = None
class Renderer(Protocol):
@@ -55,18 +55,16 @@ class Renderer(Protocol):
class GenericHtmlRenderer:
- """Preserve the public v1 renderer API over the plan-only manual renderer."""
+ """Render validated nodes through escaped CommonMark and a strict token template."""
renderer_id = "generic_html"
contract_version = "1"
- page_component_version = "manual.page@1"
-
- def __init__(self, *, incremental: bool = True) -> None:
+ def __init__(self) -> None:
+ self.markdown = MarkdownIt("commonmark", {"html": False, "typographer": False})
self.renderer_version = (
f"{self.contract_version}+markdown-it-py-{version('markdown-it-py')}"
)
- self.incremental = incremental
def prepare(
self,
@@ -76,6 +74,22 @@ class GenericHtmlRenderer:
*,
changeset_hash: str | None,
) -> PreparedRender:
+ try:
+ template = template_bytes.decode("utf-8")
+ except UnicodeDecodeError as error:
+ raise DocForgeError("invalid_template", "Render template is not valid UTF-8") from error
+ tokens = _TEMPLATE_TOKEN.findall(template)
+ unknown = sorted(set(tokens) - _ALLOWED_TOKENS)
+ remainder = _TEMPLATE_TOKEN.sub("", template)
+ if unknown or "{{" in remainder or "}}" in remainder:
+ raise DocForgeError(
+ "invalid_template", "Render template contains unsupported tokens", tokens=unknown
+ )
+ if tokens.count("docforge_content") != 1:
+ raise DocForgeError(
+ "invalid_template", "Render template must contain docforge_content exactly once"
+ )
+
selected = tuple(
node for node in snapshot.nodes if not view.families or node.family in view.families
)
@@ -114,31 +128,16 @@ class GenericHtmlRenderer:
render_identity = hashlib.sha256(
json.dumps(identity_payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
).hexdigest()
- plan = build_manual_render_plan(snapshot, view, changeset_hash=changeset_hash)
- full_package = build_manual_projection_package(
- plan,
- template_bytes,
- renderer_id=self.renderer_id,
- renderer_version=self.renderer_version,
- max_output_bytes=snapshot.descriptor.limits.max_render_bytes,
- render_identity=render_identity,
- )
- if self.incremental:
- result = self._incremental_result(
- snapshot,
- plan,
- template_bytes,
- full_package=full_package,
- render_identity=render_identity,
- )
- else:
- result = render_projection_in_worker(full_package)
- if len(result.artifacts) != 1:
- raise DocForgeError(
- "invalid_projection",
- "Manual renderer returned an unsupported artifact set",
- )
- output = result.artifacts[0].content
+ content = self._content(selected, selected_edges)
+ replacements = {
+ "docforge_content": content,
+ "docforge_project_id": html.escape(snapshot.descriptor.project_id, quote=True),
+ "docforge_render_identity": render_identity,
+ "docforge_title": html.escape(view.title, quote=True),
+ "docforge_view_id": html.escape(view.view_id, quote=True),
+ }
+ rendered = _TEMPLATE_TOKEN.sub(lambda match: replacements[match.group(1)], template)
+ output = rendered.rstrip().encode("utf-8") + b"\n"
return PreparedRender(
render_identity=render_identity,
output_hash=hashlib.sha256(output).hexdigest(),
@@ -146,114 +145,45 @@ class GenericHtmlRenderer:
renderer=self.renderer_id,
renderer_version=self.renderer_version,
template_hash=template_hash,
- projection_receipt=result.receipt.as_dict(),
)
- def _incremental_result(
- self,
- snapshot: ProjectSnapshot,
- plan: ManualRenderPlanV1,
- template_bytes: bytes,
- *,
- full_package: ProjectionPackageV1,
- render_identity: str,
- ) -> ProjectionRenderResult:
- cache = ProjectionFragmentCache(
- snapshot.descriptor.root,
- snapshot.descriptor.cache_root,
- )
- pages = cast(list[object], plan.document["pages"])
- records: list[FragmentRecord | None] = []
- missing: list[tuple[int, FragmentKey]] = []
- for value in pages:
- page = cast(dict[str, object], value)
- key = FragmentKey.create(
- projection_kind="manual",
- renderer_id=self.renderer_id,
- renderer_version=self.renderer_version,
- component_version=self.page_component_version,
- semantic_input_hash=fragment_semantic_hash(page),
+ def _content(self, nodes: tuple[Node, ...], edges: tuple[Edge, ...]) -> str:
+ navigation = ['
")
+ sections = [*navigation]
+ edge_map: dict[str, list[Edge]] = {}
+ for edge in edges:
+ edge_map.setdefault(edge.source_id, []).append(edge)
+ for node in nodes:
+ sections.extend(
+ [
+ f'
',
+ f"{html.escape(node.title)}
",
+ '',
+ f"- ID
- {html.escape(node.node_id)}
",
+ f"- Family
- {html.escape(node.family)}
",
+ f"- Status
- {html.escape(node.status)}
",
+ f"- Authority
- {html.escape(node.authority)}
",
+ "
",
+ f'{html.escape(node.summary)}
',
+ self.markdown.render(node.content).rstrip(),
+ ]
)
- try:
- for position, key in missing:
- record = FragmentRecord.create(key, fragments[position])
- records[position] = record
- new_records.append(record)
- except DocForgeError:
- return full_result
- complete_records = [record for record in records if record is not None]
- if len(complete_records) != len(records):
- return full_result or render_projection_in_worker(full_package)
- try:
- incremental_package = build_manual_projection_package(
- plan,
- template_bytes,
- fragment_records=[record.as_dict() for record in complete_records],
- renderer_id=self.renderer_id,
- renderer_version=self.renderer_version,
- max_output_bytes=snapshot.descriptor.limits.max_render_bytes,
- render_identity=render_identity,
- )
- incremental_result = render_projection_in_worker(incremental_package)
- except DocForgeError:
- cache.prune(())
- return full_result or render_projection_in_worker(full_package)
- if full_result is None:
- cache.prune(tuple(record.key for record in complete_records))
- return incremental_result
- if tuple(
- (artifact.artifact_id, artifact.media_type, artifact.content)
- for artifact in incremental_result.artifacts
- ) != tuple(
- (artifact.artifact_id, artifact.media_type, artifact.content)
- for artifact in full_result.artifacts
- ):
- cache.prune(())
- return full_result
- for record in new_records:
- cache.put(record.key, record.content)
- cache.prune(tuple(record.key for record in complete_records))
- return incremental_result
-
- @staticmethod
- def _extract_page_fragments(
- pages: list[object],
- output: bytes,
- ) -> list[bytes]:
- """Extract exact deterministic page sections from one trusted full artifact."""
-
- fragments: list[bytes] = []
- cursor = 0
- closing = b""
- for value in pages:
- page = cast(dict[str, object], value)
- node_id = cast(str, page["node_id"])
- marker = f'
'.encode()
- start = output.find(marker, cursor)
- end = output.find(closing, start + len(marker)) if start >= 0 else -1
- if start < 0 or end < 0:
- raise DocForgeError(
- "invalid_projection",
- "Full manual artifact does not contain its planned page fragments",
- )
- end += len(closing)
- fragments.append(output[start:end])
- cursor = end
- return fragments
+ relationships = edge_map.get(node.node_id, [])
+ if relationships:
+ sections.append('')
+ for edge in relationships:
+ sections.append(
+ f"- {html.escape(edge.relation)}: {html.escape(edge.target_id)}
"
+ )
+ sections.append("
")
+ sections.append("")
+ return "\n".join(sections)
_RENDERERS: dict[str, type[GenericHtmlRenderer]] = {
@@ -261,13 +191,13 @@ _RENDERERS: dict[str, type[GenericHtmlRenderer]] = {
}
-def renderer_for(view: RenderView, *, incremental: bool = True) -> Renderer:
+def renderer_for(view: RenderView) -> Renderer:
factory = _RENDERERS.get(view.renderer)
if factory is None:
raise DocForgeError(
"unsupported_renderer", "View does not name a supported built-in renderer"
)
- return factory(incremental=incremental)
+ return factory()
def relative_output(snapshot: ProjectSnapshot, path: Path) -> str:
diff --git a/src/docforge/rendering.py b/src/docforge/rendering.py
index 86738d3..79e4116 100644
--- a/src/docforge/rendering.py
+++ b/src/docforge/rendering.py
@@ -26,8 +26,6 @@ from .models import (
RenderView,
)
from .project import project_root_fingerprint
-from .projection_contract import ProjectionReceiptV1
-from .projection_policy import ManualProjectionMode, validate_manual_projection_mode
from .render_contract import PreparedRender, relative_output, renderer_for
from .telemetry import increment, stage
@@ -38,26 +36,9 @@ MAX_RENDER_RECEIPT_BYTES = 64_000
class RenderService:
"""Render only declared views through fixed built-in renderer implementations."""
- def __init__(
- self,
- project: ProjectService,
- changesets: ChangesetStore | None = None,
- *,
- manual_policy: ManualProjectionMode = "explicit",
- ) -> None:
+ def __init__(self, project: ProjectService, changesets: ChangesetStore | None = None) -> None:
self.project = project
self.changesets = changesets or ChangesetStore(project)
- self.manual_policy = validate_manual_projection_mode(manual_policy)
-
- def _require_rendering(self, operation: str) -> None:
- if self.manual_policy == "disabled":
- raise DocForgeError(
- "projection_policy_forbids_operation",
- "Manual projection policy disables rendering work",
- projection="manual",
- mode=self.manual_policy,
- operation=operation,
- )
def status(self, view_id: str | None = None) -> dict[str, object]:
"""Report publication state from bounded receipts without rendering canonical content."""
@@ -105,7 +86,6 @@ class RenderService:
def deep_status(self, view_id: str | None = None) -> dict[str, object]:
"""Recompute render output as the explicit side-effect-free equivalence oracle."""
- self._require_rendering("deep_status")
snapshot = self.project.load()
config = snapshot.descriptor.render
if config is None:
@@ -127,12 +107,7 @@ class RenderService:
snapshot.descriptor.root,
view.output_path,
)
- prepared, _ = self._prepare(
- snapshot,
- view,
- changeset_hash=None,
- incremental=False,
- )
+ prepared, _ = self._prepare(snapshot, view, changeset_hash=None)
state = "missing"
actual_hash: str | None = None
output = view.output_path
@@ -176,7 +151,6 @@ class RenderService:
)
def render(self, view_id: str) -> dict[str, object]:
- self._require_rendering("render")
with self._lock():
snapshot = self.project.load()
config = self._config(snapshot)
@@ -399,8 +373,6 @@ class RenderService:
"template_file": final_template_file,
"output_file": final_output_file,
}
- if prepared.projection_receipt is not None:
- payload["projection_receipt"] = prepared.projection_receipt
raw = json.dumps(payload, sort_keys=True, indent=2).encode("utf-8") + b"\n"
if len(raw) > MAX_RENDER_RECEIPT_BYTES:
raise DocForgeError(
@@ -600,10 +572,8 @@ class RenderService:
renderer = renderer_for(view)
template_file = receipt.get("template_file")
output_file = receipt.get("output_file")
- fields = set(receipt)
- projection_receipt = receipt.get("projection_receipt")
return (
- fields in (required, required | {"projection_receipt"})
+ set(receipt) == required
and receipt.get("schema_version") == RENDER_RECEIPT_SCHEMA_VERSION
and receipt.get("project_id") == descriptor.project_id
and receipt.get("project_root_fingerprint") == project_root_fingerprint(descriptor.root)
@@ -632,50 +602,6 @@ class RenderService:
descriptor.limits.max_render_bytes,
)
and cast(dict[str, object], output_file)["size"] == receipt.get("output_bytes")
- and (
- projection_receipt is None
- or self._valid_projection_receipt(
- projection_receipt,
- renderer_id=renderer.renderer_id,
- renderer_version=renderer.renderer_version,
- output_hash=cast(str, receipt["output_hash"]),
- output_bytes=cast(int, receipt["output_bytes"]),
- )
- )
- )
-
- @staticmethod
- def _valid_projection_receipt(
- value: object,
- *,
- renderer_id: str,
- renderer_version: str,
- output_hash: str,
- output_bytes: int,
- ) -> bool:
- if not isinstance(value, dict):
- return False
- try:
- receipt = ProjectionReceiptV1.from_dict(cast(dict[str, object], value))
- except DocForgeError:
- return False
- document = receipt.document
- return (
- document.get("kind") == "manual"
- and document.get("renderer")
- == {
- "renderer_id": renderer_id,
- "renderer_version": renderer_version,
- }
- and document.get("artifacts")
- == [
- {
- "artifact_id": "manual.html",
- "media_type": "text/html; charset=utf-8",
- "sha256": output_hash,
- "bytes": output_bytes,
- }
- ]
)
@staticmethod
@@ -737,7 +663,6 @@ class RenderService:
"reason": reason,
"verification": "receipt",
"receipt_schema_version": payload.get("schema_version"),
- "projection_receipt": payload.get("projection_receipt"),
}
def _current_state(self) -> ProjectState | None:
@@ -762,7 +687,6 @@ class RenderService:
}
def preview(self, changeset_id: str, view_id: str) -> dict[str, object]:
- self._require_rendering("preview")
with self._lock():
snapshot, changeset_hash = self.changesets.projected_snapshot(changeset_id)
config = self._config(snapshot)
@@ -807,12 +731,11 @@ class RenderService:
view: RenderView,
*,
changeset_hash: str | None,
- incremental: bool = True,
) -> tuple[PreparedRender, bytes]:
increment("render_prepare_calls")
template = self._template_bytes(snapshot, view)
with stage("render.prepare"):
- prepared = renderer_for(view, incremental=incremental).prepare(
+ prepared = renderer_for(view).prepare(
snapshot,
view,
template,
@@ -927,7 +850,6 @@ class RenderService:
"expected_output_hash": prepared.output_hash,
"actual_output_hash": actual_hash,
"template_hash": prepared.template_hash,
- "projection_receipt": prepared.projection_receipt,
"path": relative_output(snapshot, view.output_path),
"state": state,
}
diff --git a/src/docforge/telemetry.py b/src/docforge/telemetry.py
index 1571c24..4c9c6d8 100644
--- a/src/docforge/telemetry.py
+++ b/src/docforge/telemetry.py
@@ -79,7 +79,6 @@ OPERATION_NAMES = frozenset(
"test",
"benchmark.m1",
"benchmark.m2",
- "benchmark.m3",
"mcp.invoke",
"mcp.bootstrap",
"mcp.sync",
@@ -97,8 +96,6 @@ OPERATION_NAMES = frozenset(
"mcp.generation_diff",
"mcp.validate_project",
"mcp.render_status",
- "mcp.graph_plan",
- "mcp.graph_render_status",
"mcp.visualize",
"mcp.visualization_status",
"mcp.stop_visualization",
@@ -120,9 +117,6 @@ OPERATION_NAMES = frozenset(
"cli.impact",
"cli.context",
"cli.generation-diff",
- "cli.graph-plan",
- "cli.graph-render",
- "cli.graph-render-status",
"cli.configure",
"cli.doctor",
"cli.render",
diff --git a/src/docforge/viewer_manager.py b/src/docforge/viewer_manager.py
index 44f0d63..cd8ca88 100644
--- a/src/docforge/viewer_manager.py
+++ b/src/docforge/viewer_manager.py
@@ -28,10 +28,6 @@ from .errors import DocForgeError
from .index import ProjectIndex
from .models import IncrementalStateProject
from .project import project_root_fingerprint
-from .projection_policy import (
- LiveViewerProjectionMode,
- validate_live_viewer_projection_mode,
-)
from .telemetry import increment, stage
from .visualization import VISUALIZATION_TEMPLATE, VisualizationIndexSnapshot
@@ -627,16 +623,9 @@ class ViewerManager:
class ViewerManagerClient:
"""Project-bound MCP-side client for the separately supervised manager service."""
- def __init__(
- self,
- index: ProjectIndex,
- *,
- state_path: Path | None = None,
- live_viewer_policy: LiveViewerProjectionMode = "on-demand",
- ) -> None:
+ def __init__(self, index: ProjectIndex, *, state_path: Path | None = None) -> None:
self.index = index
self.state_path = state_path or default_state_path()
- self.live_viewer_policy = validate_live_viewer_projection_mode(live_viewer_policy)
def start(
self,
@@ -645,14 +634,6 @@ class ViewerManagerClient:
query: str | None = None,
depth: int = 1,
) -> dict[str, object]:
- if self.live_viewer_policy == "disabled":
- raise DocForgeError(
- "projection_policy_forbids_operation",
- "Live viewer projection policy disables viewer startup",
- projection="live_viewer",
- mode=self.live_viewer_policy,
- operation="start",
- )
if node_id is not None and query is not None:
raise DocForgeError(
"invalid_visualization_target",
diff --git a/src/docforge/visualization.py b/src/docforge/visualization.py
index 9dfcb7e..621cb83 100644
--- a/src/docforge/visualization.py
+++ b/src/docforge/visualization.py
@@ -506,11 +506,11 @@ class VisualizationIndexSnapshot:
)
def source(self, node_id: str) -> dict[str, object]:
- """Return bounded source evidence stored in the pinned index generation."""
+ """Return one node's bounded, project-confined UTF-8 source file."""
with self._connection() as connection:
row = connection.execute(
- "SELECT node_id, source_path, source_anchor, content FROM nodes WHERE node_id = ?",
+ "SELECT node_id, source_path, source_anchor FROM nodes WHERE node_id = ?",
(node_id,),
).fetchone()
if row is None:
@@ -518,8 +518,7 @@ class VisualizationIndexSnapshot:
"""
SELECT logic.logic_id AS node_id,
owner.source_path AS source_path,
- logic.source_anchor AS source_anchor,
- owner.content AS content
+ logic.source_anchor AS source_anchor
FROM logic_nodes AS logic
JOIN nodes AS owner ON owner.node_id = logic.owner_node_id
WHERE logic.logic_id = ?
@@ -534,26 +533,51 @@ class VisualizationIndexSnapshot:
"No node has the requested stable ID",
node_id=node_id,
)
- content = row["content"]
- if not isinstance(content, str):
+ relative = Path(row["source_path"])
+ if relative.is_absolute() or ".." in relative.parts or not relative.parts:
+ raise DocForgeError("path_escape", "Node source path is unsafe", node_id=node_id)
+ source = self.project_root / relative
+ try:
+ resolved = source.resolve(strict=True)
+ except OSError as error:
raise DocForgeError(
- "invalid_index",
- "Pinned source evidence is invalid",
+ "missing_source",
+ "Node source file is unavailable",
+ node_id=node_id,
+ ) from error
+ if (
+ source.is_symlink()
+ or resolved != source
+ or not source.is_relative_to(self.project_root)
+ or not source.is_file()
+ ):
+ raise DocForgeError("path_escape", "Node source file is unsafe", node_id=node_id)
+ if source.stat().st_size > self.max_source_bytes:
+ raise DocForgeError(
+ "source_too_large",
+ "Node source exceeds the configured source limit",
node_id=node_id,
)
- raw = content.encode("utf-8")
+ raw = source.read_bytes()
if len(raw) > self.max_source_bytes:
raise DocForgeError(
"source_too_large",
- "Pinned source evidence exceeds the configured source limit",
+ "Node source exceeds the configured source limit",
node_id=node_id,
)
+ try:
+ content = raw.decode("utf-8")
+ except UnicodeDecodeError as error:
+ raise DocForgeError(
+ "invalid_source",
+ "Node source is not UTF-8",
+ node_id=node_id,
+ ) from error
return self._result(
node_id=node_id,
source_path=row["source_path"],
source_anchor=row["source_anchor"],
content=content,
- source_provenance="index_snapshot",
snapshot=True,
)
diff --git a/src/docforge_renderers/__init__.py b/src/docforge_renderers/__init__.py
deleted file mode 100644
index 94c4706..0000000
--- a/src/docforge_renderers/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-"""Capability-isolated renderer implementations for DocForge projection packages."""
diff --git a/src/docforge_renderers/graph.py b/src/docforge_renderers/graph.py
deleted file mode 100644
index a36528b..0000000
--- a/src/docforge_renderers/graph.py
+++ /dev/null
@@ -1,321 +0,0 @@
-"""Deterministic self-contained renderer for one portable graph package."""
-
-from __future__ import annotations
-
-import base64
-import hashlib
-import html
-import json
-from time import perf_counter_ns
-from typing import cast
-
-from docforge.errors import DocForgeError
-from docforge.projection_contract import (
- ProjectionArtifact,
- ProjectionPackageV1,
- ProjectionReceiptV1,
- ProjectionRenderResult,
-)
-
-PORTABLE_GRAPH_CSS = """
-:root { color-scheme: light dark; font-family: system-ui, sans-serif; }
-* { box-sizing: border-box; }
-body { margin: 0; background: Canvas; color: CanvasText; }
-.skip { position: absolute; left: -10000px; top: auto; }
-.skip:focus { left: 1rem; top: 1rem; z-index: 2; padding: .5rem; background: Canvas; }
-header, main { width: min(96%, 1100px); margin: 0 auto; }
-header { padding: 1rem 0; }
-.controls { display: flex; flex-wrap: wrap; gap: .75rem; align-items: end; }
-label { display: grid; gap: .25rem; font-weight: 600; }
-input, select, button { font: inherit; min-height: 2.75rem; padding: .45rem .65rem; }
-button { cursor: pointer; }
-button:focus-visible, input:focus-visible, select:focus-visible { outline: .2rem solid Highlight; }
-.summary { margin: 1rem 0; }
-.layout { display: grid; grid-template-columns: minmax(16rem, 1fr) minmax(20rem, 2fr); gap: 1rem; }
-.panel { border: 1px solid GrayText; border-radius: .5rem; padding: 1rem; overflow: auto; }
-html[data-enhanced="true"] main[data-mode="nodes"] .layout,
-html[data-enhanced="true"] main[data-mode="flow"] .layout { grid-template-columns: 1fr; }
-html[data-enhanced="true"] main[data-mode="nodes"] [data-panel="relationships"] { display: none; }
-html[data-enhanced="true"] main[data-mode="flow"] [data-panel="nodes"] { display: none; }
-.node-list { list-style: none; padding: 0; margin: 0; display: grid; gap: .5rem; }
-.node-list button {
- width: 100%; text-align: left; border: 1px solid GrayText; border-radius: .35rem;
-}
-.node-list button[aria-current="true"] { border-width: .2rem; }
-table { border-collapse: collapse; width: 100%; }
-th, td { text-align: left; border-bottom: 1px solid GrayText; padding: .5rem; vertical-align: top; }
-caption { text-align: left; font-weight: 700; margin-bottom: .5rem; }
-.muted { color: CanvasText; }
-dialog {
- max-width: min(42rem, calc(100% - 2rem));
- border: 1px solid GrayText; border-radius: .5rem;
-}
-dialog::backdrop { background: rgb(0 0 0 / 55%); }
-@media (max-width: 48rem) { .layout { grid-template-columns: 1fr; } }
-@media (prefers-reduced-motion: reduce) {
- *, *::before, *::after { scroll-behavior: auto !important; }
-}
-@media (forced-colors: active) {
- .panel, .node-list button, dialog { border: 2px solid CanvasText; }
-}
-""".strip()
-
-PORTABLE_GRAPH_JAVASCRIPT = r"""
-(() => {
- "use strict";
- const plan = JSON.parse(document.getElementById("docforge-graph-plan").textContent);
- const nodes = plan.graph.nodes;
- const edges = plan.graph.edges;
- const list = document.getElementById("node-list");
- const rows = document.getElementById("edge-rows");
- const filter = document.getElementById("filter");
- const mode = document.getElementById("mode");
- const main = document.getElementById("main");
- const status = document.getElementById("status");
- const dialog = document.getElementById("node-dialog");
- const detail = document.getElementById("node-detail");
- const close = document.getElementById("close-dialog");
- let opener = null;
- document.documentElement.dataset.enhanced = "true";
-
- const matches = (node) => {
- const query = filter.value.trim().toLocaleLowerCase();
- const fields = [
- node.node_id, node.title, node.summary, node.family, node.status, ...node.tags
- ];
- return !query || fields
- .join(" ").toLocaleLowerCase().includes(query);
- };
- const selectedIds = () => new Set(nodes.filter(matches).map((node) => node.node_id));
- const render = () => {
- main.dataset.mode = mode.value;
- const visible = nodes.filter(matches);
- const ids = selectedIds();
- list.replaceChildren(...visible.map((node) => {
- const item = document.createElement("li");
- const button = document.createElement("button");
- button.type = "button";
- button.textContent = `${node.title} (${node.node_id})`;
- button.dataset.nodeId = node.node_id;
- button.addEventListener("click", () => inspect(node, button));
- item.append(button);
- return item;
- }));
- const visibleEdges = edges.filter((edge) => ids.has(edge.source_id) && ids.has(edge.target_id));
- rows.replaceChildren(...visibleEdges.map((edge) => {
- const row = document.createElement("tr");
- [edge.source_id, edge.relation, edge.target_id].forEach((value) => {
- const cell = document.createElement("td");
- cell.textContent = value;
- row.append(cell);
- });
- return row;
- }));
- status.textContent = `${visible.length} nodes and ${visibleEdges.length} relationships `
- + `shown in ${mode.value} mode.`;
- };
- const inspect = (node, button) => {
- opener = button;
- detail.replaceChildren();
- const heading = document.createElement("h2");
- heading.id = "node-dialog-title";
- heading.textContent = node.title;
- const identity = document.createElement("p");
- identity.textContent = `${node.node_id} · ${node.family} · ${node.status}`;
- const summary = document.createElement("p");
- summary.textContent = node.summary;
- detail.append(heading, identity, summary);
- dialog.showModal();
- close.focus();
- };
- close.addEventListener("click", () => dialog.close());
- dialog.addEventListener("close", () => opener?.focus());
- filter.addEventListener("input", render);
- mode.addEventListener("change", render);
- render();
-})();
-""".strip()
-
-
-def _csp_hash(content: str) -> str:
- digest = hashlib.sha256(content.encode("utf-8")).digest()
- return base64.b64encode(digest).decode("ascii")
-
-
-def _embedded_json(value: object) -> str:
- return (
- json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
- .replace("&", "\\u0026")
- .replace("<", "\\u003c")
- .replace(">", "\\u003e")
- )
-
-
-def _static_node_markup(plan: dict[str, object]) -> str:
- graph = cast(dict[str, object], plan["graph"])
- nodes = cast(list[dict[str, object]], graph["nodes"])
- parts: list[str] = []
- for node in nodes:
- node_id = html.escape(cast(str, node["node_id"]))
- attribute_node_id = html.escape(cast(str, node["node_id"]), quote=True)
- title = html.escape(cast(str, node["title"]))
- family = html.escape(cast(str, node["family"]))
- status = html.escape(cast(str, node["status"]))
- summary = html.escape(cast(str, node["summary"]))
- parts.append(
- "
"
- f'"
- f'{family} · {status}
'
- f"{summary}
"
- ""
- )
- return "".join(parts)
-
-
-def _static_edge_markup(plan: dict[str, object]) -> str:
- graph = cast(dict[str, object], plan["graph"])
- edges = cast(list[dict[str, object]], graph["edges"])
- return "".join(
- "
"
- f"| {html.escape(cast(str, edge['source_id']))} | "
- f"{html.escape(cast(str, edge['relation']))} | "
- f"{html.escape(cast(str, edge['target_id']))} | "
- "
"
- for edge in edges
- )
-
-
-class PortableGraphHtmlRenderer:
- """Render a validated graph package without querying or publishing project state."""
-
- renderer_id = "portable_graph_html"
- renderer_version = "1"
-
- def render(self, package: ProjectionPackageV1) -> ProjectionRenderResult:
- started = perf_counter_ns()
- package = ProjectionPackageV1.from_dict(package.as_dict())
- document = package.document
- if package.kind != "graph":
- raise DocForgeError("invalid_projection", "Graph renderer requires a graph package")
- renderer = cast(dict[str, object], document["renderer"])
- if renderer != {
- "renderer_id": self.renderer_id,
- "renderer_version": self.renderer_version,
- }:
- raise DocForgeError("unsupported_renderer", "Graph renderer identity is incompatible")
- if document["components"] != [
- {"component_id": "graph.portable-document@1"},
- {"component_id": "graph.accessible-list@1"},
- {"component_id": "graph.relationship-table@1"},
- ]:
- raise DocForgeError(
- "invalid_projection",
- "Portable graph renderer component declarations are incompatible",
- )
- if document["assets"] != []:
- raise DocForgeError(
- "invalid_projection",
- "Portable graph renderer does not accept project-provided assets",
- )
- plan = cast(dict[str, object], document["plan"])
- view = cast(dict[str, object], plan["view"])
- initial_mode = view.get("initial_mode")
- policy = cast(dict[str, object], plan["policy"])
- if (
- initial_mode not in {"nodes", "flow", "web"}
- or policy.get("logic_requested") is not False
- ):
- raise DocForgeError(
- "unsupported_renderer",
- "Portable graph renderer version 1 does not render Logic projections",
- )
- title = html.escape(cast(str, view["title"]))
- project = cast(dict[str, object], plan["project"])
- embedded = _embedded_json(plan)
- static_nodes = _static_node_markup(plan)
- static_edges = _static_edge_markup(plan)
- csp = (
- "default-src 'none'; "
- f"style-src 'sha256-{_csp_hash(PORTABLE_GRAPH_CSS)}'; "
- f"script-src 'sha256-{_csp_hash(PORTABLE_GRAPH_JAVASCRIPT)}'; "
- "img-src 'none'; connect-src 'none'; object-src 'none'; base-uri 'none'; "
- "form-action 'none'; frame-ancestors 'none'"
- )
- output = (
- "\n"
- '\n'
- "\n"
- '
\n'
- '
\n'
- '
\n'
- f"
{title} · DocForge graph\n"
- f"\n"
- "\n"
- "\n"
- '
Skip to graph content\n'
- "
\n"
- f"{title}
\n"
- f'Generation {html.escape(cast(str, project["source_hash"]))}
\n'
- '\n'
- '\n'
- '\n"
- "
\n"
- '\n'
- "\n"
- f'
\n'
- '\n'
- '
\n'
- '
'
- 'Relationships
'
- "Selected graph facts"
- '| Source | Relation | '
- f'Target |
{static_edges}'
- "
"
- "\n"
- "
\n"
- '
\n'
- f'\n'
- f"\n"
- "\n"
- "\n"
- ).encode()
- policy = cast(dict[str, object], document["output_policy"])
- maximum = policy.get("max_total_bytes")
- if set(policy) != {"artifact_ids", "max_total_bytes"} or policy.get("artifact_ids") != [
- "portable-graph.html"
- ]:
- raise DocForgeError(
- "invalid_projection",
- "Portable graph output policy is incompatible",
- )
- if type(maximum) is not int or maximum < 1 or len(output) > maximum:
- raise DocForgeError("render_too_large", "Rendered output exceeds the configured limit")
- artifact = ProjectionArtifact(
- artifact_id="portable-graph.html",
- media_type="text/html; charset=utf-8",
- content=output,
- )
- receipt = ProjectionReceiptV1.create(
- kind="graph",
- package_id=package.package_id,
- plan_id=cast(str, document["plan_id"]),
- renderer=dict(renderer),
- artifacts=[artifact.evidence()],
- diagnostics={
- "warnings": [],
- },
- timing={"elapsed_ns": perf_counter_ns() - started},
- peak_memory_bytes=None,
- )
- return ProjectionRenderResult((artifact,), receipt)
diff --git a/src/docforge_renderers/manual.py b/src/docforge_renderers/manual.py
deleted file mode 100644
index e816919..0000000
--- a/src/docforge_renderers/manual.py
+++ /dev/null
@@ -1,264 +0,0 @@
-"""Plan-only renderer for the built-in DocForge manual artifact."""
-
-from __future__ import annotations
-
-import hashlib
-import html
-import re
-from time import perf_counter_ns
-from typing import cast
-
-from markdown_it import MarkdownIt
-
-from docforge.errors import DocForgeError
-from docforge.projection_contract import (
- ProjectionArtifact,
- ProjectionPackageV1,
- ProjectionReceiptV1,
- ProjectionRenderResult,
-)
-from docforge.projection_fragments import (
- FragmentRecord,
- fragment_semantic_hash,
-)
-
-_TEMPLATE_TOKEN = re.compile(r"{{\s*([a-z_][a-z0-9_]*)\s*}}")
-_ALLOWED_TOKENS = frozenset(
- {
- "docforge_content",
- "docforge_project_id",
- "docforge_render_identity",
- "docforge_title",
- "docforge_view_id",
- }
-)
-_ACTIVE_TEMPLATE_CONTENT = re.compile(
- r"<\s*(?:script|iframe|object|embed)\b"
- r"|\son[a-z0-9_-]+\s*="
- r"|javascript\s*:"
- r"|<\s*meta\b[^>]*\bhttp-equiv\s*=\s*[\"']?\s*refresh\b",
- re.IGNORECASE,
-)
-_MANUAL_PAGE_COMPONENT = "manual.page@1"
-
-
-class ManualHtmlRenderer:
- """Transform one validated path-free package without graph-selection authority."""
-
- renderer_id = "generic_html"
-
- def __init__(self, renderer_version: str) -> None:
- self.renderer_version = renderer_version
- self.markdown = MarkdownIt("commonmark", {"html": False, "typographer": False})
-
- def render(
- self,
- package: ProjectionPackageV1,
- *,
- render_identity: str | None = None,
- ) -> ProjectionRenderResult:
- started = perf_counter_ns()
- package = ProjectionPackageV1.from_dict(package.as_dict())
- document = package.document
- if package.kind != "manual":
- raise DocForgeError("invalid_projection", "Manual renderer requires a manual package")
- renderer = cast(dict[str, object], document["renderer"])
- if renderer != {
- "renderer_id": self.renderer_id,
- "renderer_version": self.renderer_version,
- }:
- raise DocForgeError("unsupported_renderer", "Manual renderer identity is incompatible")
- plan = cast(dict[str, object], document["plan"])
- assets = cast(list[object], document["assets"])
- if len(assets) not in {1, 2} or not isinstance(assets[0], dict):
- raise DocForgeError("invalid_projection", "Manual template asset is invalid")
- asset = cast(dict[str, object], assets[0])
- if (
- set(asset)
- not in (
- {"asset_id", "media_type", "sha256", "text"},
- {"asset_id", "media_type", "sha256", "text", "render_identity"},
- )
- or asset.get("asset_id") != "manual.template"
- or asset.get("media_type") != "text/html; charset=utf-8"
- or not isinstance(asset.get("text"), str)
- ):
- raise DocForgeError("invalid_projection", "Manual template asset is invalid")
- template = cast(str, asset["text"])
- template_bytes = template.encode("utf-8")
- if hashlib.sha256(template_bytes).hexdigest() != asset.get("sha256"):
- raise DocForgeError("invalid_projection", "Manual template asset hash is invalid")
- if _ACTIVE_TEMPLATE_CONTENT.search(template):
- raise DocForgeError(
- "invalid_template",
- "Render template contains active or executable content",
- )
- tokens = _TEMPLATE_TOKEN.findall(template)
- unknown = sorted(set(tokens) - _ALLOWED_TOKENS)
- remainder = _TEMPLATE_TOKEN.sub("", template)
- if unknown or "{{" in remainder or "}}" in remainder:
- raise DocForgeError(
- "invalid_template",
- "Render template contains unsupported tokens",
- tokens=unknown,
- )
- if tokens.count("docforge_content") != 1:
- raise DocForgeError(
- "invalid_template",
- "Render template must contain docforge_content exactly once",
- )
- packaged_identity = asset.get("render_identity")
- if packaged_identity is not None and (
- not isinstance(packaged_identity, str)
- or len(packaged_identity) != 64
- or any(character not in "0123456789abcdef" for character in packaged_identity)
- ):
- raise DocForgeError(
- "invalid_projection",
- "Manual render identity is invalid",
- )
- if render_identity is not None and packaged_identity not in {None, render_identity}:
- raise DocForgeError(
- "invalid_projection",
- "Manual render identity is inconsistent",
- )
- identity = render_identity or packaged_identity or cast(str, plan["plan_id"])
- fragments = self._fragments(plan, assets[1:] if len(assets) == 2 else [])
- project = cast(dict[str, object], plan["project"])
- view = cast(dict[str, object], plan["view"])
- replacements = {
- "docforge_content": self._content(plan, fragments),
- "docforge_project_id": html.escape(cast(str, project["project_id"]), quote=True),
- "docforge_render_identity": identity,
- "docforge_title": html.escape(cast(str, view["title"]), quote=True),
- "docforge_view_id": html.escape(cast(str, view["view_id"]), quote=True),
- }
- rendered = _TEMPLATE_TOKEN.sub(lambda match: replacements[match.group(1)], template)
- output = rendered.rstrip().encode("utf-8") + b"\n"
- policy = cast(dict[str, object], document["output_policy"])
- maximum = policy.get("max_total_bytes")
- if type(maximum) is not int or maximum < 1 or len(output) > maximum:
- raise DocForgeError("render_too_large", "Rendered output exceeds the configured limit")
- artifact = ProjectionArtifact(
- artifact_id="manual.html",
- media_type="text/html; charset=utf-8",
- content=output,
- )
- receipt = ProjectionReceiptV1.create(
- kind="manual",
- package_id=package.package_id,
- plan_id=cast(str, document["plan_id"]),
- renderer=dict(renderer),
- artifacts=[artifact.evidence()],
- diagnostics={"warnings": []},
- timing={"elapsed_ns": perf_counter_ns() - started},
- peak_memory_bytes=None,
- )
- return ProjectionRenderResult((artifact,), receipt)
-
- def _fragments(
- self,
- plan: dict[str, object],
- assets: list[object],
- ) -> dict[str, str]:
- if not assets:
- return {}
- asset = assets[0]
- if not isinstance(asset, dict):
- raise DocForgeError("invalid_projection", "Manual fragment asset is invalid")
- document = cast(dict[str, object], asset)
- if (
- set(document) != {"asset_id", "media_type", "records"}
- or document.get("asset_id") != "manual.fragments"
- or document.get("media_type") != "application/vnd.docforge.projection-fragments.v1+json"
- or not isinstance(document.get("records"), list)
- ):
- raise DocForgeError("invalid_projection", "Manual fragment asset is invalid")
- pages = cast(list[object], plan["pages"])
- records = cast(list[object], document["records"])
- if len(records) != len(pages):
- raise DocForgeError(
- "invalid_projection",
- "Manual fragment inventory is incomplete",
- )
- fragments: dict[str, str] = {}
- for page_value, record_value in zip(pages, records, strict=True):
- if not isinstance(page_value, dict):
- raise DocForgeError("invalid_projection", "Manual page is invalid")
- page = cast(dict[str, object], page_value)
- record = FragmentRecord.from_dict(record_value)
- if (
- record.key.projection_kind != "manual"
- or record.key.renderer_id != self.renderer_id
- or record.key.renderer_version != self.renderer_version
- or record.key.component_version != _MANUAL_PAGE_COMPONENT
- or record.key.semantic_input_hash != fragment_semantic_hash(page)
- ):
- raise DocForgeError(
- "invalid_projection",
- "Manual fragment identity does not match its page semantics",
- )
- try:
- fragment = record.content.decode("utf-8")
- except UnicodeDecodeError as error:
- raise DocForgeError(
- "invalid_projection",
- "Manual fragment content is not valid UTF-8",
- ) from error
- node_id = cast(str, page["node_id"])
- if node_id in fragments or fragment != self.render_page_fragment(page):
- raise DocForgeError(
- "invalid_projection",
- "Manual fragment content does not match its page semantics",
- )
- fragments[node_id] = fragment
- return fragments
-
- def render_page_fragment(self, page: dict[str, object]) -> str:
- """Render one page from complete plan semantics without project authority."""
-
- node_id = cast(str, page["node_id"])
- sections = [
- f'
',
- f"{html.escape(cast(str, page['title']))}
",
- '',
- f"- ID
- {html.escape(node_id)}
",
- f"- Family
- {html.escape(cast(str, page['family']))}
",
- f"- Status
- {html.escape(cast(str, page['status']))}
",
- f"- Authority
- {html.escape(cast(str, page['authority']))}
",
- "
",
- f'{html.escape(cast(str, page["summary"]))}
',
- self.markdown.render(cast(str, page["content"])).rstrip(),
- ]
- relationships = cast(list[object], page["cross_references"])
- if relationships:
- sections.append('')
- for relationship_value in relationships:
- relationship = cast(dict[str, object], relationship_value)
- sections.append(
- f"- {html.escape(cast(str, relationship['relation']))}: "
- f"{html.escape(cast(str, relationship['target_id']))}
"
- )
- sections.append("
")
- sections.append("")
- return "\n".join(sections)
-
- def _content(
- self,
- plan: dict[str, object],
- fragments: dict[str, str],
- ) -> str:
- navigation = ['
")
- sections = [*navigation]
- for value in cast(list[object], plan["pages"]):
- page = cast(dict[str, object], value)
- node_id = cast(str, page["node_id"])
- sections.append(fragments.get(node_id, self.render_page_fragment(page)))
- return "\n".join(sections)
diff --git a/src/docforge_renderers/py.typed b/src/docforge_renderers/py.typed
deleted file mode 100644
index e75b43f..0000000
--- a/src/docforge_renderers/py.typed
+++ /dev/null
@@ -1 +0,0 @@
-# PEP 561 marker for the typed DocForge renderer package.
diff --git a/tests/accessibility.spec.mjs b/tests/accessibility.spec.mjs
deleted file mode 100644
index 82f92c3..0000000
--- a/tests/accessibility.spec.mjs
+++ /dev/null
@@ -1,187 +0,0 @@
-import AxeBuilder from "@axe-core/playwright";
-import { expect, test } from "@playwright/test";
-import { spawn } from "node:child_process";
-import { createInterface } from "node:readline";
-
-const AXE_TAGS = [
- "wcag2a",
- "wcag2aa",
- "wcag21a",
- "wcag21aa",
- "wcag22a",
- "wcag22aa",
-];
-const MANUAL_AXE_TAGS = AXE_TAGS.filter((tag) => !tag.startsWith("wcag22"));
-
-let fixtureProcess;
-let surfaces;
-
-function startFixture() {
- const python = process.env.DOCFORGE_PYTHON || ".venv/bin/python";
- const child = spawn(python, ["tools/accessibility_fixture.py"], {
- cwd: process.cwd(),
- stdio: ["pipe", "pipe", "pipe"],
- });
- let stderr = "";
- child.stderr.setEncoding("utf8");
- child.stderr.on("data", (chunk) => {
- stderr += chunk;
- });
- const lines = createInterface({ input: child.stdout });
- const ready = new Promise((resolve, reject) => {
- let settled = false;
- lines.once("line", (line) => {
- settled = true;
- try {
- const payload = JSON.parse(line);
- if (
- payload.schema_version !== 1
- || typeof payload.manual_html !== "string"
- || typeof payload.portable_html !== "string"
- || typeof payload.live_url !== "string"
- ) {
- throw new Error("Accessibility fixture returned an invalid payload");
- }
- resolve(payload);
- } catch (error) {
- reject(error);
- } finally {
- lines.close();
- }
- });
- child.once("exit", (code, signal) => {
- if (!settled) {
- reject(
- new Error(
- `Accessibility fixture exited before readiness `
- + `(code=${code}, signal=${signal}):\n${stderr}`,
- ),
- );
- }
- });
- });
- return { child, ready };
-}
-
-async function stopFixture(child) {
- if (child.exitCode !== null || child.signalCode !== null) {
- return;
- }
- const exited = new Promise((resolve) => child.once("exit", resolve));
- child.stdin.end();
- await Promise.race([
- exited,
- new Promise((_, reject) => {
- setTimeout(() => reject(new Error("Accessibility fixture did not stop")), 5_000);
- }),
- ]);
-}
-
-function violationReport(violations) {
- return violations.map((violation) => {
- const targets = violation.nodes
- .flatMap((node) => node.target)
- .join(", ");
- return `${violation.id} (${violation.impact}): ${violation.help}\n ${targets}`;
- }).join("\n");
-}
-
-async function expectNoAxeViolations(page, tags = AXE_TAGS) {
- const results = await new AxeBuilder({ page }).withTags(tags).analyze();
- expect(results.violations, violationReport(results.violations)).toEqual([]);
-}
-
-async function tabTo(page, selector, maximumTabs = 40) {
- for (let count = 0; count < maximumTabs; count += 1) {
- await page.keyboard.press("Tab");
- if (await page.evaluate((target) => document.activeElement?.matches(target), selector)) {
- return page.locator(selector).filter({ visible: true }).first();
- }
- }
- throw new Error(`Keyboard focus did not reach ${selector}`);
-}
-
-test.beforeAll(async () => {
- const fixture = startFixture();
- fixtureProcess = fixture.child;
- surfaces = await fixture.ready;
-});
-
-test.afterAll(async () => {
- await stopFixture(fixtureProcess);
-});
-
-test("generated manual has no axe violations and its navigation works by keyboard", async ({
- page,
-}) => {
- await page.setContent(surfaces.manual_html, { waitUntil: "load" });
- await expect(page.locator("main section")).not.toHaveCount(0);
- // The generic renderer owns structure, while this frozen project template owns target sizing.
- await expectNoAxeViolations(page, MANUAL_AXE_TAGS);
-
- await page.keyboard.press("Tab");
- const firstNavigationLink = page.locator("nav[aria-label='Documentation'] a").first();
- await expect(firstNavigationLink).toBeFocused();
- const target = await firstNavigationLink.getAttribute("href");
- expect(target).toMatch(/^#[A-Za-z0-9_.-]+$/);
- await page.keyboard.press("Enter");
- await expect.poll(() => page.evaluate(() => window.location.hash)).toBe(target);
-});
-
-test("portable graph supports skip, filter, view, and dialog keyboard flows", async ({ page }) => {
- await page.goto("about:blank");
- await page.setContent(surfaces.portable_html, { waitUntil: "load" });
- await expect(page.locator("#status")).toContainText("nodes and");
- await expectNoAxeViolations(page);
-
- await page.keyboard.press("Tab");
- await expect(page.locator("a.skip")).toBeFocused();
- await page.keyboard.press("Enter");
- await expect(page.locator("main#main")).toBeFocused();
-
- await page.goto("about:blank");
- await page.setContent(surfaces.portable_html, { waitUntil: "load" });
- await page.keyboard.press("Tab");
- await page.keyboard.press("Tab");
- await expect(page.locator("#filter")).toBeFocused();
- await page.keyboard.type("guide.workflow");
- await expect(page.locator("#status")).toContainText("1 nodes and");
-
- await page.keyboard.press("Tab");
- await expect(page.locator("#mode")).toBeFocused();
- await page.keyboard.press("ArrowDown");
- await expect(page.locator("main#main")).toHaveAttribute("data-mode", "flow");
- await page.keyboard.press("ArrowUp");
- await expect(page.locator("main#main")).toHaveAttribute("data-mode", "nodes");
-
- await page.keyboard.press("Tab");
- const nodeButton = page.locator("#node-list button").first();
- await expect(nodeButton).toBeFocused();
- await page.keyboard.press("Enter");
- await expect(page.locator("#node-dialog")).toHaveAttribute("open", "");
- await expect(page.locator("#close-dialog")).toBeFocused();
- await expectNoAxeViolations(page);
- await page.keyboard.press("Escape");
- await expect(page.locator("#node-dialog")).not.toHaveAttribute("open", "");
- await expect(nodeButton).toBeFocused();
-});
-
-test("live viewer passes axe and exposes keyboard graph and resize controls", async ({ page }) => {
- await page.goto(surfaces.live_url);
- await expect(page.locator("#status")).toContainText("nodes ·");
- await expect(page.locator("#graph g.node[role='button']").first()).toBeVisible();
- await expectNoAxeViolations(page);
-
- const resizer = await tabTo(page, "#left-resizer");
- const originalWidth = Number(await resizer.getAttribute("aria-valuenow"));
- await page.keyboard.press("ArrowRight");
- await expect(resizer).toHaveAttribute("aria-valuenow", String(originalWidth + 16));
-
- await tabTo(page, "#graph g.node[role='button']");
- await page.keyboard.press("Shift+Enter");
- await expect(page.locator("#node-dialog")).toHaveAttribute("open", "");
- await expect(page.locator("#close-node-dialog")).toBeFocused();
- await expectNoAxeViolations(page);
- await page.keyboard.press("Escape");
- await expect(page.locator("#node-dialog")).not.toHaveAttribute("open", "");
-});
diff --git a/tests/test_cli.py b/tests/test_cli.py
index bd5a039..92e3cda 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -17,25 +17,6 @@ from docforge.viewer_manager import ViewerManager
ROOT = Path(__file__).resolve().parents[1]
FIXTURES = ROOT / "tests" / "fixtures"
-GRAPH_CONFIG = """
-
-[graph_render]
-output_root = ".docforge/portable-graph"
-
-[[graph_render.views]]
-id = "architecture"
-renderer = "portable_graph_html"
-output = "architecture.html"
-title = "Alpha architecture"
-root = "guide.workflow"
-initial_mode = "nodes"
-depth = 2
-max_nodes = 20
-max_edges = 40
-max_work = 1000
-include_logic = false
-"""
-
class DocForgeCliTests(unittest.TestCase):
def copy_fixture(self, destination: Path) -> Path:
@@ -153,30 +134,6 @@ class DocForgeCliTests(unittest.TestCase):
else:
os.environ["DOCFORGE_VIEWER_MANAGER_STATE"] = previous
- def test_portable_graph_plan_render_and_status_are_self_service(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- root = self.copy_fixture(Path(directory))
- descriptor = root / ".docforge/project.toml"
- descriptor.write_text(
- descriptor.read_text(encoding="utf-8") + GRAPH_CONFIG,
- encoding="utf-8",
- )
- parser = _parser()
- planned = _run(
- parser.parse_args(["--project-root", str(root), "graph-plan", "architecture"])
- )
- self.assertEqual("architecture", planned["view_id"])
- rendered = _run(
- parser.parse_args(["--project-root", str(root), "graph-render", "architecture"])
- )
- self.assertEqual("current", rendered["state"])
- status = _run(
- parser.parse_args(
- ["--project-root", str(root), "graph-render-status", "architecture"]
- )
- )
- self.assertEqual("current", status["state"])
-
if __name__ == "__main__":
unittest.main()
diff --git a/tests/test_client_integration.py b/tests/test_client_integration.py
index 539f089..778b96a 100644
--- a/tests/test_client_integration.py
+++ b/tests/test_client_integration.py
@@ -1,7 +1,6 @@
from __future__ import annotations
import contextlib
-import hashlib
import io
import json
import os
@@ -19,7 +18,6 @@ from jsonschema import Draft202012Validator
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
-from docforge.changeset_contract import document_hash
from docforge.cli import _parser, _run, main
from docforge.client_config import (
_read_existing,
@@ -41,19 +39,6 @@ CONFIGURATION_SCHEMA = json.loads(
DOCTOR_SCHEMA = json.loads((SCHEMAS / "doctor-result.schema.json").read_text(encoding="utf-8"))
POLICY_SCHEMA = json.loads((SCHEMAS / "policy.schema.json").read_text(encoding="utf-8"))
-GRAPH_RENDER_CONFIG = """
-
-[graph_render]
-output_root = ".docforge/portable-graph"
-
-[[graph_render.views]]
-id = "architecture"
-renderer = "portable_graph_html"
-output = "architecture.html"
-title = "Alpha architecture"
-root = "guide.workflow"
-"""
-
class ClientIntegrationTests(unittest.TestCase):
def copy_fixture(self, destination: Path) -> Path:
@@ -171,256 +156,6 @@ class ClientIntegrationTests(unittest.TestCase):
)
self.assertEqual("invalid_capability_binding", escalated.exception.code)
- def test_nondefault_projection_policy_selectors_serialize_and_validate(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- root = self.copy_fixture(Path(directory))
- descriptor = root / ".docforge" / "project.toml"
- descriptor.write_text(
- descriptor.read_text(encoding="utf-8") + GRAPH_RENDER_CONFIG,
- encoding="utf-8",
- )
- project = Project.open(root)
- expected_arguments = [
- "-I",
- "-m",
- "docforge.mcp_server",
- "--project-root",
- str(root),
- "--capability-mode",
- "read",
- "--manual-render-policy",
- "disabled",
- "--portable-graph-policy",
- "disabled",
- "--live-viewer-policy",
- "disabled",
- ]
- for client in ("codex", "claude", "openclaw"):
- with self.subTest(client=client):
- result = generate_client_configuration(
- project,
- client,
- manual_render_policy="disabled",
- portable_graph_policy="disabled",
- live_viewer_policy="disabled",
- )
- Draft202012Validator(CONFIGURATION_SCHEMA).validate(result)
- _validate_configuration_result(result)
- self.assertEqual(
- {
- "schema_version": 2,
- "manual": "disabled",
- "portable_graph": "disabled",
- "live_viewer": "disabled",
- },
- result["projection_policy"],
- )
- self.assertEqual(expected_arguments, result["binding"]["args"])
- content = result["artifact"]["content"]
- if client == "codex":
- document = tomllib.loads(content)
- serialized = document["mcp_servers"][result["server_name"]]["args"]
- elif client == "claude":
- document = json.loads(content)
- serialized = document["mcpServers"][result["server_name"]]["args"]
- else:
- document = json.loads(content)
- serialized = document["mcp"]["servers"][result["server_name"]]["args"]
- self.assertEqual(expected_arguments, serialized)
- canonical = json.dumps(
- result["projection_policy"],
- sort_keys=True,
- separators=(",", ":"),
- ensure_ascii=False,
- ).encode("utf-8")
- self.assertEqual(
- hashlib.sha256(canonical).hexdigest(),
- result["projection_policy_hash"],
- )
-
- def test_projection_policy_schema_and_configuration_validation_reject_drift(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- project = Project.open(self.copy_fixture(Path(directory)))
- result = generate_client_configuration(
- project,
- "codex",
- manual_render_policy="disabled",
- live_viewer_policy="disabled",
- )
- validator = Draft202012Validator(CONFIGURATION_SCHEMA)
- validator.validate(result)
- _validate_configuration_result(result)
-
- for field, value in (
- ("schema_version", 1),
- ("manual", "on-demand"),
- ("portable_graph", "auto"),
- ("live_viewer", "explicit"),
- ):
- with self.subTest(field=field):
- drifted = json.loads(json.dumps(result))
- drifted["projection_policy"][field] = value
- self.assertTrue(list(validator.iter_errors(drifted)))
-
- missing = json.loads(json.dumps(result))
- missing.pop("projection_policy")
- self.assertTrue(list(validator.iter_errors(missing)))
- extra = json.loads(json.dumps(result))
- extra["projection_policy"]["project_path"] = "/private/project"
- self.assertTrue(list(validator.iter_errors(extra)))
-
- mismatched = json.loads(json.dumps(result))
- mismatched["projection_policy"]["manual"] = "explicit"
- canonical = json.dumps(
- mismatched["projection_policy"],
- sort_keys=True,
- separators=(",", ":"),
- ensure_ascii=False,
- ).encode("utf-8")
- mismatched["projection_policy_hash"] = hashlib.sha256(canonical).hexdigest()
- with self.assertRaises(AssertionError):
- _validate_configuration_result(mismatched)
-
- bad_hash = json.loads(json.dumps(result))
- bad_hash["projection_policy_hash"] = "0" * 64
- with self.assertRaises(AssertionError):
- _validate_configuration_result(bad_hash)
-
- defaulted = generate_client_configuration(project, "codex")
- self.assertNotIn(
- "--manual-render-policy",
- defaulted["binding"]["args"],
- )
- defaulted["projection_policy"]["manual"] = "disabled"
- canonical = json.dumps(
- defaulted["projection_policy"],
- sort_keys=True,
- separators=(",", ":"),
- ensure_ascii=False,
- ).encode("utf-8")
- defaulted["projection_policy_hash"] = hashlib.sha256(canonical).hexdigest()
- with self.assertRaises(AssertionError):
- _validate_configuration_result(defaulted)
-
- unavailable = json.loads(json.dumps(result))
- unavailable["projection_availability"]["manual_configured"] = False
- with self.assertRaises(AssertionError):
- _validate_configuration_result(unavailable)
-
- descriptor = project.descriptor.descriptor_path
- descriptor.write_text(
- descriptor.read_text(encoding="utf-8") + GRAPH_RENDER_CONFIG,
- encoding="utf-8",
- )
- graph_project = Project.open(project.descriptor.root)
- graph_defaulted = generate_client_configuration(graph_project, "codex")
- self.assertNotIn(
- "--portable-graph-policy",
- graph_defaulted["binding"]["args"],
- )
- coordinated_graph_drift = json.loads(json.dumps(graph_defaulted))
- coordinated_graph_drift["projection_policy"]["portable_graph"] = "disabled"
- coordinated_graph_drift["projection_availability"]["portable_graph_configured"] = False
- canonical = json.dumps(
- coordinated_graph_drift["projection_policy"],
- sort_keys=True,
- separators=(",", ":"),
- ensure_ascii=False,
- ).encode("utf-8")
- coordinated_graph_drift["projection_policy_hash"] = hashlib.sha256(
- canonical
- ).hexdigest()
- coordinated_graph_drift["configuration_hash"] = document_hash(
- {
- "schema_version": 1,
- "client": coordinated_graph_drift["client"],
- "server_name": coordinated_graph_drift["server_name"],
- "project": coordinated_graph_drift["project"],
- "binding": coordinated_graph_drift["binding"],
- "effective_policy": coordinated_graph_drift["effective_policy"],
- "projection_policy": coordinated_graph_drift["projection_policy"],
- "projection_policy_hash": coordinated_graph_drift["projection_policy_hash"],
- "projection_availability": coordinated_graph_drift["projection_availability"],
- "artifact_format": coordinated_graph_drift["artifact"]["format"],
- "artifact_content_sha256": coordinated_graph_drift["artifact"][
- "content_sha256"
- ],
- }
- )
- with self.assertRaises(AssertionError):
- _validate_configuration_result(coordinated_graph_drift)
-
- invalid_selections = (
- {"manual_render_policy": "sometimes"},
- {"portable_graph_policy": "auto"},
- {"live_viewer_policy": "always"},
- )
- for selection in invalid_selections:
- with self.subTest(selection=selection):
- with self.assertRaises(DocForgeError) as raised:
- generate_client_configuration(graph_project, "codex", **selection)
- self.assertEqual("invalid_projection_policy", raised.exception.code)
-
- def test_doctor_round_trips_projection_selectors_and_rejects_invalid_modes(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- parent = Path(directory)
- project = Project.open(self.copy_fixture(parent))
- ProjectIndex(project).build()
- config = parent / "openclaw.json"
- generated = generate_client_configuration(
- project,
- "openclaw",
- manual_render_policy="disabled",
- live_viewer_policy="disabled",
- output=config,
- )
- healthy = run_doctor(
- project,
- "openclaw",
- config_path=config,
- server_name=generated["server_name"],
- )
- Draft202012Validator(DOCTOR_SCHEMA).validate(healthy)
- self.assertEqual("healthy", healthy["doctor_state"])
- self.assertIn(
- "effective_policy_valid",
- [check["code"] for check in healthy["checks"]],
- )
-
- document = json.loads(config.read_text(encoding="utf-8"))
- entry = document["mcp"]["servers"][generated["server_name"]]
- arguments = entry["args"]
- manual_position = arguments.index("--manual-render-policy") + 1
- arguments[manual_position] = "sometimes"
- config.write_text(json.dumps(document, sort_keys=True), encoding="utf-8")
- invalid = run_doctor(
- project,
- "openclaw",
- config_path=config,
- server_name=generated["server_name"],
- )
- Draft202012Validator(DOCTOR_SCHEMA).validate(invalid)
- self.assertEqual("unhealthy", invalid["doctor_state"])
- policy_check = next(
- check for check in invalid["checks"] if check["check_id"] == "policy.effective"
- )
- self.assertEqual("invalid_projection_policy", policy_check["code"])
-
- arguments[manual_position] = "auto"
- config.write_text(json.dumps(document, sort_keys=True), encoding="utf-8")
- unavailable = run_doctor(
- project,
- "openclaw",
- config_path=config,
- server_name=generated["server_name"],
- )
- Draft202012Validator(DOCTOR_SCHEMA).validate(unavailable)
- self.assertEqual("unhealthy", unavailable["doctor_state"])
- policy_check = next(
- check for check in unavailable["checks"] if check["check_id"] == "policy.effective"
- )
- self.assertEqual("projection_policy_unavailable", policy_check["code"])
-
def test_explicit_fragment_write_is_atomic_conflict_aware_and_private(self) -> None:
with tempfile.TemporaryDirectory() as directory:
parent = Path(directory)
diff --git a/tests/test_graph_projection.py b/tests/test_graph_projection.py
deleted file mode 100644
index d0b516a..0000000
--- a/tests/test_graph_projection.py
+++ /dev/null
@@ -1,404 +0,0 @@
-from __future__ import annotations
-
-import json
-import tempfile
-import unittest
-from dataclasses import replace
-from pathlib import Path
-from typing import Any, cast
-
-from docforge.errors import DocForgeError
-from docforge.graph_projection import (
- GraphViewRequestV1,
- build_graph_view_plan,
-)
-from docforge.models import Edge, Limits, Node, ProjectDescriptor, ProjectSnapshot
-from docforge.projection_contract import GraphViewPlanV1
-
-
-def _document(plan: GraphViewPlanV1) -> dict[str, Any]:
- return cast(dict[str, Any], plan.as_dict())
-
-
-def _node(
- node_id: str,
- *,
- title: str | None = None,
- family: str = "code",
- authority: str = "derived",
- status: str = "active",
- tags: tuple[str, ...] = (),
-) -> Node:
- return Node(
- node_id=node_id,
- title=title or node_id,
- family=family,
- authority=authority,
- status=status,
- tags=tags,
- summary=f"Summary for {node_id}",
- content=f"SECRET SOURCE BODY {node_id}",
- source_path=f"/private/source/{node_id}.py",
- source_anchor=f"line-{len(node_id)}",
- content_hash=(node_id.encode("utf-8").hex() + "0" * 64)[:64],
- )
-
-
-def _snapshot(
- root: Path,
- nodes: tuple[Node, ...],
- edges: tuple[Edge, ...],
-) -> ProjectSnapshot:
- descriptor = ProjectDescriptor(
- schema_version=1,
- project_id="graph-project",
- title="Graph project",
- adapter="generic",
- root=root,
- descriptor_path=root / ".docforge" / "project.toml",
- descriptor_hash="d" * 64,
- content_roots=(root / "docs",),
- authority_files=(),
- cache_root=root / ".docforge" / "cache",
- index_path=root / ".docforge" / "cache" / "index.sqlite3",
- changeset_root=root / ".docforge" / "changesets",
- proposal_writers=(),
- render=None,
- allowed_relations=tuple(sorted({edge.relation for edge in edges})),
- profiles=(),
- limits=Limits(),
- )
- return ProjectSnapshot(
- descriptor=descriptor,
- nodes=nodes,
- edges=edges,
- revision="revision-1",
- source_hash="a" * 64,
- )
-
-
-class GraphProjectionTests(unittest.TestCase):
- def test_exact_root_plan_is_deterministic_sorted_and_path_free(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- root = Path(directory)
- nodes = (
- _node("c", family="docs", tags=("python",)),
- _node("a", tags=("python", "callable")),
- _node("b", tags=("python",)),
- _node("unrelated"),
- )
- edges = (
- Edge("b", "calls", "c"),
- Edge("a", "calls", "b"),
- Edge("unrelated", "calls", "c"),
- )
- request = GraphViewRequestV1(
- view_id="architecture",
- title="Architecture",
- root_node_id="a",
- depth=2,
- max_nodes=10,
- max_edges=10,
- max_work=100,
- )
- first = build_graph_view_plan(_snapshot(root, nodes, edges), request, True)
- second = build_graph_view_plan(
- _snapshot(root, tuple(reversed(nodes)), tuple(reversed(edges))),
- request,
- True,
- )
- self.assertEqual(first.as_dict(), second.as_dict())
- GraphViewPlanV1.from_dict(first.as_dict())
- document = _document(first)
- self.assertEqual(
- ["a", "b", "c"], [node["node_id"] for node in document["graph"]["nodes"]]
- )
- self.assertEqual(
- [
- {"source_id": "a", "relation": "calls", "target_id": "b"},
- {"source_id": "b", "relation": "calls", "target_id": "c"},
- ],
- document["graph"]["edges"],
- )
- encoded = json.dumps(document, sort_keys=True)
- self.assertNotIn(str(root), encoded)
- self.assertNotIn("SECRET SOURCE BODY", encoded)
- self.assertNotIn("/private/source/", encoded)
- self.assertNotIn("line-1", encoded)
- self.assertEqual("excluded", document["policy"]["source_paths"])
- self.assertEqual("excluded", document["policy"]["source_bodies"])
- self.assertEqual("allowed", document["policy"]["logic"])
- self.assertEqual("exact_root", document["view"]["scope"]["kind"])
-
- def test_lexical_scope_uses_metadata_only_and_closed_filters(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- root = Path(directory)
- nodes = (
- _node(
- "api.handler",
- title="Request handler",
- family="code",
- authority="derived",
- tags=("python", "route"),
- ),
- _node(
- "api.test",
- title="Handler proof",
- family="test",
- authority="approved_plan",
- tags=("python", "test"),
- ),
- replace(
- _node("hidden.body", family="code", tags=("python",)),
- content="request handler appears only in the forbidden source body",
- ),
- )
- edges = (
- Edge("api.handler", "tested_by", "api.test"),
- Edge("hidden.body", "relates_to", "api.handler"),
- )
- request = GraphViewRequestV1(
- view_id="routes",
- title="Routes",
- query="request handler",
- families=("code",),
- authorities=("derived",),
- tags=("python", "route"),
- relations=("tested_by",),
- max_nodes=10,
- max_edges=10,
- max_work=100,
- )
- plan = build_graph_view_plan(_snapshot(root, nodes, edges), request, False)
- document = _document(plan)
- self.assertEqual(
- ["api.handler"],
- [node["node_id"] for node in document["graph"]["nodes"]],
- )
- self.assertEqual([], document["graph"]["edges"])
- self.assertEqual(
- {
- "families": ["code"],
- "relations": ["tested_by"],
- "authorities": ["derived"],
- "statuses": [],
- "tags": ["python", "route"],
- },
- document["view"]["filters"],
- )
- self.assertEqual("lexical", document["view"]["scope"]["kind"])
-
- def test_result_and_work_limits_emit_explicit_omissions(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- root = Path(directory)
- nodes = tuple(_node(value) for value in ("a", "b", "c", "d"))
- edges = (
- Edge("a", "calls", "b"),
- Edge("a", "calls", "c"),
- Edge("a", "calls", "d"),
- Edge("b", "calls", "c"),
- )
- result_limited = build_graph_view_plan(
- _snapshot(root, nodes, edges),
- GraphViewRequestV1(
- view_id="limited",
- title="Limited",
- root_node_id="a",
- max_nodes=2,
- max_edges=0,
- max_work=100,
- ),
- False,
- )
- result_limited = _document(result_limited)
- self.assertEqual(
- ["a", "b"], [node["node_id"] for node in result_limited["graph"]["nodes"]]
- )
- self.assertEqual([], result_limited["graph"]["edges"])
- self.assertEqual(
- ["edge_result_limit", "node_result_limit"],
- [item["code"] for item in result_limited["omissions"]],
- )
-
- work_limited = build_graph_view_plan(
- _snapshot(root, nodes, edges),
- GraphViewRequestV1(
- view_id="work",
- title="Work",
- root_node_id="a",
- max_nodes=10,
- max_edges=10,
- max_work=1,
- ),
- False,
- )
- work_limited = _document(work_limited)
- self.assertIn(
- "work_limit",
- [item["code"] for item in work_limited["omissions"]],
- )
- self.assertEqual(
- 1,
- work_limited["diagnostics"]["examined_work_units"],
- )
- self.assertTrue(work_limited["diagnostics"]["truncated"])
-
- def test_no_ast_policy_excludes_requested_logic(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- root = Path(directory)
- snapshot = _snapshot(root, (_node("a"),), ())
- request = GraphViewRequestV1(
- view_id="logic",
- title="Logic",
- root_node_id="a",
- initial_mode="logic",
- include_logic=True,
- )
- blocked = _document(build_graph_view_plan(snapshot, request, False))
- self.assertEqual("forbidden", blocked["policy"]["logic"])
- self.assertEqual([], blocked["graph"]["logic_projections"])
- self.assertIn(
- "logic_forbidden",
- [item["code"] for item in blocked["omissions"]],
- )
- allowed = _document(build_graph_view_plan(snapshot, request, True))
- self.assertEqual("allowed", allowed["policy"]["logic"])
- self.assertNotIn(
- "logic_forbidden",
- [item["code"] for item in allowed["omissions"]],
- )
-
- def test_edge_and_node_filters_constrain_exact_root_bfs(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- root = Path(directory)
- nodes = (
- _node("root", family="code", status="active"),
- _node("code-child", family="code", status="active"),
- _node("doc-child", family="docs", status="active"),
- _node("old-child", family="code", status="historical"),
- )
- edges = (
- Edge("root", "calls", "code-child"),
- Edge("root", "documents", "doc-child"),
- Edge("root", "calls", "old-child"),
- )
- plan = build_graph_view_plan(
- _snapshot(root, nodes, edges),
- GraphViewRequestV1(
- view_id="filtered",
- title="Filtered",
- root_node_id="root",
- families=("code",),
- statuses=("active",),
- relations=("calls",),
- max_work=100,
- ),
- False,
- )
- plan = _document(plan)
- self.assertEqual(
- ["code-child", "root"], [node["node_id"] for node in plan["graph"]["nodes"]]
- )
- self.assertEqual(
- [{"source_id": "root", "relation": "calls", "target_id": "code-child"}],
- plan["graph"]["edges"],
- )
-
- def test_invalid_requests_and_graphs_fail_closed(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- root = Path(directory)
- snapshot = _snapshot(root, (_node("a"),), ())
- invalid_requests = (
- GraphViewRequestV1(view_id="v", title="V"),
- GraphViewRequestV1(
- view_id="v",
- title="V",
- root_node_id="a",
- query="a",
- ),
- GraphViewRequestV1(
- view_id="v",
- title="V",
- root_node_id="a",
- max_nodes=0,
- ),
- GraphViewRequestV1(
- view_id="v",
- title="V",
- query="***",
- ),
- GraphViewRequestV1(
- view_id="v",
- title="V",
- root_node_id="a",
- families=("code", "code"),
- ),
- )
- for request in invalid_requests:
- with self.subTest(request=request), self.assertRaises(DocForgeError) as error:
- build_graph_view_plan(snapshot, request, False)
- self.assertEqual("invalid_graph_view_request", error.exception.code)
-
- with self.assertRaises(DocForgeError) as missing:
- build_graph_view_plan(
- snapshot,
- GraphViewRequestV1(
- view_id="v",
- title="V",
- root_node_id="missing",
- ),
- False,
- )
- self.assertEqual("missing_node", missing.exception.code)
-
- duplicate = _snapshot(root, (_node("a"), _node("a")), ())
- with self.assertRaises(DocForgeError) as invalid:
- build_graph_view_plan(
- duplicate,
- GraphViewRequestV1(
- view_id="v",
- title="V",
- root_node_id="a",
- ),
- False,
- )
- self.assertEqual("invalid_projection", invalid.exception.code)
-
- def test_plan_identity_changes_with_generation_request_and_policy(self) -> None:
- with tempfile.TemporaryDirectory() as directory:
- root = Path(directory)
- snapshot = _snapshot(root, (_node("a"),), ())
- request = GraphViewRequestV1(
- view_id="v",
- title="V",
- root_node_id="a",
- )
- base = build_graph_view_plan(snapshot, request, False)
- self.assertEqual(
- base.plan_id,
- build_graph_view_plan(snapshot, request, False).plan_id,
- )
- self.assertNotEqual(
- base.plan_id,
- build_graph_view_plan(
- replace(snapshot, source_hash="b" * 64),
- request,
- False,
- ).plan_id,
- )
- self.assertNotEqual(
- base.plan_id,
- build_graph_view_plan(
- snapshot,
- replace(request, title="Other"),
- False,
- ).plan_id,
- )
- self.assertNotEqual(
- base.plan_id,
- build_graph_view_plan(snapshot, request, True).plan_id,
- )
-
-
-if __name__ == "__main__":
- unittest.main()
diff --git a/tests/test_graph_publication.py b/tests/test_graph_publication.py
deleted file mode 100644
index 1d6d110..0000000
--- a/tests/test_graph_publication.py
+++ /dev/null
@@ -1,344 +0,0 @@
-from __future__ import annotations
-
-import json
-import shutil
-import tempfile
-import tomllib
-import unittest
-from pathlib import Path
-from unittest import mock
-
-from jsonschema import Draft202012Validator
-
-from docforge.errors import DocForgeError
-from docforge.graph_rendering import GraphRenderService
-from docforge.models import ProjectState
-from docforge.project import Project
-from docforge.projection_contract import projection_hash
-
-ROOT = Path(__file__).resolve().parents[1]
-FIXTURES = ROOT / "tests" / "fixtures"
-PROJECT_SCHEMA = json.loads((ROOT / "schemas/project.schema.json").read_text(encoding="utf-8"))
-
-GRAPH_CONFIG = """
-
-[graph_render]
-output_root = ".docforge/portable-graph"
-
-[[graph_render.views]]
-id = "architecture"
-renderer = "portable_graph_html"
-output = "architecture.html"
-title = "Alpha architecture"
-root = "guide.workflow"
-initial_mode = "nodes"
-depth = 2
-max_nodes = 20
-max_edges = 40
-max_work = 1000
-families = ["guide", "proof"]
-relations = ["depends_on", "proves"]
-authorities = []
-statuses = []
-tags = []
-include_logic = false
-"""
-
-
-class GraphPublicationTests(unittest.TestCase):
- def setUp(self) -> None:
- self.temporary = tempfile.TemporaryDirectory()
- self.addCleanup(self.temporary.cleanup)
- self.root = Path(self.temporary.name) / "alpha"
- shutil.copytree(FIXTURES / "alpha", self.root)
- descriptor = self.root / ".docforge/project.toml"
- descriptor.write_text(
- descriptor.read_text(encoding="utf-8") + GRAPH_CONFIG,
- encoding="utf-8",
- )
- self.project = Project.open(self.root)
- self.service = GraphRenderService(self.project)
-
- def test_descriptor_schema_and_runtime_accept_the_separate_graph_view(self) -> None:
- document = tomllib.loads((self.root / ".docforge/project.toml").read_text(encoding="utf-8"))
- Draft202012Validator(PROJECT_SCHEMA).validate(document)
- config = self.project.descriptor.graph_render
- assert config is not None
- self.assertEqual(self.root / ".docforge/portable-graph", config.output_root)
- self.assertEqual("architecture", config.views[0].view_id)
- self.assertEqual("guide.workflow", config.views[0].root_node_id)
- self.assertIsNone(config.views[0].query)
-
- def test_render_publication_is_deterministic_durable_and_unchanged_on_reuse(self) -> None:
- missing = self.service.status("architecture")
- self.assertEqual("stale", missing["state"])
- self.assertEqual("missing", missing["outputs"][0]["state"])
-
- first = self.service.render("architecture")
- output = self.root / ".docforge/portable-graph/architecture.html"
- manifest = self.root / ".docforge/cache/projection-publications/graph/architecture.json"
- artifact_root = self.root / ".docforge/cache/projection-artifacts"
- self.assertEqual("current", first["state"])
- self.assertEqual("published", first["publication"])
- self.assertTrue(output.is_file())
- self.assertTrue(manifest.is_file())
- self.assertEqual(1, len(tuple(artifact_root.glob("*.html"))))
- before = output.stat()
- before_bytes = output.read_bytes()
-
- current = self.service.status("architecture")
- self.assertEqual("current", current["state"])
- self.assertEqual("manifest", current["outputs"][0]["verification"])
- second = self.service.render("architecture")
- after = output.stat()
- self.assertEqual("unchanged", second["publication"])
- self.assertEqual(before_bytes, output.read_bytes())
- self.assertEqual((before.st_dev, before.st_ino), (after.st_dev, after.st_ino))
-
- def test_status_is_manifest_only_and_detects_source_output_and_manifest_changes(self) -> None:
- self.service.render("architecture")
- output = self.root / ".docforge/portable-graph/architecture.html"
- manifest = self.root / ".docforge/cache/projection-publications/graph/architecture.json"
- with mock.patch.object(
- self.project,
- "load",
- side_effect=AssertionError("status must not load or plan"),
- ):
- self.assertEqual("current", self.service.status("architecture")["state"])
-
- output.write_bytes(output.read_bytes() + b"\n")
- changed_output = self.service.status("architecture")
- self.assertEqual("stale", changed_output["state"])
- self.assertEqual("output_changed", changed_output["outputs"][0]["reason"])
-
- self.service.render("architecture")
- source = self.root / "docs/content/workflow.md"
- source.write_text(
- source.read_text(encoding="utf-8") + "\nChanged after publication.\n",
- encoding="utf-8",
- )
- changed_source = self.service.status("architecture")
- self.assertEqual("stale", changed_source["state"])
- self.assertEqual("stale", changed_source["outputs"][0]["state"])
- self.assertEqual(
- "source_generation_changed",
- changed_source["outputs"][0]["reason"],
- )
-
- self.service.render("architecture")
- manifest.write_text("{bad-json", encoding="utf-8")
- corrupt = self.service.status("architecture")
- self.assertEqual("missing", corrupt["outputs"][0]["state"])
-
- def test_status_validates_nested_manifest_and_artifact_store_evidence(self) -> None:
- self.service.render("architecture")
- manifest_path = (
- self.root / ".docforge/cache/projection-publications/graph/architecture.json"
- )
- original = json.loads(manifest_path.read_text(encoding="utf-8"))
- mutations = {
- "bad_project": lambda value: value.__setitem__("project", "bad"),
- "forged_artifact": lambda value: value.__setitem__(
- "artifact",
- {
- "artifact_id": "portable-graph.html",
- "media_type": "text/html; charset=utf-8",
- "sha256": "0" * 64,
- "bytes": 1,
- },
- ),
- "bad_store": lambda value: value["store"].__setitem__("size", -1),
- }
- for name, mutate in mutations.items():
- with self.subTest(name=name):
- value = json.loads(json.dumps(original))
- mutate(value)
- value.pop("publication_id")
- value["publication_id"] = projection_hash(value)
- manifest_path.write_text(
- json.dumps(value, sort_keys=True, indent=2) + "\n",
- encoding="utf-8",
- )
- status = self.service.status("architecture")
- self.assertEqual("unverified", status["outputs"][0]["state"])
- self.assertEqual("manifest_invalid", status["outputs"][0]["reason"])
- manifest_path.write_text(
- json.dumps(original, sort_keys=True, indent=2) + "\n",
- encoding="utf-8",
- )
-
- artifact = next((self.root / ".docforge/cache/projection-artifacts").glob("*.html"))
- artifact.unlink()
- missing = self.service.status("architecture")
- self.assertEqual("stale", missing["outputs"][0]["state"])
- self.assertEqual("artifact_store_missing", missing["outputs"][0]["reason"])
- repaired = self.service.render("architecture")
- self.assertEqual("current", repaired["state"])
- self.assertTrue(artifact.is_file())
-
- def test_status_detects_source_and_publication_races(self) -> None:
- self.service.render("architecture")
- current = self.project.incremental_state()
- assert current is not None
- changed = ProjectState(source_hash="0" * 64, revision="changed")
- with mock.patch.object(
- self.project,
- "incremental_state",
- side_effect=(current, changed),
- ):
- raced_source = self.service.status("architecture")
- self.assertEqual("stale", raced_source["state"])
- self.assertEqual(
- "source_changed_during_status",
- raced_source["outputs"][0]["reason"],
- )
-
- baseline = self.service._manifest_status(
- self.project.descriptor.graph_render.views[0], # type: ignore[union-attr]
- current,
- )
- replaced = dict(baseline)
- replaced["publication_id"] = "f" * 64
- with mock.patch.object(
- self.service,
- "_manifest_status",
- side_effect=(baseline, replaced),
- ):
- raced_publication = self.service.status("architecture")
- self.assertEqual("stale", raced_publication["state"])
- self.assertEqual(
- "publication_changed_during_status",
- raced_publication["outputs"][0]["reason"],
- )
-
- def test_manifest_failure_after_output_is_degraded_success(self) -> None:
- with mock.patch.object(
- self.service,
- "_publish_manifest",
- side_effect=DocForgeError(
- "publication_failure",
- "Synthetic manifest failure",
- ),
- ):
- result = self.service.render("architecture")
- self.assertEqual("degraded", result["state"])
- self.assertEqual("published", result["publication"])
- self.assertEqual("manifest", result["committed_stage"])
- self.assertTrue((self.root / ".docforge/portable-graph/architecture.html").is_file())
- self.assertEqual("failed", result["manifest"]["state"])
-
- def test_post_commit_stage_failures_are_degraded_and_precommit_failures_raise(self) -> None:
- committed = DocForgeError(
- "publication_failure",
- "Synthetic committed failure",
- mutation_committed=True,
- )
- cases = (
- ("_publish_artifact", "artifact_store", "partial", False),
- ("_publish_output", "output", "published", None),
- )
- for method, stage, publication, output_exists in cases:
- with self.subTest(method=method):
- root = Path(self.temporary.name) / method
- shutil.copytree(FIXTURES / "alpha", root)
- descriptor = root / ".docforge/project.toml"
- descriptor.write_text(
- descriptor.read_text(encoding="utf-8") + GRAPH_CONFIG,
- encoding="utf-8",
- )
- service = GraphRenderService(Project.open(root))
- with mock.patch.object(service, method, side_effect=committed):
- result = service.render("architecture")
- self.assertEqual("degraded", result["state"])
- self.assertEqual(stage, result["committed_stage"])
- self.assertEqual(publication, result["publication"])
- if output_exists is not None:
- self.assertEqual(
- output_exists,
- (root / ".docforge/portable-graph/architecture.html").exists(),
- )
-
- uncommitted = DocForgeError(
- "publication_failure",
- "Synthetic precommit failure",
- mutation_committed=False,
- )
- with (
- mock.patch.object(
- self.service,
- "_publish_output",
- side_effect=uncommitted,
- ),
- self.assertRaises(DocForgeError),
- ):
- self.service.render("architecture")
-
- def test_configuration_rejects_unsafe_ambiguous_and_overlapping_views(self) -> None:
- cases = {
- "both_scope": GRAPH_CONFIG.replace(
- 'root = "guide.workflow"',
- 'root = "guide.workflow"\nquery = "workflow"',
- ),
- "output_overlap": GRAPH_CONFIG.replace(
- 'output_root = ".docforge/portable-graph"',
- 'output_root = "docs/content"',
- ),
- "active_renderer": GRAPH_CONFIG.replace(
- 'renderer = "portable_graph_html"',
- 'renderer = "shell"',
- ),
- "oversized": GRAPH_CONFIG.replace("max_nodes = 20", "max_nodes = 100000"),
- "logic_mode": GRAPH_CONFIG.replace('initial_mode = "nodes"', 'initial_mode = "logic"'),
- "logic_projection": GRAPH_CONFIG.replace(
- "include_logic = false",
- "include_logic = true",
- ),
- "long_title": GRAPH_CONFIG.replace(
- 'title = "Alpha architecture"',
- f'title = "{"x" * 1025}"',
- ),
- "long_query": GRAPH_CONFIG.replace(
- 'root = "guide.workflow"',
- f'query = "{"x" * 10001}"',
- ),
- "too_many_filters": GRAPH_CONFIG.replace(
- 'families = ["guide", "proof"]',
- "families = [" + ", ".join(f'"family-{index}"' for index in range(65)) + "]",
- ),
- }
- for name, graph_config in cases.items():
- with self.subTest(name=name):
- root = Path(self.temporary.name) / name
- shutil.copytree(FIXTURES / "alpha", root)
- descriptor = root / ".docforge/project.toml"
- descriptor.write_text(
- descriptor.read_text(encoding="utf-8") + graph_config,
- encoding="utf-8",
- )
- parsed = tomllib.loads(descriptor.read_text(encoding="utf-8"))
- if name != "output_overlap":
- self.assertFalse(Draft202012Validator(PROJECT_SCHEMA).is_valid(parsed))
- with self.assertRaises(DocForgeError):
- Project.open(root)
-
- relocated = Path(self.temporary.name) / "descriptor-overlap"
- shutil.copytree(FIXTURES / "alpha", relocated)
- descriptor = relocated / ".docforge/project.toml"
- base = descriptor.read_text(encoding="utf-8").replace(
- 'cache_root = ".docforge/cache"\nindex = ".docforge/cache/index.sqlite3"',
- 'cache_root = "var/cache"\nindex = "var/cache/index.sqlite3"',
- )
- descriptor.write_text(
- base
- + GRAPH_CONFIG.replace(
- 'output_root = ".docforge/portable-graph"',
- 'output_root = ".docforge"',
- ),
- encoding="utf-8",
- )
- with self.assertRaises(DocForgeError):
- Project.open(relocated)
-
-
-if __name__ == "__main__":
- unittest.main()
diff --git a/tests/test_graph_rendering.py b/tests/test_graph_rendering.py
deleted file mode 100644
index bdb4831..0000000
--- a/tests/test_graph_rendering.py
+++ /dev/null
@@ -1,284 +0,0 @@
-from __future__ import annotations
-
-import copy
-import hashlib
-import json
-import os
-import shutil
-import sqlite3
-import tempfile
-import unittest
-from pathlib import Path
-from typing import cast
-from unittest import mock
-
-from docforge.errors import DocForgeError
-from docforge.graph_projection import (
- GraphViewRequestV1,
- build_graph_projection_package,
- build_graph_view_plan,
-)
-from docforge.project import Project
-from docforge.projection_contract import ProjectionPackageV1
-from docforge_renderers.graph import PortableGraphHtmlRenderer
-
-ROOT = Path(__file__).resolve().parents[1]
-FIXTURES = ROOT / "tests" / "fixtures"
-
-
-class PortableGraphRenderingTests(unittest.TestCase):
- def setUp(self) -> None:
- self.temporary = tempfile.TemporaryDirectory()
- self.addCleanup(self.temporary.cleanup)
- self.root = Path(self.temporary.name) / "alpha"
- shutil.copytree(FIXTURES / "alpha", self.root)
- self.project = Project.open(self.root)
- self.snapshot = self.project.load()
- self.request = GraphViewRequestV1(
- view_id="architecture",
- title="Alpha architecture",
- root_node_id="guide.workflow",
- depth=2,
- max_nodes=20,
- max_edges=40,
- max_work=1_000,
- )
- self.plan = build_graph_view_plan(self.snapshot, self.request, False)
- self.package = build_graph_projection_package(
- self.plan,
- renderer_id=PortableGraphHtmlRenderer.renderer_id,
- renderer_version=PortableGraphHtmlRenderer.renderer_version,
- max_output_bytes=1_000_000,
- )
-
- def test_portable_artifact_is_deterministic_self_contained_and_generation_bound(self) -> None:
- renderer = PortableGraphHtmlRenderer()
- first = renderer.render(self.package)
- second = renderer.render(self.package)
- self.assertEqual(first.artifacts, second.artifacts)
- self.assertEqual(1, len(first.artifacts))
- artifact = first.artifacts[0]
- self.assertEqual("portable-graph.html", artifact.artifact_id)
- self.assertEqual("text/html; charset=utf-8", artifact.media_type)
- receipt = first.receipt.as_dict()
- evidence = cast(list[dict[str, object]], receipt["artifacts"])
- self.assertEqual(
- hashlib.sha256(artifact.content).hexdigest(),
- evidence[0]["sha256"],
- )
- rendered = artifact.content.decode("utf-8")
- self.assertIn("Content-Security-Policy", rendered)
- self.assertIn("default-src 'none'", rendered)
- self.assertIn('type="application/json"', rendered)
- self.assertNotIn(str(self.root), rendered)
- self.assertNotIn("docs/content/", rendered)
- self.assertNotIn("Editors change canonical nodes", rendered)
- self.assertNotIn("fetch(", rendered)
- self.assertNotIn("XMLHttpRequest", rendered)
- self.assertNotIn("WebSocket", rendered)
- self.assertIn(self.snapshot.source_hash, rendered)
-
- def test_embedded_plan_is_exact_and_script_breakout_is_inert(self) -> None:
- plan = copy.deepcopy(self.plan.as_dict())
- view = plan["view"]
- assert isinstance(view, dict)
- view["title"] = ''
- plan.pop("plan_id")
- from docforge.projection_contract import GraphViewPlanV1
-
- malicious = GraphViewPlanV1.create(plan)
- package = build_graph_projection_package(
- malicious,
- renderer_id=PortableGraphHtmlRenderer.renderer_id,
- renderer_version=PortableGraphHtmlRenderer.renderer_version,
- max_output_bytes=1_000_000,
- )
- rendered = PortableGraphHtmlRenderer().render(package).artifacts[0].content.decode("utf-8")
- self.assertNotIn('", 1)[0]
- self.assertEqual(malicious.as_dict(), json.loads(embedded))
-
- def test_renderer_has_no_project_database_or_filesystem_write_capability(self) -> None:
- forbidden = AssertionError("portable graph renderer crossed its capability boundary")
- with (
- mock.patch.object(Project, "open", side_effect=forbidden),
- mock.patch.object(Project, "load", side_effect=forbidden),
- mock.patch.object(sqlite3, "connect", side_effect=forbidden),
- mock.patch.object(Path, "write_bytes", side_effect=forbidden),
- mock.patch.object(Path, "write_text", side_effect=forbidden),
- mock.patch.object(Path, "mkdir", side_effect=forbidden),
- mock.patch.object(os, "replace", side_effect=forbidden),
- mock.patch.object(os, "rename", side_effect=forbidden),
- mock.patch.object(os, "unlink", side_effect=forbidden),
- ):
- result = PortableGraphHtmlRenderer().render(self.package)
- self.assertEqual(1, len(result.artifacts))
-
- def test_renderer_rejects_wrong_kind_identity_assets_and_size(self) -> None:
- wrong = ProjectionPackageV1.create(
- kind="graph",
- plan=self.plan,
- renderer={
- "renderer_id": PortableGraphHtmlRenderer.renderer_id,
- "renderer_version": "other",
- },
- components=[],
- assets=[],
- output_policy={
- "artifact_ids": ["portable-graph.html"],
- "max_total_bytes": 1_000_000,
- },
- )
- with self.assertRaises(DocForgeError) as unsupported:
- PortableGraphHtmlRenderer().render(wrong)
- self.assertEqual("unsupported_renderer", unsupported.exception.code)
-
- with_asset = ProjectionPackageV1.create(
- kind="graph",
- plan=self.plan,
- renderer={
- "renderer_id": PortableGraphHtmlRenderer.renderer_id,
- "renderer_version": PortableGraphHtmlRenderer.renderer_version,
- },
- components=[],
- assets=[
- {
- "asset_id": "project-script",
- "media_type": "text/javascript",
- "sha256": "0" * 64,
- "text": "alert(1)",
- }
- ],
- output_policy={"artifact_ids": ["portable-graph.html"], "max_total_bytes": 1_000_000},
- )
- with self.assertRaises(DocForgeError) as assets:
- PortableGraphHtmlRenderer().render(with_asset)
- self.assertEqual("invalid_projection", assets.exception.code)
-
- wrong_components = ProjectionPackageV1.create(
- kind="graph",
- plan=self.plan,
- renderer={
- "renderer_id": PortableGraphHtmlRenderer.renderer_id,
- "renderer_version": PortableGraphHtmlRenderer.renderer_version,
- },
- components=[],
- assets=[],
- output_policy={
- "artifact_ids": ["portable-graph.html"],
- "max_total_bytes": 1_000_000,
- },
- )
- with self.assertRaises(DocForgeError) as components:
- PortableGraphHtmlRenderer().render(wrong_components)
- self.assertEqual("invalid_projection", components.exception.code)
-
- wrong_artifact = ProjectionPackageV1.create(
- kind="graph",
- plan=self.plan,
- renderer={
- "renderer_id": PortableGraphHtmlRenderer.renderer_id,
- "renderer_version": PortableGraphHtmlRenderer.renderer_version,
- },
- components=self.package.document["components"], # type: ignore[arg-type]
- assets=[],
- output_policy={
- "artifact_ids": ["unexpected.html"],
- "max_total_bytes": 1_000_000,
- },
- )
- with self.assertRaises(DocForgeError) as artifact:
- PortableGraphHtmlRenderer().render(wrong_artifact)
- self.assertEqual("invalid_projection", artifact.exception.code)
-
- tiny = build_graph_projection_package(
- self.plan,
- renderer_id=PortableGraphHtmlRenderer.renderer_id,
- renderer_version=PortableGraphHtmlRenderer.renderer_version,
- max_output_bytes=1,
- )
- with self.assertRaises(DocForgeError) as too_large:
- PortableGraphHtmlRenderer().render(tiny)
- self.assertEqual("render_too_large", too_large.exception.code)
-
- def test_initial_mode_is_honored_and_logic_is_rejected(self) -> None:
- for mode in ("nodes", "flow", "web"):
- with self.subTest(mode=mode):
- plan = build_graph_view_plan(
- self.snapshot,
- GraphViewRequestV1(
- view_id=f"{mode}-view",
- title=f"{mode.title()} view",
- root_node_id="guide.workflow",
- initial_mode=mode, # type: ignore[arg-type]
- depth=2,
- max_nodes=20,
- max_edges=40,
- max_work=1_000,
- ),
- False,
- )
- package = build_graph_projection_package(
- plan,
- renderer_id=PortableGraphHtmlRenderer.renderer_id,
- renderer_version=PortableGraphHtmlRenderer.renderer_version,
- max_output_bytes=1_000_000,
- )
- rendered = (
- PortableGraphHtmlRenderer().render(package).artifacts[0].content.decode("utf-8")
- )
- self.assertIn(f'data-mode="{mode}"', rendered)
- self.assertIn(f'