mrseanryan / tslint-folders Goto Github PK

:file_folder: Use tslint to check for invalid imports between packages and folders in your TypeScript project. Automatic validation and documentation of package architecture.

License: MIT License

Shell 0.22% TypeScript 99.78%

tslint static-analysis linter linting code-analysis folders checker architecture structure analysis

tslint-folders's Introduction

📁 tslint-folders

Use tslint to check for invalid imports between packages and folders in your TypeScript project.

Automatic validation and documentation of package architecture (via tslint-folders-diagrams).

status - stable

tslint-folders is stable and in use every day in CI builds and on dev boxes (Linux, Mac, Windows) for at least one major product.

why?

Save time spent manually code reviewing for 'silly' mistakes such as:

Architecture violations:
- importing from a 'higher level' package or folder
- importing from folders in both directions
Importing from an 'invalid' folder like 'dist' or 'modules' (ugly, and in some cases this can cause issues like webpack bundling the same code twice)
Pushing code with disabled tests or with breakpoint code
Inconsistent naming of files (the default tslint rule file-name-casing only allows for 1 style)

features

Uses a simple JSON file to model the desired relations between folders and sub-folders
Provides a custom tslint rule that walks your TypeScript project, checking for imports that violate the model
Other custom rules:
- configurably detect disabled tests
- detect debug/breakpoint code
- detect invalid imports from folders like 'node_modules' or 'dist'
- detect filenames that do not match expected style (allows for more than 1 filename style)
Provides a tool to generate architecture diagrams from the same model, via tslint-folders-diagrams

versioning

We use SemVer for versioning. For the versions available, see Releases.

usage

1 Install via yarn into your website

yarn add tslint-folders

2 Configure tslint to pick up the custom rules

Edit your tslint.json to have an entry "rulesDirectory" that points to tslint-folders.

Normally this would be like:

  "rulesDirectory": "./node_modules/tslint-folders/dist/lib/"

See tslint.tslint-folders.json for an example.

3 Configure the rules

The tslint rules are enabled and configured in tslint.json.

See the section under tsf-folders-imports-between-packages in tslint.tslint-folders.json or the unit tests for examples.

Optionally, you can split out the tslint-folders configuration into a separate file, like tslint.tslint-folders.json. To reference the file, add this code to tslint.json:

  "extends": "./tslint.tslint-folders.json"

Assuming tslint is already in place, then you should now see any unexpected imports (or disabled tests) be flagged by tslint. This should work as usual for tslint: on the command line, or in an editor such as Visual Code (may require refreshing the editor).

4 Generate a summary of the package configuration

See tslint-folders-diagrams

using graphviz to generate image diagrams of the architecture

A diagram can be automatically generated from the same config used to validated the code:

see tslint-folders-diagrams for details.

Summary of the Custom Rules

here is a summary of the current custom rules.

Rule ID	Description
tsf-folders-disabled-test	Detect a disabled unit test, test suite or integration test.
tsf-folders-file-names	Validates casing of filenames. Similar to standard rule `file-name-casing` except it supports multiple allowed casings, and disallows file names with invalid characters (such as spaces or commas).
tsf-folders-import-from-disallowed-folders	Detect an import from a non-standard folder like node_modules
tsf-folders-imports-between-packages	Detect an import from a 'higher level' package: for example, import from an application 'shell' package when inside an 'area' package. This is the main custom rule. Also can detect when a package has imports using this packages name (instead of a relative path).
tsf-folders-test-with-breakpoint	Detect when an integration test has a break point like `browser.debug()`

sites

site	URL
source code (github)	https://github.com/mrseanryan/tslint-folders
github page	https://mrseanryan.github.io/tslint-folders/
npm	https://www.npmjs.com/package/tslint-folders

approach taken

All of the rules use the same prefix tsf-folders-.

To make it clear to developers that a custom rule is involved, all messages from the rules also include the rule id.

Some of these rules could be replaced by standard tslint configuration. However, having custom rules gives clearer messages to help the developer to know what to fix (or what rule to disable for that piece of code).

Some of the rules are not strictly about 'folders', but are included here as they also seem useful.

For more details and examples please see the unit tests

building and testing this source code

