Skip to content

extensions.md

Latest commit

 

History

History
53 lines (40 loc) · 2.11 KB

extensions.md

File metadata and controls

53 lines (40 loc) · 2.11 KB
Raw

Extensions: forge rules & status provider

Forge rules — source permalinks for self-hosted git

The metadata sidecar stores, per repo, its forge kind and web base URL, so every search result and graph node can carry a permalink (https://…/blob/<commit>/<path>#L12-L34). Detection from the origin remote:

  1. an explicit rule in the manifest (exact host match) wins,
  2. else a substring heuristic: host containing github → github, gitlab → gitlab,
  3. else other → no URL (an empty link beats a wrong one).
forges:
  - {host: git.example.org, kind: gitlab}     # self-hosted GitLab
  - {host: ghe.corp.internal, kind: github}   # GitHub Enterprise

kind decides the permalink shape (/-/blob/ + #L12-34 for GitLab, /blob/ + #L12-L34 for GitHub). SSH remotes, custom ports, and .git suffixes are parsed away. Repos whose HEAD is not pushed get a default-branch link instead of a 404-prone commit link.

Status provider — governance labels in the ranking

If your workspace knows which code is active / doubtful / dead (a pipeline inventory, a service catalog, CODEOWNERS-derived data…), plug it in and repolens will (a) stamp each indexed file with its status, (b) let queries filter on it (search_code(..., status="actif")), and (c) nudge ranking — dead code sinks to the bottom of the top-k even when semantically relevant.

extensions:
  status_provider: "my_pkg.governance:file_status"

The hook is a plain callable:

def file_status(base_dir: Path, manifest) -> dict[str, str]:
    """Return { "repo/relative/path.py": "label", ... }.

    Called once per `repolens meta` / `repolens build` run, where the .git
    directories live. Unlisted files simply get no status.
    """

Labels are free-form, but the built-in rerank penalties recognize mort (dead, sinks hard), douteux (doubtful, small penalty) and actif (small boost) — other labels are stored and filterable without affecting rank.

The module must be importable where the build runs (installed, or PYTHONPATH). A misconfigured dotted path fails at build time with the exact spec in the message.