andrewjensen / hekla

A pluggable static code analysis toolset for understanding large Javascript projects

DEPRECATED

This project is deprecated. I have not kept up with maintenance of Hekla so I believe it is best to archive it.

Using static code analysis for reporting is still immensely useful. Here are some related projects that might be helpful in doing this analysis:

• jscodeshift, a codemod toolkit that can also be used for gathering data
• tree-sitter, a cross-language parser generator tool
• AST Explorer, for quickly seeing ASTs and prototyping codemods+linter rules
• react-scanner, static code analysis specifically for React components

hekla

A pluggable static code analysis toolset for understanding large Javascript projects

Getting Started

The easiest way to start using Hekla is through the Webpack plugin and the CLI tool. You can also install and use the core analysis package directly.

"Hekla?"

Hekla is named after a volcano in Iceland!

hekla's Issues

Update documentation

TODO:

• Update top-level readme file
• Update readme file for hekla-core
• Update readme file for hekla-cli
• Create readme file for hekla-webpack-plugin

Update tooling

TODO:

• Update lerna
• Update other package dependencies
• Check in package-lock.json files? (What is best practice with lerna?)

Add support to bring your own parser

Developers should be able to swap out the default babel parser for another one, like typescript.

Create plugin system

Overview

• Everything is a plugin
• Plugins can register other plugins (Angular plugin is a group of plugins)
• Context system keeps track of callbacks
• Use tapable
• Maybe have a distinction between an in-progress module and a fully analyzed module
  • We need to keep a lot of junk in memory that we can later throw away

Hooks

• initialize plugin
• filtering modules out from the list, before parsing each one
• ready to extract components from a module
• after components have been extracted from a module
• while visiting each component during dependency graph linking
• When ready to report

apply(analyzer) {
  analyzer.hooks.newModule.tap('MyPlugin', () => {});
}

TODO

• Setup hooks in the Analyzer class
• Have each Parser hook into an event

Add integration tests for hekla-cli

We need some basic test coverage on the hekla-cli package so we know changes aren't causing regressions.

Things to test:

• Calling the CLI creates an analysis.json file
• Calling the CLI runs plugins that influence the analysis file
• Calling the CLI runs reporter plugins that create other files

Create webpack plugin

TODO:

• Create hekla-webpack-plugin package
• Trigger on all files
• Read from the filesystem provided by webpack
• Create output file

Add shortName property to modules

Having the full moduleName of a Module is useful, but it can create a lot of visual noise when creating visualizations of the analysis.

Add a shortName property to each Module, which is just the filename, unless it is named something like index.js or app.js, in which case it should add the parent directory to the shortName.

Add documentation comments

Add documentation comments on public classes and functions, to make the codebase more accessible to contributors and plugin developers.

Add first-class support for UI frameworks

UI frameworks contain entities that are important to identify and track for dependency analysis. Hekla should recognize these entities and provide hooks for plugins to act on them.

Examples:

• Identify AngularJS entities (components, directives, factories, etc.)
• Identify React components
• Identify Backbone views and models

Convert to Typescript

The project will be much easier to use and contribute to if it has type safety.

Opt into terminal output while analyzing

We don't always want to see the workers running, if analysis is running on CI, or in tests. We should be able to opt into the output.

Can we extract the logic into a built-in plugin? Then we could use it in the CLI as well.

Add plugin for Github CODEOWNERS file

The current code owners plugin supports a data structure that doesn't match a convention like CODEOWNERS. We should make a new plugin specifically for the format, and reuse some of the logic to generate a similar tree.

Add integration tests for webpack plugin

We need integration tests for the webpack plugin package, to make sure there are not any breaking changes in core that would regress the plugin's behavior.

Make sure Travis runs these tests once they are ready.

Clean up core

• Move Analyzer and core logic from webpack plugin
• Delete older unused core
• Rename files/folders so everything is easier to find

Add guidelines for contributing

TODO:

• CONTRIBUTING.md file
• Github issue/PR templates
• Code of conduct file

Add ability to run on a single file or pattern

Add ability to introduce new language grammars

A few people have mentioned being interested in using Hekla for non-web languages (specifically Java, Kotlin, and C#), and Hekla needs a more modular way of adding grammars anyway. We still need support for CSS-family languages and this may be a good opportunity to add plugin support for totally custom grammars.

Add ability to run from create-react-app

We should be able to run Hekla from an app maintained with create-react-app, where the build dependencies are hidden and inaccessible.

A possible way to handle this would be to run a build with stats (npm run build --stats) and then have Hekla run on the generated stats file, since it contains everything we need for analysis. It would not be as fast as integrating with Webpack at compile time, but this doesn't seem to be an option.

Add support to identify and act on HTML templates in JS files

It's common in UI code, especially older frameworks like Backbone and AngularJS, to include snippets of HTML that are compiled into templates. These template fragments have important logic that should be available for analysis, just like HTML files are.

Add ability to set top-level metadata on the analysis

We should be able to set metadata on the analysis, that is not specific to any specific module.

The finished analysis might look like this:

{
  "meta": {
    "title": "My Application", // Defined in `hekla.config.js`
    "unusedImports": [ // Created by an `UnusedImportsPlugin`
      "my-unused-module",
      "my-other-unused-module"
    ]
  },
  "modules": [
    // ...
  ]
}