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.

• Overview
• Disclaimer
• VSCode extension
  • Installation
  • Usage
• Command line
  • Installation
  • Usage
• Behavior
  • Linter
  • Formatter
• Configuration (i.e., project-wide settings)
• Directives (i.e., inline settings)
• Tests
• License

Overview

GTLint's linter flags these things:

• unrecognized keywords
• invalid sub-keywords
• invalid keyword arguments
• missing required sub-keywords
• empty blocks (e.g., *if: 0 < 1 without a body)
• undefined variables
• unused variables
• nonexistent labels
• duplicate labels
• unused labels
• unreachable code
• unclosed strings
• unclosed brackets
• single quotes instead of double quotes around string literals
• spaces instead of tabs for indentation
• incorrect indentation levels

GTLint's formatter does these things:

• trims trailing whitespace (per-line)
• collapses consecutive empty lines
• adds spaces around operators (e.g., +, =, >, etc.)
• adds spaces around arrows (->) in associations
• adds spaces after commas in collections and associations
• normalizes spacing immediately inside braces, brackets, and parens
• normalizes >> to be followed by a single space
• collapses runs of whitespace in expressions

Virtually all of these behaviors can be modified by using a configuration file and/or inline directives.

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/gtlint/releases/latest/download/gtlint.vsix

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

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

(3) Select the gtlint.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.

Auto-complete

The extension provides context-aware auto-complete:

• Keywords — Type * at the start of a line to see available keywords. When indented under a parent keyword (e.g., *question), the sub-keywords for that parent are shown first (e.g., *type, *save, *shuffle), followed by all top-level keywords.
• Methods — Type . after a variable name to see all built-in GuidedTrack methods (e.g., .size, .uppercase, .add()). Methods are shown with their applicable type(s) and snippets with tab stops for parameters.

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/gtlint

Or globally:

npm install -g @jrc03c/gtlint

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 {
  // files to ignore (glob patterns, relative to project root)
  ignore: [
    "**/node_modules/**", // ignored by default
    "**/dist/**",         // ignored by default
    "path/to/some-file.gt",
    "**/scratch/**",
  ],

  // formatter settings
  format: {
    insertFinalNewline: true,
    spaceAfterComma: true,
    spaceAroundArrow: true,
    spaceAroundOperators: true,
    spaceInsideBraces: 0,
    spaceInsideBrackets: 0,
    spaceInsideParens: 0,
    trimTrailingWhitespace: true,
  },

  // linter settings
  lint: {
    correctIndentation: "error",
    gotoNeedsResetInEvents: "warn",
    indentStyle: "error",
    noDuplicateLabels: "error",
    noEmptyBlocks: "error",
    noInlineArgument: "error",
    noInvalidGoto: "error",
    noSingleQuotes: "error",
    noUnclosedBracket: "error",
    noUnclosedString: "error",
    noUndefinedVars: "error",
    noUnreachableCode: "warn",
    noUnusedLabels: "warn",
    noUnusedVars: "warn",
    purchaseSubkeywordConstraints: "error",
    requiredSubkeywords: "error",
    validKeyword: "error",
    validSubKeyword: "error",
    validSubkeywordValue: "error",
  },
}

When ignore is not specified, **/node_modules/** and **/dist/** are ignored by default. Specifying ignore replaces these defaults, so include them explicitly if you still want them ignored. Ignore patterns apply to both lint and format commands.

Lint 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