Presubmit.Source.Facts (presubmit v0.2.2)

Copy Markdown View Source

Structural facts about one Elixir source file, extracted from its AST.

Facts are pure functions of the file's text: modules with their uses, attributes, functions, struct fields, and the modules they reference, with aliases resolved to full names. Nothing is compiled or evaluated, so facts can be extracted from any revision regardless of whether its dependencies are available.

Facts for git-backed trees are memoised by blob object id and path in Presubmit.Source.Cache, shared by every process: facts are a pure function of a file's contents and its path, so a range of commits parses each distinct version of a file exactly once. clear_cache/0 empties it.

Summary

Types

t()

Functions

cached?(tree, path)

Whether facts for path in tree are already cached.

clear_cache()

Drops every cached fact set.

extract(tree, path)

Extracts facts for the file at path in tree.

extract!(tree, path)

Extracts facts, returning an empty fact set for missing or unparseable files.

from_source(source, path \\ "nofile.ex", opts \\ [])

Extracts facts from source text directly (for tests and synthetic input).

resolve(parts, env)

Resolves alias parts to a full module name under env.

Types

t()

@type t() :: %Presubmit.Source.Facts{
  modules: [Presubmit.Source.Facts.Module.t()],
  path: String.t()
}

Functions

cached?(tree, path)

@spec cached?(Presubmit.Tree.t(), String.t()) :: boolean()

Whether facts for path in tree are already cached.

clear_cache()

@spec clear_cache() :: :ok

Drops every cached fact set.

extract(tree, path)

@spec extract(Presubmit.Tree.t(), String.t()) :: {:ok, t()} | {:error, term()}

Extracts facts for the file at path in tree.

Returns {:error, reason} when the file is missing or does not parse.

extract!(tree, path)

@spec extract!(Presubmit.Tree.t(), String.t()) :: t()

Extracts facts, returning an empty fact set for missing or unparseable files.

from_source(source, path \\ "nofile.ex", opts \\ [])

@spec from_source(String.t(), String.t(), keyword()) :: {:ok, t()} | {:error, term()}

Extracts facts from source text directly (for tests and synthetic input).

With renames: %{Old => New}, every resolved module reference — in function bodies and in the modules' own names — is mapped through the renames, so facts from before a rename can be compared with facts from after it.

resolve(parts, env)

@spec resolve([atom()], %{optional(atom()) => module()}) :: module()

Resolves alias parts to a full module name under env.

env maps the first segment of an alias to the module it stands for, and :__MODULE__ to the enclosing module.