{"id":21417933,"url":"https://github.com/msg-systems/codingpolicyjs","last_synced_at":"2025-03-16T19:21:23.116Z","repository":{"id":57202576,"uuid":"51311943","full_name":"msg-systems/codingpolicyjs","owner":"msg-systems","description":"Coding Policy for JavaScript","archived":false,"fork":false,"pushed_at":"2023-10-26T03:52:47.000Z","size":54,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-15T23:57:11.193Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msg-systems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-08T17:02:28.000Z","updated_at":"2021-04-22T05:00:03.000Z","dependencies_parsed_at":"2022-09-15T13:21:02.027Z","dependency_job_id":null,"html_url":"https://github.com/msg-systems/codingpolicyjs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msg-systems%2Fcodingpolicyjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msg-systems%2Fcodingpolicyjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msg-systems%2Fcodingpolicyjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msg-systems%2Fcodingpolicyjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msg-systems","download_url":"https://codeload.github.com/msg-systems/codingpolicyjs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243918629,"owners_count":20368745,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T19:18:14.994Z","updated_at":"2025-03-16T19:21:23.092Z","avatar_url":"https://github.com/msg-systems.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# codingpolicyjs\n\nJavaScript coding policy engine for architectonical rules.\nThis module is available as node module, \u003ca href='#command-line-interface'\u003ecommand line interface\u003c/a\u003e and \u003ca href='#grunt-plugin'\u003egrunt plugin\u003c/a\u003e.\n\n\u003cp/\u003e\n\u003cimg src=\"https://nodei.co/npm/codingpolicyjs.png?downloads=true\u0026stars=true\" alt=\"\"/\u003e\n\n\u003cp/\u003e\n\u003cimg src=\"https://david-dm.org/msg-systems/codingpolicyjs.png\" alt=\"\"/\u003e\n\n## Modules purpose\n\nThis 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. \n\n## Command Line Interface\n\nThe cli of `codingpolicy` encapsules the node module. The tool has the following interface:\n\n```shell\ncodingpolicyjs: USAGE: codingpolicy [options] arguments\noptions:\n    -V, --version       Print tool version and exit.\n    -h, --help          Print this help and exit.\n    -v, --verbose       Print verbose processing information.\n    -r ARG, --root=ARG  Root directory for include files.\n```\n\n## Grunt Plugin\n\nThe grunt plugin requires Grunt `\u003e=0.4.0` and  encapsules the node module. \n\nIf you haven't used [Grunt](http://gruntjs.com/)\nbefore, be sure to check out the [Getting\nStarted](http://gruntjs.com/getting-started) guide, as it explains how\nto create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as\ninstall and use Grunt plugins. Once you're familiar with that process,\nyou may install this plugin with this command:\n\n```shell\nnpm install codingpolicyjs --save-dev\n```\n\nOnce the plugin has been installed, it may be enabled inside your\nGruntfile with this line of JavaScript:\n\n```js\ngrunt.loadNpmTasks('codingpolicyjs');\n```\n\n### codingpolicy Task\n\n_Run this task with the `grunt codingpolicy` command._\n\nThe tasks input is a file or directory directing to the initial `codingpolicy.yaml` file.\n\n### Task Options\n| Option | Default value | Description |\n| --- | --- | --- |\n| root | \".\" | Root directory for include files. |\n\n### Task Example\n\n```grunt\n    grunt.initConfig({\n        codingpolicy: {\n            \"all\": {\n                src: [\".\"],\n                options: {\n                    root: \"../../src/app\"\n                }\n            },\n            \"test\": {\n                src: [\"codingpolicyTest.yaml\"],\n                options: {\n                    root: \"../../src/test\"\n                }\n            }\n        }\n    });\n\n```\n\n## codingpolicy.yaml\n\nThe `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.\n\n### Importing other config files\n\nAn `import` for another `codingpolicy.yaml` config file is done within the `codingpolicy.yaml` using a collection within the `import` attribute. \n\nYou can `import` using \n- a glob pattern like `- **/rules*.yaml`. In this case a single file or a list of files can be imported.\n- a node module name `- codingpolicyjs`. In this case the import looks for a `codingpolicy.yaml` inside the node modules root.\n   \n### Register coding policy rules\n\nIn order to be able to use `rules` you have to register the concrete rule class within a `register` block in the config file\n\nThe `rules.yaml` file demonstrates the registration of a `rule`. The file location is always relative to the config file.\n\n```yaml\nregister:\n  RegExpRule: ./RegExpRule.js\n``` \n\n### Define coding policy rules\n\nConcrete coding policy rules can be defined within the `rules` block in the config file. The syntax is described as followed:\n\n```yaml\nrules:\n  \u003cruleName\u003e:\n    ruleText: \u003cruleText\u003e\n    fixText: \u003cfixText\u003e\n    rule: \u003cRuleAlias\u003e\n    options:\n      includeFiles: \u003cglobPattern\u003e\n\t  \u003cany\u003e: \u003cvalue\u003e\n```\n\nThe `\u003cruleName\u003e` must be unique. \nThe `\u003cruleText\u003e` will be displayed on coding policy execution. \nThe `\u003cfixText\u003e` will be displayed if a rule violation is found.\nThe `\u003cruleAlias\u003e` is the alias name of a registered `rule`.\nThe `options` will be handed over to any `rule`as first function argument. You can add `\u003cany\u003e` attribute to this block and will be able to access it in a concrete `rule`.\nThe `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`.  \n\n### Example codingpolicy.yaml\n\nThe 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`.\n\n```yaml\nimport:\n# use the glob pattern to import other config files\n- rules/rules.yaml\n# use a node module name to import that modules codingpolicy.yaml \n- codingpolicyjs\n\nrules:\n# define a new rule with the proper attributes and options\n  ConsoleLogRule:\n    ruleText: \"console.log usage\"\n    fixText: \"do not check 'console.log' in - it should not be committed into the master repo - please delete it before commit\"\n    rule: RegExpRule\n    options:\n# RegExpRule needs the desired regExp as option\n      regExp: '/^(.*console\\.log.*)$/mg'\n      includeFiles: \"*(bin|lib|tasks|rules)/**/*.js\"\n# define a new rule with the proper attributes and options\n  NoLooseEndsRule:\n    ruleText: \"unfinished business (TODO, FIXME etc.)\"\n    fixText: \"tie up the loose ends\"\n    rule: RegExpRule\n    options:\n      regExp: '/^(.*(?:FIXME|TODO).*)$/img'\n      includeFiles: \"*(bin|lib|tasks|rules)/**/*.js\"\n```\n\n### Example Rules \n\nFor 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`.\n\n## Rule interface\n\nThe coding policy is executing concrete `rules` according to the configuration file. A concrete `rule` must therefor match the proper signature to be executed correctly:\n\n```js\n    return function (options, tools) {\n\t\t\n\t\treturn findings\n\t}\n\n```\n\n### Rule options\n\nThe `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 \u003ca href='#command-line-interface'\u003ecommand line interface\u003c/a\u003e or the \u003ca href='#grunt-plugin'\u003egrunt plugin\u003c/a\u003e.\n\n### Rule tools\n\nThe `tools` are a predefined set of internal tools that help you handling your source code. \n\nYou will be able to work with the following tools:\n\n#### astJS\n\nThis 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.\n\n| Attribute | Type | Description |\n| --- | --- | --- |\n| `astq` | node module | Direct access to the `astq` node module for JavaScript AST queries |\n| `astToString` | `function (ast)` | Morphs an `ast` object into the corresponding source code using `escodegen` |\n| `findViolations` | `function (ast, file, query)` | Executes the given `query` on the `ast` and reports back an  \u003ca href='#finding-object'\u003e`finding object`\u003c/a\u003e pointing to the given `file` if the `query` returns results. |\n| `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. |\n| `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)`. |\n\n#### astTS\n\nThis 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.\n\n| Attribute | Type | Description |\n| --- | --- | --- |\n| `astq` | node module | Direct access to the `astq` node module for TypeScript AST queries |\n| `astToString` | `function (ast)` | Morphs an `ast` object into the corresponding source code using `ts-morph` |\n| `findViolations` | `function (ast, file, query)` | Executes the given `query` on the `ast` and reports back an  \u003ca href='#finding-object'\u003e`finding object`\u003c/a\u003e pointing to the given `file` if the `query` returns results. |\n| `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. |\n\n#### astHTML5\n\nThis 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.\n\n| Attribute | Type | Description |\n| --- | --- | --- |\n| `astq` | node module | Direct access to the `astq` node module for HTML5 AST queries |\n| `astToString` | `function (ast)` | Morphs an `ast` object into the corresponding source code using `parse5` |\n| `findViolations` | `function (ast, file, query)` | Executes the given `query` on the `ast` and reports back an  \u003ca href='#finding-object'\u003e`finding object`\u003c/a\u003e pointing to the given `file` if the `query` returns results. |\n| `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. |\n\n#### astStylesheet\n\nThis 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.\n\n| Attribute | Type | Description |\n| --- | --- | --- |\n| `astq` | node module | Direct access to the `astq` node module for Stylesheet AST queries |\n| `astToString` | `function (ast)` | Morphs an `ast` object into the corresponding source code using `gonzales-pe` |\n| `findViolations` | `function (ast, file, query)` | Executes the given `query` on the `ast` and reports back an  \u003ca href='#finding-object'\u003e`finding object`\u003c/a\u003e pointing to the given `file` if the `query` returns results. |\n| `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. |\n\n#### regExpFileScanner\n\nThis tool enables you to run RegExp matches on file contents.\n\n| Attribute | Type | Description |\n| --- | --- | --- |\n| `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` |\n\n## Finding objects\n\nA `finding object` is a simple object defining two attributes: `file` and `text`.\nThe `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`.\n\n### Example finding object\n```js\n{\n  file: \"bin\\codingpolicy.js\",\n  text: \"    console.log('foo');\"\n}\n```\n\n## Included rules\n\nWe already included a single `rule` named `RegExpRule` since it is often required and globally usable due to config settings.\n\n## RegExpRule\n\nThe `RegExpRule` is registered when you import `codingpolicyjs` as node module in your own `codingpolicy.yaml` file.\n\nIt's options enable you to define your `regExp` in the config file. The other options used by this `rule` are common for all `rules`\n\n- `root` - the root directory for all files\n- `includeFiles` - a list of files where the RegExp search should be applied to\n- `excludedFiles` - a list of files that can be excluded from the search","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsg-systems%2Fcodingpolicyjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsg-systems%2Fcodingpolicyjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsg-systems%2Fcodingpolicyjs/lists"}