To work on the source code for tslint-folders, there are a few scripts:

command	description
yarn build	Builds the rules to the 'dist' folder, from where they can be executed.
yarn lint	Lints the source code of the rules.
yarn start	Builds, tests and lints the code.
yarn test	Tests the rules against spec files (*.lint)
yarn test-one	Test a single rule against spec files (*.lint)

unit tests

The unit tests for the rule tsf-folders-imports-between-packages are here.

The unit tests use test data to check the package boundaries of a fairly typical website.

The matching configuration can be seen in tslint.tslint-folders.json

test data - packages

The test data is based around a website that uses multiple packages:

Package name	Description
shell	The application shell - this is the top level package, and it can import from any other package.
todo-area	A 'todo app' area of the website, that is hosted within the shell. It should not import from the shell or from other 'area' packages.
todo-contact	A 'contact info' area of the website, that is hosted within the shell. It should not import from the shell or from other 'area' packages.
grid-package	A UI grid that is used by area packages. It should not import any other recognised packages.
utils	A 'utils' package used by the shell and area packages. It should not import any other recognised packages.

Example validation: 'shell' should be able to import from 'todo-area', but not the other way around (shell is at a higher level of abstraction, and also want to avoid 2-way dependencies).

test data - packages with sub-folders

tslint-folders can also validate imports between sub-folders of a package.

The test data 'todo-area' package is configured with fairly typical sub-folders such as 'components' and 'models'. tslint.tslint-folders.json has been configured to check the imports between these folders.

Sub-folder name	Description
components	Top-level folder of UI components. Can import from any of the other recognised folders.
viewmodels	Folder of view models, used by the UI components. Can only import from models or utils.
models	Folder of models, used by the view models. Can only import from utils.
utils	A 'utils' folder. It should not import any other recognised folders.

Example validation: 'components' should be able to import from 'models', but not the other way around (components is at a higher level of abstraction, and also want to avoid 2-way dependencies).

developing code in this repository

see the contributing readme.

origin

This project is based on the excellent seeder project typescript-library-starter.

The project was started to avoid having to repeatedly fix similar coding issues in large TypeScript code bases.

ORIGINAL readme (from the seeder project)

see here

that's it

That's pretty much it. Let me know if this is useful or how it can be improved!

authors

Original work by Sean Ryan - mr.sean.ryan(at gmail.com)

licence = MIT

This project is licensed under the MIT License - see the LICENSE file for details

tslint-folders's People

Contributors

Stargazers

Watchers

Forkers

wisebird

tslint-folders's Issues

Add architecture as label and keyword (also tslint diag)

Add architecture as gitlab label and keyword (also tslint diag)

Hide the dev dependencies button

Hide the dev dependencies button

As is not relevant for users.

rollout to 4 other projects

Multicomponent path from tsconfig.json - does not work on Windows

some code in 618a7cf assumes Unix style path separator.

relates to #26

At least - I think that is the problem!

Add support for paths configured in tsconfig.json

Paths can be configured in tsconfig.json.

This can help to disambiguate a folder setup like this:

my-editor/src/
my-editor/api/

