🚀 Feature: rule `prefer-scoped-name`

[wesleytodd]

Feature Request Checklist

• I have searched for related issues and found none that matched my issue.

Overview

I will be implementing a "safe list" rule for scopes which we support folks publishing with and wanted to propose I do so here instead of on top of this plugin in our internal code base. Something like this:

rules: {
  // Require a single scope, any unrecognized will be fixed to this value
  'package-json/prefer-scoped-name": ['error', { default: '@foo' }],

  // Prefer the @foo scope, any unrecognized will be fixed to this value
  // also allow the @bar scope which will neither error or be fixed
  'package-json/prefer-scoped-name": ['error', {
    default: '@foo',
    allowed: ['@bar']
  }]
}

[michaelfaith]

Thanks for the feature request! You didn't mention this explicitly, but based on the description, I think you're suggesting that this applies to the name property? As in, report on the name property if it doesn't use a preferred scope. Is that right?

If so, i'm generally in favor of the spirit of this, but have a few thoughts:

• the name is a bit too ambiguous (and especially alongside the 30-some-odd require-* rules that we have already). Recommend something like prefer-scoped-name instead
• I'm a bit wary about having auto-fixes on this, since it could change the name of a package that's already been published, which may not be expected - maybe limit fixes to only private packages, and only report suggestions on public packages?
• I'm not a fan of the config api. We generally prefer to use object type options for everything, since they're more extensible. what about something like this:

type Options = {
  /** allow list for acceptable scopes (if populated, any other scopes would fail validation; if not populated, any scopes would pass) */
  allowed?: string[];

  /** scope used for suggestions / fixes */
  default?: string;
};

If no options are provided, then it just validates that some scope is used in the name.

Thoughts?

NOTE: I think your lint rules are broken on main for the website.

I don't think so. They're running locally for me and in CI. Did you run pnpm site:sync first like CI does?

[wesleytodd]

I think you're suggesting that this applies to the name property? As in, report on the name property if it doesn't use a preferred scope. Is that right?

Yep exactly. Sorry I was not very clear on that.

Recommend something like prefer-scoped-name instead

Perfect.

I'm a bit wary about having auto-fixes on this, since it could change the name of a package that's already been published, which may not be expected

There are multiple use cases, and you are absolutely right that in the case of an already published package this type of fix is dangerous at worst and unexpected at best. FWIW, I do not think this rule would ever be enabled by default, but would be one specific projects enable, like a monorepo which would want to enforce this for any new packages. So Ideally folks would configure it for their already published packages in their repo when they enable this rule.

maybe limit fixes to only private packages, and only report suggestions on public packages?

I personally need it for all, but I am 100% on board with following the pattern of ignorePrivate: true like the other rules do. And setting that as the default.

We generally prefer to use object type options for everything

Ah, I didn't notice that. I was following what I see in more core JS rules from eslint, but I am not opinionated at all on this. So happy to follow your preference.

If no options are provided, then it just validates that some scope is used in the name.

I didn't call this out, but actually I was thinking it would require an option. Otherwise I think the rule should just be off. I just don't think "require any scope at all" is something worth doing because the goal of this rule is to use "safe" scopes for your project/company.

They're running locally for me and in CI. Did you run pnpm site:sync first like CI does?

Ah, no I did not do that. I was loosely looking at https://github.com/michaelfaith/eslint-plugin-package-json/blob/main/.github/DEVELOPMENT.md and ran pnpm i && pnpm build && pnpm lint because I was not considering the website as part of what I would contribute to. Would you be open to a small PR that adds a single setup script that gets the repo off the ground with a single command?

EDIT: applied the suggested changes to the proposal, let me know if I missed any or didn't interpret them correctly.

[wesleytodd]

I just realized while starting to write the scaffold for this rule that the option name default means you cannot destructure or name a keep the named variable the same as the config option. While this isn't exactly a deal breaker, I always try to avoid things that conflict with language syntax were possible. What about preferred?

[michaelfaith]

FWIW, I do not think this rule would ever be enabled by default, but would be one specific projects enable, like a monorepo which would want to enforce this for any new packages. So Ideally folks would configure it for their already published packages in their repo when they enable this rule.

I think that's fair. 👍

I didn't call this out, but actually I was thinking it would require an option. Otherwise I think the rule should just be off. I just don't think "require any scope at all" is something worth doing because the goal of this rule is to use "safe" scopes for your project/company.

Fair enough.

I just realized...that the option name default means you cannot destructure... What about preferred?

Ah, that's true. preferred seems fine to me.

Would you be open to a small PR that adds a single setup script that gets the repo off the ground with a single command?

Sure! Either that or just updating the DEVELOPMENT doc. Thanks 🙏

Marking this as "accepting PRs". Thanks again for the proposal. It sounds like this is something you'd also like to contribute a PR for. Is that right?

[michaelfaith]

@all-contributors please add @wesleytodd for idea

[wesleytodd]

Awesome, I had mostly already written out an implementation of the rule with those specifcs in my internal project. I will look at opening the PR tomorrow morning.

Since it is short, posting it here in case (other than the obvious things of converting it to use your helpers and typescript, etc):

import npa from 'npm-package-arg';

const rule = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Prefer a scoped package name'
    },
    messages: {
      missingPreferredScope: 'Use the preferred scope {{preferred}} in package name, found {{name}}',
      usePreferredScope: 'Use the preferred scope {{preferred}}, found {{scope}} in {{name}}',
      useAllowedScope: 'Use an allowed scope (preferably {{preferred}}), found {{scope}} in {{name}}'
    },
    fixable: 'code',
    schema: [
      {
        type: 'object',
        requiredProperties: ['preferred'],
        properties: {
          preferred: {
            type: 'string'
          },
          allowed: {
            anyOf: [
              { type: 'string' },
              {
                type: 'array',
                items: 'string'
              }
            ]
          }
        }
      }
    ]
  },
  create: function (context) {
    const { preferred, allowed } = context.options[0];

    return {
      'Program > JSONExpressionStatement > JSONObjectExpression': (node) => {
        const exp = node.properties.find((prop) => prop.key.type === 'JSONLiteral' && prop.key.value === 'name');
        if (!exp) {
          return;
        }

        const pkgarg = npa(exp.value.value);
        if (!pkgarg.scope) {
          context.report({
            messageId: 'missingPreferredScope',
            node: exp.value,
            data: {
              name: pkgarg.name,
              preferred
            }
          });
          return;
        }

        if (pkgarg.scope !== preferred && !allowed) {
          context.report({
            messageId: 'usePreferredScope',
            node: exp.value,
            data: {
              name: pkgarg.name,
              scope: pkgarg.scope,
              preferred
            }
          });
          return;
        }

        if (pkgarg.scope !== preferred && allowed && !allowed.includes(pkgarg.scope)) {
          context.report({
            messageId: 'useAllowedScope',
            node: exp.value,
            data: {
              name: pkgarg.name,
              scope: pkgarg.scope,
              preferred
            }
          });
        }
      }
    };
  }
};

export default rule;

[wesleytodd]

#1892