marcoroth / stimulus-parser

Statically analyze Stimulus controllers in your project.

stimulus-parser

Installation

To add stimulus-parser to your project, run the following command in your terminal:

yarn add stimulus-parser

Usage

import { Project } from "stimulus-parser"

const project = new Project("/Users/user/path/to/project")

const controllers = project.controllerDefinitions
const controller = controllers[0]

console.log(controller.actionNames)
// => ["connect", "click", "disconnect"]

console.log(controller.targetNames)
// => ["name", "output"]

console.log(controller.classNames)
// => ["loading"]

console.log(controller.values)
// => [{ url: { type: "String", default: "" } }]

Playground

You can inspect parse results on the hosted playground at https://stimulus-parser.hotwire.io.

Development

To run the tests:

yarn install
yarn build
yarn test

stimulus-parser's Issues

Add support for parsing TypeScript syntax

Maybe we need to move on from acorn for this, but to enable support for TypeScript controller files in Stimulus LSP we need to be able to parse TypeScript syntax.

marcoroth/stimulus-lsp#18

Support inheritance for `methods`, `targets`, `values`, etc.

It's common for Stimulus controllers to inherit some behaviour from an (abstract) base controller.

Currently the inherited methods, targets, values, etc. aren't provided on the child controller.

Like:

// base_controller.js

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["base"]
}

// specfic_controller.js

import BaseController from "./base_controller"

export default class extends BaseController {
  static targets = ["specific"]
}

The specific controller should now have both the base and specific target.

Detect multiple Stimulus controllers in single file

Currently the parser doesn't recognize if a file defines more than one controller.

Support detecting controllers that don't end with the `_controller` suffix in the filename

Most people follow the convention of having the controllers in a **/**/controllers/ folder and having the filename end with the _controller.{js,ts} suffix. Though there are still cases where people don't or cannot follow this convention.

In order to still support that we would need to look into all *.js or *.ts in a project and check if they somehow reference Stimulus controllers.

Support dasherized controller filenames

We currently assume that the Stimulus controller files are named with underscores.

stimulus-parser/src/project.ts

Line 83 in c0fab10

const controllerFiles = await glob(`${this.projectPath}/**/*_controller.js`, {

We should also support dasherized file names or files that don't include the _controller suffix.

Public class fields without a default value break the parser

I was playing around with the LSP and noticed errors for some of my Stimulus controllers.

Debugging a bit I noticed that the parser fails on them, because we use some empty public class fields like so:

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  someField;

  // this is just an example how we use them later, not related to the bug
  doSomething() {
    this.someField = "some value";
  }
}

• It does work if you set it with a value, like someField = "initial value".
• Having static in front of it also breaks

It fails on this line:

stimulus-parser/src/parser.ts

Line 45 in 31842f4

if (node.value.type === "ArrowFunctionExpression") {

with TypeError: Cannot read properties of null (reading 'type')

I guess those nodes don't have a type, so some other parsing exception should be added.

Happy to help, but I don't have a good idea in what direction to go.

edit later that day: I made a PR that implements a possible fix in #21!

Using the defintionsFromContext webpack helper does not mark controllers as registered

We are using Debian Rails which is at 6.1 for the time being. Note that this Rails version isn't deprecated and will continue to receive security fixes even after Rails stops supporting it, unless there is a new stable Debian.

Using definitionsFromContext from the @hotwired/stimulus-webpack-helpers package does not mark Stimulus controllers as registered.

import { definitionsFromContext } from '@hotwired/stimulus-webpack-helpers';

const application = Application.start(document.documentElement);

// Normally you'd need to add the webpack env types, but since we'll migrate
// away (in Rails 7), and we know the signatures here, it's ignored and casted
// as any instead.

// @ts-ignore
// eslint-disable-next-line no-undef
const context = require.context('../controllers', true, /_controller\.ts$/);
application.load(definitionsFromContext(context));

declare const window: Window & { Stimulus: Application };
window.Stimulus = application;

The result in the Stimulus Controllers view:

I don't know if this is related, but I don't see any autocompletion in .html.erb files. I would expect them to not show for unregistered controllers, hence me opening this issue.

Trying to circumvent it by using the Register controller definition on the stimulus application yields the following error message:

Function `analyzeStaticPropertiesExpressions` needs to take `object` into account

Currently, given this file, the targets ["name", "output"] will be assigned to both classes

import { Controller } from "@hotwired/stimulus"

class One extends Controller {}
class Two extends Controller {}

One.targets = ["name", "output"]

Playground: https://stimulus-parser.hotwire.io/#JYWwDg9gTgLgBAbzgYQgOxlCAbbBTKOAXzgDMsQ4AiAAQAsIYB3YKPAEwHoBnGUAV2z9uVAFCiAxtgCG3bnADyaPHDwAPGHjTt5qDFlwFERSTLlwAKkwiqNWnSnSYc+QghOileAHQxpUAHM8GHkAXjgAbSo0aRA8KgAaagh+GDBUqgBdIA

Error parsing private getters

An unexpected token error will be raised if a Stimulus controller has a private getter defined, such as:

get #activeItems () {
    return this.itemTargets.filter(div => !div.classList.contains('destroying'))
}

Consider Typescript Parser

Acorn might not be the best choice here. While slower and harder to reason with, the TypeScript parser might be the easier route to take in order to obtain lexical context of each controller.

Referencing #9

Support Symfony's Stimulus Bridge

https://github.com/symfony/stimulus-bridge
https://github.com/symfony/stimulus-bundle

Parse kind of value definition

Shorthand-version:

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static values = {
    name: String
  }
}

