https://github.com/msg-systems/codingpolicyjs
Coding Policy for JavaScript
https://github.com/msg-systems/codingpolicyjs
Last synced: 3 months ago
JSON representation
Coding Policy for JavaScript
- Host: GitHub
- URL: https://github.com/msg-systems/codingpolicyjs
- Owner: msg-systems
- License: mit
- Created: 2016-02-08T17:02:28.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2023-10-26T03:52:47.000Z (over 1 year ago)
- Last Synced: 2025-03-15T23:57:11.193Z (3 months ago)
- Language: JavaScript
- Homepage:
- Size: 52.7 KB
- Stars: 1
- Watchers: 5
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# codingpolicyjs
JavaScript coding policy engine for architectonical rules.
This module is available as node module, command line interface and grunt plugin.
## Modules purpose
This module is used for running architectonical rules against source code (ES5, ES6, HTML5, LESS). It is designed as a supporting tool for continous integration environments. The architectonical rules should check stuff beyond jshint, eslint and others.
## Command Line Interface
The cli of `codingpolicy` encapsules the node module. The tool has the following interface:
```shell
codingpolicyjs: USAGE: codingpolicy [options] arguments
options:
-V, --version Print tool version and exit.
-h, --help Print this help and exit.
-v, --verbose Print verbose processing information.
-r ARG, --root=ARG Root directory for include files.
```
## Grunt Plugin
The grunt plugin requires Grunt `>=0.4.0` and encapsules the node module.
If you haven't used [Grunt](http://gruntjs.com/)
before, be sure to check out the [Getting
Started](http://gruntjs.com/getting-started) guide, as it explains how
to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as
install and use Grunt plugins. Once you're familiar with that process,
you may install this plugin with this command:
```shell
npm install codingpolicyjs --save-dev
```
Once the plugin has been installed, it may be enabled inside your
Gruntfile with this line of JavaScript:
```js
grunt.loadNpmTasks('codingpolicyjs');
```
### codingpolicy Task
_Run this task with the `grunt codingpolicy` command._
The tasks input is a file or directory directing to the initial `codingpolicy.yaml` file.
### Task Options
| Option | Default value | Description |
| --- | --- | --- |
| root | "." | Root directory for include files. |
### Task Example
```grunt
grunt.initConfig({
codingpolicy: {
"all": {
src: ["."],
options: {
root: "../../src/app"
}
},
"test": {
src: ["codingpolicyTest.yaml"],
options: {
root: "../../src/test"
}
}
}
});
```
## codingpolicy.yaml
The `codingpolicy.yaml` file registers and defines the concrete `rules` for the policy check. Since a single `rule` might be used several times with different options we work with alias names for the concrete `rules`. In order to get the policy check work correctly the `rules` must be `registered` with its alias name. The module is enabled to support delegated rule configurations. The `codingpolicy.yaml` therefore is able to `import` other config files.
### Importing other config files
An `import` for another `codingpolicy.yaml` config file is done within the `codingpolicy.yaml` using a collection within the `import` attribute.
You can `import` using
- a glob pattern like `- **/rules*.yaml`. In this case a single file or a list of files can be imported.
- a node module name `- codingpolicyjs`. In this case the import looks for a `codingpolicy.yaml` inside the node modules root.
### Register coding policy rules
In order to be able to use `rules` you have to register the concrete rule class within a `register` block in the config file
The `rules.yaml` file demonstrates the registration of a `rule`. The file location is always relative to the config file.
```yaml
register:
RegExpRule: ./RegExpRule.js
```
### Define coding policy rules
Concrete coding policy rules can be defined within the `rules` block in the config file. The syntax is described as followed:
```yaml
rules:
:
ruleText:
fixText:
rule:
options:
includeFiles:
:
```
The `` must be unique.
The `` will be displayed on coding policy execution.
The `` will be displayed if a rule violation is found.
The `` is the alias name of a registered `rule`.
The `options` will be handed over to any `rule`as first function argument. You can add `` attribute to this block and will be able to access it in a concrete `rule`.
The `includeFiles` attribute inside the `options` is the a predefined attribute that will be handed to the concrete `rule` even if it is not set. Default value for `includeFiles` is `**/*.js`.
### Example codingpolicy.yaml
The following example imports a specific rule file with the given glob pattern and defines the copding policy rules in the stated order. The alias names for `RegExpRule` has been defined in the imported `rules.yaml`.
```yaml
import:
# use the glob pattern to import other config files
- rules/rules.yaml
# use a node module name to import that modules codingpolicy.yaml
- codingpolicyjs
rules:
# define a new rule with the proper attributes and options
ConsoleLogRule:
ruleText: "console.log usage"
fixText: "do not check 'console.log' in - it should not be committed into the master repo - please delete it before commit"
rule: RegExpRule
options:
# RegExpRule needs the desired regExp as option
regExp: '/^(.*console\.log.*)$/mg'
includeFiles: "*(bin|lib|tasks|rules)/**/*.js"
# define a new rule with the proper attributes and options
NoLooseEndsRule:
ruleText: "unfinished business (TODO, FIXME etc.)"
fixText: "tie up the loose ends"
rule: RegExpRule
options:
regExp: '/^(.*(?:FIXME|TODO).*)$/img'
includeFiles: "*(bin|lib|tasks|rules)/**/*.js"
```
### Example Rules
For testing the different adapter (for JS, TS, HTML) there are some test rules. You can find them under test/testRules. The tests are included in the condingpolicyTest.yaml. To execute the test rules open a Command Line Interface and enter `npm run test`.
## Rule interface
The coding policy is executing concrete `rules` according to the configuration file. A concrete `rule` must therefor match the proper signature to be executed correctly:
```js
return function (options, tools) {
return findings
}
```
### Rule options
The `options` are taken from the `condingpolicy.yaml` as stated above. You can access any `options` from the config file as you defined it. Beside the `includeFiles` you will also be able to access the `root` attribute that is handed over to the concrete `rule`. The `root` attribute is coming either from the command line interface or the grunt plugin.
### Rule tools
The `tools` are a predefined set of internal tools that help you handling your source code.
You will be able to work with the following tools:
#### astJS
This tool encapsules `Esprima` and `astq`. `Esprima` is used for reading JavaScript source code files into an AST (abstract syntax tree). `astq` is used for queries on JavaScript ast objects.
| Attribute | Type | Description |
| --- | --- | --- |
| `astq` | node module | Direct access to the `astq` node module for JavaScript AST queries |
| `astToString` | `function (ast)` | Morphs an `ast` object into the corresponding source code using `escodegen` |
| `findViolations` | `function (ast, file, query)` | Executes the given `query` on the `ast` and reports back an `finding object` pointing to the given `file` if the `query` returns results. |
| `findAstList` | `function (root, clazzRegexp, excludedFiles)` | This function reads a list of files using the `root` value, `classRegexp` pattern and `excludedFiles` list. Each file will be transformed into an ast. |
| `findAndLoopAstList` | `function (root, clazzRegexp, excludedFiles, callback)` | This function loops through a list of files using the `root` value, `classRegexp` pattern and `excludedFiles` list. Each file will be transformed into an ast and will be handed back to the `callback` method. The `callback` method has the signature `function (ast, file)`. |
#### astTS
This tool encapsules `ts-morph` and `astq`. `ts-morph` is used for reading TypeScript source code files into an AST (abstract syntax tree). `astq` is used for queries on TypeScript ast objects.
| Attribute | Type | Description |
| --- | --- | --- |
| `astq` | node module | Direct access to the `astq` node module for TypeScript AST queries |
| `astToString` | `function (ast)` | Morphs an `ast` object into the corresponding source code using `ts-morph` |
| `findViolations` | `function (ast, file, query)` | Executes the given `query` on the `ast` and reports back an `finding object` pointing to the given `file` if the `query` returns results. |
| `findAstList` | `function (root, clazzRegexp, excludedFiles)` | This function reads a list of files using the `root` value, `classRegexp` pattern and `excludedFiles` list. Each file will be transformed into an ast. |
#### astHTML5
This tool encapsules `parse5` and `astq`. `parse5` is used for reading HTML5 source files into an AST. `astq` is used for queries on HTML5 ast objects.
| Attribute | Type | Description |
| --- | --- | --- |
| `astq` | node module | Direct access to the `astq` node module for HTML5 AST queries |
| `astToString` | `function (ast)` | Morphs an `ast` object into the corresponding source code using `parse5` |
| `findViolations` | `function (ast, file, query)` | Executes the given `query` on the `ast` and reports back an `finding object` pointing to the given `file` if the `query` returns results. |
| `findAstList` | `function (root, clazzRegexp, excludedFiles)` | This function reads a list of files using the `root` value, `classRegexp` pattern and `excludedFiles` list. Each file will be transformed into an ast. |
#### astStylesheet
This tool encapsules `gonzales-pe` and `astq`. `gonzales-pe` is used for reading Stylesheet (CSS/LESS/SASS/SCSS) source files into an AST. `astq` is used for queries on Stylesheet ast objects.
| Attribute | Type | Description |
| --- | --- | --- |
| `astq` | node module | Direct access to the `astq` node module for Stylesheet AST queries |
| `astToString` | `function (ast)` | Morphs an `ast` object into the corresponding source code using `gonzales-pe` |
| `findViolations` | `function (ast, file, query)` | Executes the given `query` on the `ast` and reports back an `finding object` pointing to the given `file` if the `query` returns results. |
| `findAstList` | `function (options)` | This function reads a list of files with the given `syntax` (options.syntax, which can be CSS, LESS, SASS or SCSS) using the `root` (options.root) value, `classRegexp` (options.classRegexp) pattern and `excludedFiles` (options.excludedFiles) list. Each file will be transformed into an ast. |
#### regExpFileScanner
This tool enables you to run RegExp matches on file contents.
| Attribute | Type | Description |
| --- | --- | --- |
| `scan` | `function (root, clazzRegexp, excludedFiles, searchRegexp)` | This function loops through a list of files using the `root` value, `classRegexp` pattern and `excludedFiles` list. All matches for the given `searchRegexp` will be transformed into a `finding object` |
## Finding objects
A `finding object` is a simple object defining two attributes: `file` and `text`.
The `file` is the file name where a violation was found. The `text` is the display text for the violation and should in most cases be the extract of the source code that violates against the `rule`.
### Example finding object
```js
{
file: "bin\codingpolicy.js",
text: " console.log('foo');"
}
```
## Included rules
We already included a single `rule` named `RegExpRule` since it is often required and globally usable due to config settings.
## RegExpRule
The `RegExpRule` is registered when you import `codingpolicyjs` as node module in your own `codingpolicy.yaml` file.
It's options enable you to define your `regExp` in the config file. The other options used by this `rule` are common for all `rules`
- `root` - the root directory for all files
- `includeFiles` - a list of files where the RegExp search should be applied to
- `excludedFiles` - a list of files that can be excluded from the search