throughline-compose 0.1.0__py3-none-any.whl

throughline_compose/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 Time Back Solutions Limited
+# SPDX-License-Identifier: Apache-2.0
+"""throughline-compose — compose one requirements graph from many reusable sources.
+
+Builds on ``throughline`` as an unmodified library (SR-0004): it prepares a union
+``Project`` from the declared sources and runs throughline's own ``validate``,
+``Index``, and ``fingerprint`` over it. The ``tl-compose`` CLI is a strict superset
+of ``tl`` (SR-0003) — it forwards local commands to throughline unchanged and
+overrides only the union-aware ones.
+"""
+from __future__ import annotations
+
+__version__ = "0.0.1"
+
+__all__ = ["__version__"]

throughline_compose/cli.py

@@ -0,0 +1,173 @@
+# Copyright (c) 2026 Time Back Solutions Limited
+# SPDX-License-Identifier: Apache-2.0
+"""The ``tl-compose`` entry point.
+
+Design intent (SR-0003): ``tl-compose`` is a strict superset of ``tl``. Every
+local-graph command is forwarded to throughline's CLI unchanged; the union-aware
+command ``check`` is layered on top. When a project declares no ``[[sources]]``,
+``check`` too is a pure pass-through, so ``tl-compose`` over an ordinary project
+behaves exactly like ``tl``.
+
+`check` composes the consumer with its declared sources into one union graph
+(union.py), runs the *unchanged* core validator over it (SR-0004), and translates
+findings back into ``<namespace>:<UID>`` vocabulary before printing.
+"""
+from __future__ import annotations
+
+import sys
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from throughline.cli import build_parser, cmd_check, cmd_docs
+from throughline.storage import ProjectError, load_project
+from throughline.validate import ERROR, validate
+
+from .resolve import ResolveError, resolve_source
+from .resolver import UnionResolver
+from .sources import SourceError, parse_sources
+from .union import ComposeError, build_union, translate_finding
+
+OK, FINDINGS, USAGE = 0, 1, 2
+
+
+def _err(msg: str) -> int:
+    print(f"tl-compose: {msg}", file=sys.stderr)
+    return USAGE
+
+
+def _pkg(name: str) -> str:
+    try:
+        return _pkg_version(name)
+    except PackageNotFoundError:  # pragma: no cover - running from a source tree
+        return "0.0.0+unknown"
+
+
+def _version_string() -> str:
+    # tl-compose is its own front door; report its version and the throughline core
+    # it composes over, not throughline's (build_parser wires `--version` to `tl`).
+    return f"tl-compose {_pkg('throughline-compose')} (throughline {_pkg('throughline')})"
+
+
+def _load_sources(sources, root) -> dict:
+    """Resolve and load each declared source into a namespace -> Project map.
+    Raises :class:`ResolveError` / :class:`ProjectError` for the caller to
+    report; a source that will not load is named in the composer's vocabulary."""
+    loaded = {}
+    for s in sources:
+        src_dir = resolve_source(s, root)
+        try:
+            loaded[s.namespace] = load_project(src_dir)
+        except ProjectError as e:
+            where = f"{s.url}@{s.ref}" if s.is_remote else s.path
+            raise ProjectError(f"source '{s.namespace}' at {where}: {e}") from e
+    return loaded
+
+
+def _compose_check(args) -> int:
+    from pathlib import Path
+
+    try:
+        consumer = load_project(args.path)
+    except ProjectError as e:
+        return _err(str(e))
+    try:
+        sources = parse_sources(consumer)
+    except SourceError as e:
+        return _err(str(e))
+
+    # No sources declared: this is a plain throughline project. Defer to the core
+    # check verbatim so the superset holds exactly (SR-0003).
+    if not sources:
+        return cmd_check(args)
+
+    try:
+        loaded = _load_sources(sources, Path(args.path))
+    except (ResolveError, ProjectError) as e:
+        return _err(str(e))
+
+    try:
+        union = build_union(consumer, loaded)
+    except ComposeError as e:
+        return _err(str(e))
+
+    findings = validate(union.project, strict=args.strict)
+    pattern = union.pattern()
+    findings = [translate_finding(f, union, pattern) for f in findings]
+
+    if getattr(args, "format", "text") == "json":
+        import json
+        print(json.dumps([f.to_dict() for f in findings], indent=2))
+        return FINDINGS if any(f.severity == ERROR for f in findings) else OK
+
+    for f in sorted(findings, key=lambda x: (x.severity != ERROR, x.uid)):
+        print(f)
+    sys.stdout.flush()
+    errs = sum(1 for f in findings if f.severity == ERROR)
+    warns = len(findings) - errs
+    if not getattr(args, "quiet", False):
+        names = ", ".join(
+            f"{s.namespace} ({s.url}@{s.ref})" if s.is_remote
+            else f"{s.namespace} ({s.path})"
+            for s in sources)
+        print(f"\ntl-compose check · {len(sources)} source(s) composed: {names}",
+              file=sys.stderr)
+    tally = f"\n{errs} error(s), {warns} warning(s)"
+    if not getattr(args, "quiet", False) and errs == 0:
+        tally += "  — composed graph is sound" + (" (strict)" if args.strict else "")
+    print(tally, file=sys.stderr)
+    return FINDINGS if any(f.severity == ERROR for f in findings) else OK
+
+
+def _compose_docs(args) -> int:
+    """Inject the consumer's documents, resolving tl:matrix target cells over the
+    union of the consumer and its declared sources (SR-0110). Injection is over
+    the *local* consumer project — counts, tables and rows are byte-identical to
+    ``tl docs`` — but a namespace-qualified matrix target can render the borrowed
+    clause's own reference number. With no sources declared this is a pure
+    pass-through to core ``tl docs`` (SR-0003)."""
+    from pathlib import Path
+
+    try:
+        consumer = load_project(args.path)
+    except ProjectError as e:
+        return _err(str(e))
+    try:
+        sources = parse_sources(consumer)
+    except SourceError as e:
+        return _err(str(e))
+
+    if not sources:
+        return cmd_docs(args)
+
+    try:
+        loaded = _load_sources(sources, Path(args.path))
+    except (ResolveError, ProjectError) as e:
+        return _err(str(e))
+
+    return cmd_docs(args, resolver=UnionResolver(consumer, loaded))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    parser.prog = "tl-compose"
+    for action in parser._actions:
+        if "--version" in action.option_strings:
+            action.version = _version_string()
+    args = parser.parse_args(argv)
+    if getattr(args, "cmd", None) == "check":
+        try:
+            return _compose_check(args)
+        except KeyboardInterrupt:  # pragma: no cover
+            return USAGE
+    if getattr(args, "cmd", None) == "docs":
+        try:
+            return _compose_docs(args)
+        except KeyboardInterrupt:  # pragma: no cover
+            return USAGE
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:  # pragma: no cover
+        return USAGE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

