Skip to content

Audit public reexports and inherited module docs#27

Merged
ChrisRackauckas merged 9 commits into
mainfrom
agent/inherited-reexport-rendering
Jul 21, 2026
Merged

Audit public reexports and inherited module docs#27
ChrisRackauckas merged 9 commits into
mainfrom
agent/inherited-reexport-rendering

Conversation

@ChrisRackauckas-Claude

@ChrisRackauckas-Claude ChrisRackauckas-Claude commented Jul 20, 2026

Copy link
Copy Markdown
Member

Ignore until reviewed by @ChrisRackauckas.

This PR handles public reexports in two separate ways:

  • Re-exported dependency modules inherit their defining package's module documentation and are not forced into a local @docs block. Re-exported functions and types still require a local rendered API entry.
  • run_qa gains an opt-in check_reexports = true audit. It remains off by default to avoid a breaking fleet-wide change. Intentional facade API is listed with reexports_allow.
  • The exported public_reexports helper detects imported functions, types, modules, constants, macros, and operators, plus aliases whose values expose module ownership.
  • Package-owned APIs defined in nested submodules are not classified as dependency reexports.
  • The version is bumped to 2.4.0 because this adds public API.

Julia cannot recover source-binding provenance after locally assigning scalar/enum values, callable objects, or constructed Union types; direct imports are fully covered.

Local verification:

  • Julia 1.10: Pkg.test() passed, 318/318.
  • Julia 1.12: Pkg.test() passed, 333/333.
  • Runic and git diff --check passed.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member Author

I validated this PR's current head (a5ccb593f0f2551b9a325da8960701b754dfd004) against the exact OptimizationOptimisers_QA harness on Optimization.jl master.

It improves the result substantially, reducing the rendered-public-API failure from 300 names to nine, but the harness still fails:

DEFAULT_CALLBACK
DEFAULT_DATA
DebugLevel
ErrorLevel
InfoLevel
MaxSense
MinSense
Silent
WarnLevel

These are inherited values/constants or enum values. parentmodule(getfield(pkg, name)) !== pkg identifies inherited functions and types, but the value itself does not retain the binding's source module in these cases.

Reproduction setup:

  • Optimization.jl 34a8fd5cb3484c1c7ce471f7964d0bf81bc9796a
  • Julia 1.12.6
  • this PR checked out as the local SciMLTesting source
  • GROUP=OptimizationOptimisers_QA JULIA_PKG_PRECOMPILE_AUTO=0 julia +1.12 --startup-file=no --project=. -e 'using Pkg; Pkg.test()'

The analogous OptimizationPolyalgorithms_QA lane also fails under released SciMLTesting 2.3.0, with 264 inherited names. I recorded the full boundary and CI evidence in SciML/Optimization.jl#1278.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas-Claude ChrisRackauckas-Claude changed the title Treat re-exported modules as inherited rendered docs Audit public reexports and inherited module docs Jul 20, 2026
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas
ChrisRackauckas marked this pull request as ready for review July 21, 2026 01:21
@ChrisRackauckas
ChrisRackauckas merged commit 61011e5 into main Jul 21, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants