repo-adapter-api

A repo adapter teaches dev how to hook into a repository: how its tests are laid out, what it ignores, which commands its checks run, and how its packaging is read. dev’s commands – build, test, lint, format, typecheck, sync, generate types, and the source analysis behind the dependency checks – are the same for every repository, and each asks the adapter the repository names for the part that is not: which process to run, which directories hold tests, what a walk passes over, what a source file imports. The language core is one part of an adapter: it holds the definition of a language – how a source file imports, how the language’s packaging metadata is spelled, how its test runner is told what to leave out – as code written once per language. Most adapters are a configuration document, adapter.yml, over an existing core, the document stating what one repository layout configures of it. A language with no core is adapted by writing one, or by an adapter written whole, one object implementing every method. The published Python adapter, language:python, is a document over the Python core, language:python-core. This package, repo-adapter-api:repo-adapter-api, is the contract all of them implement.

Setting one up

This takes a repository with no adapter to one whose gate passes. It assumes dev --version answers and the repository has a clean working tree. Every file named below is at the repository’s root unless the step says otherwise. Where a command refuses, its message names a code and the repair; do what it says and run the step again.

  1. Choose the adapter. For each language the repository holds, pick one, in this order:

    • An adapter your organization already published into its adapter catalog (step 6), where its document matches this repository’s layout and commands. pkgmgr pkg list --catalog-root "$CATALOG_REPO_ADAPTER" --namespace language lists them, and each has a template of the same name, whose adapter.yml is the document to compare. Name its coordinate as it is and skip steps 2 to 4: the repository writes no document of its own.
    • The published Python adapter, language:python, where the repository keeps its tests in __tests__ packages divided into tier folders (__tests__/__unit__/, __tests__/__integration__/) and lints with ruff, formats with ruff and type-checks with pyright, each started through uv. Skip steps 2 to 4.
    • A document over the Python core, language:python-core, for any other Python layout. This is the usual case. Do steps 2 to 4.
    • A core of your own, for a language with no published core: a package exporting core, implementing LanguageCore (“Writing a core or a whole adapter”, below). Then do steps 2 to 4 with a document naming it.

    Done when you know the coordinate the repository will name: language:python, or one of your own for a document, language:<project>-<language> (language:acme-python), <project> being the name step 5 gives the repository.

  2. Create the document at .dev-tool/adapters/<language>/packages/repo_adapter/adapter.yml. The directory may be anywhere in the repository, but the path must end packages/repo_adapter/adapter.yml, which is where an adapter is read from. Start from a template rather than a blank file. Where your organization’s adapter catalog holds one for the language, copy its directory, "$CATALOG_REPO_ADAPTER/templates/<name>/", to .dev-tool/adapters/<language>/; pkgmgr template list --catalog-root "$CATALOG_REPO_ADAPTER" lists them. Otherwise start from this, which is the published Python adapter less what is particular to its layout:

    schemaVersion: '0.0.0-dev'
    core: language:python-core
    testDirectories:
    - tests
    testFilePatterns:
    - test_*.py
    - '*_test.py'
    nonSourcePatterns:
    - __pycache__
    - .mypy_cache
    - .ruff_cache
    - .pytest_cache
    - /.venv*
    - '*.egg-info'
    gitignoreRules:
    - pattern: '**/__pycache__'
      why: The compiler's cache, which appears beside any module it has run.
    - pattern: '**/*.py[cod]'
      why: The compiled files themselves, where one is written without its directory.
    - pattern: .pytest_cache
      why: The test runner's cache.
    - pattern: .ruff_cache
      why: The linter's cache.
    - pattern: .mypy_cache
      why: A type checker's cache.
    - pattern: .venv*
      why: An environment installed into the checkout.
    - pattern: '*.egg-info'
      why: Packaging metadata a build writes.
    commands: {}

    Done when the file exists. It is checked against its schema in step 8.

  3. State the layout in the document. Change each of these to what the repository has; “The adapter document”, below, says what each means:

    • testDirectories – where tests are kept. tests matches a directory of that name at any depth; /tests only at a module’s root.
    • testFilePatterns – the test file names the runner collects where the repository’s runner configuration names none.
    • tierDirectory – only if tests are already divided into folders by kind, such as tests/unit/ and tests/integration/: {tier} there. Leave it out otherwise.
    • nonSourcePatterns – add every cache, environment and output directory the repository’s own tools write (.tox, .nox, htmlcov). The repository’s .gitignore is the list of candidates.
    • gitignoreRules – what the language’s tools leave behind, each with its reason. The repository’s own rules do not go here.

    Done when every field states this repository’s answer.

  4. Declare the commands under commands, one entry per verb the repository has a tool for – test:, lint:, format:, typecheck:, and sync: where one command installs its development environment – each as the repository’s CI already runs it. Where the repository has no CI, declare each as it is run by hand. Declare format: and lint: in their repairing form: the gate runs format and lint --fix to repair what they find, and a gate asked only to check (dev gate --validate) refuses a tree they changed, so no check-only form is needed. Declare the check form instead (--check, --no-fix) only where the gate must never rewrite the repository’s source, as when somebody else’s repository is being onboarded: the gate then fails where it would have repaired. lint: passes fix through as the flag that asks its tool for repairs:

    commands:
      test:
        executable: uv
        args: [run, pytest]
        passthroughArgs:
        - value: paths
      lint:
        executable: uv
        args: [run, ruff, check]
        passthroughArgs:
        - value: fix
          flag: --fix
        - value: paths
      format:
        executable: uv
        args: [run, ruff, format]
        passthroughArgs:
        - value: paths

    format: takes paths alone, and typecheck: the same. A verb the repository has no tool for is not declared, and its check is taken out of the gate in step 7, so the first gate passes. Declare test: whenever the repository’s tests need its own environment: left out, the Python core runs pytest under the tool’s interpreter, where the repository’s dependencies are not installed. sync: is no check of the gate: declare it where one command installs the development environment (uv sync), and it needs no omission. Done when each verb the repository runs has an entry.

  5. Name the adapter in manifest.yml, creating the file where the repository has none. Set repoAdapter to the coordinate from step 1, at the top and on each module the adapter reads, and declare the catalog the coordinate resolves against. Declare the repository’s own code as modules too, one per package, each with its rootDir, the entryPoint file inside it, repoAdapter and kind: library: the dependency checks the gate runs read only the modules a manifest declares, so code left undeclared is checked by none of them. For a document, also declare it as a module whose runtimeCoordinate is its coordinate. A complete file, for a repository whose one package is src/acme:

    schemaVersion: '0.0.0-dev'
    project: acme
    version: 0.1.0
    repoAdapter: language:acme-python
    catalogs:
      repo-adapter:
        path: repo-adapter
        pkg: repo-adapter
    modules:
    - name: acme
      rootDir: src/acme
      entryPoint: __init__.py
      repoAdapter: language:acme-python
      kind: library
    - name: acme-python
      rootDir: .dev-tool/adapters/python/packages/repo_adapter
      entryPoint: adapter.yml
      repoAdapter: language:acme-python
      runtimeCoordinate: language:acme-python
      kind: library

    schemaVersion is the version of the manifest’s schema that the tools read, written whole; a file stating another is refused as it loads, with a message naming the version the loader expects (declares '…' but loader expects '…'), which is the one to write. project is the repository’s name, and the namespace its packages are published under. version is the version the repository is at, major.minor.patch, and every module’s version. Keep modules sorted by name.

    Done when dev module list lists the adapter’s module and each of the repository’s own. Every run of dev in the repository writes its log and its record of commands into logs/, so git status shows that directory until step 9’s ignore file covers it.

  6. Wire the adapter catalog in .pkgmgr/config.yml to your organization’s adapter catalog. That catalog is one repository every repository of the organization pulls its adapters from, and the one you publish your own adapters into. It is made once from the shared adapter catalog, whose address came with the tools: as a fork of it on GitHub, or on any other forge as a new repository seeded with git clone --bare <shared address> and git push --mirror <your address>. Clone it once on each machine, give the clone the shared catalog as its upstream remote (git remote add upstream <shared address>), which is how new releases of the cores reach it, and set the environment variable CATALOG_REPO_ADAPTER to the clone’s directory. Set it as a user variable for a clone of your own, kept under the toolchain’s per-user directory (%LOCALAPPDATA%\toolchain\repo-adapter, ~/.local/share/toolchain/repo-adapter). Set it as a machine variable for a clone every user of the machine shares (%ProgramData%\toolchain\repo-adapter, /var/lib/toolchain/repo-adapter), which takes administrator rights. A CI job clones the catalog into its workspace and sets the variable for the steps that run the tools. The repository’s configuration then names the clone through the variable, so the same file reads whichever clone each machine holds:

    schemaVersion: '0.0.0'
    catalogs:
      repo-adapter:
        stores:
          organization:
            location: ${CATALOG_REPO_ADAPTER}
            updateOnRead: true
            updateOnWrite: true
        upstream:
        - store: organization
          pullOnly: true

    updateOnRead brings the clone up to date before an adapter is read from it, and updateOnWrite before one is published into it. A run where CATALOG_REPO_ADAPTER is unset is refused by name as STORE_LOCATION_VARIABLE_UNSET, never read as some other directory. Done when the variable is set and pkgmgr pkg list --catalog-root "$CATALOG_REPO_ADAPTER" lists the language cores.

  7. State the tiers and the gate in .dev-tool/config.yml. Without tierDirectory, write testTiers: []: the repository has no tiers and every run collects every test. With one, list each tier as name, and mark the one a plain dev test collects default: true. Set ownRoots to the directories that hold source and tests. Take out of the gate each check whose verb step 4 declared nothing for. There are two ways: remove it from a gate list the repository states, or list it under gateOmissions, by the name the gate reports it under. gateOmissions is the usual way, since it leaves the default list to dev-tool, so a check the tools add later still reaches the repository; a name the gate does not hold is refused as GATE_OMISSION_UNKNOWN, listing the checks it does:

    schemaVersion: '0.0.0-dev'
    testTiers: []
    ownRoots:
    - src
    - tests
    gateOmissions:
    - typecheck

    Done when the file states the tiers, the roots and an omission for each verb with no tool.

  8. Obtain the adapter: dev vendor. It resolves each coordinate the manifest names, reads each document against its schema, and unpacks each core the documents name into repo-adapter/, recording which answered in .dev-tool/resolved.yml. A document that does not fit is refused as REPO_ADAPTER_CONTRACT_UNMET naming the field; a repository whose requires-python is outside the core’s versions is refused as REPO_ADAPTER_LANGUAGE_VERSION_UNSERVED, which no setting repairs. One refused as REPO_ADAPTER_UNAVAILABLE found the catalog and no release of the core in it; dev vendor has written the adapter catalog’s own configuration by then, so pkgmgr pkg list --catalog-root repo-adapter --store shared --namespace language --versions lists the releases the shared catalog holds, which tells a wrong address from a wrong coordinate. Done when dev vendor --validate prints the adapter it holds and exits 0, as Vendored adapter: language:python-core@0.0.0 (0.0.0) -> <repository>/repo-adapter – the core where the coordinate is a document, with what answered for it in brackets. A copy behind what the catalog holds is printed as a Stale: <coordinate> line instead, and the run exits 1; dev vendor without --validate writes it again.

  9. Ignore what was obtained: dev gitignore gen. It writes the whole .gitignore: the adapter’s gitignoreRules, and the framework’s own rules for what its tools write in a checkout – logs/, the catalogs and stores (repo-adapter/, .schema/, .command/, lib/), .dev-tool/resolved.yml, /build/ and /dist/, and the runner’s and the queue’s directories – each with the reason beside it. It refuses to replace a hand-written file while that file holds a rule it would drop, as GITIGNORE_WOULD_DROP_RULES naming each: for each rule it names, compare it with the generated rules listed above and in the adapter’s gitignoreRules – .venv/ is covered by .venv*, __pycache__/ by **/__pycache__ – and delete the rule from .gitignore where one covers it; list each rule nothing covers under gitignoreAdditions in .dev-tool/config.yml. Run it again once .gitignore holds none of the rules it named; it writes the whole file. A rule can now ignore a file the repository tracks, which git status never shows: git ls-files -ci --exclude-standard lists them. Untrack each one that is build output (git rm -r --cached <path>), or drop the rule that matches source from the adapter’s gitignoreRules. Done when dev gitignore gen --validate reports nothing out of date and git ls-files -ci --exclude-standard lists nothing.

  10. Run the gate: dev gate, then dev test. Each ends with a [PASS] or [FAIL] line per check and exits non-zero on a failure. A check whose verb the adapter does not declare fails as REPO_ADAPTER_COMMAND_NOT_IMPLEMENTED: take it out of the gate either way step 7 gives – list it under gateOmissions, the usual way, or remove it from the gate list where the repository states one – and run the gate again. Run dev gate --all once as well, which adds the checks a plain run leaves to CI; its README check lists every module’s README and reports one that is missing without refusing it, which matters only for a module released to clients. Done when all three pass and git status --short shows nothing changed under the repository’s own source and tests: the new files, the regenerated .gitignore and any build output untracked in step 9 are the setup, and are committed together.

  11. Publish the adapter into your organization’s catalog, where you wrote a document and want other repositories to take it as it is or start from it. Build its archive with dev build --libraries-only --modules <project>-<language>, which reports where it filed it. Register that archive with pkgmgr pkg register --catalog-root repo-adapter --store organization --coordinate language:<project>-<language>@<version> --source . --pkgs <archive>, at the manifest’s version; a version is written once, and the same version with other content is refused as VERSION_CLOBBER. Copy the document’s directory to repo-adapter/templates/<project>-<language>/ and push it as a template with pkgmgr template push --catalog-root repo-adapter --name <project>-<language>. Then commit what the two wrote in the clone and push it to the organization’s forge. Done when pkgmgr pkg list --catalog-root "$CATALOG_REPO_ADAPTER" --namespace language lists the adapter and pkgmgr template list --catalog-root "$CATALOG_REPO_ADAPTER" lists its template.

