graded - v0.1.0

graded

Effect checker for Gleam via sidecar .graded annotation files.

graded verifies that your Gleam functions respect their declared effect budgets. Annotations live in .graded sidecar files alongside your source — your Gleam code stays clean.

Usage

gleam run -m graded check [directory]   # enforce check annotations (default)
gleam run -m graded infer [directory]   # infer and write effect annotations
gleam run -m graded format [directory]  # normalize .graded file formatting

Programmatic API

Use run to check a directory and get back a list of CheckResult values, each containing any violations found per file. Use run_infer to infer effects and write .graded files.

Types

GradedError

</>

Errors that can occur during checking, inference, or formatting.

pub type GradedError {
  DirectoryReadError(path: String, cause: simplifile.FileError)
  FileReadError(path: String, cause: simplifile.FileError)
  FileWriteError(path: String, cause: simplifile.FileError)
  DirectoryCreateError(path: String, cause: simplifile.FileError)
  GleamParseError(path: String, cause: glance.Error)
  GradedParseError(path: String, cause: @internal ParseError)
  FormatCheckFailed(paths: List(String))
}

Constructors 

  • DirectoryReadError(path: String, cause: simplifile.FileError)

    Could not read the source directory.

  • FileReadError(path: String, cause: simplifile.FileError)

    Could not read a source or annotation file.

  • FileWriteError(path: String, cause: simplifile.FileError)

    Could not write an annotation file.

  • DirectoryCreateError(path: String, cause: simplifile.FileError)

    Could not create the output directory for annotation files.

  • GleamParseError(path: String, cause: glance.Error)

    A .gleam source file could not be parsed.

  • GradedParseError(path: String, cause: @internal ParseError)

    A .graded annotation file could not be parsed.

  • FormatCheckFailed(paths: List(String))

    One or more .graded files are not formatted (returned by run_format_check).

Values

gleam_to_graded_path

</> 
pub fn gleam_to_graded_path(
  gleam_path: String,
  source_directory: String,
) -> String

Convert a .gleam source path to its .graded path in priv/graded/.

main

</> 
pub fn main() -> Nil

run

</> 
pub fn run(
  directory: String,
) -> Result(List(@internal CheckResult), GradedError)

Run the checker on all .gleam files in a directory. Only enforces check annotations.

run_format

</> 
pub fn run_format(directory: String) -> Result(Nil, GradedError)

Format all .graded files in priv/graded/ for a given source directory.

run_format_check

</> 
pub fn run_format_check(
  directory: String,
) -> Result(Nil, GradedError)

Check that all .graded files are already formatted. Returns error with the list of unformatted file paths. Exit code 1 in CI.

run_infer

</> 
pub fn run_infer(directory: String) -> Result(Nil, GradedError)

Infer effects for all .gleam files and write/merge .graded files.

✨ Search Document