antler

Antler

Directory structure linter

About

Antler allows you to configure linting rules to enforce the structure of your project directories and files.

Installation

Install with NPM:

npm i antler -S

Note: -S is shorthand for --save to automatically add this to your package.json

If you are using a version of NPM that doesn't support package lock files I'd recommend using -SE or --save-exact, which will pin the version in your package.json.

Usage

Currently Antler only supports supplying a root directory to lint from, but I intend to allow multiple root directories in the future.

antler <directory>

If no directory is supplied Antler won't run. If you'd like to lint the current directory you can supply . or ./, as you like.

Note: there are no rules configured by default. You will have to configure your own .antlerrc.json config file as explained below.

Configuration

All Antler configuration is stored in an .antlerrc.json file. Antler will look in the target directory, and all of its parent directories until it finds a file named .antlerrc.json.

The basic structure of a config file is as follows:

{
  "rules": {
    "RuleName": "warning",
    "AnotherRule": {
      "level": "error",
      "options": {
        "allow": "^my-file$",
        "disallow": ["nope", "bad"]
      }
    }
  }
}

Each rule can be provided with either a string representing the error level (off, warning, or error), or an object with a level key.

Some rules allow (or require) the user to provide additional options as an object in the options key.

Options are (at the time of writing) always strings, or arrays of strings.

See the example .antlerrc.json file in the root of this project for a more complex example.

Rules

NoLonelyIndex

Ensures that no directories contain only a single index file e.g. index.js, or index.html.

{
  "NoLonelyIndex": "error"
}

Acceptable

foo/
  cli.js
  index.js

foo/
  index/
    file.js

Unacceptable

foo/
  index.js

NoJuniors

Ensures that no files, or directories share a name with their parent directory.

{
  "NoJuniors": "error"
}

Acceptable

foo/
  bar.js

Unacceptable

foo/
  foo.js

foo/
  foo/

NoEmptyDirectory

Ensures that there are no empty directories.

{
  "NoEmptyDirectory": "error"
}

Acceptable

foo/
  bar/
    baz.js

foo/
  bar.js

Unacceptable

foo/
  bar/

foo/

FileName

Allows the user to define allowed and disallowed patterns to match all file names against.

The patterns provided are converted to case sensitive regular expressions, and should be prefixed with ^ (start of string) and suffixed with $ (end of string), if you want to ensure that the whole string matches your pattern, and not just a section of it.

The options; allow and disallow, can be either a string, or array of strings.

{
  "FileName": {
    "level": "error",
    "options": {
      "allow": "",
      "disallow": ""
    }
  }
}

DirectoryName

Allows the user to define allowed and disallowed patterns to match all directory names against.

The patterns provided are converted to case sensitive regular expressions, and should be prefixed with ^ (start of string) and suffixed with $ (end of string), if you want to ensure that the whole string matches your pattern, and not just a section of it.

The options; allow and disallow, can be either a string, or array of strings.

{
  "DirectoryName": {
    "level": "error",
    "options": {
      "allow": "",
      "disallow": ""
    }
  }
}

Extension

Allows the user to define allowed and disallowed patterns to match all file extensions against. The extensions are extracted using Node's path.extname, and so will include only the last period and following characters e.g.

All of the following files will be tested against .ts:

index.ts
index.d.ts
index.min.ts

If you want to enforce checking of the .min.ts section, you should use the FileName rule.

The patterns provided are converted to case sensitive regular expressions, and should be prefixed with ^ (start of string) and suffixed with $ (end of string), if you want to ensure that the whole string matches your pattern, and not just a section of it.

The options; allow and disallow, can be either a string, or array of strings.

{
  "Extension": {
    "level": "error",
    "options": {
      "allow": "",
      "disallow": ""
    }
  }
}

Path

Allows the user to define allowed and disallowed patterns to match all paths against. The paths will include the root directory that you specified in the command e.g.

If you run:

antler src/

Against the structure:

src/
  foo/
    bar.js

The paths that are checked will be:

src/
src/foo/
src/foo/bar.js

The patterns provided are converted to case sensitive regular expressions, and should be prefixed with ^ (start of string) and suffixed with $ (end of string), if you want to ensure that the whole string matches your pattern, and not just a section of it.

The options; allow and disallow, can be either a string, or array of strings.

{
  "Path": {
    "level": "error",
    "options": {
      "allow": "",
      "disallow": ""
    }
  }
}