# grunt-notify-offenses

> Searches through a list of files and notifies on all declarative offenses.

Latest version **0.1.1** (published 2013-12-06) · 0 weekly downloads

## Install

```sh
npm install grunt-notify-offenses
pnpm add grunt-notify-offenses
yarn add grunt-notify-offenses
bun add grunt-notify-offenses
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2013-12-06 |
| First published | 2013-12-06 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.8.0 |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Christian Monsegue |
| Maintainers | christianmonsegue |
| Keywords | notify-offenses |

## Links

- npm: https://www.npmjs.com/package/grunt-notify-offenses
- Repository: https://github.com/kinnser/gruntplugins
- Issues: https://github.com/kinnser/gruntplugins/issues
- npm.io page: https://npm.io/package/grunt-notify-offenses

## Recent versions

- 0.1.1 (latest) — 2013-12-06

## README

# grunt-notify-offenses

> Searches through a list of files and notifies on all declarative offenses.

![Running with user-defined offenses](images/title-screenshot.jpg) 

## Getting Started
This plugin requires Grunt `~0.4.1`

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, follow the instructions below to install the plugin:

Pull down the plugins from the repository into your current working directory:

```shell
git clone git@github.com:kinnser/gruntplugins.git
```

...or download the ZIP file from [Kinnser Grunt Plugins Repo](https://github.com/kinnser/gruntplugins).

Move the grunt-notify-offenses folder into the node_modules folder that resides in the same directory of your Gruntfile.

The grunt-notify-offenses plugin may be enabled inside your Gruntfile with this line of JavaScript:

```js
grunt.loadNpmTasks('grunt-notify-offenses');
```

## The "notify_offenses" task

### Overview
In your project's Gruntfile, add an object named `notify_offenses` to the data object passed into `grunt.initConfig()`. Inside `notify_offenses`, be sure to create another defined obejct to hold a specified notify offenses run.

```js
grunt.initConfig({
  notify_offenses: {
    [NAME OF SPECIFIED RUN]: {
      options: {
        // Task-specific options go here.
      },
      files: {
        // Target-specific file lists and/or options go here.
      }
    }
  }
})
```

## Options

#### save
Type: `Boolean` _optional_
Default value: `false`

Determines if the output should be sent to both standard output **and** an output file. If set to `true`, then the result will be printed in the terminal and also be written into a new file specified in the files property.

_____________________________
###Finder Options

#### override
Type: `Boolean` _optional_
Default value: `false`

Determines if the user-defined offenses will override the pre-defined offenses given that their types are equivalent, regardless of case. For example, if the type of a user-defined offense is "Style", and the override option is set to `true`, then the pre-defined "Style" offense will be overridden. Keep in mind that overriding will **ONLY** work if the user-defined offense has both a type **and** a valid pattern, else it will fall back to the pre-defined offense of the same type.

If **override** is set to `false`, then the pre-defined offenses will have priority.

#### force
Type: `Boolean` _optional_
Default value: `true`

Determines if the pre-defined offenses are also evaluated along with the user-defined offenses. If set to `true`, the pre-defined offenses are also considered in the search along with the user-defined offenses, else they are not when set to `false`. The option **force** is implied to be `true` if the user-defined offenses are undefined.

#### offenses
Type: `Object Literal` _optional_
Default value: `{}`

Contains each user-defined offense. The key of each entry is the offense type and the value is another object literal that contains a `String` message and an `Array` pattern. The pattern itself should have the regular expression at the first index, and at every subsequent index is a regex modifier.

```js
  notify_offenses: {
    options: {
      offenses: {
        'type': {
          message: 'message',
          pattern: ['pattern', 'modifier 1',...,'modifier n'],
          extentions: ['extension 1',....,'extension n']
        }
      }
    }
  }
