skott is a minimalist developer tool that can be used to efficiently generate directed graphs from your JavaScript/TypeScript/Node.js project. It can automatically collect metadata such as file size, third-party or builtin dependencies, detect circular dependencies or help you building tools relying on graph data structures thanks to the exposed primitives. Many display modes exists (such as embedded interactive web application shown just below) but also other from the CLI (.svg, .png, .md, .json).

skott exposes directed graphs primitives so that it can be used to implement tools on top of graph structures e.g. affected/incremental patterns as it exposes a way to know precisely and deeply dependencies for each graph node. More generally speaking, anything that can be implemented using graphs can be implemented using skott.

✅ Works for modern JavaScript/TypeScript projects (TSX/JSX, ECMAScript and CommonJS modules all supported). TypeScript's path aliases are also supported.

✅ Works with any custom dependency resolver (useful for specific monorepos integration)

✅ File tree traversal supports ignore pattern and Git ignored files (via .gitignore files)

✅ Runs incrementally (experimental), meaning that Skott will only analyze files that were modified/added since the last run, offering performance boosts.

✅ Deeply detects circular dependencies in an efficient way, with the ability to provide a max depth for the search

✅ Detect unused npm third-party dependencies. Note that all unused devDependencies are not guaranteed to be detected as depcheck only provides analysis for set of supported libraries (eslint, karma, mocha, etc).

✅ Deeply collect all dependencies of the project graph

✅ Deep parent and child dependencies traversals

✅ Metadata collection for each traversed node (file size, view dependencies towards Node.js builtin modules and npm third-party libraries)

✅ Node.js binary and JSON modules are excluded by default

✅ Generate static files including raw JSON, mermaid-js diagrams (.svg, .png, .md) representing your project's graph directly generated from the CLI.

Note

skott can either build the project graph using an entrypoint file or build it starting from the current root directory and recursively traverse all directories/folders. Currently, supported files are .js, .jsx, .cjs, .mjs, .ts, .tsx. In addition to .gitignore-d files, some directories will be ignored by default, please check the code to see more about that.

The whole purpose of Skott is to build a graph from your project source code and offer many features relying on that generated graph.

Overall, a generated project graph in software engineering acts as a powerful tool that enhances code comprehension, project management, code maintenance and refactoring, and collaboration. It provides a holistic view of the project's structure, dependencies, and relationships, enabling developers to make informed decisions and streamline their development process.

Moreover, Skott aims to provide a comprehensive visual representation of the project's structure, dependencies, and relationships between different components. This visual overview allows developers to better understand the overall architecture and organization of the codebase, making it easier to navigate and identify potential areas of improvement or optimization.

In the essence the main goal of Skott is to help developers understand the codebase's structure and to enable more effective refactoring, reducing code duplication, getting rid of circular dependencies and improving overall code quality.

1. Circular (also known as cyclic) dependencies

Let's start with an example of a simple circular dependency between three graph nodes:

In the context of skott, nodes represent JavaScript files.

  graph LR
    src/fileA.js --> src/fileB.js
    src/fileB.js --> src/fileC.js
    src/fileC.js --> src/fileA.js

What is the problem with cycles?

Circular dependencies can make your program crash or introduce inconsistencies while modules are being loaded. Node.js module systems try to resolve circular dependencies using different approaches which are more or less successful. For example, CommonJS can (due to its dynamic nature of resolving imports) introduce inconsistencies when building the project graph.

If you're using ECMAScript modules, you can consider yourself safe about module resolution inconsistencies mentioned above, mostly thanks to its static nature.

Nevertheless, cyclic dependencies at the file-level are sometimes choices but more often code smells revealing design misconceptions, so be sure to double check that.

2. Dead code

Dead code can be defined as a code literally having no impact on the application, meaning that removing dead code should not alter in any way the behavior of the system. Some module bundlers such as Rollup and Webpack allow to delete some of the dead code leveraging tree shaking.

However, tree shaking is not an easy task and can mostly work with module systems using static-based imports/exports such as ECMAScript modules. To avoid removing code that appears to be used at runtime, module bundlers are being very precise about determining automatically chunks of code that can be safely removed. Module bundlers can also be helped by providing them manually clues about what can be safely removed e.g. /*#__PURE__*/ for Webpack.

If you're not using tools implementing tree shaking, you will be able soon to use skott, which will bring up soon unused imports/exports warnings 🚀

Please refer to the documentation at the skott package level

skott is powered by digraph-js, a 0 dependency Node.js library to make Directed Graph construction and traversal effortless.

While traversing the project, skott automatically loads the appropriate parser required. When meeting ".js, .cjs, .mjs, .jsx" files, a specific JS parser will be used, otherwise for ".ts, .tsx" files a specific TS parser will be used instead.

• JavaScript: JavaScript/JSX parsing is done using meriyah
• TypeScript: TypeScript/TSX parsing is done using typescript-estree