Skip to content

README.md

Latest commit

 

History

History
64 lines (50 loc) · 3.22 KB

README.md

File metadata and controls

64 lines (50 loc) · 3.22 KB
Raw

repocli 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:

python -m pip install ./toolkit/python
from repocli 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 fix, make lint, make test, make build. Tests consume the shared conformance/inspect cases and generated filename probes. See the inspection contract.

Repository toolkit

工具包提供仓库组织、内容身份与 Git 查询。Python 还提供 worktree、提交、推送、rebase 和 GitHub/GitLab 的 PR/MR 操作；调用方直接导入库，组织自己的开发流程。 分析接口保持只读，操作接口接收明确参数，不隐式执行验证或管理任务状态。

详见 操作契约。

Repository entries

tree lists directories, files, Git entry kinds and known roles independently of Component configuration, for working-tree, index and commit inputs. Project Manifest files retain their ecosystem; Component bindings retain manifests as path evidence. Repositories without manifests or explicit declarations have no implicit root Component. See repository contract and snapshot v2.