Reference

Importing the contract

An adapter or core author imports one name, from repo_adapter_api import adapter, and reaches through it everything an implementation writes against: the two protocols (adapter.RepoAdapter, adapter.LanguageCore), what a method is handed, what it answers with, and the helpers and constants an implementation reads (adapter.is_non_source, adapter.all_test_patterns, adapter.REPO_ADAPTER_API_VERSION). The rest of the package root is the host’s. A command producer answers with Command, which is process’s: from process import Command. The contract’s dependencies manifest, process, type and schema arrive with it.

The adapter document

Held to the schema repo-adapter-api:adapter-configuration when it is read; an unknown field or a wrong shape is refused before the core is asked anything. Every field but core may be left out.

A repository can also replace one verb’s command without an adapter of its own, under repoAdapterCommands in .dev-tool/config.yml, written the same way; that replacement wins over the adapter.

Tree patterns

Every pattern list above but gitignoreRules is a list of globs, the glob built-in, refused where the document loads if one is malformed, and read like a .gitignore line, by adapter.is_non_source and adapter.is_test_file, never by hand. Segments are separated by /. A leading / roots the pattern – at the module root for nonSourcePatterns and testDirectories – and without one it matches at any depth. *, ? and [...] match within a segment, case-sensitively; a segment of exactly ** matches any number of segments. A pattern that matches a directory covers everything beneath it.

