docs: Update Create a Plugin for flat config

[nzakas]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

Updated the plugin documentation to be the correct format for flat config.

Refs #13481

Is there anything you'd like reviewers to focus on?

Did I miss anything?

[netlify]

✅ Deploy Preview for docs-eslint ready!

Name	Link
🔨 Latest commit	8c3b64f
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/658b6725db702a0008fa2daf
😎 Deploy Preview	https://deploy-preview-17826--docs-eslint.netlify.app/extend/custom-processors
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[nzakas]

@christian-bromann looks like browser test is failing again. :(

[christian-bromann]

@nzakas I just reverted changes we released 10h ago, should be all good again.

[nzakas]

@christian-bromann thanks, looks like it's working again. 🙏

[github-actions]

Hi everyone, it looks like we lost track of this pull request. Please review and see what the next steps are. This pull request will auto-close in 7 days without an update.

[nzakas]

@eslint/eslint-team this is ready for review.

[kecrily]

Perhaps we should mention that the use of / in rule ID is not supported because #17901 (comment)

[mdjermanovic]

Looks like parsing is different when the plugin doesn't start with @ (i.e., the plugin is not scoped), so / in rule ID would work in that case.

eslint/lib/config/flat-config-helpers.js

Lines 24 to 29 in 3826cdf

	// mimic scoped npm packages
	if (ruleId.startsWith("@")) {
	pluginName = ruleId.slice(0, ruleId.lastIndexOf("/"));
	} else {
	pluginName = ruleId.slice(0, ruleId.indexOf("/"));
	}

// this works
module.exports = {
    plugins: {
        "foo": {
            rules: {
                "bar/baz": {
                    create() {
                        return {}
                    }
                }
            }
        }
    },
    rules: {
        "foo/bar/baz": 2
    }
};

// this throws TypeError: Key "rules": Key "@foo/bar/baz": Could not find plugin "@foo/bar"
module.exports = {
    plugins: {
        "@foo": {
            rules: {
                "bar/baz": {
                    create() {
                        return {}
                    }
                }
            }
        }
    },
    rules: {
        "@foo/bar/baz": 2
    }
};

Nevertheless, it does seem best to generally say that rule IDs should not contain /, to avoid ambiguity.

[nzakas]

Yeah, I needed to do this to mimic the behavior of eslintrc plugin names. I've added a note about the slash.

[nzakas]

Also added a note about the @ restrictions in namespaces.

[mdjermanovic]

I think this doesn't reflect the current restrictions in flat config.

Namespaces that don't begin with @ have a restriction that they must not contain a /.

// this throws: TypeError: Key "rules": Key "foo/bar/my-rule": Could not find plugin "foo".
module.exports = [{
    plugins: {
        "foo/bar": {
            rules: {
                "my-rule": {
                    create() {
                        return {};
                    }
                }
            }
        }
    },
    rules: {
        "foo/bar/my-rule": 2,
    }
}];

Namespaces that begin with @ don't have any restrictions (except that their rule names definitely cannot contain /, but we recommend that for all rules regardless of the namespace). These namespaces can contain / but aren't required to. As for the backwards compatibility, @typecript-eslint, for instance, was a valid namespace in eslintrc (rules are in the form @typescript-eslint/rule-name).

// this all works
module.exports = [{
    plugins: {
        "@foo": {
            rules: {
                "my-rule": {
                    create() {
                        return {};
                    }
                }
            }
        },
        "@foo/bar": {
            rules: {
                "my-rule": {
                    create() {
                        return {};
                    }
                }
            }
        }
    },
    rules: {
        "@foo/my-rule": 2,
        "@foo/bar/my-rule": 2
    }
}];

[nzakas]

Ah good call. My brain is a bit fried from reading and writing all this documentation.

[mdjermanovic]

LGTM, thanks!