Skip to content

AGENTS.md

Latest commit

 

History

History
52 lines (36 loc) · 3.09 KB

AGENTS.md

File metadata and controls

52 lines (36 loc) · 3.09 KB
Raw

Running Julia code

  • If you have a Julia MCP tool, always run code with that. Don't invoke julia from bash as that is very slow.

  • To investigate formatting with JuliaFormatter, use the julia_format tool. The first time you run it, you need to specify formatter_path=... with the local checkout of JulaiFormatter.

  • To run generic Julia code, use the julia_eval tool. Avoid passing a specific env_path as that will clutter the user's environment. In the absence of an env_path, the tool will create a temporary environment for you. In this environment you can Pkg.develop(; path=...) the local checkout of JuliaFormatter and add any other packages you need.

  • Code changes in the local checkout should be immediately visible without having to reload the session (thanks to Revise.jl). If you encounter any issues with this, try restarting the MCP session.

Tracing JuliaFormatter's output

  • Always use the JuliaFormatter.Internal.format_to_stage function to inspect the output of each stage of the formatting process. If s is a string containing the code to be formatted, then format_to_stage(stage, s[, style]; options...) will give the output of the specified stage, where stage is one of:

    • :cst gives the CST from JuliaSyntax;
    • :fst gives the initial FST that JuliaFormatter constructs from the CST using pretty();
    • :nest gives the FST after flattening, alignment, and nesting;
    • :out gives the final formatted string;
    • :print prints the final formatted string.

    If format_text generates invalid Julia code, it will throw, which is unhelpful for debugging. In such cases you should use format_to_stage(:out, ...) as that will show you the actual invalid code.

Running tests

  • Do NOT run complete segments of the test suite unless explicitly instructed to. Only run specific, targeted tests that are relevant to the changes you are making, using JuliaFormatter.Internal.test_format(input_string, expected_output[, style]; options...) This function checks that formatting input_string produces expected_output, and also for idempotence. It also prints helpful information if it fails so that you can easily debug the issue.

  • To test whether a string is valid Julia code, you can use Meta.parse(s) or format_to_stage(:cst, s). Both throw if the code is invalid.

Comment style

JuliaFormatter is a complex codebase with many moving parts. Do not assume that other developers will understand terse comments as they do not have the same context as you. For example, when writing function-level comments, it's useful to illustrate your point with a concrete example of code that is being formatted.

Avoid hacks

  • Do not write off any valid syntactic construct as "pathological" or not worth supporting. ALL valid Julia code should be supported by the formatter, even if it's not common in practice.

  • Do not use fragile heuristics or hacks to achieve the desired formatting. Where possible, you should always try to implement formatting logic at the CST stage (i.e. pretty()), because the CST has more precise structural information about the code being run.