compforge-repokit 0.15.0__py3-none-any.whl

compforge_repokit-0.15.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: compforge-repokit
+Version: 0.15.0
+Summary: Native repository inspection, content identity, Git and Forge operations
+Requires-Python: >=3.11
+Requires-Dist: harness-common<0.7,>=0.6
+Requires-Dist: pyyaml<7,>=6
+Description-Content-Type: text/markdown
+
+# RepoKit for Python
+
+Native organization inspection for Git repositories: discover Components, language and
+package-tool evidence, then locate the owner of a repository-relative path.
+Python 3.11+ on macOS/Linux and Git on PATH are required. Organization analysis runs
+in Python; Git provides version-control facts through batched commands.
+
+Install from the repository checkout:
+
+```sh
+python -m pip install ./toolkit/python
+```
+
+```python
+from repokit import inspect, owner
+
+report = inspect("/path/to/repo", timeout=5)
+if not report.complete:
+    raise RuntimeError(report.diagnostics)
+component = owner(report, "server/main.py")
+if component is not None:
+    print(component.name, component.root, component.language)
+```
+
+`inspect(..., staged=True)` selects the index; `inspect(..., head="HEAD")` selects a
+resolved commit. The default observes the working tree, including non-ignored untracked
+paths. `timeout` is a whole-call budget in seconds; an optional `threading.Event` passed
+as `cancel` requests cancellation. Git processes are terminated and reaped on timeout,
+cancellation or output overflow. Filesystem reads and Python analysis check the budget
+between operations. Timeout raises `TimeoutError`, cancellation raises `InterruptedError`,
+invalid selections/configuration or limits raise `ValueError`, and filesystem/Git failures
+propagate `OSError` / `subprocess.CalledProcessError`.
+
+Reports and their nested collections are immutable dataclasses and tuples. Shared
+Repository, Component, Product and Forge identities come from `harness-common`;
+ComponentBinding adds checkout layout and tool evidence. `owner` accepts a repository-relative
+path and returns the deepest binding or None, including for deleted paths.
+Python properties use snake_case; these objects are not a CLI JSON protocol adapter.
+
+Inspection reads filenames and necessary metadata, not source contents or ASTs. It never
+runs project code or installs dependencies. `complete` concerns observed organization;
+concurrent metadata changes return an incomplete report with diagnostics. Consumers own
+acceptance, command selection and validation policy. Snapshot, diff and graph analysis
+remain available through the Go toolkit / CLI.
+
+Development: `uv sync --locked`, then `make format`, `make lint`, `make test`, `make build`.
+Tests consume the shared `conformance/inspect` cases and generated filename probes.
+See [the inspection contract](../../docs/repository.md).
+
+## Repository toolkit
+
+工具包提供仓库组织、内容身份与 Git 查询。Python 还提供 worktree、提交、推送、rebase 和
+GitHub/GitLab 的 PR/MR 操作；调用方直接导入库，组织自己的开发流程。
+分析接口保持只读，操作接口接收明确参数，不隐式执行验证或管理任务状态。
+
+详见 [Git 操作](../../docs/git.md)与[PR 契约](../../docs/pr.md)。
+
+## Repository entries
+
+`tree` lists directories, files, Git entry kinds and known roles independently of
+Component discovery, for working-tree, index and commit inputs. Project Manifest
+files retain their ecosystem; Component bindings retain `manifests` as path evidence.
+Components provide the granularity for lint, test and packaging operations. Discovery prefers
+manifests, then Makefiles with unknown language. Without either, the repository has no
+recognized Component; no root Component or tool-specific configuration file is created.
+See [repository contract](../../docs/repository.md) and [snapshot v2](../../docs/snapshot.md).
+
+### Component content identities
+
+```python
+from repokit import component_scopes, inspect, snapshot
+
+layout = inspect(repository)
+contents = snapshot(repository, scopes=component_scopes(layout))
+for component in contents.scopes:
+    print(component.name, component.digest, component.complete)
+```
+
+Verify layout/content consistency in the calling operation. These scopes follow file
+ownership, not transitive build dependencies; see [Snapshot](../../docs/snapshot.md).
+
+## Makefile validation
+
+```python
+from repokit import plan_validation, execute_validation
+
+plan = plan_validation(repo, components=("backend",), checks=("lint", "test"))
+report = execute_validation(plan, timeout=600)
+# Use report.complete and report.passed together, not an isolated command exit code.
+```
+
+Planning never executes Make. Targets and optional LINT_FILES/TEST_FILES filtering follow
+[the shared Makefile contract](../../docs/validation.md). Prepare dependencies and run any
+formatter before planning. Execution freezes the environment, bounds subprocesses, and
+checks repository contents once before and once after the round. Reports contain execution
+facts; callers own persistence, reuse and workflow gates.
+
+PR lifecycle queries are native Python: `repokit.forge.PullRequestObserver` owns durable observations,
+terminal-state convergence, retries and optional periodic maintenance. `PullRequestContext` relates PRs
+to live local branches and checkouts without choosing workflow or cleanup policy. See [PR contracts](../../docs/pr.md).
+
+
+PR 创建和复用使用 `repokit.forge.ensure_pull_request`，无需调用方解析目标仓或默认分支。
+Git 提交与推送使用 `repokit.git.commit` / `push`；提交范围、验证门禁和动作顺序仍由调用方负责。
+完整契约见 [PR](../../docs/pr.md#创建与复用) 与 [Git](../../docs/git.md)。

compforge_repokit-0.15.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+repokit/__init__.py,sha256=jOrujMX5YX2Tg7K9P3CiK_JEVwQxQbF0TLcq-AHLMwQ,1949
+repokit/_git.py,sha256=ZG0RmvyJyoEMUPDNWtZIBzRGrELV9De4zoPT1r3M23Y,7231
+repokit/_inspect.py,sha256=DLvhhnqmRnqZ5cUz0I3XTA15fKeY0KF6nDNkruuRBgE,2365
+repokit/_language.py,sha256=VPY-Rt4R9w7CrwR60O3KDyb8BZo6OA8mUdTtyFB_HX8,841
+repokit/_layout.py,sha256=0Fh2o18c2URNHfzRuLXcwD9d3O4eupuMzS30c8ZGfEE,5874
+repokit/_process.py,sha256=hcIVDko1k9wPuumhQdWJmG2nEli_rVbz4epf1FiIjPM,4929
+repokit/_staging.py,sha256=IYrwLJGJlKAhLm6gEx9adqQp1513IN7bH3iq7f8I7QM,2061
+repokit/budget.py,sha256=FfI9QIVzyipTkykNyUH8fpSf7JNVxtjCKfBDDdp318Y,1325
+repokit/dependencies.py,sha256=NPKyWtBG8Rr2Do9gbegWgnJzm_WqMYF_lbaY3hElVIU,15015
+repokit/git.py,sha256=7XdbLA2dW5PzmLlOcsKpT9dW-bXcZaRZfA18P522nVY,10349
+repokit/git_index.py,sha256=ck1kzGtCUF1WuleMQzHWwn_B9dBPiJcNygec7p6Y3V4,9684
+repokit/git_state.py,sha256=_oILnnWRe1hkyUMTt0tLHWN3BfcWcl7E_3HVE3uRWtQ,17506
+repokit/languages.json,sha256=as3uFeqWw-SovOSHSYHpD3ezurHt21c8uEZWMr07wVc,22404
+repokit/model.py,sha256=myuv9HzQrX6I8XClQhKTpT2YSh1GWrnYAV3cyJFZQ80,1794
+repokit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+repokit/remote.py,sha256=yDb5vaQKDo07DtbJKsqaBF1DuCax5hc5JPbCQwUKV74,1344
+repokit/repository.py,sha256=cGToy2aJQfwccFw4Ez8qkXTfGZ5WXqreI4CSNkJ_RdE,3364
+repokit/snapshot.py,sha256=eCs5g9a9g2XSWRPDsfaNj2lt_YYeInmKe4owF4g0HXo,10187
+repokit/stash.py,sha256=3TX58q0vaWYSZPyf0LHpn-Xjpw0QflAup9gqJh7IWQg,2065
+repokit/tree.py,sha256=Ke0YCvBuLvyM9n51t4VEOLp32o4bXDUNmXFHoCIvOU8,6194
+repokit/validation.py,sha256=iVitF-ZuWoLS_ZAIfZ3uFTH3h27VMgJqXxpeEs4G5Zo,17942
+repokit/forge/__init__.py,sha256=4_Z3jJlAIK0IufxcrUiT_VP_8tuhzqAwdh9mXSeMLEM,757
+repokit/forge/_http_state.py,sha256=X4YPRmko9txmsq2pj1T7XPGEAk0-be23xYo0ODyj7fU,3483
+repokit/forge/_page.py,sha256=8abeVy0UKWqLIE77E-1K-3z3r9B0Ya2I3vjtCIkqpP4,1331
+repokit/forge/_rest.py,sha256=oMithQcRNkqsCiUId0Ivw4DC9B9CFSykTvOWlQjatoY,10377
+repokit/forge/creation.py,sha256=xCpXHKBQ8_tSicJ3nkHTpLozEzH5OCt2JrK8oUcLcc8,3056
+repokit/forge/github.py,sha256=sbyhyjr-8pe8PK6xGvvDHZZ6-yhd6MnHS9pw0K4qG-Y,18366
+repokit/forge/gitlab.py,sha256=pVC1dCfgZhC-EDJb4GsiJj8iJzj3rUDat9OeJWh0Gcc,17105
+repokit/forge/model.py,sha256=ULg7WsKdngqb1XoFb7jjuxeqTWk60vC89YcOTBbPIzI,15003
+repokit/forge/observation/__init__.py,sha256=QChAwEBoZXoxKpgI5je27MOJOkCg_3U8Qh6RI3oxkms,521
+repokit/forge/observation/context.py,sha256=XT2Co2d_wacErWJRmREbDIgUrwbK5DJJzZ6po7lm-YU,11155
+repokit/forge/observation/model.py,sha256=hdkvJJU4Vx5jQxg3eOT537hi0KqTUORML6-h9q2SLR0,945
+repokit/forge/observation/service.py,sha256=UrFkiIM2G0krREe5SEyNXPrhe3PlI1tPhEDf4iXuDsQ,11997
+repokit/forge/observation/store.py,sha256=xgrzRD2TLkKYcHo-2uoZ-IzZSnYwrC3RwcO-AP3Yhwo,4786
+compforge_repokit-0.15.0.dist-info/METADATA,sha256=xZKJSTlqxmsgKCQt_e0IND9aYj25kfnlOd3qfmak_jg,5627
+compforge_repokit-0.15.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+compforge_repokit-0.15.0.dist-info/RECORD,,

compforge_repokit-0.15.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

repokit/__init__.py

@@ -0,0 +1,40 @@
+"""Native repository organization; using Git paths and metadata."""
+
+from harness_common import Component as Component
+from harness_common import Forge as Forge
+from harness_common import Product as Product
+from harness_common import Repository as Repository
+
+from ._inspect import inspect as inspect
+from .budget import operation as operation
+from .dependencies import DependencyEnvironment as DependencyEnvironment
+from .dependencies import DependencyPreparation as DependencyPreparation
+from .dependencies import inspect_dependencies as inspect_dependencies
+from .dependencies import prepare_dependencies as prepare_dependencies
+from .model import ComponentBinding as ComponentBinding
+from .model import Diagnostic as Diagnostic
+from .model import InspectReport as InspectReport
+from .model import Layout as Layout
+from .model import PackageTool as PackageTool
+from .model import owner as owner
+from .snapshot import ScopedSnapshot as ScopedSnapshot
+from .snapshot import Snapshot as Snapshot
+from .snapshot import SnapshotScope as SnapshotScope
+from .snapshot import component_scopes as component_scopes
+from .snapshot import snapshot as snapshot
+from .tree import Directory as Directory
+from .tree import File as File
+from .tree import Manifest as Manifest
+from .tree import TreeReport as TreeReport
+from .tree import tree as tree
+from .validation import CheckResult as CheckResult
+from .validation import CheckSpec as CheckSpec
+from .validation import ComponentValidationPlan as ComponentValidationPlan
+from .validation import ComponentValidationResult as ComponentValidationResult
+from .validation import ValidationPlan as ValidationPlan
+from .validation import ValidationReport as ValidationReport
+from .validation import execute_validation as execute_validation
+from .validation import lint as lint
+from .validation import plan_validation as plan_validation
+from .validation import test as test
+from .validation import validate as validate

repokit/_git.py

@@ -0,0 +1,177 @@
+"""Read Git catalogs and layout metadata without reading source contents."""
+
+import os
+import stat
+from pathlib import Path
+
+from ._layout import Catalog, needs_content, valid_path
+from ._process import Budget, run
+
+MAX_FILE_BYTES = 2 << 20
+MAX_TOTAL_BYTES = 128 << 20
+MAX_FILES = 10_000
+
+
+class Git:
+    def __init__(self, root: Path, budget: Budget):
+        self.root = root
+        self.budget = budget
+
+    def run(
+        self,
+        args: list[str],
+        *,
+        input: bytes = b"",
+        allow_missing: bool = False,
+        max_output: int = 16 << 20,
+    ) -> bytes:
+        return run(
+            self.root,
+            args,
+            self.budget,
+            input=input,
+            allow_missing=allow_missing,
+            max_output=max_output,
+        )
+
+    def gitlink_oid(self, name: str, oid: str) -> str:
+        """Read checkout HEAD only; uninitialized entries retain the index reference."""
+        path = self.root / name
+        try:
+            (path / ".git").lstat()
+        except FileNotFoundError:
+            return oid
+        if path.resolve() != path:
+            raise ValueError(f"symlinked gitlink checkout: {name}")
+        child = Git(path, self.budget)
+        root = os.fsdecode(child.run(["rev-parse", "--show-toplevel"])).removesuffix("\n")
+        if Path(root) != path:
+            raise ValueError(f"invalid gitlink checkout: {name}")
+        return child.run(["rev-parse", "--verify", "HEAD"]).decode().strip()
+
+    def catalog(self, head: str, staged: bool) -> Catalog:
+        committed = bool(head) or staged
+        output = self.run(
+            ["ls-tree", "-r", "-z", "--full-tree", head] if head else ["ls-files", "--stage", "-z"]
+        )
+        entries: dict[str, str] = {}
+        for entry in output.split(b"\0"):
+            if not entry:
+                continue
+            fields, separator, raw_name = entry.partition(b"\t")
+            parts = fields.split()
+            name = os.fsdecode(raw_name)
+            if not separator or len(parts) != 3 or not valid_path(name):
+                raise ValueError("invalid Git catalog entry")
+            mode = parts[0]
+            if not head and parts[2] != b"0":
+                raise ValueError(f"unmerged index entry: {name}")
+            if mode == b"160000":
+                continue
+            if mode == b"120000" and committed:
+                if needs_content(name):
+                    raise ValueError(f"metadata {name} is a symlink")
+                continue
+            if mode not in (b"100644", b"100755", b"120000"):
+                raise ValueError(f"unsupported Git entry mode for {name}")
+            entries[name] = parts[2 if head else 1].decode("ascii")
+        if not committed:
+            for raw_name in self.run(["ls-files", "-z", "--others", "--exclude-standard"]).split(
+                b"\0"
+            ):
+                name = os.fsdecode(raw_name)
+                if not name or name.endswith("/"):
+                    continue
+                if not valid_path(name):
+                    raise ValueError("unsafe repository path")
+                entries[name] = ""
+        if len(entries) > MAX_FILES:
+            raise ValueError("repository exceeds 10000 files")
+        files: Catalog = {}
+        selected: list[tuple[str, str]] = []
+        total = 0
+        for name in sorted(entries):
+            self.budget.remaining()
+            if committed:
+                files[name] = None
+                if needs_content(name):
+                    oid = entries[name]
+                    selected.append((name, oid))
+                continue
+            path = self.root / name
+            try:
+                info = path.lstat()
+            except FileNotFoundError:
+                continue
+            if not stat.S_ISREG(info.st_mode):
+                if needs_content(name):
+                    raise ValueError(f"metadata {name} is not a regular file")
+                continue
+            if path.parent.resolve() != path.parent:
+                if needs_content(name):
+                    raise ValueError(f"metadata {name} has a symlinked directory")
+                continue
+            files[name] = None
+            if not needs_content(name):
+                continue
+            if info.st_size > MAX_FILE_BYTES:
+                raise ValueError(f"metadata {name} exceeds {MAX_FILE_BYTES} bytes")
+            fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+            try:
+                if not stat.S_ISREG(os.fstat(fd).st_mode):
+                    raise ValueError(f"metadata {name} is not a regular file")
+                content = bytearray()
+                while len(content) <= MAX_FILE_BYTES:
+                    self.budget.remaining()
+                    chunk = os.read(fd, min(65536, MAX_FILE_BYTES + 1 - len(content)))
+                    if not chunk:
+                        break
+                    content.extend(chunk)
+                if len(content) > MAX_FILE_BYTES:
+                    raise ValueError(f"metadata {name} exceeds {MAX_FILE_BYTES} bytes")
+                total += len(content)
+                if total > MAX_TOTAL_BYTES:
+                    raise ValueError("metadata exceeds 128 MiB")
+                files[name] = bytes(content)
+            finally:
+                os.close(fd)
+        if selected:
+            self._blobs(selected, files)
+        return files
+
+    def _blobs(self, selected: list[tuple[str, str]], files: Catalog) -> None:
+        batch = ("\n".join(oid for _, oid in selected) + "\n").encode("ascii")
+        headers = self.run(["cat-file", "--batch-check"], input=batch).splitlines()
+        if len(headers) != len(selected):
+            raise ValueError("invalid Git blob batch")
+        sizes: list[int] = []
+        total = 0
+        # Check immutable object sizes before reading any metadata contents.
+        for (name, oid), header in zip(selected, headers, strict=True):
+            fields = header.split()
+            if len(fields) != 3 or fields[:2] != [oid.encode("ascii"), b"blob"]:
+                raise ValueError("invalid Git blob")
+            size = int(fields[2])
+            if size < 0:
+                raise ValueError("invalid Git blob size")
+            if size > MAX_FILE_BYTES:
+                raise ValueError(f"metadata {name} exceeds {MAX_FILE_BYTES} bytes")
+            total += size
+            if total > MAX_TOTAL_BYTES:
+                raise ValueError("metadata exceeds 128 MiB")
+            sizes.append(size)
+        data = self.run(
+            ["cat-file", "--batch"], input=batch, max_output=total + len(selected) * 128
+        )
+        offset = 0
+        for (name, oid), size in zip(selected, sizes, strict=True):
+            end = data.find(b"\n", offset)
+            if end < 0 or data[offset:end] != f"{oid} blob {size}".encode("ascii"):
+                raise ValueError("invalid Git blob header")
+            offset = end + 1
+            if data[offset + size : offset + size + 1] != b"\n":
+                raise ValueError("truncated Git blob")
+            files[name] = data[offset : offset + size]
+            offset += size + 1
+        if offset != len(data):
+            raise ValueError("unexpected Git blob bytes")

repokit/_inspect.py

@@ -0,0 +1,70 @@
+"""One operation owns input selection, deadline and consistency observation."""
+
+import math
+import os
+from pathlib import Path
+from threading import Event
+
+from ._git import Git
+from ._layout import load
+from ._process import Budget
+from .model import Diagnostic, InspectReport
+
+
+def inspect(
+    repository: str | os.PathLike[str] = ".",
+    *,
+    head: str | None = None,
+    staged: bool = False,
+    timeout: float = 5.0,
+    cancel: Event | None = None,
+) -> InspectReport:
+    """Inspect organization using Git paths and layout metadata only.
+
+    timeout is a whole-call budget in seconds; cancel accepts a threading.Event.
+    Git processes are killed and reaped on timeout/cancellation. Filesystem reads and
+    Python projection check the budget between operations. Concurrent catalog changes
+    return complete=False; consumers decide whether to accept the observation.
+    """
+    if head and staged:
+        raise ValueError("head and staged are mutually exclusive")
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError("timeout must be positive and finite")
+    budget = Budget(timeout, cancel)
+    budget.remaining()
+    start = Path(repository).resolve(strict=True)
+    initial = Git(start, budget)
+    root = Path(
+        os.fsdecode(initial.run(["rev-parse", "--show-toplevel"])).removesuffix("\n")
+    ).resolve()
+    git = Git(root, budget)
+    commit = (
+        git.run(["rev-parse", "--verify", "--end-of-options", head + "^{commit}"]).decode().strip()
+        if head
+        else ""
+    )
+    files = git.catalog(commit, staged)
+    origin = (
+        git.run(["config", "--get", "remote.origin.url"], allow_missing=True)
+        .decode("utf-8", errors="replace")
+        .rstrip("\n")
+    )
+    layout = load(files, origin)
+    complete = bool(commit) or files == git.catalog(commit, staged)
+    budget.remaining()
+    return InspectReport(
+        repository=layout.repository,
+        components=layout.components,
+        checkout=str(root),
+        input="commit" if commit else "index" if staged else "working_tree",
+        head=commit or None,
+        complete=complete,
+        diagnostics=()
+        if complete
+        else (
+            Diagnostic(
+                "inspection_changed",
+                "repository paths or layout metadata changed during inspection",
+            ),
+        ),
+    )

repokit/_language.py

@@ -0,0 +1,23 @@
+"""Filename metadata generated from pinned CodeGraph, without loading a parser."""
+
+import json
+import posixpath
+from importlib.resources import files
+
+_CATALOG: dict[str, dict[str, str]] = json.loads(
+    files("repokit").joinpath("languages.json").read_text(encoding="utf-8")
+)
+
+
+def language(path: str) -> str:
+    base = posixpath.basename(path)
+    ext = ("." + base.rsplit(".", 1)[1]).lower() if "." in base else ""
+    if ext in _CATALOG["overrides"]:
+        return _CATALOG["overrides"][ext]
+    if base in _CATALOG["filenames"]:
+        return _CATALOG["filenames"][base]
+    suffixes = [base[i:] for i in range(len(base) - 1, 0, -1) if base[i] == "."][:4]
+    for suffix in reversed(suffixes):
+        if suffix in _CATALOG["registry"]:
+            return _CATALOG["registry"][suffix]
+    return _CATALOG["fallback"].get(ext, "")

repokit/_layout.py

@@ -0,0 +1,187 @@
+"""Pure organization projection from a version's paths and necessary metadata."""
+
+import json
+import posixpath
+from collections.abc import Mapping
+
+from harness_common import Forge, Repository
+
+from .model import ComponentBinding, Layout, PackageTool
+from .remote import parse_remote_url
+
+Catalog = dict[str, bytes | None]
+_EXCLUDED = {
+    "node_modules",
+    "vendor",
+    "venv",
+    "env",
+    "dist",
+    "build",
+    "target",
+    "__pycache__",
+    "testdata",
+}
+_MARKERS = (
+    ("python", "pyproject.toml", "setup.py"),
+    ("go", "go.mod"),
+    ("node", "package.json"),
+    ("rust", "Cargo.toml"),
+)
+
+
+def manifest_ecosystem(path: str) -> str:
+    return next(
+        (ecosystem for ecosystem, *names in _MARKERS if posixpath.basename(path) in names), ""
+    )
+
+
+def valid_path(name: str) -> bool:
+    return (
+        name not in ("", ".", "..")
+        and "\0" not in name
+        and "\\" not in name
+        and not name.startswith(("/", "../"))
+        and posixpath.normpath(name) == name
+        and not name.endswith("/")
+    )
+
+
+def needs_content(name: str) -> bool:
+    return posixpath.basename(name) == "package.json"
+
+
+def _origin(origin: str) -> Repository | None:
+    remote = parse_remote_url(origin)
+    if remote is None:
+        return None
+    forge = {"github.com": "github", "gitlab.com": "gitlab"}.get(remote.host, remote.host)
+    return Repository(Forge(forge), remote.path)
+
+
+def _skip(name: str) -> bool:
+    return any(part.startswith(".") or part in _EXCLUDED for part in name.split("/")[:-1])
+
+
+def _detect(files: Catalog, root: str) -> str:
+    for ecosystem, *markers in _MARKERS:
+        for marker in markers:
+            name = posixpath.join(root, marker).removeprefix("./")
+            if name not in files:
+                continue
+            if ecosystem != "node":
+                return ecosystem
+            text = (files[name] or b"").decode("utf-8", errors="replace").lower()
+            tsconfig = posixpath.join(root, "tsconfig.json").removeprefix("./")
+            return (
+                "typescript"
+                if "typescript" in text or "@types/" in text or tsconfig in files
+                else "javascript"
+            )
+    return ""
+
+
+def _discover(files: Catalog) -> list[str]:
+    """Find Component boundaries independently of their ancestors.
+
+    @spec Manifest and Makefile boundaries remain discoverable at every nesting depth.
+    @link component://docs/repository.md
+    """
+    candidates: set[str] = set()
+    for name in files:
+        if _skip(name):
+            continue
+        if manifest_ecosystem(name) or posixpath.basename(name) == "Makefile":
+            candidates.add(posixpath.dirname(name) or ".")
+    return sorted(candidates)
+
+
+# Match Go's JSON field semantics when reading package-manager evidence.
+def _invalid_constant(value: str) -> object:
+    raise ValueError(f"invalid JSON constant: {value}")
+
+
+def _json(data: bytes) -> object:
+    # Match UTF-8 JSON in Go/TS, not Python's UTF-16 auto-detection or NaN extension.
+    return json.loads(data.decode("utf-8", errors="replace"), parse_constant=_invalid_constant)
+
+
+def _object(value: object) -> dict[str, object]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
+        raise ValueError("expected an object")
+    return value
+
+
+def _field(value: Mapping[str, object], key: str, default: object = None) -> object:
+    return next(
+        (value[name] for name in reversed(list(value)) if name.lower() == key.lower()), default
+    )
+
+
+def _string(value: object) -> str:
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise ValueError("expected a string")
+    return value
+
+
+def _tools(files: Catalog, root: str) -> tuple[PackageTool, ...]:
+    found: dict[str, PackageTool] = {}
+
+    def add(name: str, version: str, evidence: str) -> None:
+        old = found.get(name, PackageTool(name))
+        found[name] = PackageTool(name, (*old.evidence, evidence), version or old.version)
+
+    manifest = posixpath.join(root, "package.json").removeprefix("./")
+    if data := files.get(manifest):
+        try:
+            metadata = _object(_json(data))
+            manager = _string(_field(metadata, "packageManager"))
+            name, _, version = manager.partition("@")
+            if name in ("npm", "pnpm", "yarn", "bun"):
+                add(name, version, manifest + "#packageManager")
+        except (ValueError, UnicodeError):
+            pass  # Malformed package.json remains a marker; lockfile evidence survives.
+    for file, tool in (
+        ("go.mod", "go"),
+        ("uv.lock", "uv"),
+        ("poetry.lock", "poetry"),
+        ("Pipfile.lock", "pipenv"),
+        ("package-lock.json", "npm"),
+        ("npm-shrinkwrap.json", "npm"),
+        ("pnpm-lock.yaml", "pnpm"),
+        ("yarn.lock", "yarn"),
+        ("bun.lock", "bun"),
+        ("bun.lockb", "bun"),
+    ):
+        name = posixpath.join(root, file).removeprefix("./")
+        if name in files:
+            add(tool, "", name)
+    return tuple(
+        PackageTool(t.name, tuple(sorted(t.evidence)), t.version) for _, t in sorted(found.items())
+    )
+
+
+def load(files: Catalog, origin: str) -> Layout:
+    repo = _origin(origin)
+    bindings = tuple(
+        ComponentBinding(
+            repository=repo or Repository(Forge(""), ""),
+            name=root,
+            root=root,
+            products=(),
+            language=_detect(files, root) or None,
+            package_tools=_tools(files, root),
+            manifests=tuple(
+                sorted(
+                    name
+                    for name in files
+                    if (posixpath.dirname(name) or ".") == root and manifest_ecosystem(name)
+                )
+            ),
+        )
+        for root in _discover(files)
+    )
+    return Layout(repo, bindings)