abstract type PkgSource

Represents the installed version of a package, e.g. a release from a registry, or a Pkg.add'd package, or a Pkg.dev'd package.

analyze(name_or_dir_or_url::AbstractString; registry=general_registry(), auth::GitHub.Authorization=github_auth(), version=nothing)

Analyze the package pointed to by the mandatory argument and return a summary of its properties.

• If name_or_dir_or_url is a valid Julia identifier, it is assumed to be the name of a

package available in registry. The function then uses find_package to find its entry in the registry and analyze the content of its latest registered version (or a different version, if the keyword argument version is supplied).

• If name_or_dir_or_url is a filesystem path, analyze the package whose source code is

located at name_or_dir_or_url.

• Otherwise, name_or_dir_or_url is assumed to be a URL. The repository is cloned to a temporary directory and analyzed.

If the GitHub authentication is non-anonymous and the repository is on GitHub, the list of contributors to the repository is also collected. Only the number of contributors will be shown in the summary. See PackageAnalyzer.github_auth to obtain a GitHub authentication.

Example

You can analyze a package just by its name, whether you have it installed locally or not:

julia> analyze("Pluto"; version=v"0.18.0")
PackageV1 Pluto:
  * repo: https://github.com/fonsp/Pluto.jl.git
  * uuid: c3e4b0f8-55cb-11ea-2926-15256bba5781
  * version: 0.18.0
  * is reachable: true
  * tree hash: db1306745717d127037c5697436b04cfb9d7b3dd
  * Julia code in `src`: 8337 lines
  * Julia code in `test`: 5448 lines (39.5% of `test` + `src`)
  * documention in `docs`: 0 lines (0.0% of `docs` + `src`)
  * documention in README: 118 lines
  * has license(s) in file: MIT
    * filename: LICENSE
    * OSI approved: true
  * has license(s) in Project.toml: MIT
    * OSI approved: true
  * has `docs/make.jl`: false
  * has `test/runtests.jl`: true
  * has continuous integration: true
    * GitHub Actions

analyze(m::Module; kwargs...) -> PackageV1

If you want to analyze a package which is already loaded in the current session, you can simply call analyze, which uses pkgdir to determine its source code:

julia> using DataFrames

julia> analyze(DataFrames)
PackageV1 DataFrames:
  * repo:
  * uuid: a93c6f00-e57d-5684-b7b6-d8193f3e46c0
  * version: 0.0.0
  * is reachable: true
  * tree hash: db2a9cb664fcea7836da4b414c3278d71dd602d2
  * Julia code in `src`: 15628 lines
  * Julia code in `test`: 21089 lines (57.4% of `test` + `src`)
  * documention in `docs`: 6270 lines (28.6% of `docs` + `src`)
  * documention in README: 21 lines
  * has license(s) in file: MIT
    * filename: LICENSE.md
    * OSI approved: true
  * has `docs/make.jl`: true
  * has `test/runtests.jl`: true
  * has continuous integration: true
    * GitHub Actions

analyze(; kwargs...) -> PackageV1

If you have an active Julia project with a package at top-level, then you can simply call analyze() to analyze its code.

analyze_code(dir::AbstractString; repo = "", reachable=true, subdir="", auth::GitHub.Authorization=github_auth(), sleep=0, only_subdir=false, version=nothing) -> PackageV1

Analyze the package whose source code is located at the local path dir. If the package's repository is hosted on GitHub and auth is a non-anonymous GitHub authentication, wait for sleep seconds before collecting the list of its contributors.

only_subdir indicates that while the package's code does live in a subdirectory of the repo, dir points only to that code and we do not have access to the top-level code. We still pass non-empty subdir in this case, to record the fact that the package does indeed live in a subdirectory.

Pass version to store the associated version number. Since this call only has access to files on disk, it does not know the associated version number in any registry.

analyze_manifest([path_to_manifest]; registries=reachable_registries(),
                 auth=github_auth(), sleep=0)

Convienence function to run find_packages_in_manifest then analyze on the results. Positional argument path_to_manifest defaults to joinpath(dirname(Base.active_project()), "Manifest.toml").

analyze_packages(pkg_entries; auth::GitHub.Authorization=github_auth(), sleep=0, root=mktempdir()) -> Vector{PackageV1}

Analyze all packages in the iterable pkg_entries, using threads, storing their code in root if it needs to be downloaded. Returns a Vector{PackageV1}.

Each element of pkg_entries should be a valid input to analyze.

If the GitHub authentication is non-anonymous and the repository is on GitHub, the list of contributors to the repositories is also collected, after waiting for sleep seconds for each entry (useful to avoid getting rate-limited by GitHub). See PackageAnalyzer.github_auth to obtain a GitHub authentication.

find_package(name_or_uuid::Union{AbstractString, UUID}; registries=reachable_registries(), version::Union{VersionNumber,Nothing}=nothing, strict=true, warn=true) -> PkgSource

Returns the PkgSource for the package pkg.

• registries: a collection of RegistryInstance to look in
• version: if nothing, finds the maximum registered version in any registry. Otherwise looks for that version number.
• If strict is true, errors if the package cannot be found. Otherwise, returns nothing.
• If warn is true, warns if the package cannot be found.

See also: find_packages.

find_packages(; registries=reachable_registries())) -> Vector{PkgSource}
find_packages(names::AbstractString...; registries=reachable_registries()) -> Vector{PkgSource}
find_packages(names; registries=reachable_registries()) -> Vector{PkgSource}

Find all packages in the given registry (specified by the registry keyword argument), the General registry by default. Return a vector of PkgSource pointing to to the directories of each package in the registry.

Pass a list of package names as the first argument to return the paths corresponding to those packages, or individual package names as separate arguments.

find_packages_in_manifest([path_to_manifest]; registries=reachable_registries(),
                          strict=true, warn=true)) -> Vector{PkgSource}

Returns Vector{PkgSource} associated to all of the package/version combinations stored in a Manifest.toml.

• path_to_manifest defaults to joinpath(dirname(Base.active_project()), "Manifest.toml")
• registries: a collection of RegistryInstance to look in
• strict and warn have the same meaning as in find_package.
• Standard libraries are always skipped, without warning or errors.

PackageAnalyzer.github_auth(token::String="")

Obtain a GitHub authetication. Use the token argument if it is non-empty, otherwise use the GITHUB_TOKEN and GITHUB_AUTH environment variables, if set and of length 40. If all these methods fail, return an anonymous authentication.

LineCategories(path)

Categorize each line in a file as a CategorizeLines.LineCategory. Every line is assigned a single category.

LineCategory

An enum corresponding to the possible categorization of a line of Julia source code. Currently:

• Blank
• Code
• Comment
• Docstring