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.
-
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 languagelists them, and each has a template of the same name, whoseadapter.ymlis 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 throughuv. 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, implementingLanguageCore(“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. - An adapter your organization already published into its adapter catalog (step 6), where its document matches this repository’s layout and commands.
-
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 endpackages/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.
-
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.testsmatches a directory of that name at any depth;/testsonly 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 astests/unit/andtests/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.gitignoreis 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.
-
Declare the commands under
commands, one entry per verb the repository has a tool for –test:,lint:,format:,typecheck:, andsync: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. Declareformat:andlint:in their repairing form: the gate runsformatandlint --fixto 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:passesfixthrough 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: pathsformat:takespathsalone, andtypecheck: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. Declaretest: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. -
Name the adapter in
manifest.yml, creating the file where the repository has none. SetrepoAdapterto 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 itsrootDir, theentryPointfile inside it,repoAdapterandkind: 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 whoseruntimeCoordinateis its coordinate. A complete file, for a repository whose one package issrc/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: libraryschemaVersionis 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.projectis the repository’s name, and the namespace its packages are published under.versionis the version the repository is at,major.minor.patch, and every module’s version. Keepmodulessorted byname.Done when
dev module listlists the adapter’s module and each of the repository’s own. Every run ofdevin the repository writes its log and its record of commands intologs/, sogit statusshows that directory until step 9’s ignore file covers it. -
Wire the adapter catalog in
.pkgmgr/config.ymlto 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 withgit clone --bare <shared address>andgit push --mirror <your address>. Clone it once on each machine, give the clone the shared catalog as itsupstreamremote (git remote add upstream <shared address>), which is how new releases of the cores reach it, and set the environment variableCATALOG_REPO_ADAPTERto 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: trueupdateOnReadbrings the clone up to date before an adapter is read from it, andupdateOnWritebefore one is published into it. A run whereCATALOG_REPO_ADAPTERis unset is refused by name asSTORE_LOCATION_VARIABLE_UNSET, never read as some other directory. Done when the variable is set andpkgmgr pkg list --catalog-root "$CATALOG_REPO_ADAPTER"lists the language cores. -
State the tiers and the gate in
.dev-tool/config.yml. WithouttierDirectory, writetestTiers: []: the repository has no tiers and every run collects every test. With one, list each tier asname, and mark the one a plaindev testcollectsdefault: true. SetownRootsto 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 agatelist the repository states, or list it undergateOmissions, by the name the gate reports it under.gateOmissionsis 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 asGATE_OMISSION_UNKNOWN, listing the checks it does:schemaVersion: '0.0.0-dev' testTiers: [] ownRoots: - src - tests gateOmissions: - typecheckDone when the file states the tiers, the roots and an omission for each verb with no tool.
-
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 intorepo-adapter/, recording which answered in.dev-tool/resolved.yml. A document that does not fit is refused asREPO_ADAPTER_CONTRACT_UNMETnaming the field; a repository whoserequires-pythonis outside the core’s versions is refused asREPO_ADAPTER_LANGUAGE_VERSION_UNSERVED, which no setting repairs. One refused asREPO_ADAPTER_UNAVAILABLEfound the catalog and no release of the core in it;dev vendorhas written the adapter catalog’s own configuration by then, sopkgmgr pkg list --catalog-root repo-adapter --store shared --namespace language --versionslists the releases the shared catalog holds, which tells a wrong address from a wrong coordinate. Done whendev vendor --validateprints the adapter it holds and exits 0, asVendored 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 aStale: <coordinate>line instead, and the run exits 1;dev vendorwithout--validatewrites it again. -
Ignore what was obtained:
dev gitignore gen. It writes the whole.gitignore: the adapter’sgitignoreRules, 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, asGITIGNORE_WOULD_DROP_RULESnaming each: for each rule it names, compare it with the generated rules listed above and in the adapter’sgitignoreRules–.venv/is covered by.venv*,__pycache__/by**/__pycache__– and delete the rule from.gitignorewhere one covers it; list each rule nothing covers undergitignoreAdditionsin.dev-tool/config.yml. Run it again once.gitignoreholds none of the rules it named; it writes the whole file. A rule can now ignore a file the repository tracks, whichgit statusnever shows:git ls-files -ci --exclude-standardlists them. Untrack each one that is build output (git rm -r --cached <path>), or drop the rule that matches source from the adapter’sgitignoreRules. Done whendev gitignore gen --validatereports nothing out of date andgit ls-files -ci --exclude-standardlists nothing. -
Run the gate:
dev gate, thendev 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 asREPO_ADAPTER_COMMAND_NOT_IMPLEMENTED: take it out of the gate either way step 7 gives – list it undergateOmissions, the usual way, or remove it from thegatelist where the repository states one – and run the gate again. Rundev gate --allonce 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 andgit status --shortshows nothing changed under the repository’s own source and tests: the new files, the regenerated.gitignoreand any build output untracked in step 9 are the setup, and are committed together. -
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 withpkgmgr 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 asVERSION_CLOBBER. Copy the document’s directory torepo-adapter/templates/<project>-<language>/and push it as a template withpkgmgr 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 whenpkgmgr pkg list --catalog-root "$CATALOG_REPO_ADAPTER" --namespace languagelists the adapter andpkgmgr 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.
core– the coordinate of the language core it configures, resolved through the same catalogs as the adapter’s own.testDirectories– directories tests are kept in, as globs (“Tree patterns”, below). Everything beneath one is test code. Default: none.testFilePatterns– file names a runner collects where the repository tells its runner nothing, as globs read from the module root:test_*.py, a lone name, is a file of that name at any depth. A core that reads the repository’s own runner configuration answers with that instead. Default: none.tierDirectory– how a tier’s directory is spelled directly inside a test directory,{tier}standing for the tier’s name:__{tier}__spellsintegrationas__integration__. Absent, no directory names a tier, and the repository statestestTiers: []. Which names are tiers istestTiersin.dev-tool/config.yml, never this field.nonSourcePatterns– what every walk passes over and a build’s digest ignores, as globs: caches, installed environments, fetched dependency trees./build,/distand/libare always passed over and are not stated here. Typically, you should keep this in step withgitignoreRules. Default: none.gitignoreRules– the.gitignorelines the language’s tools make a checkout need, each apattern(read as git reads it) and awhy, written into the generated file beside it. A pattern here is not a glob: git reads a leading!, a trailing/and an interior/in one as no glob does. Default: none.commands– the command line each verb runs, keyed bybuild:,test:,lint:,format:,typecheck:orsync:. Each is anexecutable(found onPATH), theargsevery run passes, andpassthroughArgs, each avalueread from the run – one of the verb’s parameters as “Methods” names it, camel-cased like every name the document holds (paths,fix,exclude,skippedTiers,repoRoot), or a field of.dev-tool/config.yml– under an optionalflag; a name the run does not carry is an error. A boolean emits the flag alone when true; a list emits the flag before each item; a scalar emits the flag and the value; no flag passes the value positionally; a path is written with forward slashes. An argument’sformsays how a glob the value holds is written: as written, oranchored, for a program that anchors a pattern holding a separator and reads a lone name at any depth, as ruff’s--extend-excludedoes – a rooted glob from./, an unrooted one of several segments as**/<glob>and**/<glob>/**.test:andbuild:left out are the core’s; any other verb left out is unsupported. Default: none.
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):
apiVersion– the contract version it was written to, as a literalmajor.minor.patchequal toadapter.REPO_ADAPTER_API_VERSION. A literal rather than the constant, so a contract that moves refuses it.language– a non-empty name.languageVersions– the versions of the language it has been run against:"3.13"(every3.13.x),["3.13", "3.14"](the span between, inclusive) or">=3.13,<3.15". A repository whoselanguage_versionfalls outside is refused the adapter asREPO_ADAPTER_LANGUAGE_VERSION_UNSERVED. An adapter made of a document answers with its core’s.
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.
test(config, paths=(), ci=False, skipped_tiers=(), isolated_tiers=()) -> Command | None– document if declared, else core. Leaves out every directory of a tier inskipped_tiersunderpaths, but runs a path named outright whatever its tier. Fails any test in anisolated_tierstier that starts a process, naming what it started. An adapter that cannot do either leaves those parameters out of its signature, and the host refuses a run that needs them.lint(config, paths=(), fix=False, exclude=()) -> Command | None– document.fixasks for repairs;excludeis what the run does not read, as the spellings of globs from the repository root.format(config, paths=()) -> Command | None– document. The command that formats the source underpathsin place, as the language’s formatter writes it. The gate runs it to repair, so the repairing form is the one declared.typecheck(config, paths=()) -> Command | None– document. The command that type-checks the source underpathsand fails where the type checker finds an error. It changes nothing.sync(repo_root, config) -> Command | None– document. The command that installs the development environment of the repository atrepo_root. Never narrowed: an environment is the whole repository’s.build(entrypoint, target_name, artifact_name, dist_path, scratch_path, packaging, config) -> Command | None– document if declared, else core. Packages the module whose entry-point file isentrypointintodist_path: either one file namedartifact_name(plus whatever suffix the packager adds), or a directorydist_path/<name>holding the executable as<name>,<name>.exeor<name>.binand everything it needs. Intermediates go underscratch_path.packagingis aPackagingInputssaying where the import graph is wrong, and the adapter renders it for its packager without adding to it.
Layout.
test_directories() -> Sequence[str]– document. Directories tests are kept in, as the spellings of globs. Empty: tests are kept in no directory of their own.test_file_patterns(repo_root) -> Sequence[str]– core, handed the document. File names that are test code wherever they sit, read from the repository’s runner configuration where it states them. Empty: every file in a test directory is a test and none outside one.test_tier(name) -> str | None– document. A tier is declared as a folder directly inside one of the directoriestest_directoriesnames, andnameis that folder’s name, one path segment. The answer is the tier the name spells bytierDirectory–__integration__spellsintegrationunder__{tier}__– orNonewhere it spells none. Whether the tier exists is the repository’stestTiers, never the adapter’s.non_source_patterns() -> Sequence[str]– document. What a walk passes over, as the spellings of globs; callers add/build,/distand/libthroughadapter.all_non_source_patterns. Empty: nothing.gitignore_rules() -> Sequence[GitignoreRule]– document. Empty: nothing.
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.
-
language_version(repo_root) -> str | None– core. The language version the repository says it is written for, read from the repository’s own declaration of it, which is why the method is handed the repository. For Python that isrequires-pythonunder[project]inpyproject.toml, answered as written and as far as written:>=3.13answers3.13, and a span answers the lowest version it admits.Nonewhere the repository states none, which no adapter is refused for. -
resolve_package_name(directory, repo_root) -> str | None– core. What the language calls the package atdirectory, orNonewhere it is no package. -
declared_package_data(repo_root) -> Sequence[PackagedFile]– core. The data files the repository’s packaging metadata declares: the file a language’s packaging tools read to build a distributable package, which states the files a package carries beside its code. A packager needs them for the reason a distributable package does, since an import graph reaches the code that reads a file and never the file. Each answer is aPackagedFile:source, the file’s path on disk when the application is packaged, anddestination, the directory the running code looks for it in, written with forward slashes and counted from the directory the code is imported from. The Python core reads[tool.setuptools.package-data]inpyproject.toml, looking for each package under the directories[tool.setuptools.packages.find] wherenames. A repository declaring[tool.setuptools.packages.find] where = ["packages"] [tool.setuptools.package-data] acme = ["*.app.yml"]and holding
packages/acme/acme.app.ymlanswers onePackagedFilewithsource<repository>/packages/acme/acme.app.ymlanddestinationacme, sinceacmeis imported frompackages/. -
declared_language_requirements(repo_root, include_development=False) -> Sequence[str]– core. Third-party requirements as written;include_developmentadds the development group. -
declared_path_sources(repo_root) -> Sequence[PathSource]– core. The packages the repository’s package manager installs from a directory rather than obtaining them from a catalog or an index, which is the coupling the dependency checks report: such a package is found where the directory happens to be, and a clone without that directory beside it cannot resolve it. Each answer is aPathSource:package, the package’s name as the declaration spells it, andpath, the directory as written, relative to the repository unless it is absolute. The Python core reads uv’s[tool.uv.sources]inpyproject.toml, where an entry naming apathis one and a git url, an index or a workspace member is not. A repository declaring[tool.uv.sources] acme-config = { path = "../config", editable = true } acme-remote = { git = "https://example.com/acme/remote.git" }answers one
PathSource, withpackageacme-configandpath../config. -
render_vendored_requirements(repo_root, requirements) -> VendoredRequirementsFile | None– core. The file, path and content, that tells the package manager what obtained packages need installed; the caller writes or compares it.None: the language needs no such file.
Source analysis. Each raises RuntimeError naming the file where it cannot parse one.
discover_dependency_groups(module, repo_root, module_by_package) -> DependencyGroups– core, handed the document. Walks the module’s source and maps each import to a manifest module name or coordinate throughmodule_by_package, never naming the module itself.detectedholds run-time imports of non-test files;detected_testimports of test files, which may overlap it;detected_devimports made only for the type checker (if TYPE_CHECKING:in Python), never overlappingdetected.read_boundary(module, repo_root, module_by_package, boundary) -> BoundaryFile | None– core. Reads the module’sexportsboundary (what it exposes outside) or itsfacade(what it hands modules nested inside it), and answers the file’s path, every module it imports, and each name it exports with the module that name comes from (Nonewhere the file defines it or takes it from inside the module) and its line.Nonewhere the module keeps no such file.unresolved_package_imports(package_root, package_name) -> Sequence[str]– core, handed the document. In an unpacked package, each import the package makes of itself that the tree does not hold, as<file>: <module>, sorted.extract_comments(path) -> list[tuple[int, str]]– core. Each comment’s 1-based line and text; empty for a file the language does not recognise. It is handed the file’s path rather than its text because reading the file is the language’s own act: how a file’s bytes are decoded is a rule of the language, and Python, for one, lets a file declare its own encoding in a coding comment on its first or second line, and its tokenizer reads bytes.generate_types(schema, generate_validators=False, generate_normalizers=False, check=False, type_runtime_binding=None) -> GeneratedTypeArtifact– core. The language’s types for one schema document. The same input renders byte-identical output, and the output marks itself generated in the language’s own terms.resolve_type_runtime_binding(submodule_ancestor_root, repo_root=None) -> str– core. An opaque token, handed back togenerate_types, naming where generated types reach the type runtime: the plain runtime where the schema’s owner is a top-level module, and through the facade of the owner’s top-level ancestor where the owner is a module nested inside another.submodule_ancestor_rootis that ancestor’s root directory, relative to the repository, orNone. In Python the token is the module generated types import their base class from:typewith no ancestor, andimpl_tool.submodule_apifor a schema owned by a module nested inside the module rooted atpackages/impl_tool, in a repository whose packages are found underpackages/.resolve_app_definition_binding(module_root, repo_root) -> str | None– core. An opaque token naming where the application atmodule_rootloads its declaration, the*.app.ymlat its module root, which the API generated for the application reaches.Nonewhere nothing, or more than one place, does. In Python the token is the import path of the one module that bindscli_configat its top level, looked for directly under the application’ssrc/and then directly under its module root: for the application atpackages/impl_toolwhosesrc/app.pyassignscli_config,impl_tool.src.app.
What methods are handed and answer
ManifestModule– one module ofmanifest.yml, as themanifestModuledefinition ofmanifest:manifestdeclares it; that definition’s field help is the reference.ModuleByPackagemaps an import name to a module name.RepositoryConfigDocument– the calling tool’s configuration document as a mapping. Read the keys you need and treat a missing one as unset.PackagingInputs–modulesLoadedByName,packagesLoadedByName,files(each aPackagedFile),nonApplicationPackages(which wins over everything else),obtainedPackageRoots,form(bundledorcompiled) andsignCommand; each field’s help inrepo-adapter-api:adapter-outputsis the reference.DependencyGroups,BoundaryFilewithBoundaryExport,GitignoreRule,PathSource,VendoredRequirementsFile– as described under the methods that answer them.AdapterSelectionUnsupported– raised by a command producer that cannot narrow to the paths it was given.
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.