Adding a new protection

[alexevanczuk]

Adding a new protection

This document contains some information on adding new protections. It's mostly focused on adding a custom one in your app, but it also applies to protections checked into this repo.

Making a new rubocop protection

1. Write a rubocop as normal. Include it in your .rubocop.yml to make sure its working as expected.
2. Add include PackageProtections::RubocopProtectionInterface, run sorbet type check, and implement the required interface methods. See https://github.com/rubyatscale/package_protections/tree/main/lib/rubocop/cop/package_protections for examples.

Backfill the protection to fail_never for all packages

By default, all protections have a default value of fail_on_new. The idea is that if we think the protection is something everything should turn on, we want the default to be the path we want folks to take. In some cases this is not the case. The visibility protection default is fail_never, because by default we don't want folks making packs only visible to some other packs (we want the default design principle to be that any pack can consume any other path, theoretically).

For new protections, its important to backfill all old packages to turn this protection OFF so it can be gradually turned on. Say your protection is prevent_foobar. You can backfill this with this script:

require 'parse_packwerk'
ParsePackwerk.all.each do |p|
  new_metadata = p.metadata.dup
  new_metadata['protections']['foobar'] = 'fail_never'
  ParsePackwerk.write_package_yml!(
    ParsePackwerk::Package.new(
      dependencies: p.dependencies,
      enforce_dependencies: p.enforce_dependencies,
      enforce_privacy: p.enforce_privacy,
      metadata: new_metadata,
      name: p.name,
    )
  )
end

This just rewrites all packages with the new protection.

In some cases, this may produce undesirable diffs related to other things that are rewritten. I recommend committing those as part of a separate diff that can be generated with the simpler command:

require 'parse_packwerk'
ParsePackwerk.all.each{|p| ParsePackwerk.write_package_yml!(p) }

Gusto today has a CI check that ensures deprecated_references.yml are up to date. We might consider adding something to ensure package.yml changes do not contain incorrect formatting (basically linting for package.yml files).

Identifying candidates to opt into the package protection

It might be helpful to identify packages that are already overwhelmingly following the new protection and opt them in to establish some examples.

For a rubocop rule, you can do this by following these steps:
Say my new cop is Style/MyNewCop and it applies to files in the public directory.

1. Turn on the rubocop for all files in .rubocop.yml

Style/MyNewCop:
  Enabled: true
  Included:
    - packs/*/app/public/**/*.rb
    - components/*/app/public/**/*.rb

2. See which files fail, and see what percentage of files abide by the new cop:

require 'parse_packwerk'
public_files_failing_cop = `bin/rubocop --only=Style/MyNewCop --format=files`.split("\n")

histogram = {}
ParsePackwerk.all.each do |p|
  total_public_files = p.directory.glob('app/public/**/*.rb').count
  # Let's not opt in packs unless they have at least one public file that abides by the cop
  next if total_public_files == 0
  files_failing_cop = public_files_failing_cop.count{|f| f.include?(p.name + "/") }
  percentage = 100 - ((files_failing_cop.to_f / total_public_files) * 100).round
  histogram[p.name] = percentage
end;

desired_threshold = 100
histogram.select{|file, percentage| percentage >= desired_threshold }

Writing tests for custom protections (rspec)

I'll fill this out with more detail later.

1. Make sure your application's spec helper require 'package_protections/rspec/support'
2. See examples of testing package protections in package_protections_spec.rb