Formatting

Code formatting

• For Julia code, default to 4-space indentation and a soft line-length target of 92 characters. These defaults are secondary to the surrounding style.
• Prioritize consistency with the surrounding code's style and line wrapping. Do not introduce unnecessary line breaks solely to meet a line-length target.
• AI agents must not run automated formatters unless explicitly requested by a human in the current conversation. This includes file-wide or project-wide formatting commands and editor-integrated formatting tools. When editing code, preserve the surrounding formatting and make only minimal local edits. If formatting seems necessary, ask before applying it.

Markdown formatting

When writing Markdown text, use 2 whitespaces for indentation and try to keep the maximum line length under 80 characters.

• Exception: CHANGELOG.md is exempt from line length rules since it is used for GitHub release notes, where hard line breaks disrupt rendering.
• Additionally, prioritize simple text style and limit unnecessary decorations (e.g. **) to only truly necessary locations. This is a style that should generally be aimed for, but pay particular attention when writing Markdown.
• Headers should use sentence case (only the first word capitalized), not title case. For example:
  • Good: ## Conclusion and alternative approaches
  • Bad: ## Conclusion And Alternative Approaches

Commit message formatting

When writing commit messages, follow the format "component: Brief summary" for the title.

In the body, write paragraphs in this order:

1. Explain the concrete problem or user-visible limitation being fixed. If appropriate, include a small code example when it makes the issue clearer.
2. Explain the approach used to fix the problem.
3. Mention important caveats, follow-up work, performance notes, or test coverage when relevant.

Use backticks for code elements (function names, variables, file paths, etc.) to improve readability.

Ensure that the maximum line length never exceeds 72 characters. When referencing external GitHub PRs or issues, use proper GitHub interlinking format (e.g., "owner/repo#123" for PRs/issues). Finally, if you write code yourself, include a co-author trailer at the end of the commit message, e.g.: Co-Authored-By: GPT-5.5 <noreply@openai.com> (adjust the model name as appropriate). However, when simply asked to write a commit message, there's no need to add that trailer.

File names

For file names, use - (hyphen) as the word separator by default. However, if the file name corresponds directly to Julia code (e.g., a module name), use _ (underscore) instead, since Julia identifiers cannot contain hyphens (unless we use var"..."). For example, test files like test_completions.jl define a module module test_completions, so they use underscores.

Coding rules

• When writing functions, use the most restrictive signature type practical so JET can catch unintended errors. Loose signatures are fine while prototyping, but committed code should specify expected argument types unless generic behavior is intentional. When unsure, prefer the more restrictive signature.
• For function calls with keyword arguments, use an explicit ; for clarity. For example, code like this:

  ...
  Position(; line=i-1, character=m.match.offset-1)
  ...

  is preferred over:

  ...
  Position(line=i-1, character=m.match.offset-1)
  ...

• When modifying config structs in JETLSCore/src/types.jl, follow the schema regeneration procedure in DEVELOPMENT.md.
• Avoid unnecessary logs: Don't clutter the language server log with excessive information. If you must use print debugging, generally use @info/@warn behind the JETLS_DEV_MODE flag, like this:

  if JETLS_DEV_MODE
      @info ...
  end

Comments guideline

Default to no comments. Add comments only when they explain non-obvious behavior, constraints, invariants, rationale, or genuine hacks. Do not restate implementation flow.

Docstrings are fine for general utilities when they clarify behavior.

The same applies to tests: concise @testset descriptions and behavior-level comments are fine when they clarify what is being tested. Explain test setup only when it encodes a non-obvious constraint or hack.

Running jetls check for self diagnostics

Please make sure to check self diagnostics after writing or modifying code.

The standard command is:

./scripts/selfcheck.sh

This is run in CI and will cause failures if new warnings are introduced.

To check only some of the projects in this repository, pass their names with -p, which may be repeated. Include the projects that depend on the changed ones as well, e.g. JETLSCore when changing LSP or TOMLSource, and docs and scripts when changing the JETLSCore APIs they use, such as the config structs:

./scripts/selfcheck.sh -p JETLSCore -p LSP

See ./scripts/selfcheck.sh --help for the project names and other options.

Running test

Please make sure to test new code when you wrote.

Run the most specific relevant tests when practical. Prefer component-specific tests over the full test suite. Avoid Pkg.test() unless changes affect multiple components, the user explicitly requests the full test suite, or no narrower validation is appropriate.

For detailed test-running workflows, use the run-test skill.

Writing test

When adding or modifying tests, keep test files independently runnable and follow the project's test file structure. For new language server features, prefer focused subroutine tests unless the core developers explicitly request full language-server interaction coverage.

For detailed test-writing workflows, use the write-test skill.

Environment-related issues

For AI agents: never modify Project.toml, JETLSCore/Project.toml, or JETLSCore/test/Project.toml by yourself.

If test failures look environment-related, first ensure the test was run from the root directory of this project. Never attempt dependency or project-file fixes yourself. If the problem remains, inform the human engineer and ask for instructions.

About modifications to code you've written

If the user manually changes work you previously produced, respect those changes. Do not reintroduce deleted code or revert user edits without explicit permission. If you think a user edit is problematic, explain your concern and ask for clarification.

Git operations

Only perform a Git operation that modifies repository state when the user explicitly requests it. Treat each such request as authorization for one write operation: after completing it, do not perform another write operation until the user explicitly requests one. Read-only Git operations and other non-mutating work may continue in the meantime.

If the user provides feedback on a commit, do not automatically amend it or create a fixup commit. Explain what could change and wait for explicit instruction.