tsconfig.json:

    "baseUrl": ".",
    "paths": {
        "my-editor": ["my-editor/src"],
        "my-editor-api": ["my-editor/api"],

Otherwise, tslint-folders will treat imports from both my-editor and my-editor-api as my-editor

dev note:

try using tsconfig-paths

as used in ts-unused-exports

chore: upgrade dev dependencies - rollup

see yarn output:

[2/5] Resolving packages...
warning @commitlint/cli > babel-polyfill > [email protected]: core-js@<3 is no longer maintained and not recommended for usage due to the number of issu
es. Please, upgrade your dependencies to the actual version of core-js@3.
warning @commitlint/cli > babel-polyfill > babel-runtime > [email protected]: core-js@<3 is no longer maintained and not recommended for usage due to th
e number of issues. Please, upgrade your dependencies to the actual version of core-js@3.
warning jest > jest-cli > jest-config > jest-environment-jsdom > jsdom > [email protected]: use String.prototype.padStart()
warning [email protected]: This module has been deprecated and is no longer maintained. Please use @rollup/plugin-json.

Consider adding back support for node 8

if drop dev-dep commitizen ?

Up contrib doc to mention the semantic release commit message format

ref = https://github.com/semantic-release/semantic-release

Copy out rules to new Eslint projects

lint-folders-config
related =
mrseanryan/tslint-folders-diagrams#42
file name rule tsf-folders-file-names = https://github.com/mrseanryan/tslint-folders/blob/master/src/tsfFoldersFileNamesRule.ts -> new eslint version = eslint-plugin-ts-lint-file-names
post on SO = https://stackoverflow.com/questions/66367573/enforce-file-naming-convention-with-typescript-eslint
create eslint-plugin-ts-lint-folders
breakpoints rule tsf-folders-test-with-breakpoint -> deprecated -> instead use https://github.com/mrseanryan/eslint-plugin-ts-ban-snippets - update the README table
disabled test rule tsf-folders-disabled-test -> deprecated -> instead use https://github.com/mrseanryan/eslint-plugin-ts-ban-snippets - update the README table
mark this project as 'stable' but recommend use the eslint equivalents eslint-plugin-ts-lint-folders or eslint-plugin-ts-lint-file-names or eslint-plugin-ts-ban-snippets as appropriate

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on Greenkeeper branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please click the 'fix repo' button on account.greenkeeper.io.

fix yarn warnings

warning commitizen > cz-conventional-changelog > @commitlint/load > babel-runtime > [email protected]: core-js@<3 is no longer maintained and not recommended for usage due to the number of issues. Please, upgrade your dependencies to the actual version of core-js@3.
warning jest > jest-cli > jest-config > jest-environment-jsdom > jsdom > [email protected]: use String.prototype.padStart()
warning [email protected]: We recommend to use Travis Build Stages instead
warning travis-deploy-once > @babel/polyfill > [email protected]: core-js@<3 is no longer maintained and not recommended for usage due to the number of issues. Please, upgrade your dependencies to the actual version of core-js@3.
warning @commitlint/cli > babel-polyfill > [email protected]: core-js@<3 is no longer maintained and not recommended for usage due to the number of issues. Please, upgrade your dependencies to the actual version of core-js@3.

Add link to releases from the readme

Add link to releases from the readme:

https://github.com/mrseanryan/tslint-folders/releases

At this point:

see the tags on this repository.

Multicomponent path from tsconfig.json

/ in tsconfig mapping is not supported.

    // tsconfig.json
    "paths": {
      "test/dal/*": [
        "./src/dal/*"
      ]
    },

    // tslint.json
    "packages": [
      {
        "importPath": "interfaces",
        "allowedToImport": [],
        "subFolders": []
      },
      {
        "importPath": "test/dal",
        "allowedToImport": ["interfaces"],
        "subFolders": []
      }
    ]

    // ts file
    import {Dto} from 'test/dal/dto'; // no error

Sample repository

First part of the mapping is used to distinguish imports from the application itself. Also @ is often used, e.g.

    "paths": {
      "@app/dal/*": [
        "./src/dal/*"
      ]
    },

[build] Fix handlebars warnings on yarn build

yarn build

Handlebars: Access has been denied to resolve the property "hasComment" because it is not an "own property" of its parent.
You can add a runtime option to disable the check or this warning:
See https://handlebarsjs.com/api-reference/runtime-options.html#options-to-control-prototype-access for details
Handlebars: Access has been denied to resolve the property "hasGetterOrSetter" because it is not an "own property" of its parent.
You can add a runtime option to disable the check or this warning:
See https://handlebarsjs.com/api-reference/runtime-options.html#options-to-control-prototype-access for detail

...
...

Try add bundling via fuse-box

fuse-box configured for server target.

ref: https://fuse-box.org/docs/getting-started/setup#start-with-server

[build] Fix yarn warning about passing options with `--` on yarn test:prod

Fix - by not passing options via --

yarn test:prod

$ tslint  --project tsconfig.json -t codeFrame 'src/**/*.ts' 'test/**/*.ts'
warning From Yarn 1.0 onwards, scripts don't require "--" for options to be forwarded. In a future version, any explicit "--" will be forwarded as-is to the scripts.

Test/Fix commitizen and commitlint

Possibly were disabled a while back...