diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9e15843..d974882 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -51,3 +51,15 @@ jobs: ruby-version: head - name: Run style checks run: bundle exec rubocop + documentation: + runs-on: ubuntu-latest + name: CLI Documentation + steps: + - uses: actions/checkout@8230315d06ad95c617244d2f265d237a1682d445 + - name: Set up Ruby + uses: ruby/setup-ruby@eae47962baca661befdfd24e4d6c34ade04858f7 + with: + bundler-cache: true + ruby-version: head + - name: Check autogenerated documentation + run: ruby docs/verify_docs.rb diff --git a/Gemfile.lock b/Gemfile.lock index 8d1aa83..403fb02 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -17,7 +17,7 @@ GIT PATH remote: . specs: - use_packs (0.0.15) + use_packs (0.0.16) code_ownership colorize packs @@ -53,7 +53,7 @@ GEM smart_properties builder (3.2.4) byebug (11.1.3) - code_ownership (1.32.13) + code_ownership (1.32.15) code_teams (~> 1.0) packs sorbet-runtime @@ -230,4 +230,4 @@ DEPENDENCIES use_packs! BUNDLED WITH - 2.2.29 + 2.2.33 diff --git a/README.md b/README.md index e1142b0..df467f7 100644 --- a/README.md +++ b/README.md @@ -5,47 +5,88 @@ UsePacks is a gem that helps in creating and maintaining packs. It exists to hel ## Usage Make sure to run `bundle binstub use_packs` to generate `bin/packs` within your application. -### General Help -`bin/packs --help` or just `bin/packs` to enter interactive mode. +## CLI Documentation +## Describe available commands or one specific command +`bin/packs help [COMMAND]` -### Pack Creation -`bin/packs create packs/your_pack_name_here` +## Create pack with name packs/your_pack +`bin/packs create packs/your_pack` -### Moving files to packs -`bin/packs move packs/your_pack_name_here path/to/file.rb path/to/directory` -This is used for moving files into a pack (the pack must already exist). -Note this works for moving files to packs from the monolith or from other packs +## Add packs/to_pack to packs/from_pack/package.yml list of dependencies +`bin/packs add_dependency packs/from_pack packs/to_pack` -Make sure there are no spaces between the comma-separated list of paths of directories. +Use this to add a dependency between packs. -### Moving a file to public API -`bin/packs make_public path/to/file.rb,path/to/directory` -This moves a file or directory to public API (that is -- the `app/public` folder). +When you use bin/packs add_dependency packs/from_pack packs/to_pack, this command will +modify packs/from_pack/package.yml's list of dependencies and add packs/to_pack. -Make sure there are no spaces between the comma-separated list of paths of directories. +This command will also sort the list and make it unique. + +## List the top dependency violations of packs/your_pack +`bin/packs list_top_dependency_violations packs/your_pack` + +Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way + +You can use this command to list the top dependency violations. + +If no pack name is passed in, this will list out violations across all packs. + +## List the top privacy violations of packs/your_pack +`bin/packs list_top_privacy_violations packs/your_pack` -### Listing top privacy violations -`bin/packs list_top_privacy_violations packs/my_pack` Want to create interfaces? Not sure how your pack's code is being used? You can use this command to list the top privacy violations. If no pack name is passed in, this will list out violations across all packs. -### Listing top dependency violations -`bin/packs list_top_dependency_violations packs/my_pack` -Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way +## Make files or directories public API +`bin/packs make_public path/to/file.rb path/to/directory` -You can use this command to list the top dependency violations. +This moves a file or directory to public API (that is -- the `app/public` folder). -If no pack name is passed in, this will list out violations across all packs. +Make sure there are no spaces between the comma-separated list of paths of directories. + +## Move files or directories from one pack to another +`bin/packs move packs/destination_pack path/to/file.rb path/to/directory` + +This is used for moving files into a pack (the pack must already exist). +Note this works for moving files to packs from the monolith or from other packs + +Make sure there are no spaces between the comma-separated list of paths of directories. + +## Lint `package_todo.yml` files to check for formatting issues +`bin/packs lint_package_todo_yml_files` + +## Lint `package.yml` files +`bin/packs lint_package_yml_files [ packs/my_pack packs/my_other_pack ]` + +## Run bin/packwerk validate (detects cycles) +`bin/packs validate` + +## Run bin/packwerk check +`bin/packs check [ packs/my_pack ]` + +## Run bin/packwerk update-todo +`bin/packs update` + +## Regenerate packs/*/package_rubocop_todo.yml for one or more packs +`bin/packs regenerate_rubocop_todo [ packs/my_pack packs/my_other_pack ]` + +## Get info about size and violations for packs +`bin/packs get_info [ packs/my_pack packs/my_other_pack ]` + +## Visualize packs +`bin/packs visualize [ packs/my_pack packs/my_other_pack ]` + +## Rename a pack +`bin/packs rename` -### Adding a dependency -`bin/packs add_dependency packs/my_pack packs/dependency_pack_name` +## Set packs/child_pack as a child of packs/parent_pack +`bin/packs move_to_parent packs/child_pack packs/parent_pack ` -This can be used to quickly modify a `package.yml` file and add a dependency. It also cleans up the list of dependencies to sort the list and remove redundant entries. -### Releasing +## Releasing Releases happen automatically through github actions once a version update is committed to `main`. ## Discussions, Issues, Questions, and More diff --git a/docs/verify_docs.rb b/docs/verify_docs.rb new file mode 100644 index 0000000..5636f58 --- /dev/null +++ b/docs/verify_docs.rb @@ -0,0 +1,41 @@ +# typed: strict + +require 'bundler/inline' + +# Send is to ward off Sorbet which can't type this method invocation +send(:gemfile) do + send(:source, 'https://rubygems.org') + gem 'use_packs', path: '../' +end + +all_docs = [] +UsePacks::CLI.all_commands.each do |_command_name, command| + all_docs << <<~DOCUMENTATION + ## #{command.description} + `bin/packs #{command.usage}` + + DOCUMENTATION + + if command.long_description + all_docs << command.long_description + all_docs << "\n" + end +end + +new_autogenerated_content = <<~MARKDOWN.chomp + ## CLI Documentation + #{all_docs.join} + ## Releasing +MARKDOWN + +readme = Pathname.new('README.md') +new_content = readme.read.gsub(/## CLI Documentation.*?## Releasing/m, new_autogenerated_content) + +if ENV['OVERWRITE'] + readme.write(new_content) +elsif readme.read == new_content + exit 0 +else + puts 'README.md is out of date. Use OVERWRITE=1 ruby docs/verify_docs.rb' + exit 1 +end diff --git a/lib/use_packs/cli.rb b/lib/use_packs/cli.rb index d0ac4ef..d89d8b5 100644 --- a/lib/use_packs/cli.rb +++ b/lib/use_packs/cli.rb @@ -30,6 +30,13 @@ def add_dependency(from_pack, to_pack) end desc 'list_top_dependency_violations packs/your_pack', 'List the top dependency violations of packs/your_pack' + long_desc <<~LONG_DESC + Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way + + You can use this command to list the top dependency violations. + + If no pack name is passed in, this will list out violations across all packs. + LONG_DESC option :limit, type: :numeric, default: 10, aliases: :l, banner: 'Specify the limit of constants to analyze' sig { params(pack_name: String).void } def list_top_dependency_violations(pack_name) @@ -40,6 +47,13 @@ def list_top_dependency_violations(pack_name) end desc 'list_top_privacy_violations packs/your_pack', 'List the top privacy violations of packs/your_pack' + long_desc <<~LONG_DESC + Want to create interfaces? Not sure how your pack's code is being used? + + You can use this command to list the top privacy violations. + + If no pack name is passed in, this will list out violations across all packs. + LONG_DESC option :limit, type: :numeric, default: 10, aliases: :l, banner: 'Specify the limit of constants to analyze' sig { params(pack_name: String).void } def list_top_privacy_violations(pack_name) @@ -49,7 +63,12 @@ def list_top_privacy_violations(pack_name) ) end - desc 'make_public path/to/file.rb path/to/directory', 'Pass in a space-separated list of file or directory paths to make public' + desc 'make_public path/to/file.rb path/to/directory', 'Make files or directories public API' + long_desc <<~LONG_DESC + This moves a file or directory to public API (that is -- the `app/public` folder). + + Make sure there are no spaces between the comma-separated list of paths of directories. + LONG_DESC sig { params(paths: String).void } def make_public(*paths) UsePacks.make_public!( @@ -58,7 +77,13 @@ def make_public(*paths) ) end - desc 'move packs/destination_pack path/to/file.rb path/to/directory', 'Pass in a destination pack and a space-separated list of file or directory paths to move to the destination pack' + desc 'move packs/destination_pack path/to/file.rb path/to/directory', 'Move files or directories from one pack to another' + long_desc <<~LONG_DESC + This is used for moving files into a pack (the pack must already exist). + Note this works for moving files to packs from the monolith or from other packs + + Make sure there are no spaces between the comma-separated list of paths of directories. + LONG_DESC sig { params(pack_name: String, paths: String).void } def move(pack_name, *paths) UsePacks.move_to_pack!( @@ -68,7 +93,7 @@ def move(pack_name, *paths) ) end - desc 'lint_package_todo_yml_files', 'Ensures `package_todo.yml` files are up to date' + desc 'lint_package_todo_yml_files', 'Lint `package_todo.yml` files to check for formatting issues' sig { void } def lint_package_todo_yml_files UsePacks.lint_package_todo_yml_files! @@ -122,7 +147,7 @@ def rename puts Private.rename_pack end - desc 'move_to_parent packs/child_pack packs/parent_pack ', 'Sets packs/child_pack as a child of packs/parent_pack' + desc 'move_to_parent packs/child_pack packs/parent_pack ', 'Set packs/child_pack as a child of packs/parent_pack' sig { params(child_pack_name: String, parent_pack_name: String).void } def move_to_parent(child_pack_name, parent_pack_name) UsePacks.move_to_parent!( diff --git a/use_packs.gemspec b/use_packs.gemspec index e632ce5..79b4931 100644 --- a/use_packs.gemspec +++ b/use_packs.gemspec @@ -1,6 +1,6 @@ Gem::Specification.new do |spec| spec.name = 'use_packs' - spec.version = '0.0.15' + spec.version = '0.0.16' spec.authors = ['Gusto Engineers'] spec.email = ['dev@gusto.com']