Configuration Tags and Stack Contracts API

TagRegistry is the one TOML tag → type map; CONTRACT_GENERICS and the dependency allow-list are what the quality gates (test_quality_gates) check across the stack; the conformance helpers test an implementation of the contracts of the Robust Estimation API page (their methods load with Test).

VisualGeometryToolkitCore.TagRegistry — Type
TagRegistry(family::Symbol, suffix::AbstractString, pairs::Pair{<:AbstractString}...;
            retired = (), paths = Regex[])
TagRegistry(family::Symbol, suffix::AbstractString, pairs::AbstractVector{<:Pair};
            retired = (), paths = Regex[])

The ONLY structure a configuration loader uses to map a TOML tag to a type (or, rarely, a value). registry[tag] returns the type; a retired tag throws ArgumentError("tag \"keep\" was renamed \"keep_model\""), and an unknown tag throws an ArgumentError that lists the known tags.

  • family names the family (:optimization_strategy, :loss) in messages.
  • suffix is the family's common type-name suffix ("Shape" for TLSShape), stripped before the spelling rule; "" for none.
  • pairs are tag => type, as arguments or one vector (a registry built from a table: no splat of a data-length collection, check_splat). The one value that is not a type is nothing, whose tag is "none".
  • retired are old => new renames: the old tag no longer loads, and the error names its successor.
  • paths are the TOML key paths whose string values are tags of this family, matched whole against the dotted path of a value ("lo.arms[2].type"; an array element is [i], counted from 1). The config gate reads them.

The tag rule: a type's tag is snake_case of its name with suffix stripped from its end when present (the whole name otherwise), and nothing is "none". Construction does not check it — a package's load never fails on a spelling — tag_rule_violations does, and the quality gate runs it over every registry constant. A duplicate tag, or a retired tag that is also current, is a construction error.

keys, values, haskey, get, length and iteration (tag => type pairs, in declaration order) cover the current tags only; tag_of is the reverse lookup.

source
Base.merge — Method
merge(a::TagRegistry, b::TagRegistry...) -> TagRegistry

The registry of one family that two packages share — the core's tags and a downstream package's (merge(VisualGeometryToolkitEstimation.OPTIMIZATION_STRATEGY_TAGS, LocalOptimizationDoneRight.LODR_STRATEGY_TAGS)): every current and retired tag of each, and their key paths. The family and its suffix must agree, and a tag declared by two of them (or current in one and retired in another) is an ArgumentError, as within one registry. There is no global registry: a caller that loads several packages' tags merges them explicitly.

source
VisualGeometryToolkitCore.config_tag_violations — Method
config_tag_violations(registries, config_dirs) -> Vector{String}

Parse every .toml under config_dirs (recursively); every string value at a key path one of the TagRegistrys claims (tag_paths, matched whole) must be a current tag of that registry — not a retired tag and not an unknown one. Each finding is "file:path: message". A file that does not parse is a finding. registries is a collection of registries or of name => registry pairs (the form tag_registries returns).

source
VisualGeometryToolkitCore.snake_case — Method
snake_case(name::Symbol) -> String
snake_case(name::AbstractString) -> String

The tag spelling of a CamelCase name, by exactly two rules, then lowercase:

  1. an _ goes before an uppercase letter that follows a lowercase letter or a digit;
  2. an _ goes before the last uppercase letter of an uppercase run when a lowercase letter follows it.

A digit stays with its letters.

snake_case(:FixedS2)              # "fixed_s2"
snake_case(:SmoothTLS)            # "smooth_tls"
snake_case(:WelschHQNewton)       # "welsch_hq_newton"
snake_case(:StudentTUniform)      # "student_t_uniform"
snake_case(:TerminalPlacement)    # "terminal_placement"
source
VisualGeometryToolkitCore.tag_of — Method
tag_of(registry::TagRegistry, x) -> String

The writer side of a TagRegistry: the tag of x. x is a registered value (nothing → "none"), a type registered as such, a subtype of a registered type (Irls{2} under a registered Irls; the most specific registered supertype wins) or an instance of one. An ArgumentError when nothing matches.

source
VisualGeometryToolkitCore.tag_table_violations — Method
tag_table_violations(dir) -> Vector{String}

A heuristic source scan of the .jl files under dir (a package's src/) for tag tables built outside a TagRegistry: a Dict{String, <:Type}-style table (keyed by a string or symbol, valued by Type, DataType or UnionAll), or a "tag" => SomeType pair — a string literal paired with a CamelCase name that is not called and is not a Base or Core type ("cutoff" => Float32 is a key's converter, not a tag). TagRegistry(...) calls, comments and triple-quoted strings are not scanned. Each finding is "file:line: text", relative to dir.

source
VisualGeometryToolkitCore.CONTRACT_GENERICS — Constant
CONTRACT_GENERICS

The generic functions of VisualGeometryToolkitCore that another package may add methods to across a package boundary — its extension points. Any stack package may declare its own CONTRACT_GENERICS (a tuple or vector of functions); the quality gate (contract_generic_violations) requires every method a package adds to another stack package's function to land on one of that owner's contracts. Functions owned by Base, Core, the standard library or any package outside the stack are exempt.

VisualGeometryToolkitCore's, by group:

  • the block-coordinate-descent hooks and readers (update_model!, …, current_s2);
  • the chart-LM row protocol (residual_rows!, residual_jacobian_rows!) and its reductions (residual_cost!, residual_normal_equations!);
  • the RANSAC / local-optimization interface, the constraint-problem protocol, the scoring and local-optimization contracts, pool selection and the chart-rows contract;
  • the minimal-solver backends PoseLib.jl implements;
  • the FitResult property forwarding and the TOML config hooks;
  • the geometry and camera accessors other packages implement for their own types (centroid, intrinsics, lens, model, division_coeffs, …);
  • the parameter protocol (parameter_vector, parameter_names, parameter_bounds, with_parameters);
  • the target-calibration protocol (regularizer, is_planar) and the target accessors calibration and design;
  • the surface protocol (intersection, normal, chart, surface_point, bounds) and surface, which builds a posed target's primitive;
  • the camera maps project and backproject, and convert_eltype;
  • the Manifold protocol: tangent_size, retract and recenter (required), local_coordinates, retract_jacobian, action_jacobian, zero_tangent, restrict, tangent_part and transform_covariance (optional), and minimal_manifold and ambient_coordinates, which a downstream model type answers (a model that is not a static array or a tuple of them adds ambient_coordinates rather than overriding retract_jacobian);
  • the plotting stubs the Makie extensions implement.
