desfero / structlint

Project structure linter for Javascript, Typescript and Flow projects

Getting Started

Install the package:

npm install --save-dev structlint

in case you prefer yarn

yarn add -D structlint

then add the config into a .structlintrc file. For example:

.structlintrc

{
  "structure": [
    {
      "description": "Core application business logic",
      "path": "./modules",
      "disallowedImports": [
        {
          "glob": "./components/**/*",
          "message": "Business logic should never import UI components"
        }
      ]
    },
    {
      "description": "Reducers",
      "path": "./reducers",
      "disallowedImports": ["./components/**/*", "./sagas/**/*"],
      "allowedImports": ["./utils/**/*"]
    }
  ]
}

You can have a single config file at the root of your project or multiple configs, one for every major sub directory.

- src
  - reducers
    - .structlintrc
    - user.reducer.js
    - settings.reducer.js
    - profile.reducer.js
  - components
    - .structlintrc
    - Header
      - Header.js
      - Header.scss
    - Footer
      - Header.js
      - Header.scss
   - sagas
     - .structlintrc
     - auth.saga.js
     - profile.saga.js
   - utils
     - .structlintrc
     - color.js
     - url.js
- tests
  - .structlintrc
  - user-tests
  - settings-tests

Usage

Run from the root of your project:

<path-to-node-modules>/.bin/structlint

OR

npx structlint

Structlint will recursively go through the sub-directories and lint them. If you prefer to lint just one sub-directory, you must change the directory before running the command: cd tests && structlint.

Config options

structure

Type: array

An array of objects containing the following:

Name	Type	Description
description	String	Name or label or description for the directory to be linted
path	String	Path to the directory to be linted relative to .structlintrc
disallowedImports	Array<String> or Array<Object>	An array of globs representing the imports to be disallowed or an array of objects containing the glob and a message
allowedImports	Array<String> or Array<Object>	An array of globs representing the imports to be allowed or an array of objects containing the glob and a message
recursive	Boolean	Defaults to true. If false, will not check sub directories.

Checkout the examples for more.

Command line options

Usage: structlint [options] Options:  --print-config - Group violations by configs (default: false) (note: by default violations from multiple config from the same file are merged)  -V, --version - output the version number  -h, --help display help for command

structlint's Issues

Fix windows support

At the moment windows support is flaky given our snaphosts tests fail ( https://github.com/desfero/structlint/pull/19/checks?check_run_id=798444999) on Windows machines.

v1.0.0 milestone

• Add allowedImports config option
• Add support for dynamic imports and CommonJS imports
• Add a full monorepo support
• Add docs
• #8 (support for index.js imports)

v2.0.0 milestone

• Deduplicate violations related to the same file but from different configs (done as a part of 1.0.0)
• Add a lint rule to disallow importing from outside of package.json folder
• Add support for structure linting styles

Ability to lint names of files

Ability enforce conventions for file names such as:

• camel case
• title case
• kebab case

Fails to parse <const> assertion

What version of this package are you using?
1.0.0-beta.0

What operating system, Node.js, and npm version?
macOS BigSur 11.6, v14.17.5, 7.24.0

What happened?
Fails to parse <const> assertion introduced in TypeScript 3.4.

Note: it's in a .ts file which is allowed.

const test = {
  type: <const>"SOME_STRING",
}

gives

FileParsingFailedError: [structlint] Failed to parse ...
Unterminated JSX contents (6:15)
    at Object.parse (/Users/arjun/Documents/GitHub/structlint/src/parsers/parser-babel.ts:103:11)
    at parse (/Users/arjun/Documents/GitHub/structlint/src/parsers/index.ts:28:17)
    at Array.forEach (<anonymous>)
    at lint (/Users/arjun/Documents/GitHub/structlint/src/tasks/importsTask.ts:67:11)
    at processTicksAndRejections (internal/process/task_queues.js:95:5)
    at async Promise.all (index 1)
    at runTask (/Users/arjun/Documents/GitHub/structlint/src/tasks/importsTask.ts:72:22)
    at async Promise.all (index 0)

What did you expect to happen?
Command runs without issues

Are you willing to submit a pull request to fix this bug?

Generate JSON with dependencies between packages

Background
To provide a dependencies graph we need to firstly provide a way to generate JSON dependencies tree.

We should provide two options for json generation.

1. Full dependencies tree (with custom monorepo packages and all external dependencies)
2. With only packages from the monorepo (if it's a monorepo)

Allow to specify `allowedExports` and `disallowedExports`

Background
Often it's more useful to restrict what can be exposed from the folder/package in the same folder to keep configs more organized. It will also simplify the refactoring of folder structure in complex projects.

Technical notes
With exports rules, we can end up with some performance downsides given we need to parse the whole project structure (up to the root structlint config). Given that let's see if it's the huge problem on for .e.g react codebase.

Doesn't ignore files from .gitignore when not run in root directory

Relates to #2

Add root option to command line and config

Allow specifying root where to start parsing file system from the command line and config

Add support for barrel (index.js) files

Background
Barrel imports are quite common patterns across javascript projects therefore supporting barrel imports is a must from the begging.

Given that we have the following structure:

- libs
- - index.js

if libs/**/* are marked as disallowed structlint should properly report an error for import Foo from "./libs"

Support absolute imports

• read the alias configuration from either webpack/rollup config
• or provide a way to accept custom module resolution