feat: add support for plugins (#228)

[SimeonC]

This adds an eslint-esque plugin system to commitlint.

Motivation and Context

See #228

Usage examples

See the new doc file in the PR.

How Has This Been Tested?

Tests have been added to the following packages; @commitlint/lint and @commitlint/load

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[SimeonC]

For reference here is eslints plugin config file; https://github.com/eslint/eslint/blob/5018378131fd5190bbccca902c0cf4276ee1581a/lib/config/plugins.js

[escapedcat]

Hey @SimeonC I think this is can be a good addtition. Tests are needed.
@byCedric what do you think?

[SimeonC]

Cool, I'll try find some time to add tests in the next while.

[SimeonC]

OK, I got some tests written. There are a few more changes as it seems prettier hadn't been run on these files so it changed a few more lines in the file than I did (mostly just brackets and whitespace).
@escapedcat I updated the docs as well.

EDIT: NVM forgot my Intellij Prettier watcher takes command line args not package.json settings. Nothing wrong with prettier.

[escapedcat]

@SimeonC I just noticed that your commit isn't actually authored by your github account. It just says Simeon Cheeseman. You wanna change that by amending the commit using correct GH account config?

[SimeonC]

@escapedcat Thanks for pointing that out, I changed my global git so it matched our work but forgot to change the GitHub repos that are under my name 😟 . I fixed it up now so it has the correct author.

[escapedcat]

Nice! Happened to me a couple of times till @marionebl told me that he removed his global github config all together so you need to explicitly set it on each repo. Helped me dealing with this :)

Thanks for your efforts. Let's get some feedback from the others.

[marionebl]

Sorry for taking so long, I'll try to carve out some time for this over the week.

[SimeonC]

I admit to having done the same multiple times to some of my open source projects, so I have no grounds to complain 😆

[marionebl]

Let's do this!

[blackswanny]

@escapedcat @marionebl Good day. Can you tell if the release with custom plugins is published in npm ? I am checking, but not yet sure. Thanks

[escapedcat]

Hey @blackswanny , not yet. We're preparing a bigger 8.0.0 release which will include this.

[escapedcat]

Hey @SimeonC , can you confirm that plugins are working correctly?
I wanted to update the docs and tried to create an example for myself.

I'm getting:

git commit -m 'chore: foo'
husky > commit-msg (node v10.1.0)
[PATH]/node_modules/@commitlint/cli/lib/cli.js:119
	throw err;
	^

RangeError: Found invalid rule names: example/dollar-sign.

My config:

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: { 
    'example/dollar-sign': 2
  },
}

My test plugin: https://github.com/escapedcat/commitlint-plugin-example/blob/master/index.js

I used npm link to add it to my test project.
Let me know if I should try something else or if I can provide more information.

[blackswanny]

@escapedcat @SimeonC when I debugged, it seems like plugins config should be like this

module.exports = {
  plugins: ['example/dollar-sign']
}

so it looks for plugin as npm package by the name of commintlint-plugin-example/dollar-sign
If it's the only way to declare plugin, I wished we didn't need to create the whole npm package for that, as plugin config is simple set of a few rules. Yes, probably it is the same as eslint plugins, but here it might be overcomplicated.

[escapedcat]

@blackswanny you are right. This works:

plugins: ['example'],
rules: { 
  'dollar-sign': [2, 'never']
},

This doesn't match the docs though. @SimeonC let me know if this is correct. I'll update the docs accordingly.

@blackswanny regarding the need for something simple. I know what you mean. On the other hand this approach will create shareable plugins per default which is great for the community.

[SimeonC]

Yea, sorry that's my fault for copy+pasting the eslint markdown and not double checking. The rule definition is the same as in https://github.com/conventional-changelog/commitlint/blob/master/docs/reference-rules.md - I didn't change rule implementation for plugins, just added in allowing new rules to be loaded.

As for loading plugins - I think a relatively easy change would be to allow rules imports like; plugins: ['./commitlint-custom-plugins.js'] and load your plugin from a file directly. The change would be done here: pluginNaming.js#L58.

If you think that's a good way forward I can do a PR to add that change, or someone else can - not sure when I will next be free to do that myself so might be better to do it yourself if you want it soon 😉 .

I think eslint had a --rulesdir hack at one point but it seems that got removed when you could install local directories/npm link eslint-issue

[CrispyDrone]

Hi,

I'm experiencing some problems when trying to write my own plugin. It's also the first time I'm explicitly working with the Node platform, so I'm not sure whether it's related to my setup, or something with commitlint specifically.

Here you can find my custom plugin: https://github.com/CrispyDrone/commitlint-plugin-cleanfeet/blob/master/index.js

And here is the commitlint.config.js:

