Planemo is basically a static code analysis tool written for the Node.js platform. Its main goal is to read everything in given directory (and recursively downwards) and
checks any found file (no matter if its its .js, .css, .html or whatever) and its contents against a set of rules, configurable by the user.
The whole idea is that Planemo should help your project to maintain coding conventions, best practices and other fun rules your software project might have, for any source code file or language.
The [code on GitHub][30] should be regarded as unstable builds. We don't have any restrictions when and how things can be checked in there (within common sense though).
The [project on npm][28] should be regarded as the stable builds. We will only publish a new version to npm once we feel Planemo is stable and has any new end user value.
Continuous build status
Planemo is continuously built by Drone.io. You can find the build history here.
Downloading and running Planemo
Planemo runs on Node.js, so make sure you have that [installed][20]. If you want to contribute you need to have [Git installed][21] as well.
Via npm (preferred way for end users)
Since Planemo is [published on npm][28], you maybe simply type npm install planemo. This should download Planemo and all its dependencies.
To start Planemo you may simply type cd node_modules/planemo/ && node planemo <configuration file>.
Via git clone (preferred way for plugin developers)
You can clone the Git project directly by typing git clone git@github.com:corgrath/planemo-open-source-software-quality-platform.git.
After it you need to install the Node.js dependencies with npm install.
Now you should be able to start Planemo using a configuration file by using
the command node planemo <configuration file>
Download as a ZIP file (preferred way for people who really like ZIP files)
On the Planemo GitHub page there is a button on the page with the text "Download ZIP".
After it you need to install the Node.js dependencies with npm install.
Now you should be able to start Planemo using a [configuration file][23] by using the command node planemo <configuration file>
The configuration file
In order to launch Planemo you need to specify a JSON formatted configuration file as the first argument. The best way to describe it is to look at a sample file, and then
look at the property explanations below to better understand what and how the different parts works.
01: The source property is required to specify the starting directory which Planemo will start analyzing files in.
05: Verbose setting, meaning if you want Planemo to be verbose or not. Valid options are true or false. If you are using plugins that should show warnings instead of errors, having verbose to false is recommended.
06: Here the user can define a list of plugins that should be invoked during the code analysis
07: The plugin name which should be used during the analysis is specified as a property
08: The the value of the property is the options that should be sent to the plugin
Available plugins
You can enable what plugins you want Planemo to run by defining them in your configuration file.
Below is a list of all the current available plugins, a brief description of their individual options and an example.
check-directory-name-plugin
Checks a directory name.
pattern - A regular expression pattern which the directory name must comply with.
disallowPropertiesStartingWith - An array of Strings that properties should not start with
disallowValuesStartingWith - An object structure where the property is a regular expression of an HTML-property, and the value is the HTML-value should not start in a specific way.
Writing new plugins to Planemo is fairly easy. A plugin is a stand alone file that is located in the /plugins/ folder.
To get a better understanding of how a simple plugin looks like, lets look at an existing one. The check-directory-name-plugin.js plugin that has the responsibility to validate directory names:
01 /*
02 * Licensed under the Apache License, Version 2.0 (the "License");
03 * you may not use this file except in compliance with the License.
04 * You may obtain a copy of the License at
05 *
06 * http://www.apache.org/licenses/LICENSE-2.0
07 *
08 * Unless required by applicable law or agreed to in writing, software
09 * distributed under the License is distributed on an "AS IS" BASIS,
10 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 * See the License for the specific language governing permissions and
12 * limitations under the License.
13 *
14 * See the NOTICE file distributed with this work for additional
15 * information regarding copyright ownership.
16 */
17
18 /*
19 * Dependencies
20 */
21
22 var observerService = require( "../services/observer-service.js" );
23 var errorUtil = require( "../utils/error-util.js" );
24
25 /*
26 * Public functions
27 */
28
29 exports.init = function ( options ) {
30
31 observerService.onDirectoryFound( function checkDirectoryNameOnDirectoryFound ( basePath, fullPath, directoryName, responseFunction ) {
32 exports.onDirectoryFound( options, basePath, fullPath, directoryName, responseFunction );
33 } );
34
35 };
36
37 exports.onDirectoryFound = function onDirectoryFound ( options, basePath, fullPath, directoryName, responseFunction ) {
38
39 if ( !options ) {
40 throw errorUtil.create( "No options were defined." );
41 }
42
43 if ( !options.regexp ) {
44 throw errorUtil.create( "Invalid regexp option." );
45 }
46
47 if ( !options.regexp ) {
48 throw errorUtil.create( "Invalid regexp option." );
49 }
50
51 var pattern = new RegExp( options.regexp );
52
53 var isLegalFilename = pattern.test( directoryName );
54
55 if ( !isLegalFilename ) {
56
57 responseFunction( errorUtil.create( "The directory name \"" + directoryName + "\" is not valid.", {
58 basePath: basePath,
59 fullPath: fullPath,
60 directoryName: directoryName
61 } ) );
62
63 }
64
65 }
Row explanations:
01 - 16: This is the [Apache 2.0 license][29] information all source files needs to embed.
22 - 23: Module dependencies are declared here
29: Each Plugin needs to have a public exports.init function. The argument to the function will be the options the user has specified in the configuration file. The Plugin developer can come up with any (or no) options as they like. However, all options should be properly documented for other Planemo end users.
31: In this plugin we simply hook into a new function once a new directory found is found. A plugin can hook function into a wide range of hooks. In this plugin we are only interested in the onDirectoryFound hook.
37: This is the primary function that will be called each time Planemo finds a directory. Since we did a fancy closure hook on row 32, we now get both the user options (options) and the hook information details ( basePath, fullPath, directoryName) and a specific callback function (responseFunction) to our function. The reason why this function is public (meaning its declared on the export object like export.onDirectoryFound = ) is because we want to be able to unit test it later.
39-45: Basic validation to make sure that the options are as we expect them to be.
57: Since the plugin's responsibility is to check a directory name towards a regular expression, we also need to be able tell Planemo that this plugin has found a problem. This is simply done returning an Error as the first argument of the responseFunction.
Plugin and Data Collector hooks
Not yet written.
Running the tests
You can execute the tests by running npm test if you are running from a [Windows Command Prompt][27] or run_tests.bat is you are using a [Shell][26], such as Git Bash.
Planemo is currently using [Mocha][31] and [Chai][32] as a part of its test framework. If you are planning to write tests it would be a good idea to look at their individual
examples and documentation to better understand how to write new or maintain old tests. If you looking for examples you can find them in the /tests/ folder in this project.
Found a bug or have a questions?
If you have found a bug and want to report it, or have any other feedback or questions, you can simply [create an issue][23].
Planemo licensed under the Apache License, Version 2.0. See the NOTICE file distributed with this work for additional information regarding copyright ownership.
Planemo logotype images Copyright (C) Christoffer Pettersson, christoffer[at]christoffer[dot]me. All Rights Reserved! Please contact Christoffer regarding the possible use of these images.
