Native organization inspection for Git repositories: discover Components, language and tools, Depot declarations and 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:
python -m pip install ./toolkit/pythonfrom 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.
工具包提供仓库组织、内容身份与 Git 查询。Python 还提供 worktree、提交、推送、rebase 和 GitHub/GitLab 的 PR/MR 操作；调用方直接导入库，组织自己的开发流程。 分析接口保持只读，操作接口接收明确参数，不隐式执行验证或管理任务状态。
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 and snapshot v2.
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.
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. 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.
PR 创建和复用使用 repokit.forge.ensure_pull_request，无需调用方解析目标仓或默认分支。
Git 提交与推送使用 repokit.git.commit / push；提交范围、验证门禁和动作顺序仍由调用方负责。
完整契约见 PR 与 Git。