ExplicitImports.jl

https://juliatesting.github.io/ExplicitImports.jl/stable/
Admin
ExplicitImports.jl is a Julia tool that detects implicit imports and helps mitigate issues with...
Tokens:6,275
Snippets:29
Trust Score:9.7
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install ExplicitImports.jl with Pkg.add

Source: https://juliatesting.github.io/ExplicitImports.jl

Install the package using Julia's package manager. Run this in a Julia REPL or script.

```julia
using Pkg; Pkg.add("ExplicitImports")
```

--------------------------------

### ExplicitImports CLI help output

Source: https://juliatesting.github.io/ExplicitImports.jl

Example output from running the ExplicitImports CLI with --help, showing the synopsis, description, and options including --check, --test, --checklist, and valid check values.

```text
NAME
       ExplicitImports.main - analyze a package's namespace

SYNOPSIS
       julia -m ExplicitImports [OPTIONS] <path>

DESCRIPTION
       `ExplicitImports.main` (typically invoked as `julia -m ExplicitImports`)
       analyzes a package's imports and qualified accesses, and prints the results.

OPTIONS
       <path>
           Path to the root directory of the package (default: pwd)
       --help
           Show this message
       --check
           Run checks instead of printing. If --checklist is not specified, all checks are run
       --test
           Run Test.jl-style checks instead of printing
       --checklist <check1,check2>,...
           Run checks specified by <check1>,<check2>,...
           This will imply --check.

           Valid values for each check are:
           - Individual checks:
                 all_explicit_imports_are_public,
                 all_qualified_accesses_are_public,
                 all_explicit_imports_via_owners,
                 all_qualified_accesses_via_owners,
                 no_implicit_imports,
                 no_self_qualified_accesses,
                 no_stale_explicit_imports
           - Select all checks: all
           - Exclude a check: prepend an individual check with 'exclude_'

           The selection logic is performed in the order given.
           If you pass only exclusions, it will assume that it starts from a complete list, and then excludes.
           If you pass any individual checks, it will assume that it starts from an empty list, and then includes.
           Passing both individual and exclusion checks does not make sense.
```

--------------------------------

### Run explicit-imports-jl CLI help

Source: https://juliatesting.github.io/ExplicitImports.jl

Runs the installed CLI executable to display its help message.

```bash
explicit-imports-jl --help
```

--------------------------------

### Install ExplicitImports CLI with Julia 1.12

Source: https://juliatesting.github.io/ExplicitImports.jl

Installs the explicit-imports-jl CLI executable using Julia v1.12's Pkg apps functionality. Requires juliaup to add Julia 1.12 first.

```bash
julia +1.12 --startup-file=no -e 'using Pkg; Pkg.activate(temp=true); Pkg.Apps.add("ExplicitImports")'
```

--------------------------------

### Dynamic include loop in MathOptInterface.Test

Source: https://juliatesting.github.io/ExplicitImports.jl

Example of a dynamic include statement in MathOptInterface.jl's Test module, where the argument is not a string literal. This prevents ExplicitImports.jl from analyzing the included files.

```julia
for file in readdir(@__DIR__)
    if startswith(file, "test_") && endswith(file, ".jl")
        include(file)
    end
end
```

--------------------------------

### Analyze a package with print_explicit_imports

Source: https://juliatesting.github.io/ExplicitImports.jl

After installing, load the target package and ExplicitImports, then call print_explicit_imports on the package to display detected implicit imports and related issues.

```julia
using MyPackage # the package you want to analyze
using ExplicitImports
print_explicit_imports(MyPackage)
```

--------------------------------

### Run main function with options

Source: https://juliatesting.github.io/ExplicitImports.jl

Invokes the main function directly with --print and --checklist options to exclude all qualified accesses are public.

```bash
julia -e 'using ExplicitImports: main; main(["--print", "--checklist", "exclude_all_qualified_accesses_are_public"])'
```

--------------------------------

### Show ExplicitImports help options

Source: https://juliatesting.github.io/ExplicitImports.jl

Displays all command-line options for ExplicitImports using various invocation methods.

```bash
julia +nightly -m ExplicitImports --help
```

```bash
julia <path/to/ExplicitImports.jl>/scripts/explicit-imports.jl --help
```

```bash
julia -e 'using ExplicitImports: main; exit(main(["--help"]))'
```

--------------------------------

### Run main function via script

Source: https://juliatesting.github.io/ExplicitImports.jl

Runs the main function by executing the explicit-imports.jl script from the repository, either with julia or directly as an executable.

```bash
julia <path/to/ExplicitImports.jl>/scripts/explicit-imports.jl path_to_package
```

```bash
./scripts/explicit-imports.jl path_to_package
```

--------------------------------

### Add Julia bin directory to PATH

Source: https://juliatesting.github.io/ExplicitImports.jl

Adds the Julia depot bin directory (default ~/.julia/bin) to the PATH environment variable, typically placed in a shell startup script like ~/.bashrc or ~/.zshrc.

```bash
export PATH="${HOME}/.julia/bin:${PATH}"
```

--------------------------------

### print_explicit_imports(ExplicitImports; show_locations=true) output

Source: https://juliatesting.github.io/ExplicitImports.jl

Pass show_locations=true to include file and line locations for each reported issue. The output is identical to the default call, listing the same stale import, self-qualified access, and 13 non-public name accesses with their source locations.

