nshki / chusaku Goto Github PK

Formalizing this into an issue from @G-Rath's comment here.

It might be worth reviewing the output later at some point:

❯ bundle exec rake dev:annotate

Chusaku has finished running.
Model files unchanged.

❯ bundle exec rake dev:annotate
Nothing to annotate.
Model files unchanged.

Specifically, removing that leading newline, and changing the "Nothing to annotate" to "Controller files unchanged" or something similar to make it clearer what it's referring to.

It would be nice if we had a rake task that could be used to invoke chusaku so that it could be easily integrated with rake-based workflows i.e. our codebases use both chusaku and annotate_models, so I'd like to create a general dev:annotate task that invokes both.

Technically I should be able to call chusaku programmatically but that would require understanding more of the internal classes than I'd like (and in every application!), and overall this feels like something reasonable for the gem to carry.

For reference, this is the rake tasks provided by annotate_models: https://github.com/ctran/annotate_models/blob/develop/lib/tasks/annotate_models.rake

There is a borked link in the development section of the readme. - https://nshki.com/chusaku-a-controller-annotation-gem/

I think GitHub is not happy with the last "/" at the end of the URL.

https://nshki.com/chusaku-a-controller-annotation-gem/ does not work
https://nshki.com/chusaku-a-controller-annotation-gem works

https://github.com/nshki/chusaku/blob/master/README.md#development

Absolutely loving this gem! In order to use in production, we want to implement a Github Actions check to validate that route annotations are up to date. When attempting to implement the workflow, I ran chusaku in the root directory but reverted the changes in one file to test the workflow.

Expected output:

Chusaku has finished running.
This was a dry run so no files were changed.
Exited with status code 1.

Output when running locally:

$ bundle exec chusaku --dry-run --exit-with-error-on-annotation
Chusaku has finished running.
This was a dry run so no files were changed.
Exited with status code 1.

Output in Github Actions Workflow:

Run bundle exec chusaku --dry-run --exit-with-error-on-annotation
  bundle exec chusaku --dry-run --exit-with-error-on-annotation
  shell: /usr/bin/bash -e {0}
Nothing to annotate.

Github Action Workflow:

name: Chusaku Check

on: pull_request

jobs:
  chusaku:
    name: Chusaku
    runs-on: ubuntu-latest

    steps:
      - uses: actions/[email protected]
      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true

      - name: Run Chusaku
        run: bundle exec chusaku --dry-run --exit-with-error-on-annotation

Running Ruby 2.7.6 and Rails 6.0.4.8. Got the same output in the Github Actions workflow when omitting the --dry-run flag for what it's worth.

Hi!
Happy to say we use Chusaku daily and it really makes our lives better :)

We set our CI to run chusaku --dry-run --exit-with-error-on-annotation, so it notifies us if we forgot to annotate some routes.

One thing that recently came to my attention is that if some developers on the team aren't familiar with chusaku use case, they are confused by CI error that just says "Annotated controller/path.rb", doesn't look really "error-y"... WDYT about expanding it to say something like this (on dry-run, for example):

Annotation comments are missing in the following controllers: ....
Run chusaku command locally to add annotation comments.

(Or, alternatively, there could be a command-line argument to provide custom error message... But I believe the message above would be helpful for all chusaku users.)

Noticed while testing #41.

Passing --verbose prints every possible annotation that Chusaku can make instead of the only changes that it makes on the given run.

Rails 6 adds some subjectively inferior annotations to controllers when scaffold is used. chusaku should detect and replace though, and ideally hook into scaffold itself.

Consider this routing (update is aliased as change):

resources :invitations do
  collection do
    put :update, as: :change
  end
end

Chusaku annotates the update action like so (change_invitation is present, but the standard invitation is missing):

# @route PUT /invitations (change_invitations)
# @route PATCH /invitations/:id
# @route PUT /invitations/:id
def update; end

Strangely, if I change it to resources :invitations, only: [:update], everything works as expected: 🤔

# @route PUT /invitations (change_invitations)
# @route PATCH /invitations/:id (invitation)
# @route PUT /invitations/:id (invitation)
def update; end

GitHub Actions supports "annotations", which is a poorly documented but really cool feature whereby CI output can tell GH to show a message on a specific line in a specific file at a particular level (error, warning, or notice).

It would be cool if chusaku supported this, to tell us exactly which controller methods are missing their annotations.

https://docs.github.com/en/actions/learn-github-actions/workflow-commands-for-github-actions#setting-an-error-message

Our app uses Rails engines and the packs standard which means our routes and controllers are in a few locations. We love this gem and would be very happy if it could work with our setup.

Our directory structure is like this

app/controllers <-- global controllers
config/routes.rb
packs/app1/app/controllers <-- controllers for app1
packs/app1/config/routes.rb
packs/app2/app/controllers <--- controllers for app2
packs/app2/config/routes.rb

And our top-level routes file looks like

Rails.application.routes.draw do
  get "top_level_route" => "top_level#show"

  mount App1::Engine, at: "/app1"
  mount App2::Engine, at: "/app2"
end

Looking at the chukasu codebase, a few things might need to be changed to make this possible.

1. It currently only looks at the top-level routes. This could be changed to also look at engine routes (eg. App1::Engine.routes.routes), either by following the engine reference in the top-level route file or by providing a configuration option of a list of engines.
2. I think the configurable controller file pattern could work, but it might need to take a list of patterns for each engine.
3. With more complex configuration, it would be great if you could have a config file, so it's easy to just run bin/chusaku and have it to do the right thing.

I'd be happy to help with PR if you provide some guidance on what approach might work best. Thank you!