Explicit-version:

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static values = {
    name: {
      type: String,
      default: "Stimulus"
    }
  }
}

Inferred-version:

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static values = {
    name: "Stimulus"
  }
}

Add nodes/locations to value definition parts

Ideally we have a node/location for each value in the value definition, while also having the node/location for the property-key and property-value.

Currently we get the range for the whole value of everything after static values =

Support when controllers are imported with a different name compared to their actual filename

For example, when we have a controller at:

app/javascript/controllers/example_controller.js

But we decide to import that controller as something-else:

import { Application } from "@hotwired/stimulus"
import ExampleController from "../controllers/example_controller.js"

const application = Application.start()

application.register("something-else", ExampleController)

Doesn't find controllers imported via importmap

stimulus-lsp is complaining about a missing controller. It's not missing though but was imported via importmaps.

Support controllers imported from npm packages

An example might be something like tailwindcss-stimulus-components, where you import and register controllers like:

import { Dropdown, Modal } from "tailwindcss-stimulus-components"

application.register('dropdown', Dropdown)
application.register('modal', Modal)

We might be able to statically analyze all Application.register("name", Controller) calls in the app to detect those controllers this way.

Support for `stimulus-use`

Similar to #12, it makes sense that the Stimulus Parser understands the mixins Stimulus Use provides. Some of the mixins Stimulus Use provides enhance the controller implicitly with properties and callback methods.

It would be neat to know that these methods and properties exist on a controller and where they come from. Kind of like a "This property is provided by Stimulus Use" message.

Support inferred Value Definition types

Currently this doesn't get parsed as a valid ValueDefinition, this is valid Stimulus though.

      import { Controller } from "@hotwired/stimulus";

      export default class extends Controller {
        static values = {
          string: "Number"
        }
      }

External Stimulus components false positive

My project have some external stimulus components specifically from Stimulus Components

Any usage of these external components gives the error:

Add `defaultValueLoc` getter to `ValueDefinition`

Related #114

Parse `ClassExpression` nodes as `ClassDeclarations`

Playground

Support for `stimulus-decorators`

stimulus-decorators is a great project bringing @github/catalyst typesafe syntax to stimulus

It would be great if we could also parse those libraries but make sure you can mix and match (i.e. static values but decorated @Targets)

Add `hasExplicitDefaultValue` to `ValueDefinition`

We should add a hasExplicitDefaultValue property to the ValueDefinition that works according to the use-cases shown below:

static values = {
  name: String
}

name: {
  type: "String",
  defaultValue: "",
  hasExplicitDefaultValue: false,
  kind: "shorthand",
  keyLoc: { ... },
  valueLoc: { ... },
}

---

static values = {
  name: { type: String },
}

name: {
  type: "String",
  defaultValue: "",
  hasExplicitDefaultValue: false,
  kind: "explicit",
  keyLoc: { ... },
  valueLoc: { ... },
}

---

static values = {
  name: { type: String, default: "Bob" },
}

name: {
  type: "String",
  defaultValue: "Bob",
  hasExplicitDefaultValue: true,
  kind: "explicit",
  keyLoc: { ... },
  valueLoc: { ... },
}

---

static values = {
  name: "Bob"
}

name: {
  type: "String",
  defaultValue: "Bob",
  hasExplicitDefaultValue: true,
  kind: "inferred",
  keyLoc: { ... },
  valueLoc: { ... },
}

---

@Value(String) nameValue!: string;

name: {
  type: "String",
  defaultValue: "",
  hasExplicitDefaultValue: false,
  kind: "decorator",
  keyLoc: { ... },
  valueLoc: { ... },
}

---

@Value(String) nameValue! = "Bob"

name: {
  type: "String",
  defaultValue: "Bob",
  hasExplicitDefaultValue: true,
  kind: "decorator",
  keyLoc: { ... },
  valueLoc: { ... },
}