throughline_compose/resolve.py

@@ -0,0 +1,120 @@
+# Copyright (c) 2026 Time Back Solutions Limited
+# SPDX-License-Identifier: Apache-2.0
+"""Resolve a declared source to a local directory (SR-0006).
+
+A ``path`` source resolves to a directory relative to the consumer project. A
+``url`` + ``ref`` source is fetched from its git origin at the pinned ref into a
+cache that lives *outside* any project tree — a shared, per-user store keyed by
+origin URL and ref, so a consumer's own item scan never ingests a resolved source
+(the reason a resolved source must not live under the project root, per SR-0006).
+
+Resolution is idempotent and offline after the first fetch: a source already
+present in the cache at the pinned ref is reused, never refetched.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .sources import Source
+
+_SLUG_RE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+class ResolveError(Exception):
+    """A source could not be resolved — bad path, or a git fetch that failed."""
+
+
+def cache_root() -> Path:
+    """The per-user source cache, outside any project tree (SR-0006).
+
+    Honours ``TL_COMPOSE_CACHE`` for tests and CI; otherwise ``XDG_CACHE_HOME`` or
+    ``~/.cache``.
+    """
+    override = os.environ.get("TL_COMPOSE_CACHE")
+    if override:
+        return Path(override)
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "throughline-compose" / "sources"
+
+
+def _slug(text: str) -> str:
+    return _SLUG_RE.sub("-", text).strip("-") or "x"
+
+
+def _cache_dir(url: str, ref: str) -> Path:
+    # Key by (url, ref). A short hash guarantees uniqueness; a readable slug of the
+    # url's last segment and the ref makes the directory legible on disk.
+    digest = hashlib.sha256(url.encode("utf-8")).hexdigest()[:16]
+    tail = _slug(url.rstrip("/").rsplit("/", 1)[-1].removesuffix(".git"))
+    return cache_root() / f"{tail}-{digest}@{_slug(ref)}"
+
+
+def _git(*args: str, cwd: Path | None = None) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(
+            ["git", *args],
+            cwd=str(cwd) if cwd else None,
+            capture_output=True, text=True,
+        )
+    except FileNotFoundError as e:  # pragma: no cover - git absent
+        raise ResolveError("git is not installed; it is required to fetch url sources") from e
+
+
+def _fetch(url: str, ref: str, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = Path(tempfile.mkdtemp(prefix=".fetch-", dir=dest.parent))
+    try:
+        # --branch accepts a tag or branch name; a bare commit SHA needs a second
+        # step, so fall back to a full clone + checkout when the pinned clone fails.
+        r = _git("clone", "--depth", "1", "--branch", ref, url, str(tmp))
+        if r.returncode != 0:
+            shutil.rmtree(tmp, ignore_errors=True)
+            tmp = Path(tempfile.mkdtemp(prefix=".fetch-", dir=dest.parent))
+            r = _git("clone", url, str(tmp))
+            if r.returncode != 0:
+                raise ResolveError(
+                    f"could not clone {url}: {r.stderr.strip() or 'git clone failed'}")
+            co = _git("checkout", ref, cwd=tmp)
+            if co.returncode != 0:
+                raise ResolveError(
+                    f"ref '{ref}' not found in {url}: "
+                    f"{co.stderr.strip() or 'git checkout failed'}")
+        # Publish atomically: dest only ever appears fully materialised.
+        os.replace(tmp, dest)
+    finally:
+        if tmp.exists():
+            shutil.rmtree(tmp, ignore_errors=True)
+
+
+def resolve_source(source: Source, consumer_root: Path) -> Path:
+    """Return the local directory a source composes from.
+
+    ``path`` sources resolve relative to ``consumer_root``; ``url`` sources are
+    fetched (once) into the per-user cache.
+    """
+    if not source.is_remote:
+        assert source.path is not None
+        local = (consumer_root / source.path).resolve()
+        if not local.is_dir():
+            raise ResolveError(
+                f"source '{source.namespace}' path does not exist: {local}")
+        return local
+
+    assert source.url is not None and source.ref is not None
+    dest = _cache_dir(source.url, source.ref)
+    if dest.is_dir() and (dest / "throughline.toml").is_file():
+        return dest  # already resolved at this pinned ref — idempotent, offline
+    if dest.exists():  # partial/corrupt leftover
+        shutil.rmtree(dest, ignore_errors=True)
+    _fetch(source.url, source.ref, dest)
+    if not (dest / "throughline.toml").is_file():
+        raise ResolveError(
+            f"source '{source.namespace}' at {source.url}@{source.ref} is not a "
+            "throughline project (no throughline.toml)")
+    return dest

throughline_compose/resolver.py

@@ -0,0 +1,83 @@
+# Copyright (c) 2026 Time Back Solutions Limited
+# SPDX-License-Identifier: Apache-2.0
+"""A target resolver backed by a consumer's declared sources (SR-0110 seam).
+
+``tl-compose docs`` injects over the *local* consumer project, exactly as ``tl
+docs`` does, so counts, tables and matrix rows stay byte-identical. The one seam
+is the target *cell* of a tl:matrix: a consumer clause that links to a borrowed
+standard by a namespace-qualified target (``asvs:SR-0227``) can then render that
+target's own reference number instead of a UID the reader cannot look up.
+
+Core injection resolves target liveness and attributes through an optional
+:class:`throughline.inject.TargetResolver` (SR-0110). This resolver overrides it
+so a namespace-qualified target resolves against the loaded source for that
+namespace; an unqualified target falls through to the consumer project, so
+behaviour over local links is identical to the core default.
+"""
+from __future__ import annotations
+
+import re
+
+from throughline import is_namespace_qualified
+from throughline.inject import TargetResolver, _render_item
+
+_NS_SPLIT = re.compile(r"^([a-z][a-z0-9_-]*):(.+)$")
+
+
+class UnionResolver(TargetResolver):
+    """Resolve tl:matrix target cells over a consumer plus its sources."""
+
+    def __init__(self, consumer, sources: dict) -> None:
+        super().__init__(consumer)
+        self._sources = sources  # namespace -> loaded source Project
+
+    def _delegate(self, uid: str) -> "TargetResolver | None":
+        """A resolver over the source project owning ``uid``, or ``None`` when
+        ``uid`` is not a namespace-qualified reference to a declared source."""
+        if not is_namespace_qualified(uid):
+            return None
+        m = _NS_SPLIT.match(uid)
+        src = self._sources.get(m.group(1))
+        return TargetResolver(src) if src is not None else None
+
+    def present(self, uid: str) -> bool:
+        d = self._delegate(uid)
+        return d.present(_local(uid)) if d else super().present(uid)
+
+    def attr(self, uid: str, name: str):
+        d = self._delegate(uid)
+        return d.attr(_local(uid), name) if d else super().attr(uid, name)
+
+    def link_display(self, uid: str) -> str:
+        """Enrich a borrowed clause's link display with its own reference number
+        (SR-0113): ``asvs:SR-0172`` reads ``asvs:SR-0172 (V7.1.1)`` when the source
+        clause carries a ``source_ref``. A local target is the bare UID as before."""
+        if not is_namespace_qualified(uid):
+            return super().link_display(uid)
+        ref = self.attr(uid, "source_ref")
+        return f"{uid} ({ref})" if ref else uid
+
+    def block(self, uid: str) -> str | None:
+        """The borrowed clause's own full block (SR-0114): render the source item a
+        namespace-qualified target names, from its source project. Returns ``None``
+        for a local target or a source that cannot render it, so ``tl:sourced``
+        mirrors only the external clauses a source backs."""
+        src = self._source_for(uid)
+        if src is None:
+            return None
+        local = _local(uid)
+        if src.get(local) is None:
+            return None
+        return _render_item(src, local, TargetResolver(src))
+
+    def _source_for(self, uid: str):
+        """The loaded source project owning a namespace-qualified ``uid``, or None."""
+        if not is_namespace_qualified(uid):
+            return None
+        return self._sources.get(_NS_SPLIT.match(uid).group(1))
+
+
+def _local(uid: str) -> str:
+    """The source-local UID of a namespace-qualified reference (``asvs:SR-0227``
+    → ``SR-0227``)."""
+    return _NS_SPLIT.match(uid).group(2)

throughline_compose/sources.py

@@ -0,0 +1,108 @@
+# Copyright (c) 2026 Time Back Solutions Limited
+# SPDX-License-Identifier: Apache-2.0
+"""Declared external sources (SR-0001, SR-0002, SR-0006).
+
+A consuming project names the throughline sources it composes in an array of
+``[[sources]]`` tables in its ``throughline.toml``. Each entry binds an
+importer-chosen *namespace* (SR-0001) to a standalone throughline source whose UIDs
+are its own (SR-0002). Clauses are then referenced from the consumer as
+``<namespace>:<UID>``.
+
+A source is located one of two ways (SR-0006):
+
+- ``url`` + ``ref`` — a git origin pinned to an edition (normally a tag). The
+  durable, shareable form; resolved into a per-user cache by ``resolve.py``.
+- ``path`` — a local directory, for developing a source and its consumer side by
+  side.
+
+The two are mutually exclusive; a ``url`` without a ``ref`` is rejected so a
+dependency can never silently track a moving default. This module is pure config
+parsing — it does not fetch or load anything.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# The namespace grammar mirrors the core's namespace-qualified reference token
+# (throughline SR-0107): a lowercase name a reference can carry before the colon.
+_NAMESPACE_RE = re.compile(r"^[a-z][a-z0-9_-]*$")
+
+
+class SourceError(ValueError):
+    """A malformed or ambiguous ``[[sources]]`` declaration — fail fast (SR-0005)."""
+
+
+@dataclass(frozen=True)
+class Source:
+    namespace: str
+    path: str | None = None
+    url: str | None = None
+    ref: str | None = None
+
+    @property
+    def is_remote(self) -> bool:
+        return self.url is not None
+
+
+def parse_sources(project) -> list[Source]:
+    """Read the ``[[sources]]`` array from a loaded consumer project's config.
+
+    Returns an empty list when none are declared — a project with no sources is
+    an ordinary throughline project and ``tl-compose`` behaves exactly like ``tl``
+    over it (SR-0003).
+    """
+    raw = project.config.get("sources", [])
+    if not isinstance(raw, list):
+        raise SourceError("[[sources]] must be an array of tables")
+    out: list[Source] = []
+    seen: set[str] = set()
+    for i, entry in enumerate(raw):
+        if not isinstance(entry, dict):
+            raise SourceError(f"[[sources]] entry {i} is not a table")
+
+        ns = entry.get("namespace")
+        if not ns or not isinstance(ns, str):
+            raise SourceError(f"[[sources]] entry {i} is missing a 'namespace'")
+        if not _NAMESPACE_RE.match(ns):
+            raise SourceError(
+                f"namespace '{ns}' is not a valid namespace name "
+                "(lowercase letter, then letters/digits/-/_)")
+        if ns in seen:
+            raise SourceError(
+                f"namespace '{ns}' is declared twice — a namespace binds one source")
+
+        path = entry.get("path")
+        url = entry.get("url")
+        ref = entry.get("ref")
+
+        has_path = bool(path)
+        has_url = bool(url)
+        if has_path and has_url:
+            raise SourceError(
+                f"source '{ns}' declares both 'path' and 'url' — they are mutually "
+                "exclusive (SR-0006)")
+        if not has_path and not has_url:
+            raise SourceError(
+                f"source '{ns}' must declare either a 'path' or a 'url'")
+
+        if has_path:
+            if not isinstance(path, str):
+                raise SourceError(f"source '{ns}' has a non-string 'path'")
+            if ref:
+                raise SourceError(
+                    f"source '{ns}' declares a 'ref' with a local 'path' — a ref "
+                    "only pins a 'url' (SR-0006)")
+            src = Source(namespace=ns, path=path)
+        else:
+            if not isinstance(url, str):
+                raise SourceError(f"source '{ns}' has a non-string 'url'")
+            if not ref or not isinstance(ref, str):
+                raise SourceError(
+                    f"source '{ns}' has a 'url' but no 'ref' — pin the edition with "
+                    "a git tag, branch, or commit (SR-0006)")
+            src = Source(namespace=ns, url=url, ref=ref)
+
+        seen.add(ns)
+        out.append(src)
+    return out

