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.
familynames the family (:optimization_strategy,:loss) in messages.suffixis the family's common type-name suffix ("Shape"forTLSShape), stripped before the spelling rule;""for none.pairsaretag => 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 isnothing, whose tag is"none".retiredareold => newrenames: the old tag no longer loads, and the error names its successor.pathsare 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.
Base.merge — Method
merge(a::TagRegistry, b::TagRegistry...) -> TagRegistryThe 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.
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).
VisualGeometryToolkitCore.expected_tag — Method
expected_tag(registry::TagRegistry, value) -> StringThe tag the rule gives value in registry: "none" for nothing, otherwise snake_case of its type name with the registry's suffix stripped from the end when present.
VisualGeometryToolkitCore.retired_tags — Method
retired_tags(registry::TagRegistry) -> Vector{Pair{String, String}}The old => new renames of a TagRegistry.
VisualGeometryToolkitCore.snake_case — Method
snake_case(name::Symbol) -> String
snake_case(name::AbstractString) -> StringThe tag spelling of a CamelCase name, by exactly two rules, then lowercase:
- an
_goes before an uppercase letter that follows a lowercase letter or a digit; - 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"VisualGeometryToolkitCore.tag_family — Method
tag_family(registry::TagRegistry) -> SymbolThe family a TagRegistry names.
VisualGeometryToolkitCore.tag_of — Method
tag_of(registry::TagRegistry, x) -> StringThe 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.
VisualGeometryToolkitCore.tag_paths — Method
tag_paths(registry::TagRegistry) -> Vector{Regex}The TOML key paths whose string values are tags of registry's family.
VisualGeometryToolkitCore.tag_registries — Method
tag_registries(M::Module) -> Vector{Pair{String, TagRegistry}}Every TagRegistry constant of M and its submodules, as "Module.NAME" => registry.
VisualGeometryToolkitCore.tag_rule_violations — Method
tag_rule_violations(registry::TagRegistry) -> Vector{String}Every way registry breaks the tag rule (see TagRegistry): a tag that is not its value's expected_tag, and a retired tag whose successor is not a current tag. Empty when the registry obeys it.
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.
VisualGeometryToolkitCore.CONTRACT_GENERICS — Constant
CONTRACT_GENERICSThe 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
FitResultproperty 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 accessorscalibrationanddesign; - the surface protocol (
intersection,normal,chart,surface_point,bounds) andsurface, which builds a posed target's primitive; - the camera maps
projectandbackproject, andconvert_eltype; - the
Manifoldprotocol:tangent_size,retractandrecenter(required),local_coordinates,retract_jacobian,action_jacobian,zero_tangent,restrict,tangent_partandtransform_covariance(optional), andminimal_manifoldandambient_coordinates, which a downstream model type answers (a model that is not a static array or a tuple of them addsambient_coordinatesrather than overridingretract_jacobian); - the plotting stubs the Makie extensions implement.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.NamingViolation — Type
NamingViolationOne finding of check_naming: the file (relative to the package directory), the line, the offending name or line of text, and the rule it breaks (:R3 … :R12, or :parse for a file that does not parse).
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.
VisualGeometryToolkitCore.naming_scope — Function
naming_scope(dir) -> Vector{String}The files check_naming reads under dir. Implemented by the VisualGeometryToolkitCoreTestExt extension: using Test loads it.
VisualGeometryToolkitCore.RECORDED_NESTED_STATES — Constant
RECORDED_NESTED_STATESThe names of the nested state types test_recorded compares field by field by default (the posterior weights, the division camera's IRLS state, the GNC ladder); every other non-bits field of a state is a workspace it points into.
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.
VisualGeometryToolkitCore.check_rows_jacobian — Function
check_rows_jacobian(lm, θ, m; atol = 0, rtol = 0, reference = ForwardDiff.jacobian,
jacobian = Matrix{Float64}(undef, m, length(θ))) -> BoolDoes 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).
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.
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).
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).
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).
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).
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).
VisualGeometryToolkitCore.readme_environment — Function
readme_environment(root, packages; developed = Dict(), setup = "") -> StringA 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).
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).
VisualGeometryToolkitCore.rows_cost — Function
rows_cost(lm, θ, m) -> RealThe chart-LM cost Σ rᵢ² of a linearization state lm at chart point θ, its m rows filled by residual_rows!. Implemented by VisualGeometryToolkitCoreTestExt (using Test loads it).
VisualGeometryToolkitCore.run_readme_child — Function
run_readme_child(env, args...) -> IntRun 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).
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...) -> SensorCharacterisationTHE 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(withblack_std_error);dark = (; offset, variance, exposure_band, frames)→ aDarkover that channel black (theFileBlackwithoutblack);darks, a vector of such named tuples → aDarks, one Dark per band, each over that channel black, which is also the shared fallback (darkordarks, not both); - noise:
read_noise→ReadNoise(withread_noise_std_error); with again→PoissonGaussian(gain_std_errorandread_noise_std_errorits 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).
VisualGeometryToolkitCore.test_docs — Function
test_docs(M::Module; exceptions = Dict{String,String}(), backlog = Set{String}(),
signature_exceptions = Set{String}(), dirs = ("src",)) -> NamedTupleThe docstring gates the Documenter build cannot run (its checkdocs = :public sees only docstrings that exist), over package M, as tests:
- every public name of
Mand its submodules has a docstring, except theexceptions(name => reason: undocumented on purpose) and thebacklog(names still to document; the list only shrinks — a name documented must leave it); a stale exception is a failure; - no docstring under
M'sdirs(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
Mainare not the package's), and a docstring that shows a sibling's signature leaves the sibling documented on its own, except thesignature_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).
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).
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).
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 = falseskips it), no method ambiguities involving a method ofM(pairs touching a test item'sMainmethods are dropped and logged), and no piracy inMor any of its submodules beyondtreat_as_own.ExplicitImports: no implicit imports, explicit imports via their owners, no stale explicit imports beyond
stale_ignore; withqualified_ignore(a tuple of names) also every qualified access public, those names excepted.JET:
report_package(M)counts at mostjet_boundreports, not counting KernelAbstractions LAUNCH reports (akwcall(::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(@testthat it finds nothing),:report(every finding logged with@warnand the gate recorded@test_broken; a gate that finds nothing is an ordinary test) or:off:tag_rules: everyTagRegistryconstant ofMand its submodules obeys the tag rule (tag_rule_violations);tag_tables: no tag table outside aTagRegistryinM'ssrc/(tag_table_violations, a heuristic scan);config_tags: every string at a registry's key path in the TOML files underconfig_dirs(default:M'sconfigs/, when it exists) is a current tag ofM's registries and of the extraregistries(config_tag_violations);stack_dependencies:M's Project.toml names only the stack packages instack_name's row of the allow-list (stack_dependency_violations); a project kept outside the published stack gives its own row asstack_extra(theextraofstack_dependencies);public_names: no_-prefixed name reached from another stack package (private_name_violationsoversrc/andext/);third_party_public(default:report): ExplicitImports'check_all_explicit_imports_are_publicandcheck_all_qualified_accesses_are_public(withqualified_ignore) — a non-public name of ANY module, the stack's or a third party's (ForwardDiff'sDual, StaticArraysCore'sStaticArray);contract_generics: every methodMadds to another stack package's function lands on that owner'sCONTRACT_GENERICS(contract_generic_violations);splat(default:report): no call splats a collection whose length is data — aVector, a generator, an abstract type — which compiles the callee once per length (check_splatoverMand its loaded extensions; exceptions areDUPLICATION.toml's[[splat]]entries).
Implemented by VisualGeometryToolkitCoreQualityExt: using Test, Aqua, ExplicitImports, JET loads it.
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).
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).
VisualGeometryToolkitCore.test_recorded — Function
test_recorded(make; nested = RECORDED_NESTED_STATES) -> IntThat 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).
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).
VisualGeometryToolkitCore.thrown_message — Function
thrown_message(f; shown = false) -> StringThe 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).
VisualGeometryToolkitCore.AGENT_DOC_FORBIDDEN — Constant
AGENT_DOC_FORBIDDENThe patterns no agent instruction file of a stack package may match (agent_doc_violations): absolute paths into a user's home directory, private keys and access tokens.
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.
VisualGeometryToolkitCore.convention_files — Method
convention_files() -> Vector{String}The absolute paths of the convention files in conventions_dir, in reading order (the order of the docs' Conventions page).
VisualGeometryToolkitCore.conventions_dir — Method
conventions_dir() -> StringThe 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.
VisualGeometryToolkitCore.DuplicationViolation — Type
DuplicationViolationOne 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.
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:
- Name ownership (the
Moduleform only). Every bindingM(or a submodule of it) owns — defined there, not imported, a function or type whoseparentmoduleis that module; method extensions of another package's function do not count — whose name an upstream stack package also owns, private_namesincluded (Julia's per-moduleeval,includeand__init__, and the per-packageCONTRACT_GENERICS, are each package's own). Upstream is every package inM's dependency closure (its loadedProject.toml[deps], transitively) that is VisualGeometryToolkitCore or depends on it: Core < IO, Features < Estimation < Eval < the downstream repositories. - 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 ofsimilarity, each a pair(jaccard, min_tokens)that both bodies' token counts must reach: by defaultJ ≥ 0.6with at least 60 tokens, orJ ≥ 0.85with 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 againststack. - Whole files. A Julia file whose token text, comments and whitespace dropped (at least
min_file_tokenstokens), equals another file's. - Retired patterns. A line of code (comments and docstrings left out) that spells a pattern whose owner lives elsewhere:
NLLSOptions((Core'sLmStops, mapped inlmsolve_chart!),acos(clamp((tr(…(Rotations'rotation_angle), the sRGB transfer constants (Features'src/linear_image.jl), and a\newcommandwriter (Eval'ssrc/reproduce/number_macros.jl). The failure names the owner. - 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(AbstractGPUArrayand 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 whateverget_backendreturns, 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), sozeros_onis a helper andfill_sqrt_weights!ortransfer_ellipseis not. - 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_cudabeside 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.
VisualGeometryToolkitCore.RawDecodingViolation — Type
RawDecodingViolationOne 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.(…)).
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.
VisualGeometryToolkitCore.githooks_dir — Method
githooks_dir() -> StringThe githooks/ folder of this VisualGeometryToolkitCore installation: the one copy of the stack's git hooks (sync-manifest, and post-checkout, post-merge, post-rewrite linking to it), which install_githooks installs.
VisualGeometryToolkitCore.install_githooks — Function
install_githooks(repo = pwd(); hooks = githooks_dir()) -> StringPoint 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.
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.
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.
VisualGeometryToolkitCore.gpu_tier — Method
gpu_tier(prefix::AbstractString; min_free_bytes::Integer = 20 * 2^30) -> BoolThe 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).
VisualGeometryToolkitCore.require_gpu — Method
require_gpu(prefix::AbstractString; min_free_bytes::Integer = 20 * 2^30) -> KA.BackendThe 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.
VisualGeometryToolkitCore.SplatViolation — Type
SplatViolationOne 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.
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.
VisualGeometryToolkitCore.MOVED_NAMES — Constant
MOVED_NAMESThe 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.
VisualGeometryToolkitCore.AbstractVignetting — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.AbstractVignetting.
VisualGeometryToolkitCore.BinnedRadialProfile — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.BinnedRadialProfile.
VisualGeometryToolkitCore.EnvironmentLight — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.EnvironmentLight.
VisualGeometryToolkitCore.LogVignetting — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.LogVignetting.
VisualGeometryToolkitCore.RADIAL_CHARTS — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.RADIAL_CHARTS.
VisualGeometryToolkitCore.RadialVignetting — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.RadialVignetting.
VisualGeometryToolkitCore.SphericalHarmonicMap — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.SphericalHarmonicMap.
VisualGeometryToolkitCore.TensorProductVignetting — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.TensorProductVignetting.
VisualGeometryToolkitCore.VIGNETTING_TAGS — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.VIGNETTING_TAGS.
VisualGeometryToolkitCore.active_coefficients — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.active_coefficients.
VisualGeometryToolkitCore.center_gradient — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.center_gradient.
VisualGeometryToolkitCore.coefficient_jacobian — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.coefficient_jacobian.
VisualGeometryToolkitCore.coefficients — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.coefficients.
VisualGeometryToolkitCore.control_points — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.control_points.
VisualGeometryToolkitCore.exit_direction — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.exit_direction.
VisualGeometryToolkitCore.field_radius — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.field_radius.
VisualGeometryToolkitCore.knot_vectors — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.knot_vectors.
VisualGeometryToolkitCore.log_spline — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.log_spline.
VisualGeometryToolkitCore.max_degree — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.max_degree.
VisualGeometryToolkitCore.n_control_points — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.n_control_points.
VisualGeometryToolkitCore.pole_regular_basis — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.pole_regular_basis.
VisualGeometryToolkitCore.projective_chart — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.projective_chart.
VisualGeometryToolkitCore.projective_knots — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.projective_knots.
VisualGeometryToolkitCore.radial_chart — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.radial_chart.
VisualGeometryToolkitCore.radial_coordinate — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.radial_coordinate.
VisualGeometryToolkitCore.radiance — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.radiance.
VisualGeometryToolkitCore.radiance_map — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.radiance_map.
VisualGeometryToolkitCore.sh_basis — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.sh_basis.
VisualGeometryToolkitCore.sh_count — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.sh_count.
VisualGeometryToolkitCore.sh_index — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.sh_index.
VisualGeometryToolkitCore.spline_degree — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.spline_degree.
VisualGeometryToolkitCore.with_center — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.with_center.
VisualGeometryToolkitCore.with_coefficients — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.with_coefficients.
VisualGeometryToolkitCore.with_control_points — Method
Retired (VisualGeometryToolkitCore 0.12.0): VisualRadiometryToolkitCore.with_control_points.
VisualGeometryToolkitCore.SCALE_INTERFACE_TAGS — Constant
SCALE_INTERFACE_TAGSThe 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.
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.
VisualGeometryToolkitCore.codecov_config — Method
codecov_config(packages) -> StringThe 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.
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.
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.
VisualGeometryToolkitCore.docs_local — Method
docs_local(variable) -> BoolWhether the environment variable variable asks for a local docs build (its value is "1"): a release's docs then build against this checkout's own builds of their sibling packages, before those are published (docs_inventory, docs_linkcheck_ignore).
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:
nameis 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'sstack_rows) for the package, test and docs projects.
Workspace:
- No tracked
Manifest*.tomlanywhere; the root Project.toml is not a package. - A root
codecov.yml, where there is one, iscodecov_configof the workspace's packages.
The General checks need the General registry in the depot; without it they are skipped with a warning.
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).
VisualGeometryToolkitCore.stack_ci — Method
stack_ci(args; root = pwd(), io = stdout, log = stderr) -> IntThe 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 alsopackages=<list>in$GITHUB_OUTPUT.affected [<base> [<head>]](defaultorigin/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;--subsequentisinitial = false.agent-docs [--all]:workspace_agent_doc_violations;--allisevery_file = true.downstream <project dir> [--compat] [Name=path ...]:source_downstream.codecov:codecov_configof the workspace's packages.
An unknown command throws.
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.
VisualGeometryToolkitCore.workspace_packages — Method
workspace_packages(root) -> Vector{String}The packages of the Pkg workspace at the repository root root: the [workspace] projects of its Project.toml, in the file's order, without the tooling members (workspace_settings).
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 toroot, of this repository's rows of the stack's dependency allow-list (theextraofstack_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.
Index
VisualGeometryToolkitCore.AGENT_DOC_FORBIDDENVisualGeometryToolkitCore.CONTRACT_GENERICSVisualGeometryToolkitCore.MOVED_NAMESVisualGeometryToolkitCore.RECORDED_NESTED_STATESVisualGeometryToolkitCore.SCALE_INTERFACE_TAGSVisualGeometryToolkitCore.DuplicationViolationVisualGeometryToolkitCore.NamingViolationVisualGeometryToolkitCore.RawDecodingViolationVisualGeometryToolkitCore.ReadmeExampleVisualGeometryToolkitCore.SplatViolationVisualGeometryToolkitCore.TagRegistryBase.mergeVisualGeometryToolkitCore.AbstractVignettingVisualGeometryToolkitCore.BinnedRadialProfileVisualGeometryToolkitCore.EnvironmentLightVisualGeometryToolkitCore.LogVignettingVisualGeometryToolkitCore.RADIAL_CHARTSVisualGeometryToolkitCore.RadialVignettingVisualGeometryToolkitCore.SphericalHarmonicMapVisualGeometryToolkitCore.TensorProductVignettingVisualGeometryToolkitCore.VIGNETTING_TAGSVisualGeometryToolkitCore.active_coefficientsVisualGeometryToolkitCore.affected_packagesVisualGeometryToolkitCore.agent_doc_violationsVisualGeometryToolkitCore.center_gradientVisualGeometryToolkitCore.check_duplicationVisualGeometryToolkitCore.check_namingVisualGeometryToolkitCore.check_raw_decodingVisualGeometryToolkitCore.check_rows_jacobianVisualGeometryToolkitCore.check_splatVisualGeometryToolkitCore.codecov_configVisualGeometryToolkitCore.coefficient_jacobianVisualGeometryToolkitCore.coefficientsVisualGeometryToolkitCore.config_tag_violationsVisualGeometryToolkitCore.contract_generic_violationsVisualGeometryToolkitCore.control_pointsVisualGeometryToolkitCore.convention_filesVisualGeometryToolkitCore.conventions_dirVisualGeometryToolkitCore.docs_inventoryVisualGeometryToolkitCore.docs_linkcheck_ignoreVisualGeometryToolkitCore.docs_localVisualGeometryToolkitCore.exit_directionVisualGeometryToolkitCore.expected_tagVisualGeometryToolkitCore.field_radiusVisualGeometryToolkitCore.githooks_dirVisualGeometryToolkitCore.gpu_problemVisualGeometryToolkitCore.gpu_tierVisualGeometryToolkitCore.install_githooksVisualGeometryToolkitCore.install_linesVisualGeometryToolkitCore.install_packagesVisualGeometryToolkitCore.install_tableVisualGeometryToolkitCore.julia_blocksVisualGeometryToolkitCore.knot_vectorsVisualGeometryToolkitCore.loaded_packagesVisualGeometryToolkitCore.log_splineVisualGeometryToolkitCore.max_degreeVisualGeometryToolkitCore.n_control_pointsVisualGeometryToolkitCore.naming_scopeVisualGeometryToolkitCore.page_examplesVisualGeometryToolkitCore.pole_regular_basisVisualGeometryToolkitCore.private_name_violationsVisualGeometryToolkitCore.projective_chartVisualGeometryToolkitCore.projective_knotsVisualGeometryToolkitCore.radial_chartVisualGeometryToolkitCore.radial_coordinateVisualGeometryToolkitCore.radianceVisualGeometryToolkitCore.radiance_mapVisualGeometryToolkitCore.readme_environmentVisualGeometryToolkitCore.readme_examplesVisualGeometryToolkitCore.registration_violationsVisualGeometryToolkitCore.require_gpuVisualGeometryToolkitCore.retired_tagsVisualGeometryToolkitCore.rows_costVisualGeometryToolkitCore.run_readme_childVisualGeometryToolkitCore.sensor_fixtureVisualGeometryToolkitCore.sh_basisVisualGeometryToolkitCore.sh_countVisualGeometryToolkitCore.sh_indexVisualGeometryToolkitCore.snake_caseVisualGeometryToolkitCore.source_downstreamVisualGeometryToolkitCore.spline_degreeVisualGeometryToolkitCore.stack_ciVisualGeometryToolkitCore.stack_dependenciesVisualGeometryToolkitCore.stack_dependency_violationsVisualGeometryToolkitCore.sync_manifestVisualGeometryToolkitCore.tag_familyVisualGeometryToolkitCore.tag_ofVisualGeometryToolkitCore.tag_pathsVisualGeometryToolkitCore.tag_registriesVisualGeometryToolkitCore.tag_rule_violationsVisualGeometryToolkitCore.tag_table_violationsVisualGeometryToolkitCore.test_constraint_problemVisualGeometryToolkitCore.test_docsVisualGeometryToolkitCore.test_duplicationVisualGeometryToolkitCore.test_local_optimization_contractVisualGeometryToolkitCore.test_manifold_contractVisualGeometryToolkitCore.test_namingVisualGeometryToolkitCore.test_quality_gatesVisualGeometryToolkitCore.test_readme_exampleVisualGeometryToolkitCore.test_readme_rowVisualGeometryToolkitCore.test_recordedVisualGeometryToolkitCore.test_scoring_contractVisualGeometryToolkitCore.test_splatVisualGeometryToolkitCore.test_termination_recordVisualGeometryToolkitCore.thrown_messageVisualGeometryToolkitCore.with_centerVisualGeometryToolkitCore.with_coefficientsVisualGeometryToolkitCore.with_control_pointsVisualGeometryToolkitCore.workspace_agent_doc_violationsVisualGeometryToolkitCore.workspace_packagesVisualGeometryToolkitCore.workspace_settings