GTLint ✨

GTLint is a linter, formatter, and syntax highlighter for the GuidedTrack language, inspired by ESLint and Prettier. It can be used at the command line or installed as a VSCode extension.

• Disclaimer
• VSCode extension
  • Installation
  • Usage
• Command Line
  • Installation
  • Usage
• Configuration (i.e., project-wide settings)
• Directives (i.e., inline settings)
• Tests
• License

Disclaimer

This tool was written almost exclusively by Claude Code. Josh Castle directed Claude Code and made a few small changes to CLAUDE.md, README.md, and the GuidedTrack files in the samples directory; but virtually everything else was written by Claude Code.

VSCode extension

Installation

(1) Download the .vsix file from here:

https://github.com/jrc03c/gt-lint/releases/latest/download/gt-lint.vsix

(2) In VSCode, open the command palette and search for "vsix":

Select "Extensions: Install from VSIX...".

(3) Select the gt-lint.vsix file that you downloaded in the first step.

Usage

The linter works while you write code in .gt files and will show errors as soon as it detects them. The formatter will format code in .gt files on save.

See the Configuration section below for more info about how to control the extension's behavior.

Command Line

Installation

NOTE: Requires Node.

In a specific project:

npm install --save-dev @jrc03c/gt-lint

Or globally:

npm install -g @jrc03c/gt-lint

Usage

NOTE: When installed in a specific project, GTLint must be invoked with npx gtlint. When installed globally, it can be invoked with just gtlint. The examples below assume that it has been installed in a specific project.

Syntax:

# lint:
npx gtlint lint [options] [files]

# format:
npx gtlint format [options] [files]

Show help:

npx gtlint

Lint:

# show errors and warnings in a particular file
npx gtlint lint path/to/some-file.gt

# show all errors and warnings in all *.gt files in a directory (recursive)
npx gtlint lint path/to/some-dir

Format:

# format a specific file
npx gtlint format path/to/some-file.gt

# format all *.gt files in a directory (recursive)
npx gtlint format path/to/some-dir

See the Configuration section below for more info about how to control the command line tool's behavior.

Configuration

The linter's and formatter's default behaviors can be controlled by settings in a gtlint.config.js file at the root of a repository. Here's a sample configuration file containing all of the default values:

export default {
  // formatter settings
  format: {
    insertFinalNewline: true,
    spaceAfterComma: true,
    spaceAroundArrow: true,
    spaceAroundOperators: true,
    trimTrailingWhitespace: true,
  },

  // linter settings
  rules: {
    correctIndentation: "error",
    indentStyle: "error",
    noDuplicateLabels: "error",
    noInvalidGoto: "error",
    noSingleQuotes: "warn",
    noUnclosedBracket: "error",
    noUnclosedString: "error",
    noUndefinedVars: "error",
    noUnusedVars: "warn",
    validKeyword: "error",
    validSubKeyword: "error",
  },
}

Linter rules can have these values:

• "off" or 0 - Disable the rule
• "warn" or 1 - Show as warning (doesn't fail linting)
• "error" or 2 - Show as error (fails linting)

Directives

The linter's and formatter's behaviors can also be overridden by inline directives written directly into .gt files. Directives are always commented out. For example:

-- @to-child: email_address
>> email_address = "[email protected]"
*program: Add to Mailing List

Here are the available directives and what they do:

Combined (lint + format):

• @gt-disable Disable lint + format until @gt-enable or EOF

• @gt-enable Re-enable lint + format

• @gt-disable-next-line Disable lint + format for next line only

• @gt-disable-next-line rule1, rule2 Disable specific lint rules + format for next line

Lint-only:

• @gtlint-disable Disable all lint rules until @gtlint-enable or EOF

• @gtlint-disable rule1, rule2 Disable specific lint rules

• @gtlint-enable Re-enable all lint rules

• @gtlint-enable rule1 Re-enable specific lint rule

• @gtlint-disable-next-line Disable all lint rules for next line

• @gtlint-disable-next-line rule1, rule2 Disable specific rules for next line

• @from-child: var1, var2, ... Do not mark listed variables as undefined (because they are defined in a child program); warns if a listed variable is never used

• @from-parent: var1, var2, ... Do not mark listed variables as undefined (because they are defined in a parent program); warns if a listed variable is never used or if its value is overwritten before being read

• @from-url: var1, var2, ... Do not mark listed variables as undefined (because they are defined in URL query string parameters); warns if a listed variable is never used or if its value is overwritten before being read

• @to-child: var1, var2, ... Do not mark listed variables as unused (because they will be used in a child program)

• @to-parent: var1, var2, ... Do not mark listed variables as unused (because they will be used in a parent program)

• @to-csv: var1, var2, ... Do not mark listed variables as unused (because they will be saved in the root program's CSV)

NOTE: Inline directive rule names always use kebab-case (e.g., no-unused-vars), even though config files use camelCase.

Format-only:

• @gtformat-disable Disable formatting until @gtformat-enable or EOF

• @gtformat-enable Re-enable formatting

NOTE: @gtformat-* directives don't support rule lists since formatting isn't rule-based.

Tests

pnpm test

The test suite includes integration tests that exercise real GuidedTrack programs from a git submodule (submodules/gt-lib). This submodule points to a private repository and is optional. If it's not initialized, those tests are skipped automatically. All other tests will run normally.

Feedback

If you run into bugs or have feature requests, please open an issue.

License

MIT