```julia
julia> print_explicit_imports(ExplicitImports; show_locations=true)
  Module ExplicitImports is not relying on any implicit imports.

  However, module ExplicitImports has stale explicit imports for this 1 unused name:

    •  parse is unused but it was imported from ExplicitImports.Vendored.JuliaSyntax at
       /Users/eph/ExplicitImports/src/ExplicitImports.jl:9:30

  Additionally, module ExplicitImports has 1 self-qualified access:

    •  parent was accessed as ExplicitImports.parent inside ExplicitImports at
       /Users/eph/ExplicitImports/src/deprecated.jl:79:21

  Additionally, module ExplicitImports accesses 13 non-public names:

    •  Code is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/precompile.jl:8:51

    •  List is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/precompile.jl:10:51

    •  Paragraph is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/precompile.jl:9:51

    •  PkgId is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/improper_explicit_imports.jl:153:18

    •  Types is not public in Pkg but it was accessed via Pkg at
       /Users/eph/ExplicitImports/src/main.jl:54:25

    •  ioproperties is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/main.jl:45:25

    •  loaded_modules is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/improper_explicit_imports.jl:154:23

    •  loaded_modules_array is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/ExplicitImports.jl:414:21

    •  maybe_root_module is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/improper_explicit_imports.jl:54:47

    •  parent is not public in ExplicitImports but it was accessed via ExplicitImports at
       /Users/eph/ExplicitImports/src/deprecated.jl:79:21

    •  parse is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/interactive_usage.jl:231:19

    •  set_active_project is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/main.jl:66:22

    •  term is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/precompile.jl:10:25
```

--------------------------------

### print_explicit_imports output with strict mode (default)

Source: https://juliatesting.github.io/ExplicitImports.jl

Output of print_explicit_imports on MathOptInterface.Test with default strict=true, showing the warning about dynamic includes and the need to pass pkgdir(MathOptInterface) as the second argument.

```julia
julia> print_explicit_imports(MathOptInterface.Test, pkgdir(MathOptInterface))
  Module MathOptInterface.Test could not be accurately analyzed, likely due to dynamic include statements. You can pass strict=false to
  attempt to get (possibly inaccurate) results anyway.

  Module MathOptInterface.Test._BaseTest could not be accurately analyzed, likely due to dynamic include statements. You can pass
  strict=false to attempt to get (possibly inaccurate) results anyway.
```

--------------------------------

### Configure pre-commit hook for ExplicitImports.jl

Source: https://juliatesting.github.io/ExplicitImports.jl

Add this YAML to .pre-commit-config.yaml to run ExplicitImports as a pre-commit hook. The hook runs the checks and fails if any fail. The --print argument prints the explicit_imports, and --checklist specifies which checks to run; if omitted, all checks run.

```yaml
- repo: https://github.com/JuliaTesting/ExplicitImports.jl
  rev: v1.10.0
  hooks:
    - id: explicit-imports
      args: [--print,--checklist,"exclude_all_qualified_accesses_are_public"]
```

--------------------------------

### Run ExplicitImports on Julia nightly

Source: https://juliatesting.github.io/ExplicitImports.jl

Runs ExplicitImports on Julia v1.12+ using the nightly channel with the -m flag, specifying a checklist to exclude all qualified accesses are public.

```bash
julia +nightly -m ExplicitImports --print --checklist exclude_all_qualified_accesses_are_public
```

--------------------------------

### print_explicit_imports(ExplicitImports) default output

Source: https://juliatesting.github.io/ExplicitImports.jl

Run this in a Julia REPL to check a module for implicit imports, stale explicit imports, self-qualified accesses, and non-public name accesses. The output reports that the module has no implicit imports but lists one stale explicit import, one self-qualified access, and 13 non-public name accesses.

```julia
julia> using ExplicitImports

julia> print_explicit_imports(ExplicitImports)
  Module ExplicitImports is not relying on any implicit imports.

  However, module ExplicitImports has stale explicit imports for this 1 unused name:

    •  parse is unused but it was imported from ExplicitImports.Vendored.JuliaSyntax at
       /Users/eph/ExplicitImports/src/ExplicitImports.jl:9:30

  Additionally, module ExplicitImports has 1 self-qualified access:

    •  parent was accessed as ExplicitImports.parent inside ExplicitImports at
       /Users/eph/ExplicitImports/src/deprecated.jl:79:21

  Additionally, module ExplicitImports accesses 13 non-public names:

    •  Code is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/precompile.jl:8:51

    •  List is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/precompile.jl:10:51

    •  Paragraph is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/precompile.jl:9:51

    •  PkgId is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/improper_explicit_imports.jl:153:18

    •  Types is not public in Pkg but it was accessed via Pkg at
       /Users/eph/ExplicitImports/src/main.jl:54:25

    •  ioproperties is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/main.jl:45:25

    •  loaded_modules is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/improper_explicit_imports.jl:154:23

    •  loaded_modules_array is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/ExplicitImports.jl:414:21

    •  maybe_root_module is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/improper_explicit_imports.jl:54:47

    •  parent is not public in ExplicitImports but it was accessed via ExplicitImports at
       /Users/eph/ExplicitImports/src/deprecated.jl:79:21

    •  parse is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/interactive_usage.jl:231:19

    •  set_active_project is not public in Base but it was accessed via Base at
       /Users/eph/ExplicitImports/src/main.jl:66:22

    •  term is not public in Markdown but it was accessed via Markdown at
       /Users/eph/ExplicitImports/src/precompile.jl:10:25
```

--------------------------------

### print_explicit_imports output with strict=false

Source: https://juliatesting.github.io/ExplicitImports.jl

Output of print_explicit_imports on MathOptInterface.Test with strict=false, showing that the module is reported as not relying on any implicit imports, but with the caveat that this may be inaccurate due to unscanned files.

```julia
julia> print_explicit_imports(MathOptInterface.Test, pkgdir(MathOptInterface); strict=false)
  Module MathOptInterface.Test is not relying on any implicit imports.

  Module MathOptInterface.Test._BaseTest is not relying on any implicit imports.
```
Tokens:
Raw