```
#####User-Defined Offense Options

######Type
Type: `String` **required**

The type is case-insensitive, so 'Style' and 'STYLE' are considered the same type.

######Message
Type: `String` _optional_

The message **must** be a `String` value, else it will default to a string consisting of a single '\s' character.

######Pattern
Type: `Array` _optional_

> **pattern: ['regex pattern', 'regex modifier 1',.....,'regex modifier n']**

The pattern uses the regexp function, so special characters **must** be double escaped. The only exceptions are single and double quotes, which can be single escaped and handled. The regex modifiers supported so far are:

* `global` Searches for _all_ matches of the pattern rather than the first match found. Can be entered as *global* or *g*.
* `case-insensitive`  Searches for a match of the pattern regardless of the alphabetical case. Can be entered as *case-insensitive* or *i*.

**All** entries in the pattern array **MUST** be a `String`.

######Extensions
Type: `Array` _optional_

> **extensions: ['extension 1',......,'extension n']**

The extensions array uses the user-defined `String` extensions to compare to the extension of each file being processed, and if there is a match, the operation will continue. This is used to filter out files where certain offenses do not pertain to. An empty or undefined **extensions** would default to the plugin searching **ALL** of the list of files to process for the offense.

**All** entries in the extensions array **MUST** be a `String` and should **NOT** include the '\.' character of the file extension.

#####List of Pre-Defined Offenses

* `'STYLE'` Searches for inline _style_ offenses in a file. This search is _case-insensitive_ and _global_ and only searches through \*.html and \*.cfm files.
> **align='center'**

    ...as an attribute in a HTML tag is an offense.

* `'ALIGN'` Searches for inline _align_ offenses in a file. This search is _case-insensitive_ and _global_ and only searches through \*.html and \*.cfm files.
> **style='color: green;'**

    ...as an attribute in an HTML tag is an offense.

* `'JAVASCRIPT'` Searches for inline _javascript_ offenses in a file. This search is _case-insensitive_ and _global_ and only searches through \*.html and \*.cfm files.
> **onclick='someFunction()'**

    ...as an attribute in an HTML tag is an offense.

* `'CONSOLE LOG'` Searches for _console\.log_ offenses in a file. This search is _case-insensitive_ and _global_ and only searches through \*.js files.
> **console.log('Message');**

    ...is an offense.


_____________________________
###Assembler Options

#### tabwidth
Type: `Number` _optional_
Default value: `4`

Removes all tab characters at the beginning of each line from the file input and replace them with a new tabwidth, normalizing the data. It is highly recommended to equate the tabwidth to the tabwidth rule of jshint for full accuracy of the column numbers.

_____________________________
###Reporter Options

#### stout
Type: `String` _optional_
Default value: `'plaintext'`

Determines how the output will be printed through standard output.

* `'plaintext'` Outputs the results in a plaintext UTF-8 format.
* `'decoratedplaintext'` Outputs the results in a plaintext format with color and emphasis on key details.
* `'minimalxml'` Outputs the results in a very basic XML format.
* `'json'` Outputs the results in a JSON format that follows the ECMA5 standard.

#### output
Type: `String` _optional_
Default value: `'plaintext'`

Determines how the output will be written to an output file.

* `'plaintext'` Outputs the results in a plaintext UTF-8 format.
* `'decoratedplaintext'` Outputs the results in a plaintext format with color and emphasis on key details.
* `'minimalxml'` Outputs the results in a very basic XML format.
* `'json'` Outputs the results in a JSON format that follows the ECMA5 standard.

#### cleaner
Type: `String` _optional_
Default value: `'none'`

Cleans each line of the output file(s) of whitespaces based on a given option:

* `'none'` Does not clean each line.
* `'trailing'` Cleans each line of all whitespace at the beginning and end of the line.
* `'all-tabs'` Cleans each line of all '\t' whitespace.
* `'all-spaces'` Cleans each line of all '\s' whitespace.
* `'all'` Cleans each line of _all_ whitespace.

## Usage Examples

### Default Options
In this example, the default options are used to look for offenses in a set of files. So with `'tmp/example-default-result'` as my destination and `'test/fixtures/inline-1.html'` as my source, the plugin does the following:

* Takes in the source file's filepath and data.
* Rearranges all tab characters at the front of each line to a **tabwidth** of `4`.
* Searches through the pre-defined list of offenses for any offending columns. Since no **offenses** were defined by the user and **override** is set to `false` and **force** is set to `true`, then the pre-defined offenses will all be checked and not overriden. Additonally, the plugin will search for offenses in **ALL** files since **extensions** was no defined.
* The **cleaner** defaults to `'none'`, so it does not clean the lines of the output of any whitespace and keeps the default formatting.
* Outputs the offending data to the standard output (**stout**) in `'plaintext'` format. Since **save** is set to `false`, the offending data will not be considered to be written to an output file and the **output** option and the destination is ignored.

```js
grunt.initConfig({
  notify_offenses: {
    default_options: {
      options: {
        save: false,
        stout: 'plaintext',
        output: 'plaintext',
        override: false,
        offenses : {},
        force: true,
        tabwidth: 4,
        cleaner: 'none'
      },
      files: {
        'tmp/example-default-result': ['test/fixtures/inline-1.html']
      }
    }
  }
});
```

![Running default_options example](images/default-options-screenshot.jpg)

### Only User-Defined Offenses From \*.html Files Written to File in XML Format
In this example, the user only wants their defined offenses to be considered and then have the output written to a file. So with `'tmp/example-user-result'` as my destination and `'test/fixtures/inline-1.html'` as my source, the plugin does the following:

* Takes in the source file's filepath and data.
* Searches through the user-defined offenses first since there are defined **offenses** by the user. Since **extensions** is defined in **offenses** and has an extension `html`, then **ONLY** \*.html files will be searched.
* Since **override** is set to `true` and **force** is set to `false`, then not only would the pre-defined offenses be overriden, but they will also not be checked (_Note: the exception is that if there is a user-defined offense that only has a type name and nothing else, then it will default to the matching type in the pre-defined offenses if it exists_). In this case, as "Style" exists as a pre-defined offense, then the pre-defined "Style" will be overriden and the user-defined offense will take its place in the results.
* Outputs the offending data to the standard output in the default `'plaintext'` format. Since **save** is set to `true` and **output** is set to `'minimalxml'`, the offending data will be written to the `'tmp/example-user-result'` file (the file will be created if it does not exist) in the XML format.

```js
grunt.initConfig({
  notify_offenses: {
    only_user_to_xml: {
      options: {
        save: true,
        output: 'minimalxml',
        override: true,
        offenses : {
          'Style': {
            message: 'Style is overriden and now looks for the "img src=\'\'" attribute with flags global and case-insentive in extension .html',
            pattern: ['img[\\s\\t]*src[\\s\\t]*\\=[\\s\\t]*(\'|\")', 'global', 'i'],
            extensions: ['html']
          },
          "erroneous": {
            message: 'Searches for the user-defined offense "erroneous" with flags global and case-insentive in extensions .html',
            pattern: ['erroneous[\\s\\t]*=[\\s\\t]*(\"|\')[\\s\\ta-z0-9\\-\\:\\;{}\\/\\(\\)\\+\\=\\&\\%\\#\\@\\!\\,\\$_\"\']*(\"|\')', 'g', 'i'],
            extensions: ['html']
          }
        },
        force: false
      },
      files: {
        'tmp/example-user-result': ['test/fixtures/inline-1.html']
      }
    }
  }
});
```

![Running only_user_to_xml example](images/only-user-to-xml-screenshot.jpg)

![Output File of only-user-to-xml example](images/xml-output-screenshot.jpg)

### Only Offense Type Subset to Standard Output in JSON
In the _Offense Type Subset_ configuration, the plugin will **only** search for matching types between the pre-defined and user-defined offenses, given that **offenses** is not empty and consists of only matching types. The pattern used is determined by if the user-defined offense is fully defined or not. So with `'tmp/example-subset-result'` as my destination and `'test/fixtures/inline-1.html'` as my source, the plugin does the following:

* Takes in the source file's filepath and data.
* Searches through the user-defined offenses first since there are defined **offenses** by the user. Additonally, the plugin will search for offenses in **ALL** files since **extensions** was no defined.
* Since **override** is set to `true` and **force** is set to `false`, then not only would the pre-defined offenses be overriden, but they will also not be checked. _However_, an exception applies here where the user-defined offenses has matching types to the pre-defined offenses. Two seperate cases happens in this particular example:
    * The "Style" user-defined offense has no defined pattern, so the plugin searches for the matching type in the pre-defined offenses and uses corresponding pattern from that type.
    * The "ALIGN" user-defined offense is fully defined, so the plugin overrides the matching type in the pre-defined offenses.
* Outputs the offending data to the standard output (**stout**) in `'json'` format. Since **save** is not defined and thus is defaultly set to `false`, the offending data will not be considered to be written to an output file and the destination is ignored.

```js
grunt.initConfig({
  notify_offenses: {
    type_subset_to_json: {
      options: {
        stout: 'json',
        override: true,
        offenses : {
          'Style': [],
          'ALIGN': {
            message: 'New ALIGN Message showing that ALIGN is overriden.',
            pattern: ['align[\\s\\t]*=[\\s\\t]*(\'|\")', 'g', 'i']
          }
        },
        force: false
      },
      files: {
        'tmp/example-subset-result': ['test/fixtures/inline-1.html']
      }
    }
  }
});
```

![Running type_subset_to_json example](images/type-subset-to-json-screenshot.jpg)

##In Progress and Consideration
All items of this list are ordered by greatest importance to least importance.

1. Right now the searches are on a per-line basis. So if a declaration with an offense extends to another line using a newline feed and splits the offense, then that offense may not be detected. Therefore, I am in the progress of making the search occur in reasonable chunks rather than by lines.

2. Robust error checking to degrade gracefully.

3. Developing the API for the parsers so that users can define their own parsers.

4. The addition of more useful pre-defined offenses.

5. The addition of more output formats.

6. Allowing users more control in the order of their output.


## Release History
* **0.1.01**  -  13 November 2013  - Added some support for user-defined parsers.
* **0.1.00**  -  11 November 2013  - First version **alpha** phase, although arguably it is incredibly messy right now.

---
_Source: https://npm.io/package/grunt-notify-offenses · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