source
VisualGeometryToolkitCore.contract_generic_violations — Method
contract_generic_violations(M::Module) -> Vector{String}

Every function owned by another loaded stack package (a key of stack_dependencies) that has a method defined in M or one of its submodules but is not in its owner's CONTRACT_GENERICS (a package without one has no contracts). Constructors of another package's types are not counted (Aqua's piracy check covers them). Each finding is "Owner.f (file:line)", located at the first such method.

source
VisualGeometryToolkitCore.private_name_violations — Method
private_name_violations(dir, name) -> Vector{String}

A heuristic source scan of the .jl files under dir (a package's src/ and ext/) for names that begin with _ and are reached from another stack package (a key of stack_dependencies other than name): imported (using Pkg: _x, import Pkg.Sub: _x) or accessed qualified (Pkg._x, Pkg.Sub._x, also through a const P = Pkg or import Pkg as P alias). Comments and string literals are not scanned. Each finding is "file:line: Pkg._x", relative to dir.

source
VisualGeometryToolkitCore.stack_dependencies — Method
stack_dependencies(; extra = nothing) -> Dict{String, Vector{String}}

The stack's dependency allow-list (configs/stack_dependencies.toml in VisualGeometryToolkitCore): each project's name → the stack packages its Project.toml may name. A stack package is any key of this table.

The table lists the published packages and paper projects only. A project kept elsewhere supplies its own row as extra: a path to a TOML file of rows in the same format, or a dictionary name → packages. Extra rows add projects; one that repeats a row of the table is an ArgumentError.

source
VisualGeometryToolkitCore.stack_dependency_violations — Method
stack_dependency_violations(project_toml_path, name; extra = nothing) -> Vector{String}

The stack packages the Project.toml at project_toml_path names — in [deps], [weakdeps], [extras] or the test target — that are not in name's row of stack_dependencies (with the extra rows, as there), one "section: Package" per finding. A project absent from the table is an ArgumentError.

source
VisualGeometryToolkitCore.test_constraint_problem — Function
test_constraint_problem(problem, θ)

The constraint-problem protocol on problem at the model θ, as tests: data_size/codimension/minimal_sample_size integers, mahalanobis_distances! type-stable, allocation-free after warm-up, ≥ 0, and equal to mahalanobis_distance at every point to rounding: rtol = 1e-11 of the point's distance or 1e-14 of the largest finite distance (a non-finite one identical); and whitened_residual in the constraint's shape at every point — a number at d_g = 1, d_g components otherwise, so a scalar override at d_g ≥ 2 (a distance under the residual's name, the pre-0.7 hook) is refused — and with its norm equal to the point's distance to the same rounding (a non-finite distance, a gate's, matched by a non-finite residual), so the two hooks describe one point. The rounding is of the observations, not of the residual: a reprojection residual is a difference of ~1000 px coordinates, so two paths differ by ~1000·eps px whatever the residual (PnP measured 4.8e-14 px on a 1.08 px residual, E 5.7e-14 px; 2026-11). Not bit for bit: the batch loop and a single call may contract StaticArrays' muladds into FMAs differently once the loop vectorizes, so a bitwise rule held for a problem only by forbidding inlining (PnP's @noinline, 15–22% per point) — result accuracy, not bit accuracy. Implemented by VisualGeometryToolkitCoreTestExt.

source
VisualGeometryToolkitCore.test_local_optimization_contract — Function
test_local_optimization_contract([T = Float64,] lo, problem, θ, scoring; allocations = true)

The local-optimization contract on lo for problem from the hypothesis θ under scoring, in the element type T (the workspace's and score buffers'), as tests: lo_workspace built once, locally_optimize! type-stable, returning a lo_estimate result of the problem's model type whose termination record satisfies test_termination_record, honest about residuals_current (the buffers then hold the refined model's residuals), allocation-free after warm-up (allocations = true). Implemented by VisualGeometryToolkitCoreTestExt.

source
VisualGeometryToolkitCore.test_manifold_contract — Function
test_manifold_contract(m::Manifold; atol = 1e-12, allocations = true)

The manifold contract on m, as tests — what an optimizer that holds m as its variable relies on: the tangent size a constant of the type (zero_tangent inferred, static); recenter inferred to typeof(m) for a step of m's own float type in any static container (SVector, MVector; a plain Vector returns that type too) and allocation-free (allocations = false records a known allocation as @test_broken); retract_jacobian at the anchor and at a step equal to ForwardDiff through retract within atol; and the chart's own invariants (the essential chart's translation on the unit sphere after a step). Run it on every manifold family a package defines. Implemented by VisualGeometryToolkitCoreTestExt.

source
VisualGeometryToolkitCore.test_scoring_contract — Function
test_scoring_contract(scoring, residuals; n = length(residuals), d_g = 1, sample = nothing)

The scoring contract on scoring over one residual vector, as tests: score! type-stable and allocation-free after warm-up and deterministic; inlier_count in 0:n; consensus_order a permutation of 1:n; the derived consensus_set and consensus_s2 inferred; check_workspace accepting the scorer's own workspace and refusing a foreign one; decision_boundary a Float64 where has_decision_boundary; and, for a bounded-sum scorer (score_bound), the early exit tie-safe: a bound the score beats or ties never changes it, and an exit returns a value at or below its bound. Implemented by VisualGeometryToolkitCoreTestExt.

source
VisualGeometryToolkitCore.test_termination_record — Function
test_termination_record(result)

The termination record of one fit result, as tests: retcode a ReturnCodeReturnCode.T, stop_rule a StopRule, converged a Bool and retcode_symbol(result) a Symbol, each inferred; converged(result) (and the property result.converged) is successful_retcode(retcode(result)), and retcode_symbol(result) is retcode_symbol(code, rule). test_local_optimization_contract runs it on the refit it checks; a producer's suite runs it on one result of each of its verbs and paths (VisualGeometryToolkitEstimation's and PoseLib's termination-record items cover every fit_*, find_* and refine_*). Implemented by VisualGeometryToolkitCoreTestExt.

source

Quality gates

The checks every stack package's quality items run: the naming rules, the rows Jacobian check, the gate bundle, the agent-docs policy and the one copy of the conventions. check_naming and test_quality_gates load with Test (the Test extension).

VisualGeometryToolkitCore.check_naming — Function
check_naming(pkgdir) -> Vector{NamingViolation}

The stack's naming rules, checked over a package directory. Implemented by the VisualGeometryToolkitCoreTestExt extension: using Test loads it.

source
VisualGeometryToolkitCore.ReadmeExample — Type
ReadmeExample(page, lang, row, illustrative, code)

One fenced code block of a documentation page (readme_examples): the page (relative to the package root), its lang ("julia", "python", "bash"), the install row its first line names (# Install row: <row>; "" when it names none), whether it is illustrative (its first line # Illustrative, the row on the second: a block that cannot run as written) and its code.

source
VisualGeometryToolkitCore.check_rows_jacobian — Function
check_rows_jacobian(lm, θ, m; atol = 0, rtol = 0, reference = ForwardDiff.jacobian,
                    jacobian = Matrix{Float64}(undef, m, length(θ))) -> Bool

Does the analytic residual_jacobian_rows! of lm at θ (m rows) match a reference Jacobian of residual_rows! to maximum|J − J_ref| ≤ atol + rtol·max(1, maximum|J_ref|)? reference(f, θ) returns the Jacobian of f at θ: ForwardDiff by default; where a Dual cannot flow through the rows, a finite difference such as (f, θ) -> FiniteDiff.finite_difference_jacobian(f, θ, Val(:central)). jacobian is the buffer the analytic Jacobian is written into — a dense matrix by default; a state whose method takes another representation (a fixed-pattern SparseMatrixCSC) is checked in that one. On a miss the two errors are logged. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.install_lines — Function
install_lines(root, page) -> Vector{String}

The packages of every pkg> add … line of the page at root/page (each line's text after add), in page order: what a README test compares with an install row's install_packages. Implemented by VisualGeometryToolkitCoreTestExt.

source
VisualGeometryToolkitCore.install_packages — Function
install_packages(entry) -> Vector{String}

The packages of the $`pkg> add …`$ line in an install table's entry; empty when it holds none. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.install_table — Function
install_table(path, tasks) -> Dict{String, String}

The install table of the page at path: each row | task | entry | … | whose task is one of tasks, as task => entry. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.julia_blocks — Function
julia_blocks(path) -> Vector{String}

The code of every $```julia$ fenced block of the page at path, in page order (a block's opening fence exactly $```julia$, so a julia-repl block — an install line — is not one; the code without its fences). What a README test compares between the README and the landing page, and runs. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.loaded_packages — Function
loaded_packages(code) -> Set{String}

The packages Julia code loads (using/import lines, a trailing comment ignored), the standard library left out: what an install line must add for the code to run. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.page_examples — Function
page_examples(examples, page; lang = "julia") -> Vector{String}

The code of the lang examples of one page, in page order, from readme_examples's records: what a README test compares between the README, the landing page and a guide ("one example, shown on every page"). Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.readme_environment — Function
readme_environment(root, packages; developed = Dict(), setup = "") -> String

A fresh environment holding exactly packages, as a reader's install line builds it: the package at root and those named in developed (name => path, the stack's unregistered checkouts) by path, the rest from the registries; setup runs after the adds (a runtime pin), then the environment is precompiled. Built in a child Julia (run_readme_child); @test that it builds. Returns its directory. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.readme_examples — Function
readme_examples(root, pages; langs = ("julia", "python", "bash")) -> Vector{ReadmeExample}

The fenced code blocks of langs in each of pages (paths relative to root), in page order, as ReadmeExamples. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.run_readme_child — Function
run_readme_child(env, args...) -> Int

Run Julia with args (a script, or "-e", code) in the environment env, a child Julia with the test run's flags (Base.julia_cmd(): --depwarn=error, coverage) and a load path of the project and the standard library only, so no default environment supplies a package the install line does not add. Returns its exit code. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.sensor_fixture — Function
sensor_fixture(; body, iso = 100, exposure = 1.0s, black = nothing, black_std_error = nothing, dark = nothing, darks = nothing,
               gain = nothing, gain_std_error = nothing, read_noise = nothing, read_noise_std_error = nothing,
               relative_noise = nothing, defects = nothing, source = SensorSource.specified)
    -> (; characterisation, capture, model)
sensor_fixture(characterisations::SensorCharacterisation...) -> SensorCharacterisation

THE builder of sensor-model fixtures for tests (owner ruling D13): a test never constructs a sensor component, a SensorCharacterisation or a SensorModel itself (checkduplication's `:sensorcomponentpattern; the absent modelSensorModel()excepted), it describes one here in plain numbers. The slots, each absent when its keywords arenothing`:

  • black: black (a 4-tuple per colour index) → ChannelBlack (with black_std_error); dark = (; offset, variance, exposure_band, frames) → a Dark over that channel black (the FileBlack without black); darks, a vector of such named tuples → a Darks, one Dark per band, each over that channel black, which is also the shared fallback (dark or darks, not both);
  • noise: read_noise → ReadNoise (with read_noise_std_error); with a gain → PoissonGaussian (gain_std_error and read_noise_std_error its standard errors); relative_noise → RelativeNoise;
  • defects: defects = (; x, y, onset, size) → DefectList.

source is one SensorSource.T for every slot or a named tuple by slot ((; black = SensorSource.measured), specified where it names none). Returns the characterisation of body with that one entry at iso, a one-frame capture (frame 1 at iso and exposure, f/8, 14 mm) and the frame's model, resolved by sensor_model. The second form merges characterisations of one body (their ISOs) into one. The components' own ArgumentErrors reach the caller. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.test_docs — Function
test_docs(M::Module; exceptions = Dict{String,String}(), backlog = Set{String}(),
          signature_exceptions = Set{String}(), dirs = ("src",)) -> NamedTuple

The docstring gates the Documenter build cannot run (its checkdocs = :public sees only docstrings that exist), over package M, as tests:

  • every public name of M and its submodules has a docstring, except the exceptions (name => reason: undocumented on purpose) and the backlog (names still to document; the list only shrinks — a name documented must leave it); a stale exception is a failure;
  • no docstring under M's dirs (relative to its package directory; a missing one is skipped) is detached from its definition — a bare string statement the parser did not attach, after a blank or comment line;
  • every signature line of a docstring is accepted by a method of its name (methods a test item defined under Main are not the package's), and a docstring that shows a sibling's signature leaves the sibling documented on its own, except the signature_exceptions (stale ones fail).

A name in a submodule is Sub.name. The exceptions are logged with @info. Returns the findings, (; undocumented, detached, mismatches). Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.test_duplication — Function
test_duplication(M::Module; kwargs...)

The stack's no-duplication rule (check_duplication) over package M, as a test: every finding printed, and @test that there is none. The keywords go to check_duplication (the stack repositories compared come from VGTK_STACK_PATHS by default). Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.test_naming — Function
test_naming(M::Module)

The stack's naming rules (check_naming) over M's package directory, as a test: every finding printed, and @test that there is none. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.test_quality_gates — Function
test_quality_gates(M::Module; jet_bound, treat_as_own = [], stale_ignore = (),
                   qualified_ignore = nothing, persistent_tasks = true,
                   tag_rules = :enforce, tag_tables = :enforce, config_tags = :enforce,
                   config_dirs = nothing, registries = (), stack_dependencies = :enforce,
                   stack_name = string(nameof(M)), stack_extra = nothing,
                   public_names = :enforce, third_party_public = :report,
                   contract_generics = :enforce, splat = :report)

The stack's static quality gates over package M, as one test set — RATCHETS: each bound is the value the package meets today and only ever moves down.

  • Aqua: undefined exports, unbound type parameters, stale deps, deps compat, project extras, persistent tasks (persistent_tasks = false skips it), no method ambiguities involving a method of M (pairs touching a test item's Main methods are dropped and logged), and no piracy in M or any of its submodules beyond treat_as_own.

  • ExplicitImports: no implicit imports, explicit imports via their owners, no stale explicit imports beyond stale_ignore; with qualified_ignore (a tuple of names) also every qualified access public, those names excepted.

  • JET: report_package(M) counts at most jet_bound reports, not counting KernelAbstractions LAUNCH reports (a kwcall(::NamedTuple{(:ndrange,)}, ::Kernel, …) no-method report, which JET raises at every launch site because the backend is known only at run time). The filter is checked against a real launch and two decoys every run.

  • Stack contracts, each gate in a mode — :enforce (@test that it finds nothing), :report (every finding logged with @warn and the gate recorded @test_broken; a gate that finds nothing is an ordinary test) or :off:

    • tag_rules: every TagRegistry constant of M and its submodules obeys the tag rule (tag_rule_violations);
    • tag_tables: no tag table outside a TagRegistry in M's src/ (tag_table_violations, a heuristic scan);
    • config_tags: every string at a registry's key path in the TOML files under config_dirs (default: M's configs/, when it exists) is a current tag of M's registries and of the extra registries (config_tag_violations);
    • stack_dependencies: M's Project.toml names only the stack packages in stack_name's row of the allow-list (stack_dependency_violations); a project kept outside the published stack gives its own row as stack_extra (the extra of stack_dependencies);
    • public_names: no _-prefixed name reached from another stack package (private_name_violations over src/ and ext/);
    • third_party_public (default :report): ExplicitImports' check_all_explicit_imports_are_public and check_all_qualified_accesses_are_public (with qualified_ignore) — a non-public name of ANY module, the stack's or a third party's (ForwardDiff's Dual, StaticArraysCore's StaticArray);
    • contract_generics: every method M adds to another stack package's function lands on that owner's CONTRACT_GENERICS (contract_generic_violations);
    • splat (default :report): no call splats a collection whose length is data — a Vector, a generator, an abstract type — which compiles the callee once per length (check_splat over M and its loaded extensions; exceptions are DUPLICATION.toml's [[splat]] entries).

Implemented by VisualGeometryToolkitCoreQualityExt: using Test, Aqua, ExplicitImports, JET loads it.

source
VisualGeometryToolkitCore.test_readme_example — Function
test_readme_example(root; index = "docs/src/index.md", install_pages = (), developed = Dict(), checks = "")

The README's one example, as tests: README.md holds one Julia block and one pkg> add line; the landing page index shows the same block, it and each of install_pages the same line; the line adds exactly the packages the block loads (loaded_packages); and the block runs in a fresh environment built from that line (readme_environment), expression by expression, every expression whose source ends # true returning true, then checks — code run with readme the example's module. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.test_readme_row — Function
test_readme_row(env, task, blocks; preamble = "", after = "")

Run each Julia example of blocks (code strings) in the environment env, each in a module of its own, so each is shown complete on its own; a block whose last line ends # true must return true. preamble is top-level code run first (an import the assertions need); after is code run in the same child after the examples, mods their modules in order (the row's assertions). @test that the child succeeds. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.test_recorded — Function
test_recorded(make; nested = RECORDED_NESTED_STATES) -> Int

That a Recorded run of block_coordinate_descent! IS the bare run, as tests: make() returns a fresh (state, likelihood, method, problem, θ₀, max_iter) each call (fresh workspaces too), whose result has estimate, retcode and iterations. The recorded run returns the bare run's estimate, retcode and iteration count and leaves the same state; it records one iterate per good iteration (a :solve_failed run one fewer), with as many costs and scales; and the bare run truncated after every k has the recorded run's k-th cost — iterate for iterate. A state is compared by what a run moves: its numbers, arrays and best iterates (Attributed(θ, (; cost))), and the fields of the nested state types whose names are in nested; anything else it points into is skipped. Returns the number of recorded iterates. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.test_splat — Function
test_splat(M::Module; mode = :enforce, extensions = true)

The stack's splat rule (check_splat) over package M, as a test in a gate mode: :enforce (@test that there is no finding), :report (each finding logged with @warn and the test recorded @test_broken; none found, an ordinary test) or :off. extensions goes to check_splat. A package on test_quality_gates gets the same check as its splat gate. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.thrown_message — Function
thrown_message(f; shown = false) -> String

The message of the ArgumentError that f() throws, "" when it throws nothing; any other exception is rethrown. With shown = true, any exception is caught and its shown text (sprint(showerror, e), its type included) is returned. For a test that reads what a refusal says: @test occursin("frame", thrown_message(() -> load(T, path))). Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).

source
VisualGeometryToolkitCore.agent_doc_violations — Method
agent_doc_violations(root; forbidden = AGENT_DOC_FORBIDDEN, extra = nothing) -> Vector{String}

The lines of the agent instruction files under the package directory root — CLAUDE.md, AGENTS.md and anything under .claude/, the files git tracks when root is a checkout — that match a pattern of forbidden or extra, one "file:line matches pattern" per finding, plus "CLAUDE.md: missing" when the package has none. These files ship with the package: they carry its conventions and nothing private.

extra adds patterns: a Regex, a collection of them, or the path to a text file of one regular expression per line (blank lines and # comments skipped; an empty path adds none). The stack's tests call it with extra = get(ENV, "AGENT_DOC_PATTERNS", nothing), so release tooling supplies its own list by setting that variable.

source
VisualGeometryToolkitCore.conventions_dir — Method
conventions_dir() -> String

The conventions/ folder of this VisualGeometryToolkitCore installation: the one canonical copy of the conventions every stack package follows (naming, signatures, data arguments, coordinate frames and normalization, pixel origins, bearings, observation noise, residuals and distances, persisted geometry, Jacobians, units, stack contracts). A downstream package finds the installed text here rather than carrying a copy.

source
VisualGeometryToolkitCore.DuplicationViolation — Type
DuplicationViolation

One finding of check_duplication: the check that found it (:name, :similar, :file, :pattern, :backend_branch, :twin_name or :stale_exception), the file (relative to the repository root) and line, the text found (a name, a function, a code line or an exception entry), and other — the upstream owner, the matching function or file elsewhere (<Repository>:<path>:<line> outside this repository, a monorepo's member as <Member>:<path>:<line>), or the owner a retired pattern names.

source
VisualGeometryToolkitCore.check_duplication — Function
check_duplication(M::Module; kwargs...) -> Vector{DuplicationViolation}
check_duplication(dir; stack = <ENV["VGTK_STACK_PATHS"]>, similarity = ((0.6, 60), (0.85, 25)),
                  shingle = 8, min_file_tokens = 25) -> Vector{DuplicationViolation}

The stack's no-duplication rule, checked over a package (M, its directory pkgdir(M)) or a directory dir. Six checks:

  1. Name ownership (the Module form only). Every binding M (or a submodule of it) owns — defined there, not imported, a function or type whose parentmodule is that module; method extensions of another package's function do not count — whose name an upstream stack package also owns, private _names included (Julia's per-module eval, include and __init__, and the per-package CONTRACT_GENERICS, are each package's own). Upstream is every package in M's dependency closure (its loaded Project.toml[deps], transitively) that is VisualGeometryToolkitCore or depends on it: Core < IO, Features < Estimation < Eval < the downstream repositories.
  2. Function-body similarity. Every function and macro definition in the Julia files is tokenized with Julia's own tokenizer (JuliaSyntax), its comments and whitespace dropped, each identifier mapped to one symbol and each string piece to another, and cut into shingle-token shingles. Two definitions in different files are a finding when their shingle sets' Jaccard index reaches a threshold of similarity, each a pair (jaccard, min_tokens) that both bodies' token counts must reach: by default J ≥ 0.6 with at least 60 tokens, or J ≥ 0.85 with at least 25. (A shingle shared by more than 40 definitions — a common idiom — is not counted towards any pair.) Compared within the repository and against stack.
  3. Whole files. A Julia file whose token text, comments and whitespace dropped (at least min_file_tokens tokens), equals another file's.
  4. Retired patterns. A line of code (comments and docstrings left out) that spells a pattern whose owner lives elsewhere: NLLSOptions( (Core's LmStops, mapped in lmsolve_chart!), acos(clamp((tr(… (Rotations' rotation_angle), the sRGB transfer constants (Features' src/linear_image.jl), and a \newcommand writer (Eval's src/reproduce/number_macros.jl). The failure names the owner.
  5. Backend branches (:backend_branch). A GPU branch's CPU branch is the SAME KernelAbstractions kernel on the CPU backend, so a definition that tests the backend to run different code is a finding: backend isa CPU (KA.CPU, GPU), get_backend(x) isa … (or ==), x isa CuArray (AbstractGPUArray and the other GPU array types), == CPU(); and a pair of methods of one function, one on a CPU type (::CPU) and one on a GPU type (::GPU, ::Backend, ::CuArray). Allowed, so not flagged: the same kernel launched on whatever get_backend returns, and the transfer and allocation helpers, by their WHOLE names: every _-separated word of the name is a transfer or allocation word (an upload or download, to_host, to_device, on_device, zeros, ones, fill, an allocation, a synchronization, adapt, a copy, the device queries), so zeros_on is a helper and fill_sqrt_weights! or transfer_ellipse is not.
  6. CPU/GPU twins (:twin_name). Two bindings of the package whose names differ only by a CPU/GPU marker: _cpu/_gpu, _host/_device, cpu_/gpu_, or _cuda beside the plain name (the transfer helpers' whole names excepted).

The repository is the git checkout holding dir. Inside a monorepo the other packages' files are compared too (the package's own files are the ones checked; a pair or a file found twice is reported by each package). stack lists other stack repositories' root directories (by default the paths in the environment variable VGTK_STACK_PATHS, separated by :, or ; on Windows); those absent are skipped with a note, so a CI checkout checks itself only. Files are the ones naming_scope reads (vendored trees out).

Exceptions live in the repository root's DUPLICATION.toml, each with its reason; an entry about this package that matches nothing is itself a finding:

[[name]]                  # a binding M owns that an upstream package also owns
module = "MyPackage"
name = "foo"
reason = "…"

[[similar]]               # two functions, `<path>::<name>` (another repository's `<Repository>:<path>::<name>`)
functions = ["src/a.jl::f", "test/b.jl::g"]
reason = "…"

[[file]]                  # two files (paths as above)
files = ["test/a.jl", "OtherRepo:test/a.jl"]
reason = "…"

[[pattern]]               # a retired pattern in one file
use = "rotation_angle"
file = "src/a.jl"
reason = "…"

[[backend]]               # a backend branch in one function of one file
file = "src/a.jl"
function = "f"
reason = "…"

[[twin]]                  # two names that differ by a CPU/GPU marker
names = ["f_cpu", "f_gpu"]
reason = "…"

Implemented by the VisualGeometryToolkitCoreTestExt extension: using Test loads it.

source
VisualGeometryToolkitCore.RawDecodingViolation — Type
RawDecodingViolation

One finding of check_raw_decoding: the file (relative to the scanned directory), the line, its code text, and the use found — :rawpy, :libraw (a LibRaw C call), :dcraw, :postprocess (rawpy's), :demosaic, :cfa_interpolation (a Bayer/CFA interpolation by another name) or :png_raw_output (a decoded RAW output re-read as an image, PNGFiles.load or Gray.(…)).

source
VisualGeometryToolkitCore.check_raw_decoding — Function
check_raw_decoding(dir; allow = ()) -> Vector{RawDecodingViolation}

The stack's one-RAW-path rule, checked over the code under dir (the files naming_scope reads, less prose: Julia, Python, shell, TOML and YAML files, with comments and docstrings left out). Flags any use, outside VisualGeometryToolkitFeatures' raw module, of rawpy, a LibRaw C call (libraw_…), dcraw, rawpy's postprocess(, a demosaic, a Bayer/CFA interpolation, or PNGFiles.load/Gray.(…) on a decoded RAW output (a line naming linear, decoded, prepared, bin2, green or raw_ images). Line-level matching: a finding is a line to port, read by a person. The raw module's own files (VisualGeometryToolkitFeatures' src/raw_image.jl, its LibRawjll extension and their tests; VisualGeometryToolkitCore's src/raw/ sensor image and its test) are the one allowed place; they are recognized when dir is the owning package's directory, so scan each package of a monorepo from its own directory (from the repository root they are flagged). The Features API asked for its display demosaic, `loadraw(…; mode = :demosaic)orLinearRaw(…; mode = :demosaic)`, is the approved display path in every repository and is not flagged: the mode keyword inside that call's own parentheses, over every line the call spans; a demosaic by any other route, on the same line or not, is.

allow lists a repository's genuine exceptions, each a path relative to dir or a Regex over such paths (one exception may be given bare). They should be rare: a file is allowed only when it cannot go through the Features raw module (say, a third-party script kept verbatim), never as a way to keep a second decoding path.

Implemented by the VisualGeometryToolkitCoreTestExt extension: using Test loads it.

source
VisualGeometryToolkitCore.install_githooks — Function
install_githooks(repo = pwd(); hooks = githooks_dir()) -> String

Point the git working tree repo's core.hooksPath at hooks (default: this VisualGeometryToolkitCore's githooks/, whose sync-manifest re-resolves the repository's root Manifest through sync_manifest whenever a checkout, merge or rebase changes a Project.toml). Run once per clone; the hooks keep the path on the resolved VisualGeometryToolkitCore afterwards. Returns the hooks path set. The git config is the repository's, so it holds in every worktree of it.

source
VisualGeometryToolkitCore.sync_manifest — Function
sync_manifest(mode = "update"; io = stdout, repo = nothing) -> NamedTuple{(:created, :moved, :seconds)}

Re-resolve the active project after git moved a Project.toml: mode = "update" runs a full Pkg.update() (an untracked Manifest: a targeted update fails on an illegal Manifest), mode = "instantiate" a Pkg.instantiate() (a tracked Manifest: download only). Prints to io what moved and returns created (no Manifest held a direct dependency before), moved (each direct dependency whose version changed, (name, before, after), before === nothing for a new one) and seconds. With repo (a git working tree whose core.hooksPathinstall_githooks set to an installed VisualGeometryToolkitCore's hooks), the hooks path is moved to the newly resolved VisualGeometryToolkitCore's, so a Core update never leaves the repository on a copy that Pkg.gc may delete.

The git hooks run it (githooks/sync-manifest) by including this file by path, without loading the package; it is VisualGeometryToolkitCore's for every other caller.

source
VisualGeometryToolkitCore.gpu_problem — Method
gpu_problem(prefix::AbstractString; min_free_bytes::Integer = 20 * 2^30) -> Union{Nothing, String}

On a GPU-tier worker: nothing when the runner decided to run the tier (<prefix>_GPU_DECIDED=1, gpu_tier) and the accelerator is still functional with min_free_bytes free; otherwise the reason the GPU items cannot run, as a sentence.

source
VisualGeometryToolkitCore.gpu_tier — Method
gpu_tier(prefix::AbstractString; min_free_bytes::Integer = 20 * 2^30) -> Bool

The test runner's ONE decision whether to run a package's GPU tier: true when an accelerator is the default device (default_device is not KA.CPU(), the backend require_gpu hands the items, so the vendor package — CUDA — must be loaded and functional before it is first resolved), the environment does not opt out (<prefix>_TEST_GPU=0) and the device has at least min_free_bytes free (device_free_bytes). A yes is handed to the GPU tier's worker processes as <prefix>_GPU_DECIDED=1 (set here, in ENV); a no logs why (@info) and clears it (a verdict inherited from an earlier process is not this one's). The GPU tier runs its items on ONE worker per device (RadiometricCamera's rule: two processes on one card fail spuriously), so each worker's re-check of the free memory sees the device as the runner did. Called once, in test/runtests.jl, before the GPU tier; each GPU item then starts with require_gpu(prefix).

source
VisualGeometryToolkitCore.require_gpu — Method
require_gpu(prefix::AbstractString; min_free_bytes::Integer = 20 * 2^30) -> KA.Backend

The first line of every GPU test item: the accelerator's backend (default_device) when gpu_problem(prefix) finds none, and an error with the reason otherwise — never a silent skip, so a GPU tier cannot succeed on the CPU path.

source
VisualGeometryToolkitCore.SplatViolation — Type
SplatViolation

One finding of check_splat: the check that found it (:splat; :unknown, a splat of a value inferred Any, with unknown = true; or :stale_exception for a [[splat]] entry of DUPLICATION.toml that matches nothing), the file (relative to the repository root) and line of the call, the function whose method holds it (closures and keyword bodies by their enclosing function's name; the name an exception entry gives), the callee, and the splatted argument's inferred type.

source
VisualGeometryToolkitCore.check_splat — Function
check_splat(M::Module; extensions = true, unknown = false,
            root = <the git checkout holding pkgdir(M)>) -> Vector{SplatViolation}

Every call in package M (its submodules, and with extensions its LOADED package extensions) that splats an argument whose inferred type is not <:Union{Tuple, NamedTuple, StaticArray, Pair}: a Vector, a generator, a Dict, a ValueIterator, a String, an abstract type. Such a splat compiles its callee once per LENGTH of the data (zip(v...) is a new zip for every length(v)), and the length is the data's.

Typed, not syntactic: each method whose module is one of M's is inferred at its own signature (code_typed(…; optimize = false): the calls as written, nothing inlined) and every Core._apply_iterate — the compiler's form of every f(x...), [x...], (x...,) — is checked argument by argument. So a bare name (f(rows...)) is found, and a call returning a tuple (f(_pad(k, 2)...)) is not a finding. A splat into a callee compiled once whatever its arity — a builtin such as Core.apply_type, or Expr — is not a finding either (Core.tuple is: its tuple carries the length).

A value inferred Any (an untyped argument, inferred at the method's own signature) may be a tuple at every call: such a splat is reported, as check :unknown, only with unknown = true. Type the argument (a Tuple, an SVector) or hand over the collection whole.

The fixes: a method that takes the collection (linkaxes!(axes), collect(T, rows), convert(Vector{T}, xs)), reduce/mapreduce (mapreduce(typeof, typejoin, xs), reduce(vcat, parts)), vcat of collections, SVector{N}(v) for a length fixed by contract.

A module that is not a package (a script's) is checked with root, the directory its files' paths and its DUPLICATION.toml are relative to.

Exceptions live in the repository root's DUPLICATION.toml (the file check_duplication reads), each with its reason; an entry about a file this run checked that matches nothing is itself a finding:

[[splat]]                 # every splat in one function of one file
file = "src/a.jl"         # relative to the repository root
function = "f"            # the name the finding prints
reason = "…"

Implemented by the VisualGeometryToolkitCoreTestExt extension: using Test loads it.

source
VisualGeometryToolkitCore.MOVED_NAMES — Constant
MOVED_NAMES

The names this package retired by moving them to another package: each is a refusal here (an ArgumentError naming its replacement), not a definition. The duplication check reads it (check_duplication's name ownership): a module does not own a name it lists in its MOVED_NAMES, so the package that took the name over is not reported for defining it. Any stack package may define its own.

source
VisualGeometryToolkitCore.SCALE_INTERFACE_TAGS — Constant
SCALE_INTERFACE_TAGS

The scale-interface labels as TOML tags (a TagRegistry of ScaleInterface values' types): "consensus_anchored", "fixed_scale", "follows_scorer", "self_scaling", "no_scale", "unspecified_scale" — snake_case of the type's name. "fixed" and "partition_anchored" are retired. A config that names an interface (an ablation's delivered interface) reads it here.

source

Workspace CI

The CI of a stack repository, one implementation for every workspace: the packages a change affects, the registration rules, the agent-docs policy over a checkout, a downstream project pointed at a workspace, the generated codecov.yml and a sibling package's docs inventory. stack_ci is their command line; a workspace's own parameters are its WORKSPACE.toml (workspace_settings).

VisualGeometryToolkitCore.affected_packages — Method
affected_packages(root, paths) -> Vector{String}

The packages of the workspace at root that a change to paths (relative to root) affects, sorted: a path under <Package>/ affects that package, a path under a neutral directory (workspace_settings) affects none, and any other path (a root file, ci/, .github/) affects every package. The result is closed under the workspace's own dependency edges — [deps], [weakdeps] and the test and docs environments of each package — so a change to a package also runs every package built on it.

source
VisualGeometryToolkitCore.codecov_config — Method
codecov_config(packages) -> String

The text of a workspace's root codecov.yml: informational project and patch statuses and one carried-forward flag per package of packages over its src/ and ext/. CI tests only the packages a change affects, so each flag carries its last report forward until its package is tested again. The file is generated, never edited: registration_violations reports a codecov.yml that differs.

source
VisualGeometryToolkitCore.docs_inventory — Method
docs_inventory(site, package; root = nothing, variable = nothing)

The inventory of the stack package package for DocumenterInterLinks: the URL of its published dev docs under site ("<site>/<package>/dev/", whose objects.inv DocumenterInterLinks reads). With root (a workspace checkout) and variable naming a set local-build variable (docs_local), the pair (url, path) of that URL and the checkout's own <package>/docs/build/objects.inv, where one exists.

source
VisualGeometryToolkitCore.docs_linkcheck_ignore — Method
docs_linkcheck_ignore(site, variable) -> Vector{Regex}

The Documenter linkcheck_ignore rule of a local docs build (docs_local(variable)): every URL under site, since an @extref into a sibling package built in the same checkout points at anchors not yet published. Empty otherwise.

source
VisualGeometryToolkitCore.registration_violations — Method
registration_violations(root; initial = true) -> NamedTuple{(:errors, :warnings)}

The General/AutoMerge rules that can be checked before registering, over the workspace at the repository root root (a git checkout): one line per finding, "ERROR <package>: …" in errors and "WARN <package>: …" in warnings.

With initial the rules of a package's FIRST registration apply to every package General does not hold yet: its version is the standard initial version 0.1.0 and its name is not within Damerau–Levenshtein distance 2 of another's (a package named in the workspace's [manual_merge] gets a warning instead). A package General holds under its UUID is never a first registration, so those rules never apply to it; initial = false drops them for every package.

A package at the workspace's placeholder_version (workspace_settings) is under construction: every structural rule still applies to it, the version rule is replaced by a warning, and General holding it is an error.

Per package directory:

  • Project.toml: name is the directory, a UUID, a version; the name rules (ASCII letters and digits, an uppercase start, at least 5 characters, no "julia", no "jl" suffix).
  • [compat] for every [deps] and [weakdeps] entry, standard libraries and julia included; each entry parses and is bounded (no *, no >=); a compat on a package of the same workspace names that package's own series — its current breaking series ("0.5" for 0.5.x, "1" for 1.x) or a raised floor inside it ("0.5.2").
  • No [sources], [extras] or [targets] in the registered file; the test and docs projects source the package itself as {path = ".."} and nothing else.
  • A LICENSE holding the MIT text inside the directory (the registered tarball is the directory only).
  • The stack's dependency allow-list (stack_dependency_violations, with the workspace's stack_rows) for the package, test and docs projects.

Workspace:

  • No tracked Manifest*.toml anywhere; the root Project.toml is not a package.
  • A root codecov.yml, where there is one, is codecov_config of the workspace's packages.

The General checks need the General registry in the depot; without it they are skipped with a warning.

source
VisualGeometryToolkitCore.source_downstream — Method
source_downstream(dir, root; compat = false, extra = Dict{String, String}()) -> Vector{String}

Point the downstream project in dir at the packages of the workspace at root: sets [sources] <Package> = {path = "<its directory in the workspace>"} in dir's Project.toml for every workspace package it names in [deps], [weakdeps] or [extras], plus each name => path of extra (another downstream checkout). An existing entry is replaced. With compat, the project's compat entries on workspace packages are set to "0.1". Returns the packages sourced.

It REWRITES the file through TOML.print (comments are lost): for a throwaway checkout only (a nightly downstream job, a dry run).

source
VisualGeometryToolkitCore.stack_ci — Method
stack_ci(args; root = pwd(), io = stdout, log = stderr) -> Int

The command line of a stack repository's CI over the workspace at root: args[1] names the command, the rest are its arguments. Findings and results print to io, the one-line summary to log; returns the exit code (0, or 1 when a check found something), so a caller ends with exit(stack_ci(ARGS)).

  • packages: the workspace's packages (workspace_packages) as a JSON list; in GitHub Actions also packages=<list> in $GITHUB_OUTPUT.
  • affected [<base> [<head>]] (default origin/main, HEAD): the packages the change <base>...<head> affects (affected_packages), printed the same way.
  • registration-lint [--subsequent]: registration_violations, the warnings then the errors; --subsequent is initial = false.
  • agent-docs [--all]: workspace_agent_doc_violations; --all is every_file = true.
  • downstream <project dir> [--compat] [Name=path ...]: source_downstream.
  • codecov: codecov_config of the workspace's packages.

An unknown command throws.

source
VisualGeometryToolkitCore.workspace_agent_doc_violations — Method
workspace_agent_doc_violations(root; every_file = false, extra = get(ENV, "AGENT_DOC_PATTERNS", nothing)) -> Vector{String}

The agent-docs policy over the whole checkout at root, once: agent_doc_violations of the repository root, where git ls-files sees every package (inside a package directory there is no .git, and that check would walk the tree and pick up untracked per-machine files).

extra is the path of a private pattern file (one regular expression per line; release tooling keeps it outside the repository). With every_file, its patterns are also matched against EVERY tracked text file, one "file:line matches extra pattern #n" per finding.

source
VisualGeometryToolkitCore.workspace_settings — Method
workspace_settings(root) -> NamedTuple{(:tooling, :neutral, :placeholder_version, :stack_rows, :manual_merge)}

A workspace's own parameters of the stack's CI, read from WORKSPACE.toml at the repository root root (every key optional; no file gives the defaults):

  • tooling (default ["ci"]): the [workspace] members that are not packages.
  • neutral (default []): top-level directories that hold no package code and no package tooling (a landing page, design notes); a change under one affects no package (affected_packages).
  • placeholder_version (default: none): the version of a package under construction, which is not registered and must not be (registration_violations).
  • stack_rows (default: none): the path, relative to root, of this repository's rows of the stack's dependency allow-list (the extra of stack_dependency_violations); returned absolute.
  • [manual_merge] (default: empty): Package = "reason" for a package whose name AutoMerge's similarity guideline refuses, so a General maintainer merges its first registration by hand.

An unknown key throws.

source

Index