{"id":13878073,"url":"https://github.com/rubyatscale/packwerk-extensions","last_synced_at":"2025-06-19T11:06:53.343Z","repository":{"id":64728683,"uuid":"560115689","full_name":"rubyatscale/packwerk-extensions","owner":"rubyatscale","description":"A collection of extensions for packwerk packages.","archived":false,"fork":false,"pushed_at":"2025-05-23T20:12:10.000Z","size":1136,"stargazers_count":45,"open_issues_count":2,"forks_count":15,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-15T01:21:43.910Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rubyatscale.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-31T19:12:55.000Z","updated_at":"2025-06-02T07:31:22.000Z","dependencies_parsed_at":"2023-10-05T05:05:50.065Z","dependency_job_id":"61ea9564-9464-4b99-8cf3-2adb05f4a5d1","html_url":"https://github.com/rubyatscale/packwerk-extensions","commit_stats":{"total_commits":21,"total_committers":5,"mean_commits":4.2,"dds":0.2857142857142857,"last_synced_commit":"78808ef0ca6d0c95ef53ff3a9eba008b629bb8a9"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/rubyatscale/packwerk-extensions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyatscale%2Fpackwerk-extensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyatscale%2Fpackwerk-extensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyatscale%2Fpackwerk-extensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyatscale%2Fpackwerk-extensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubyatscale","download_url":"https://codeload.github.com/rubyatscale/packwerk-extensions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyatscale%2Fpackwerk-extensions/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260739050,"owners_count":23055073,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:01:39.103Z","updated_at":"2025-06-19T11:06:48.332Z","avatar_url":"https://github.com/rubyatscale.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# packwerk-extensions\n\n`packwerk-extensions` is a home for checker extensions for [packwerk](https://github.com/Shopify/packwerk) 3.\n\nCurrently, it ships the following checkers to help improve the boundaries between packages. These checkers are:\n- A `privacy` checker that ensures other packages are using your package's public API\n- A `visibility` checker that allows packages to be private except to an explicit group of other packages.\n- A `folder_privacy` checker that allows packages to their sibling packs and parent pack (to be used in an application that uses folder packs)\n- A `layer` (formerly `architecture`) checker that allows packages to specify their \"layer\" and requires that each layer only communicate with layers below it.\n\n## Installation\n\nAdd `packwerk-extensions` to your `Gemfile`.\n\nTo register all checkers included in this gem, add the following to your `packwerk.yml`:\n\n```yaml\nrequire:\n  - packwerk-extensions\n```\n\nAlternatively, you can require individual checkers:\n\n```yaml\nrequire:\n  - packwerk/privacy/checker\n  - packwerk/visibility/checker\n  - packwerk/folder_privacy/checker\n  - packwerk/layer/checker\n```\n\n## Privacy Checker\nThe privacy checker extension was originally extracted from [packwerk](https://github.com/Shopify/packwerk).\n\nA package's privacy boundary is violated when there is a reference to the package's private constants from a source outside the package.\n\nTo enforce privacy for your package, set `enforce_privacy` to `true` or `strict` on your pack:\n\n```yaml\n# components/merchandising/package.yml\nenforce_privacy: true\n```\n\nSetting `enforce_privacy` to `true` will make all references to private constants in your package a violation.\n\nSetting `enforce_privacy` to `strict` will forbid all references to private constants in your package. **This includes violations that have been added to other packages' `package_todo.yml` files.**\n\nNote: You will need to remove all existing privacy violations before setting `enforce_privacy` to `strict`.\n\n### Using public folders\nYou may enforce privacy either way mentioned above and still expose a public API for your package by placing constants in the public folder, which by default is `app/public`. The constants in the public folder will be made available for use by the rest of the application.\n\n### Defining your own public folder\n\nYou may prefer to override the default public folder, you can do so on a per-package basis by defining a `public_path`.\n\nExample:\n\n```yaml\npublic_path: my/custom/path/\n```\n\n### Defining public constants through sigil\n\n\u003e [!WARNING]\n\u003e This way of of defining the public API of a package should be considered WIP. It is not supported by all tooling in the RubyAtScale ecosystem, as @alexevanczuk pointed out in a [comment on the PR](https://github.com/rubyatscale/packwerk-extensions/pull/35#discussion_r1334331797):\n\u003e\n\u003e There are a couple of other places that will require changes related to this sigil. Namely, everything that is coupled to the public folder implementation of privacy.\n\u003e\n\u003e In the rubyatscale org:\n\u003e\n\u003e * pack_stats, example https://github.com/rubyatscale/pack_stats/blob/main/lib/pack_stats/private/metrics/public_usage.rb. (IMO though we can just remove this metric – it has never been useful)\n\u003e * Other places that mention public_path or app/public.\n\u003e   * Org wide search for app/public link\n\u003e   * Org wide search for public_path link\n\u003e   * packs (the Rust port of packwerk – I could take this one over unless someone is interested in implementing whatever we come up with there\n\n\n\nYou may make individual files public within a private package by usage of a comment within the first 5 lines of the `.rb` file containing `pack_public: true`.\n\nExample:\n\n```ruby\n# pack_public: true\nmodule Foo\n  class Update\n  end\nend\n```\nNow `Foo::Update` is considered public even though the `foo` package might be set to `enforce_privacy: (true || strict)`.\n\nIt's important to note that when combining `public_api: true` with the declaration of `private_constants`,\n`packwerk validate` will raise an exception if both are used for the same constant. This must be resolved by removing\nthe sigil from the `.rb` file or removing the constant from the list of `private_constants`.\n\nIf you are using rubocop, it may be configured in such a way that there must be an empty line after the magic keywords at the top of the file. Currently, this extension is not modifying rubocop in any way so it does not recognize `pack_public: true` as a valid magic keyword option. That means placing it at the end of the magic keywords will throw a rubocop exception. However, you can place it first in the list to avoid an exception in rubocop.\n```\n-----\n# typed: ignore\n# frozen_string_literal: true\n# pack_public: true\n\nclass Foo\n...\nend =\u003e Layout/EmptyLineAfterMagicComment: Add an empty line after magic comments.\n\n------\n# typed: ignore\n# frozen_string_literal: true\n\n# pack_public: true\n\nclass Foo\n...\nend =\u003e Less than ideal. This won't raise an issue in rubocop, however, only the first 5 lines are scanned for the magic comment of pack_public so there is risk at it being missed. It also is requiring extra empty lines in the group of magic comments.\n\n-----\n# pack_public: true\n# typed: ignore\n# frozen_string_literal: true\n\nclass Foo\n...\nend =\u003e Ideal solution. No exceptions from rubocop and very low risk of the magic comment being out of range since\n```\n\n### Using specific private constants\nSometimes it is desirable to only enforce privacy on a subset of constants in a package. You can do so by defining a `private_constants` list in your package.yml. Note that `enforce_privacy` must be set to `true` or `'strict'` for this to work.\n\n### Ignore strict mode for violation coming from specific path patterns\nIf you want to activate `'strict'` mode on your package but have a few privacy violations you know you will deal with later,\nyou can set a list of patterns to exclude.\n\n```yaml\nenforce_privacy: strict\nstrict_privacy_ignored_patterns:\n- engines/another_engine/test/**/*\n```\n\nIn this example, violations on constants of your engine referenced in those files `engines/another_engine/test/**/*` will not fail Packwerk checks.\n\n### Package Privacy violation\nPackwerk thinks something is a privacy violation if you're referencing a constant, class, or module defined in the private implementation (i.e. not the public folder) of another package. We care about these because we want to make sure we only use parts of a package that have been exposed as public API.\n\n#### Interpreting Privacy violation\n\n\u003e /Users/JaneDoe/src/github.com/sample-project/user/app/controllers/labels_controller.rb:170:30\n\u003e Privacy violation: '::Billing::CarrierInvoiceTransaction' is private to 'billing' but referenced from 'user'.\n\u003e Is there a public entrypoint in 'billing/app/public/' that you can use instead?\n\u003e\n\u003e Inference details: 'Billing::CarrierInvoiceTransaction' refers to ::Billing::CarrierInvoiceTransaction which seems to be defined in billing/app/models/billing/carrier_invoice_transaction.rb.\n\nThere has been a privacy violation of the package `billing` in the package `user`, through the use of the constant `Billing::CarrierInvoiceTransaction` in the file `user/app/controllers/labels_controller.rb`.\n\n#### Suggestions\nYou may be accessing the implementation of a piece of functionality that is supposed to be accessed through a public interface on the package. Try to use the public interface instead. A package’s public interface should be defined in its `app/public` folder and documented.\n\nThe functionality you’re looking for may not be intended to be reused across packages at all. If there is no public interface for it but you have a good reason to use it from outside of its package, find the people responsible for the package and discuss a solution with them.\n\n## Visibility Checker\nThe visibility checker can be used to allow a package to be a private implementation detail of other packages.\n\nTo enforce visibility for your package, set `enforce_visibility` to `true` on your pack and specify `visible_to` for other packages that can use your package.\n\n```yaml\n# components/merchandising/package.yml\nenforce_visibility: true\nvisible_to:\n  - components/other_package\n```\n\n## Folder-Visibility Checker\nThe folder privacy checker can be used to allow a package to be private to their sibling packs and parent packs and will create todos if used by any other package.\n\nTo enforce folder privacy for your package, set `enforce_folder_privacy` to `true` on your pack.\n\n```yaml\n# components/merchandising/package.yml\nenforce_folder_privacy: true\n```\n\nHere is an example of paths and whether their use of `packs/b/packs/e` is OK or not, assuming that protects itself via `enforce_folder_privacy`\n\n```\n.                         OK (parent of parent)\npacks/a                   VIOLATION\npacks/b                   OK (parent)\npacks/b/packs/d           OK (sibling)\npacks/b/packs/e           ENFORCE_NESTED_VISIBILITY: TRUE\npacks/b/packs/e/packs/f   VIOLATION\npacks/b/packs/e/packs/g   VIOLATION\npacks/b/packs/h           OK (sibling)\npacks/c                   VIOLATION\n```\n\n## Layer Checker\nThe layer checker can be used to enforce constraints on what can depend on what.\n\nTo enforce layers for your package, first define the `layers` in `packwerk.yml`, for example:\n```\nlayers:\n  - package\n  - utility\n```\n\nThen, turn on the checker in your package:\n```yaml\n# components/merchandising/package.yml\nenforce_layers: true\nlayer: utility\n```\n\nNow this pack can only depend on other utility packages.\n\n### Deprecated Architecture Checker\nThe \"Layer Checker\" was formerly named \"Architecture Checker\". The associated keys were:\n- packwerk.yml `architecture_layers`, which is now `layers`\n- package.yml `enforce_architecture`, which is now `enforce_layers`\n- package.yml `layer` is still a valid key\n- package_todo.yml - `architecture`, which is now `layer`\n\n```bash\n  # script to migrate code from deprecated \"architecture\" violations to \"layer\" violations\n  # sed and ripgrep required\n\n  # replace 'architecture_layers' with 'layers' in packwerk.yml\n  sed -i '' 's/architecture_layers/layers/g' ./packwerk.yml\n\n  # replace 'enforce_architecture' with 'enforce_layers' in package.yml files\n  `rg -l 'enforce_architecture' -g 'package.yml' | xargs sed -i '' 's,enforce_architecture,enforce_layers,g'`\n\n  # replace '- architecture' with '- layer' in package_todo.yml files\n  `rg -l 'architecture' -g 'package_todo.yml' | xargs sed -i '' 's/- architecture/- layer/g'`\n```\n\n\n## Contributing\n\nGot another checker you would like to add? Add it to this repo!\n\nPlease ensure these commands pass for you locally:\n\n```\nbundle\nsrb tc\nbin/rubocop\nbin/rake test\n```\n\nThen, submit a PR!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyatscale%2Fpackwerk-extensions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubyatscale%2Fpackwerk-extensions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyatscale%2Fpackwerk-extensions/lists"}