module.exports = {
	//parserPreset: 'conventional-changelog-conventionalcommits',
	plugins: ['cleanfeet'],
	rules: {
		'body-leading-blank': [1, 'always'],
		'footer-leading-blank': [1, 'always'],
		'header-max-length': [2, 'always', 50],
		'scope-case': [2, 'always', 'lower-case'],
		'subject-case': [
			2,
			'always',
			['sentence-case']
		],
		'subject-empty': [2, 'never'],
		'subject-full-stop': [2, 'never', '.'],
		'type-case': [2, 'always', 'lower-case'],
		'type-empty': [2, 'never'],
		'type-enum': [
			2,
			'always',
			[
				'chore',
				'docs',
				'feat',
				'fix',
				'refactor',
				'style',
				'test'
			]
		],
		'footer-format': [
			2, 
			'always', 
			[
				'^BREAKING CHANGE: .*',
				'^[a-zA-Z0-9-]+: .*',
				'^[a-zA-Z0-9-]+ #.*'
			]
		],
		'footer-max-occurrence-breaking-change': [2, 'always', 1]
	}
};

There are two issues with this configuration:

1. When I add parserPreset: 'conventional-changelog-conventionalcommits',, I receive the following error message:

Error: Cannot find module 'conventional-changelog-conventionalcommits'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:582:15)
    at resolveFileName (C:\Users\CrispyDrone\AppData\Roaming\npm\node_modules\@commitlint\cli\node_modules
\resolve-from\index.js:29:39)
    at resolveFrom (C:\Users\CrispyDrone\AppData\Roaming\npm\node_modules\@commitlint\cli\node_modules\res
olve-from\index.js:43:9)
    at module.exports (C:\Users\CrispyDrone\AppData\Roaming\npm\node_modules\@commitlint\cli\node_modules\
resolve-from\index.js:46:47)
    at Object.<anonymous> (C:\Users\CrispyDrone\AppData\Roaming\npm\node_modules\@commitlint\cli\node_modu
les\@commitlint\load\lib\index.js:54:54)

2. When I remove the parserPreset, the first plugin rule's function is being called, but the second one isn't due to an error being thrown:

C:\Users\CrispyDrone\AppData\Roaming\npm\node_modules\@commitlint\cli\lib\cli.js:119
        throw err;
        ^

TypeError: Invalid attempt to destructure non-iterable instance
    at C:\Users\CrispyDrone\AppData\Roaming\npm\node_modules\@commitlint\cli\node_modules\babel-runtime\he
lpers\slicedToArray.js:48:13
    at results.filter.map.entry (C:\Users\CrispyDrone\AppData\Roaming\npm\node_modules\@commitlint\cli\nod
e_modules\@commitlint\lint\lib\index.js:152:46)
    at Array.map (<anonymous>)
    at Object.<anonymous> (C:\Users\CrispyDrone\AppData\Roaming\npm\node_modules\@commitlint\cli\node_modu
les\@commitlint\lint\lib\index.js:131:7)
    at process._tickCallback (internal/process/next_tick.js:68:7)

Thank you for any assistance with this issue.

[byCedric]

@CrispyDrone We are currently working on some issues with the parser preset, you can see some progress here #830. As for now, be sure to use 8.2.0, not 8.3.0 or 8.3.1. For now I'm afraid the new conventional commit parser is not usable with commitlint until we resolve this PR #834.

Your issue without the parser preset seems to be related to an unexpected result from your rule. I totally agree that it could use some better error handling to inform you about this. Could you try using this in your plugin? It makes sure the rules are returning [true];, which means that it "passed successfully, without extra message".

module.exports = {
	rules: {
		"footer-format": function(parsed, when, value) {
			console.log('footer-format', { parsed, when, value });
			return [true];
		},
		"footer-max-occurrence-breaking-change": function(parsed, when, value) {
			console.log('footer-max-occurrence-breaking-change', { parsed, when, value });
			return [true];
		},
	},
};

[CrispyDrone]

Hi,

Thank you for your prompt reply! I adjusted the return values and it is working.

[CrispyDrone]

@byCedric
Hello,

It seems I'm still experiencing the same issue with the parser preset whenever I try to set: parserPreset: 'conventional-changelog-conventionalcommits'. Do I need to install something other than just:

npm install -g @commitlint/config-conventional @commitlint/cli

I've tried installing conventional-changelog-conventionalcommits as well but that doesn't solve anything. From the stacktrace it seems that @commitlint/load can't find this module, so is it possible there is something wrong with this package?

C:\Program Files\nodejs\node_modules\@commitlint\cli\lib\cli.js:119
        throw err;
        ^

Error: Cannot find module 'conventional-changelog-conventionalcommits'
    at Function.Module._resolveFilename (module.js:538:15)
    at resolveFileName (C:\Program Files\nodejs\node_modules\@commitlint\cli\node_modules\resolve-from\index.js:29:39)
    at resolveFrom (C:\Program Files\nodejs\node_modules\@commitlint\cli\node_modules\resolve-from\index.js:43:9)
    at module.exports (C:\Program Files\nodejs\node_modules\@commitlint\cli\node_modules\resolve-from\index.js:46:47)
    at Object.<anonymous> (C:\Program Files\nodejs\node_modules\@commitlint\cli\node_modules\@commitlint\load\lib\index.js:54:54)
    at <anonymous>

I'm currently on version 8.2.0 for @commitlint/cli and version v8.9.4 for node.

Thank you for any assistance.