throughline_compose/union.py

@@ -0,0 +1,185 @@
+# Copyright (c) 2026 Time Back Solutions Limited
+# SPDX-License-Identifier: Apache-2.0
+"""Build one throughline graph from a consumer plus its declared sources (SR-0004).
+
+The core throughline validator is reused *unchanged* (SR-0004): rather than teach
+`tl` about namespaces, `tl-compose` folds every source's items into a single union
+:class:`~throughline.model.Project` and runs the ordinary `validate` over it. The
+one trick is identity. A source's UIDs are its own (SR-0002), so two sources — or a
+source and the consumer — may both hold ``SR-0001``. Before merging, each borrowed
+UID is *mangled* to a synthetic prefix derived from its namespace (``gds:SR-0001``
+→ ``GDSSR-0001``), so the union has globally-unique, grammar-valid UIDs. Every
+namespace-qualified reference (SR-0001) and every source-internal reference is
+rewritten to the mangled form, so the graph resolves with no colons left.
+
+Findings from the core are then translated back: mangled UIDs in a finding's target
+and message become their original ``<namespace>:<UID>`` form, so the composer reads
+diagnostics in the vocabulary they wrote.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, replace
+
+from throughline import is_external, is_namespace_qualified
+from throughline.model import Item, Project, Register
+from throughline.uid import UID_RE, parse_uid
+
+# The prefix a mangled UID may occupy: core UID grammar (throughline SR-0001).
+_PREFIX_RE = re.compile(r"^[A-Z][A-Z0-9]{1,15}$")
+# Split a namespace-qualified reference into (namespace, uid).
+_NS_REF_RE = re.compile(r"^([a-z][a-z0-9_-]*):(.+)$")
+
+
+class ComposeError(Exception):
+    """Composition cannot proceed — an unbound namespace, a UID that will not
+    mangle to a legal prefix, or a synthetic-prefix clash. Fail fast (SR-0005)."""
+
+
+@dataclass
+class Union:
+    project: Project                    # merged graph, governed by consumer schema
+    owners: dict[str, tuple[str, str]]  # synthetic prefix -> (namespace, source prefix)
+
+    def qualified(self, uid: str) -> str:
+        """Reconstruct the original ``<namespace>:<UID>`` for any union UID whose
+        prefix is a mangled one — including a reference to a source clause that
+        does *not* exist, so a dangling cross-source link reads in the composer's
+        own vocabulary. A consumer-local UID is returned unchanged."""
+        m = UID_RE.match(uid)
+        if m and m.group(1) in self.owners:
+            namespace, src_prefix = self.owners[m.group(1)]
+            return f"{namespace}:{src_prefix}-{m.group(2)}"
+        return uid
+
+    def pattern(self) -> re.Pattern | None:
+        """A regex matching any mangled UID token, for message translation."""
+        if not self.owners:
+            return None
+        prefixes = "|".join(re.escape(p) for p in
+                            sorted(self.owners, key=len, reverse=True))
+        return re.compile(rf"(?:{prefixes})-[0-9]+")
+
+
+def _sanitize_ns(namespace: str) -> str:
+    """The uppercase, alphanumeric-only stem a namespace contributes to a mangled
+    prefix. A namespace starts with a lowercase letter (sources.py), so the stem
+    always starts with a letter and is a legal prefix head."""
+    return re.sub(r"[^A-Z0-9]", "", namespace.upper())
+
+
+class _Mangler:
+    """Deterministic, collision-checked mapping from ``(namespace, source UID)`` to
+    a unique, grammar-valid union UID. Only the prefix changes; the number is
+    preserved verbatim so the width and value survive."""
+
+    def __init__(self) -> None:
+        # synthetic prefix -> (namespace, source prefix) that owns it, to catch two
+        # distinct (namespace, prefix) pairs colliding on one synthetic prefix.
+        self.owners: dict[str, tuple[str, str]] = {}
+
+    def prefix(self, namespace: str, src_prefix: str) -> str:
+        syn = _sanitize_ns(namespace) + src_prefix
+        if not _PREFIX_RE.match(syn):
+            raise ComposeError(
+                f"namespace '{namespace}' + prefix '{src_prefix}' mangles to "
+                f"'{syn}', which is not a legal UID prefix (max 16 chars) — "
+                "import the source under a shorter namespace")
+        owner = self.owners.setdefault(syn, (namespace, src_prefix))
+        if owner != (namespace, src_prefix):
+            raise ComposeError(
+                f"namespaces '{owner[0]}' and '{namespace}' both mangle prefix "
+                f"'{src_prefix}' to '{syn}' — import one under a distinct namespace")
+        return syn
+
+    def uid(self, namespace: str, uid: str) -> str:
+        m = UID_RE.match(uid)
+        if not m:
+            return uid  # malformed target — leave for the core to flag as dangling
+        pfx, num = m.group(1), m.group(2)
+        return f"{self.prefix(namespace, pfx)}-{num}"
+
+
+def _rewrite_target(target: str, current_ns: str | None,
+                    namespaces: set[str], mangler: _Mangler) -> str:
+    """Map one link target into union space.
+
+    - External pointers (URLs, paths, anchors — SR-0031) stay opaque.
+    - A namespace-qualified ``ns:UID`` resolves to that namespace's mangled UID;
+      an undeclared namespace is a fail-fast :class:`ComposeError`.
+    - A bare UID inside a *source* item is a source-internal reference and mangles
+      into that source's namespace; inside the *consumer* it is a local UID and is
+      left untouched.
+    """
+    if is_external(target):
+        return target
+    if is_namespace_qualified(target):
+        m = _NS_REF_RE.match(target)
+        ns, uid = m.group(1), m.group(2)
+        if ns not in namespaces:
+            raise ComposeError(
+                f"reference '{target}' names namespace '{ns}', which is not a "
+                "declared [[sources]] namespace")
+        return mangler.uid(ns, uid)
+    if current_ns is not None:
+        return mangler.uid(current_ns, target)
+    return target
+
+
+def _rewrite_links(item: Item, current_ns: str | None,
+                   namespaces: set[str], mangler: _Mangler) -> Item:
+    new_links = [replace(link, target=_rewrite_target(
+        link.target, current_ns, namespaces, mangler)) for link in item.links]
+    return replace(item, links=new_links)
+
+
+def build_union(consumer: Project, sources: dict[str, Project]) -> Union:
+    """Fold ``sources`` (namespace -> loaded source project) into ``consumer`` and
+    return the merged :class:`Union`. The union is governed by the *consumer's*
+    schema — the consumer decides which types, links and statuses are legal for
+    the composed graph."""
+    namespaces = set(sources)
+    mangler = _Mangler()
+
+    union = Project(path=consumer.path, config=consumer.config)
+
+    # Consumer items keep their own UIDs; only their ns-qualified references are
+    # rewritten. Copy registers so the loaded consumer objects stay untouched.
+    for prefix, reg in consumer.registers.items():
+        items = {uid: _rewrite_links(it, None, namespaces, mangler)
+                 for uid, it in reg.items.items()}
+        union.registers[prefix] = replace(reg, items=items)
+
+    # Each source's items are mangled into namespace-derived prefixes and merged.
+    for namespace, source in sources.items():
+        for reg in source.registers.values():
+            for uid, it in reg.items.items():
+                mangled_uid = mangler.uid(namespace, uid)
+                mangled_prefix = parse_uid(mangled_uid)[0]
+                rewritten = _rewrite_links(it, namespace, namespaces, mangler)
+                merged = replace(rewritten, uid=mangled_uid,
+                                 _register_prefix=mangled_prefix)
+                target = union.registers.get(mangled_prefix)
+                if target is None:
+                    if mangled_prefix in consumer.registers:
+                        raise ComposeError(
+                            f"source '{namespace}' mangles to prefix "
+                            f"'{mangled_prefix}', which the consumer already uses — "
+                            "import the source under a distinct namespace")
+                    target = Register(prefix=mangled_prefix,
+                                      title=f"{namespace}:{reg.prefix}")
+                    union.registers[mangled_prefix] = target
+                target.items[mangled_uid] = merged
+
+    return Union(project=union, owners=mangler.owners)
+
+
+def translate_finding(finding, union: Union, pattern: re.Pattern | None):
+    """Rewrite a core :class:`~throughline.validate.Finding` back into namespace
+    vocabulary: its ``uid`` and any mangled UID token in its ``message`` become the
+    original ``<namespace>:<UID>``. Returns a shallow copy; the original is
+    untouched."""
+    message = finding.message
+    if pattern is not None:
+        message = pattern.sub(lambda m: union.qualified(m.group(0)), message)
+    return replace(finding, uid=union.qualified(finding.uid), message=message)

throughline_compose-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: throughline-compose
+Version: 0.1.0
+Summary: Compose one requirements graph from many reusable throughline sources: importer-assigned namespaces, source-native UIDs, and a union checked by throughline's own validator. Ships the tl-compose CLI, a strict superset of tl.
+Author: Time Back Solutions Limited
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/rhodium-org/throughline-compose
+Project-URL: Repository, https://github.com/rhodium-org/throughline-compose
+Project-URL: Issues, https://github.com/rhodium-org/throughline-compose/issues
+Keywords: requirements,requirements-management,traceability,composition,git-native,idd,intent-driven-development,throughline
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: throughline>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# throughline-compose
+
+**Compose one requirements graph from many reusable
+[throughline](https://github.com/rhodium-org/throughline) sources** — a house style
+guide, a platform standard, a regulatory baseline — alongside the requirements you
+write yourself, and work the combined graph as one.
+
+This repository is itself a throughline project: its own design is captured as a
+grounded IDD spine of
+<!-- tl:count type == 'user_requirement' -->
+3
+<!-- tl:end --> user requirements and
+<!-- tl:count type == 'system_requirement' -->
+7
+<!-- tl:end --> system requirements under [`vision/`](vision), [`goals/`](goals),
+[`user-requirements/`](user-requirements),
+[`system-requirements/`](system-requirements), and [`non-goals/`](non-goals), and
+published to [`docs/spec.md`](docs/spec.md). The graph is gated by `tl-compose check
+--strict` and the document by `tl-compose docs --check`; these two counts are
+rendered from the live spine by the `tl:count` directive, so they cannot drift.
+
+> **Status: alpha.** The composition engine is built. `tl-compose check` composes the
+> declared `[[sources]]` into a union graph and validates it, and `tl-compose docs`
+> renders the published document over that same union, resolving borrowed
+> (`namespace:UID`) targets ([SR-0007](system-requirements/SR-0007.yml)). Each source
+> resolves from either a local `path` or a pinned git `url` + `ref` into a per-user
+> cache ([SR-0006](system-requirements/SR-0006.yml)). Still pending: the
+> `tl-compose source add/update/pin` subcommands for managing source declarations from
+> the CLI (today you edit the `[[sources]]` tables by hand).
+
+## The idea
+
+A team should be able to adopt standard requirement sets *by reference*, not by
+copy-paste, and receive upstream revisions without ever forking. Two identity rules
+make that safe:
+
+- **Imported items keep their source-native UID** ([SR-0002](system-requirements/SR-0002.yml)).
+  Composition never renumbers or copies. Canonical identity is the pair
+  `(source-namespace, UID)`, so the same `SR-0001` may legitimately exist in two
+  sources without collision — the immutable-UID rule is never violated.
+- **The composer controls the namespaces** ([SR-0001](system-requirements/SR-0001.yml)).
+  The consumer's own `throughline.toml` binds each source to a short name it chooses
+  (`import X as Y`). A qualified reference like `gds:SR-0001` denotes a borrowed item;
+  a bare UID is always local. Renaming a namespace is a local-only change with a
+  bounded blast radius.
+
+## Declaring sources
+
+A consumer names the sources it composes in an array of `[[sources]]` tables in its
+own `throughline.toml`. Each entry binds a `namespace` to one source, located either
+by a pinned git `url` or by a local `path` ([SR-0006](system-requirements/SR-0006.yml)):
+
+```toml
+# Adopt a published standard by reference, pinned to an edition.
+[[sources]]
+namespace = "asvs"
+url = "https://github.com/rhodium-org/standard-asvs"
+ref = "v4.0.3"                       # a git tag (normal form), branch, or commit SHA
+
+# Develop a source and its consumer side by side.
+[[sources]]
+namespace = "house-style"
+path = "../house-style"              # a directory relative to this project
+```
+
+- **`url` + `ref` is the durable, shareable form.** The `ref` pins the exact edition
+  — normally a release tag, but any git ref (branch or commit SHA) works. `tl-compose`
+  fetches the source from its origin on first use into a per-user cache that lives
+  *outside* any project tree (`$TL_COMPOSE_CACHE`, else `$XDG_CACHE_HOME`, else
+  `~/.cache/throughline-compose/sources/`), keyed by `(url, ref)`. Resolution is
+  idempotent and offline thereafter: a source already cached at the pinned ref is
+  reused, never refetched. Nothing is vendored into your repo, so your own item scan
+  never ingests a borrowed graph.
+- **`path` is for local development.** A directory, relative to the consumer, for
+  working on a source alongside the project that consumes it.
+- **The two are mutually exclusive, and a `url` must carry a `ref`.** Declaring both
+  `path` and `url`, or a `url` with no `ref`, is rejected at check time — a dependency
+  can never silently track a moving default. (A `ref` alongside a `path` is likewise
+  rejected: a ref only pins a `url`.)
+
+Moving to a new upstream edition is a one-line change to the `ref`; the borrowed graph
+is never edited. See [`rhodium-org/idd-example`](https://github.com/rhodium-org/idd-example)
+for a complete worked consumer that adopts `standard-asvs` this way.
+
+## One tool, one set of guarantees
+
+In a composed project you drive everything through **`tl-compose`**, never `tl`
+directly ([UR-0002](user-requirements/UR-0002.yml)). The architecture keeps that
+honest:
+
+- **`tl-compose` is a strict superset of `tl`** ([SR-0003](system-requirements/SR-0003.yml)).
+  Local-graph commands are forwarded to the throughline library unchanged; the
+  union-aware `check` and `docs` are overridden to compose, validate, and render the
+  combined graph. (The `source` subcommands for editing declarations are the remaining
+  superset surface — see the status note above.) The core command set is obtained
+  programmatically, so the two surfaces cannot drift apart.
+- **Composition reuses throughline unchanged** ([SR-0004](system-requirements/SR-0004.yml)).
+  It merges the sources into one in-memory `Project` and runs throughline's existing
+  `validate`, `Index`, and `fingerprint` over that union — no second validation
+  engine. A composed graph is exactly as sound as a native one.
+- **Bare `tl check` fails fast on unresolved cross-source refs**
+  ([SR-0005](system-requirements/SR-0005.yml)). If you run core `tl` in a composed
+  repo by habit, a namespace-qualified reference it cannot resolve makes it stop and
+  point you at `tl-compose` — never a false clean result. Free external references (a
+  URL, a linked standard) stay opaque, as intended.
+
+Composition deliberately lives here, not in the throughline core
+([NG-0001](non-goals/NG-0001.yml)) — the core stays a single-purpose, offline tool
+over one graph, consumed here as a library.
+
+## Working here
+
+```sh
+pip install .            # pulls throughline transitively; installs tl and tl-compose
+tl-compose context       # agent brief, generated from throughline.toml
+tl-compose check --strict # gate the whole graph
+tl-compose docs --check  # gate published-document freshness
+tl-compose docs          # regenerate docs/spec.md from the graph
+```

throughline_compose-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+throughline_compose/__init__.py,sha256=EenkGGkr26g91lfe1elyNVwvCd20hMEUHGdBXfbRSmk,625
+throughline_compose/cli.py,sha256=1UCOgGUlxBCrHZkB9_ZqHucjeMXRnEpTNjxihWZ5gUQ,6173
+throughline_compose/resolve.py,sha256=R3qbd17bsu9zcY4wEPIcICNDnAriZwOjh4e6p_VQFQQ,4757
+throughline_compose/resolver.py,sha256=zO6WuACWouZabj2EYMR5eNxP5IXWleexFLxhLzRuFic,3640
+throughline_compose/sources.py,sha256=hU5v-_ItlFH-F9FsrjF3LcMi-dB4WkBl-Io8ZEFBspM,4153
+throughline_compose/union.py,sha256=MSnYuOIstEfzSr29LITDeGknNU764HZt5hd-8AOJpHI,8851
+throughline_compose-0.1.0.dist-info/licenses/LICENSE,sha256=_Zc5I-iUut1YEYW8UD2_NaMhBTPmCNfyXQG2113H-6M,11357
+throughline_compose-0.1.0.dist-info/licenses/NOTICE,sha256=I4wJH0vg9C_6HTaTAhoCodnPw7Wc_MhfdCZC4q6JWU8,523
+throughline_compose-0.1.0.dist-info/METADATA,sha256=gTXCx8VnX_HjXHs5ftPuBCmbmL2TnRU4aG5UEv7RHRs,7847
+throughline_compose-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+throughline_compose-0.1.0.dist-info/entry_points.txt,sha256=xMJpVHrQH9ExiL1Zx1kA5pqEKDCRpZUoyZwlAUIdX4Y,60
+throughline_compose-0.1.0.dist-info/top_level.txt,sha256=4ehGfSKMF-MJ3Mn3Gy0ATp8jBfCqd9nBqnEpCr7fMbs,20
+throughline_compose-0.1.0.dist-info/RECORD,,

throughline_compose-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

throughline_compose-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tl-compose = throughline_compose.cli:main

throughline_compose-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Time Back Solutions Limited
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

throughline_compose-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,12 @@
+throughline-compose
+Copyright 2026 Time Back Solutions Limited
+
+This product includes software developed by Time Back Solutions Limited.
+
+Licensed under the Apache License, Version 2.0. See the LICENSE file for the
+full terms.
+
+throughline-compose builds on throughline (https://pypi.org/project/throughline/),
+which it consumes as an unmodified library. It adds source composition — namespace
+declaration, pinning, fetching, and union merging — over that library and reuses
+throughline's validator without forking it.

throughline_compose-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+throughline_compose