sphinx-traceability-view 1.0.0__py3-none-any.whl

sphinx_traceability_view/__init__.py

@@ -0,0 +1,3 @@
+"""Public Sphinx extension entry point; implementation belongs to directive."""
+from .directive import setup
+from ._version import __version__

sphinx_traceability_view/_version.py

@@ -0,0 +1,2 @@
+"""Canonical development/package version; change only this file for version updates."""
+__version__ = "1.0.0"

sphinx_traceability_view/bundle/__init__.py

@@ -0,0 +1,39 @@
+"""Content-addressed classic scripts, committed only after complete extraction."""
+import hashlib
+import json
+import os
+
+
+def encoded(value):
+    return json.dumps(value, ensure_ascii=True, sort_keys=True, separators=(",", ":")).replace("<", "\\u003c")
+
+
+def digest(value):
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def atomic(path, value):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(value, encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def emit(graph, fragments, output):
+    graph = dict(graph, details={})
+    files = {}
+    for identity, fragment in fragments.items():
+        content_hash = digest(fragment)
+        name = f"_static/stv/details/{content_hash}.js"
+        graph["details"][identity] = {"url": name, "digest": content_hash}
+        files[name] = 'globalThis.__STV_DATA__ ||= {graphs:{},fragments:{}};globalThis.__STV_DATA__.fragments[' + encoded(content_hash) + '] = ' + encoded(fragment) + ';'
+    identity = digest(encoded(graph))
+    graph["identity"] = identity
+    name = f"_static/stv/graph-{identity}.js"
+    # JSON.parse preserves data keys such as __proto__; object-literal source
+    # would interpret that key as a prototype assignment. Null dictionaries
+    # also prevent missing IDs such as "constructor" resolving through inheritance.
+    files[name] = 'globalThis.__STV_DATA__ ||= {graphs:{},fragments:{}};globalThis.__STV_DATA__.graphs[' + encoded(identity) + '] = JSON.parse(' + encoded(encoded(graph)) + ',(_,v)=>v&&typeof v==="object"&&!Array.isArray(v)?Object.assign(Object.create(null),v):v);'
+    for relative, content in files.items():
+        atomic(output / relative, content)
+    return identity, name

sphinx_traceability_view/detail_build/__init__.py

@@ -0,0 +1,148 @@
+"""Extract static host markup and make local resources portable."""
+from copy import copy
+from html import escape
+import posixpath
+import re
+from urllib.parse import urlsplit, urlunsplit, unquote
+from bs4 import BeautifulSoup
+
+
+def static_css(css, page):
+    resources = []
+    def url(match):
+        raw = match.group(1).strip().strip('\"\'')
+        target = portable_url(raw, page)
+        parsed = urlsplit(target or "")
+        if target and (parsed.netloc or parsed.scheme in ("http", "https")):
+            resources.append(target)
+            return "none"
+        if not target or parsed.scheme not in ("", "data"):
+            return "none"
+        if parsed.scheme == "data" and not target.lower().startswith(("data:image/png", "data:image/jpeg", "data:image/gif", "data:image/webp")):
+            return "none"
+        return 'url("' + target.replace('"', '%22') + '")'
+    def imported(match):
+        targets = re.findall(r'(?:url\(\s*)?[\"\']([^\"\']+)[\"\']', match.group())
+        resources.extend(target for value in targets if (target := portable_url(value, page)))
+        return ""
+    css = re.sub(r'@import\s+[^;]+;?', imported, css, flags=re.I)
+    return re.sub(r'url\(\s*([^)]*)\)', url, css, flags=re.I), resources
+
+
+def portable_url(value, page):
+    parsed = urlsplit(value.strip())
+    if parsed.scheme.lower() not in ("", "http", "https", "mailto", "tel", "data"):
+        return None
+    if parsed.scheme or parsed.netloc:
+        return value
+    path = posixpath.normpath(posixpath.join(posixpath.dirname(page), parsed.path)) if parsed.path else page
+    if path.startswith("../") or path.startswith("/"):
+        return None
+    return urlunsplit(("", "", path, parsed.query, parsed.fragment))
+
+
+def transform(markup, page, hidden, relation_names=()):
+    soup = BeautifulSoup(markup, "html.parser")
+    relation_names = set(relation_names)
+    for tag in list(soup.find_all(True)):
+        if tag.parent is None:
+            continue
+        if tag.name in ("script", "iframe", "object", "embed", "link", "base", "form", "meta"):
+            source = tag.get("src") or tag.get("data") or tag.get("href")
+            source = portable_url(source, page) if source else None
+            if source and urlsplit(source).scheme == "data":
+                source = None
+            if source:
+                placeholder = soup.new_tag("span")
+                placeholder.string = "Embedded resource unavailable offline. "
+                link = soup.new_tag("a", href=source)
+                if not urlsplit(source).scheme and not urlsplit(source).netloc:
+                    link["data-stv-href"] = source
+                link.string = "Original resource"
+                placeholder.append(link)
+                tag.replace_with(placeholder)
+            else:
+                tag.decompose()
+            continue
+        if tag.name == "a" and hidden and unquote(urlsplit(tag.get("href", "")).fragment) in hidden:
+            relationship_reference = any(set(parent.get("class", [])) & relation_names
+                                         for parent in tag.parents if parent.name)
+            if relationship_reference:
+                tag.decompose()
+                continue
+        for attr in list(tag.attrs):
+            if attr.lower().startswith(("on", "data-stv-")):
+                del tag[attr]
+        resources = []
+        for attr in ("href", "xlink:href", "src", "poster"):
+            if attr not in tag.attrs:
+                continue
+            value = portable_url(tag[attr], page)
+            parsed = urlsplit(value or "")
+            embedded = attr != "href" or tag.name != "a"
+            if value is None or (parsed.scheme == "data" and not (embedded and value.lower().startswith(("data:image/png", "data:image/jpeg", "data:image/gif", "data:image/webp")))):
+                del tag[attr]
+            elif embedded and (parsed.netloc or parsed.scheme in ("http", "https")):
+                resources.append(value)
+                del tag[attr]
+            else:
+                tag[attr] = value
+                if not parsed.scheme and not parsed.netloc:
+                    tag[f"data-stv-{attr.replace(':', '-')}"] = value
+        if tag.has_attr("srcset"):
+            value = tag["srcset"]
+            del tag["srcset"]
+            sources = []
+            candidates = re.finditer(r'\s*(data:[^\s]+|[^,\s]+)(?:\s+([0-9.]+[wx]))?\s*(?:,|$)', value)
+            for candidate in candidates:
+                url = portable_url(candidate[1].rstrip(','), page)
+                descriptor = candidate[2] or ""
+                permitted_data = url and url.lower().startswith(("data:image/png", "data:image/jpeg", "data:image/gif", "data:image/webp"))
+                if url and ((not urlsplit(url).scheme and not urlsplit(url).netloc) or permitted_data):
+                    sources.append((url + " " + descriptor).strip())
+                elif url:
+                    resources.append(url)
+            if sources:
+                tag["data-stv-srcset"] = ", ".join(sources)
+        if tag.has_attr("style") or tag.name == "style":
+            text = tag.get("style", "") if tag.name != "style" else tag.get_text()
+            css, css_resources = static_css(text, page)
+            resources.extend(css_resources)
+            if tag.name == "style":
+                tag.string = css
+                tag["data-stv-css"] = css
+            else:
+                tag["style"] = css
+                tag["data-stv-style"] = css
+        for url in resources:
+            note = soup.new_tag("span", attrs={"class": "stv-unavailable"})
+            note.string = "Resource unavailable offline. "
+            link = soup.new_tag("a", href=url)
+            if not urlsplit(url).scheme and not urlsplit(url).netloc:
+                link["data-stv-href"] = url
+            link.string = "Original resource"
+            note.append(link)
+            tag.insert_after(note)
+    return str(soup)
+
+
+def extract(graph, output, hidden):
+    pages = {}
+    fragments = {}
+    for identity, obj in graph["objects"].items():
+        if obj["external"]:
+            fields = "".join(f"<dt>{escape(k)}</dt><dd>{escape(str(v))}</dd>" for k, v in obj.get("metadata", obj).items() if v is not None)
+            fragments[identity] = f'<div><p>External object: full body unavailable offline.</p><dl>{fields}</dl></div>'
+            continue
+        page = urlsplit(obj["url"]).path
+        if page not in pages:
+            path = (output / page).resolve()
+            if not path.is_relative_to(output.resolve()):
+                raise ValueError(f"Object page escapes output directory: {page}")
+            soup = BeautifulSoup(path.read_text(encoding="utf-8"), "html.parser")
+            pages[page] = {tag["id"]: tag for tag in soup.find_all(id=True)}
+        original = pages[page].get(obj["parent"] or identity)
+        if original is None:
+            raise ValueError(f"Rendered Need {identity!r} missing in {page}")
+        fragments[identity] = transform(str(copy(original)), page, hidden, graph["model"]["relations"])
+    return fragments

sphinx_traceability_view/directive/__init__.py

@@ -0,0 +1,2 @@
+"""STV_SWE_DIRECTIVE: Sphinx lifecycle and directive integration."""
+from .lifecycle import setup

sphinx_traceability_view/directive/directives.py

@@ -0,0 +1,36 @@
+"""Serializable directive records and a small page-local initialization node."""
+import json
+from hashlib import sha256
+from html import escape
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+
+class ViewNode(nodes.General, nodes.Element):
+    pass
+
+
+class TraceabilityView(SphinxDirective):
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+    has_content = False
+
+    def run(self):
+        seeds = list(dict.fromkeys(self.arguments[0].split())) if self.arguments else []
+        if len(seeds) > 200:
+            raise self.error("traceability-view: at most 200 distinct starting IDs are permitted")
+        records = getattr(self.env, "stv_views", {})
+        entries = records.setdefault(self.env.docname, [])
+        document_key = sha256(self.env.docname.encode("utf-8")).hexdigest()
+        record = {"id": f"stv-{document_key}-{len(entries)}", "seeds": seeds,
+                  "source": self.get_source_info()[0], "line": self.lineno}
+        entries.append(record)
+        self.env.stv_views = records
+        return [ViewNode("", **record)]
+
+
+def visit_html(translator, node):
+    data = escape(json.dumps(node["seeds"]), quote=True)
+    translator.body.append(f'<section class="stv-view" id="{escape(node["id"], quote=True)}" data-stv-seeds="{data}" data-stv-build="STV_PENDING" aria-label="Interactive traceability view"></section>')
+    raise nodes.SkipNode

sphinx_traceability_view/directive/lifecycle.py

@@ -0,0 +1,112 @@
+"""Sphinx entry point; the host owns Needs collection and trace diagnostics."""
+from copy import deepcopy
+from hashlib import sha256
+import shutil
+from html import escape
+from pathlib import Path
+from sphinx.errors import SphinxError
+from sphinx.util.osutil import relative_uri
+from sphinx_needs.data import SphinxNeedsData
+from .directives import TraceabilityView, ViewNode, visit_html
+from .._version import __version__
+from ..model import normalize, validate_details_limit, DETAILS_LIMIT_DEFAULT
+from ..graph import snapshot
+from ..detail_build import extract
+from ..bundle import emit, atomic
+
+
+def initialize(app):
+    # The host later injects unused GitHub service types unconditionally. Validate
+    # the author's schema plus types actually used by service-produced objects.
+    app._stv_declared_types = deepcopy(app.config.needs_types)
+
+
+def purge(app, env, docname):
+    getattr(env, "stv_views", {}).pop(docname, None)
+
+
+def outdated(app, env, added, changed, removed):
+    return sorted(env.found_docs) if getattr(env, "stv_views", {}) else []
+
+
+def prepare(app, builder):
+    views = getattr(app.env, "stv_views", {})
+    app._stv_graph = None
+    if not any(views.values()):
+        return
+    if builder.name != "html":
+        raise SphinxError("traceability-view supports only the html builder")
+    records = [record for entries in views.values() for record in entries]
+    location = f'{records[0]["source"]}:{records[0]["line"]}'
+    try:
+        details_limit = validate_details_limit(app.config.traceability_view_details_limit)
+        needs = SphinxNeedsData(app.env).get_needs_view()
+        declared = {t["directive"] for t in app._stv_declared_types}
+        used = {n["type"] for n in needs.values()}
+        host_types = [t for t in app.config.needs_types if t["directive"] in declared | used]
+        model = normalize(host_types, app.config.needs_links,
+                          app.config.traceability_view_model,
+                          any(not r["seeds"] for r in records))
+        graph, hidden = snapshot(needs, model,
+                                 builder.get_target_uri, app.config.project)
+        graph["details_limit"] = details_limit
+        for record in records:
+            for seed in record["seeds"]:
+                if seed not in graph["objects"]:
+                    raise SphinxError(f'{record["source"]}:{record["line"]}: traceability-view: unknown or hidden starting ID {seed!r}')
+        app._stv_graph, app._stv_hidden = graph, hidden
+    except ValueError as error:
+        raise SphinxError(f"{location}: traceability-view: {error}") from error
+    target = Path(app.outdir) / "_static" / "stv"
+    target.mkdir(parents=True, exist_ok=True)
+    for name in ("stv.js", "stv.css", "LICENSE.txt", "THIRD_PARTY_NOTICES.txt", "vendor/ELK-SOURCE.txt", "vendor/ELK-INVENTORY.json"):
+        source = Path(__file__).parents[1] / "static" / name
+        if not source.is_file():
+            raise SphinxError(f"Missing packaged STV asset {name}; maintainers must build frontend assets")
+        (target / name).parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(source, target / name)
+
+
+def context(app, pagename, templatename, context, doctree):
+    if not getattr(app.env, "stv_views", {}).get(pagename):
+        return
+    page = app.builder.get_target_uri(pagename)
+    root = relative_uri(page, "index.html").removesuffix("index.html") or "./"
+    static = Path(__file__).parents[1] / "static"
+    css = escape(root + "_static/stv/stv.css?v=" + sha256((static / "stv.css").read_bytes()).hexdigest(), quote=True)
+    runtime = escape(root + "_static/stv/stv.js?v=" + sha256((static / "stv.js").read_bytes()).hexdigest(), quote=True)
+    context["metatags"] += f'<link rel="stylesheet" href="{css}"><script data-stv-graph src="STV_PENDING"></script><script defer src="{runtime}" data-stv-root="{escape(root, quote=True)}"></script>'
+
+
+def finish(app, exception):
+    graph = getattr(app, "_stv_graph", None)
+    if graph is None or exception is not None:
+        return
+    output = Path(app.outdir)
+    try:
+        fragments = extract(graph, output, app._stv_hidden)
+        identity, graph_path = emit(graph, fragments, output)
+        for docname in getattr(app.env, "stv_views", {}):
+            page = app.builder.get_target_uri(docname)
+            path = output / page
+            content = path.read_text(encoding="utf-8")
+            content = content.replace('data-stv-build="STV_PENDING"', f'data-stv-build="{identity}"')
+            content = content.replace('data-stv-graph src="STV_PENDING"', f'data-stv-graph src="{escape(relative_uri(page, graph_path), quote=True)}"')
+            atomic(path, content)
+    except (OSError, ValueError) as error:
+        raise SphinxError(f"traceability-view bundle finalization failed: {error}") from error
+
+
+def setup(app):
+    app.setup_extension("sphinx_needs")
+    app.add_config_value("traceability_view_model", None, "env", types=[dict, type(None)])
+    app.add_config_value("traceability_view_details_limit", DETAILS_LIMIT_DEFAULT, "env", types=[int])
+    app.add_directive("traceability-view", TraceabilityView)
+    app.add_node(ViewNode, html=(visit_html, None))
+    app.connect("builder-inited", initialize)
+    app.connect("env-purge-doc", purge)
+    app.connect("env-get-outdated", outdated)
+    app.connect("write-started", prepare, priority=800)
+    app.connect("html-page-context", context)
+    app.connect("build-finished", finish, priority=900)
+    return {"version": __version__, "parallel_read_safe": False, "parallel_write_safe": False}

sphinx_traceability_view/graph/__init__.py

@@ -0,0 +1,55 @@
+"""Adapt the completed NeedsView into deterministic, bidirectional graph data."""
+from urllib.parse import urlsplit
+from collections.abc import Mapping
+from .placement import resolve_placements
+
+
+def metadata_value(value):
+    if isinstance(value, Mapping):
+        return {str(key): metadata_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [metadata_value(item) for item in value]
+    if isinstance(value, (str, int, float, bool, type(None))):
+        return value
+    return str(value)
+
+
+def snapshot(needs, model, uri, project):
+    records = list(needs.to_list_with_parts())
+    hidden = {n.get("id_complete", n["id"]) for n in records if n.get("hide")}
+    hidden.update(n.get("id_complete", n["id"]) for n in records if n.get("id_parent") in hidden)
+    objects = {}
+    for n in records:
+        identity = n.get("id_complete", n["id"])
+        if identity in hidden:
+            continue
+        original = n.get("external_url") if n.get("is_external") else uri(n["docname"]) + "#" + identity
+        if not original or urlsplit(original).scheme.lower() not in ("", "http", "https"):
+            raise ValueError(f"Need {identity!r}: original documentation URL must be a local path or HTTP(S) URL")
+        objects[identity] = {"id": identity, "title": n.get("title", n.get("content", "")),
+                             "type": n["type"], "status": n.get("status") or "",
+                             "url": original, "docname": n.get("docname"),
+                             "parent": n.get("id_parent") if n.get("is_part") else None,
+                             "external": bool(n.get("is_external"))}
+        if n.get("is_external"):
+            excluded = set(model["relations"]) | {name + "_back" for name in model["relations"]} | {"parts"}
+            objects[identity]["metadata"] = {key: metadata_value(value) for key, value in n.items()
+                if key not in excluded}
+    edges = set()
+    for n in records:
+        source = n.get("id_complete", n["id"])
+        if source not in objects:
+            continue
+        for relation in model["relations"]:
+            for target in n.get(relation, []):
+                if target not in hidden:
+                    edges.add((source, relation, target))
+    adjacency = {i: {"incoming": {}, "outgoing": {}} for i in objects}
+    for source, relation, target in sorted(edges):
+        adjacency[source]["outgoing"].setdefault(relation, []).append(target)
+        if target in objects:
+            adjacency[target]["incoming"].setdefault(relation, []).append(source)
+    resolve_placements({n.get("id_complete", n["id"]): n for n in records}, objects, adjacency, model)
+    return {"schema": 1, "project": project, "model": model,
+            "objects": dict(sorted(objects.items())), "edges": sorted(edges), "adjacency": adjacency,
+            "entries": sorted(i for i, n in objects.items() if not n["parent"] and model["types"][n["type"]].get("role") == "stakeholder")}, hidden

sphinx_traceability_view/graph/placement.py

@@ -0,0 +1,48 @@
+"""Resolve evidence placement from complete published metadata, never view state."""
+
+
+def resolve_placements(records, objects, adjacency, model):
+    types = model["types"]
+    resolved = {}
+
+    def assign(identity, choices):
+        placement = types[objects[identity]["type"]]
+        if len(choices) == 1:
+            level = next(iter(choices))
+        else:
+            level = placement.get("fallback_level")
+            if level is None:
+                raise ValueError(f"Need {identity!r}: placement classification is missing or conflicting")
+            objects[identity]["placement_fallback"] = True
+        objects[identity]["level"] = level
+        resolved[identity] = level
+
+    for identity, obj in objects.items():
+        placement = types[obj["type"]]
+        if "level" in placement:
+            resolved[identity] = placement["level"]
+        elif "levels_by_tag" in placement:
+            tags = records[identity].get("tags") or []
+            if not isinstance(tags, (list, tuple, set, frozenset)):
+                tags = []
+            assign(identity, {level for tag, level in placement["levels_by_tag"].items() if tag in tags})
+
+    for identity, obj in objects.items():
+        placement = types[obj["type"]]
+        if "level_from" not in placement:
+            continue
+        rule = placement["level_from"]
+        owners = adjacency[identity][rule["direction"]].get(rule["relation"], [])
+        choices = set()
+        complete = bool(owners)
+        for owner in owners:
+            other = objects.get(owner)
+            if other and "level_from" in types[other["type"]]:
+                complete = False
+                continue
+            target = rule["levels"].get(resolved.get(owner))
+            if target is None or (other and other.get("placement_fallback")):
+                complete = False
+            else:
+                choices.add(target)
+        assign(identity, choices if complete else set())

sphinx_traceability_view/model/__init__.py

@@ -0,0 +1,98 @@
+"""Validate layout metadata without altering the host schema."""
+from copy import deepcopy
+
+DEFAULT = {
+    "levels": ["stakeholder", "system", "system_arch", "software", "software_arch"],
+    "types": {"shr": {"level": "stakeholder", "role": "stakeholder"},
+              "sysr": {"level": "system"}, "syse": {"level": "system_arch"},
+              "swr": {"level": "software"}, "swe": {"level": "software_arch"}},
+    "accepted_statuses": ["accepted"],
+}
+PALETTE = ["#dceaf7", "#e1efdc", "#f7e5ca", "#e9ddf2", "#d8efeb"]
+
+
+def normalize(host_types, host_links, supplied=None, project_mode=False):
+    model = deepcopy(DEFAULT if supplied is None else supplied)
+    if not isinstance(model, dict):
+        raise ValueError("traceability_view_model: expected a mapping")
+    levels = model.get("levels")
+    if not isinstance(levels, list) or not levels or any(not isinstance(x, str) or not x for x in levels) or len(set(levels)) != len(levels):
+        raise ValueError("traceability_view_model.levels: expected unique nonempty level names")
+    types = model.get("types", {})
+    if not isinstance(types, dict):
+        raise ValueError("traceability_view_model.types: expected a mapping")
+    names = {t["directive"] for t in host_types}
+    if set(types) != names:
+        raise ValueError(f"traceability_view_model.types: missing {sorted(names-set(types))}; unknown {sorted(set(types)-names)}")
+    host = {t["directive"]: t for t in host_types}
+    for index, name in enumerate(sorted(names)):
+        placement = types[name]
+        if not isinstance(placement, dict):
+            raise ValueError(f"traceability_view_model.types.{name}: expected a mapping")
+        role = placement.get("role")
+        selectors = [key for key in ("level", "levels_by_tag", "level_from") if key in placement]
+        path = f"traceability_view_model.types.{name}"
+        if role == "test":
+            if selectors or "fallback_level" in placement:
+                raise ValueError(f"{path}: legacy test role cannot have a level selector")
+        elif role not in (None, "stakeholder") or len(selectors) != 1:
+            raise ValueError(f"{path}: expected one level/role placement")
+        elif role == "stakeholder" and selectors != ["level"]:
+            raise ValueError(f"{path}: stakeholder role requires a fixed level")
+        elif selectors == ["level"]:
+            if placement["level"] not in levels or "fallback_level" in placement:
+                raise ValueError(f"{path}: invalid fixed level placement")
+        else:
+            selector = selectors[0]
+            value = placement[selector]
+            if selector == "level_from":
+                if (not isinstance(value, dict) or set(value) != {"relation", "direction", "levels"}
+                        or not isinstance(value["relation"], str)
+                        or value["direction"] not in ("incoming", "outgoing")):
+                    raise ValueError(f"{path}.level_from: expected relation, direction and levels")
+                value = value["levels"]
+            if (not isinstance(value, dict) or not value
+                    or any(not isinstance(key, str) or not key or not isinstance(target, str)
+                           or target not in levels for key, target in value.items())):
+                raise ValueError(f"{path}.{selector}: expected nonempty level mapping")
+            if "fallback_level" in placement and placement["fallback_level"] not in levels:
+                raise ValueError(f"{path}.fallback_level: unknown level")
+        placement["color"] = host[name].get("color") or PALETTE[index % len(PALETTE)]
+        placement["title"] = host[name].get("title", name)
+    if project_mode and not any(t.get("role") == "stakeholder" for t in types.values()):
+        raise ValueError("traceability_view_model.types: project mode requires a stakeholder role")
+    statuses = model.setdefault("accepted_statuses", ["accepted"])
+    if not isinstance(statuses, list) or any(not isinstance(x, str) for x in statuses):
+        raise ValueError("traceability_view_model.accepted_statuses: expected a list of strings")
+    model["relations"] = {}
+    relations = ({"option": name, **value} for name, value in host_links.items()) if isinstance(host_links, dict) else host_links
+    for relation in relations:
+        name = relation["option"]
+        if any(not isinstance(relation.get(direction), str) or not relation[direction].strip()
+               for direction in ("incoming", "outgoing")):
+            raise ValueError(f"needs_links.{name}: incoming and outgoing labels are required")
+        model["relations"][name] = {k: relation[k] for k in ("incoming", "outgoing")}
+    owner_levels = {p["level"] for p in types.values() if "level" in p}
+    owner_levels.update(level for p in types.values() for level in p.get("levels_by_tag", {}).values())
+    owner_levels.update(p["fallback_level"] for p in types.values()
+                        if "levels_by_tag" in p and "fallback_level" in p)
+    for name, placement in types.items():
+        if "level_from" not in placement:
+            continue
+        rule = placement["level_from"]
+        path = f"traceability_view_model.types.{name}.level_from"
+        if rule["relation"] not in model["relations"]:
+            raise ValueError(f"{path}.relation: unknown host relation")
+        if not set(rule["levels"]).issubset(owner_levels):
+            raise ValueError(f"{path}.levels: owners must use fixed/tag-resolved levels")
+    return model
+
+
+DETAILS_LIMIT_DEFAULT = 10
+
+
+def validate_details_limit(value=DETAILS_LIMIT_DEFAULT):
+    """Keep author capacity exact across Python and the JavaScript consumer."""
+    if type(value) is not int or not 1 <= value <= 9007199254740991:
+        raise ValueError("traceability_view_details_limit: expected a positive integer no greater than 9007199254740991")
+    return value

sphinx_traceability_view/static/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henning Heikes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.