The adapter object

A core, or an adapter written whole, states three attributes, and is checked when it is loaded (REPO_ADAPTER_CONTRACT_UNMET names every failure at once):

Every method below must be written; one inherited unchanged from the protocol is refused. No method is optional: each has an answer meaning nothing to say, given in its entry.

Methods

Written by “document” where the configuration answers it in an adapter made of a document, “core” otherwise. Every parameter is keyword-only.

Command producers. Each answers a Command describing a process the host runs, or None where the language has no such process. Those taking paths are handed absolute paths, all in one call; an empty paths is an unnarrowed run over the adapter’s default surface. Given paths, a producer narrows to them or raises AdapterSelectionUnsupported, never runs the whole target. Paths may also be a repository’s whole run, so a producer treats both alike.

Layout.

Packaging metadata. Each reads what the language’s own packaging files already state and answers it as written; empty or None where the repository states nothing the adapter reads.

Source analysis. Each raises RuntimeError naming the file where it cannot parse one.

What methods are handed and answer

Writing a core or a whole adapter

A core is a package at packages/repo_adapter exporting core, an object implementing adapter.LanguageCore: the methods above marked “core”, where those marked “handed the document” also take configuration. An adapter written whole is the same package exporting adapter instead, implementing every method of adapter.RepoAdapter; it suits a language with one layout and nothing to share. Either is published under a coordinate a document or a manifest names. An adapter imports only this contract, the packages it is built on, and the standard-library modules adapter.ADAPTER_IMPORTABLE_STANDARD_MODULES names, because it runs inside the compiled tool, which carries nothing else; a publish refuses one that imports past them as ADAPTER_IMPORTS_BEYOND_THE_CONTRACT.

Versions

REPO_ADAPTER_API_VERSION is one number for the whole contract, moved by a release of it; every core and whole adapter moves its apiVersion with it, and one stating another is refused. A document carries its own schemaVersion, the version of adapter-configuration it was written under. languageVersions is no part of either and moves when the adapter is run on another version of its language.