technical-validation

Tool for the technical validation of custom code that extends the Alfresco open source document management system. In other words it's an automated AMP file checker (both repo AMPs and Share AMPs).

Important note: this tool is a beta, and has issues including:

• Criteria that require manual followup
• Criteria that are not yet checked at all
• False positives
• False negatives
• Ugly output
• Confusing output

That said, in experienced hands it can greatly expedite the process of technically validating an Alfresco extension, by pinpointing potentially problematic areas of the code for further manual investigation.

Dependencies

1. Java 1.7+
2. neo4j 2.0+
3. Ohcount (optional - without it some statistics will be missing from the reports generated by the tool)

Notes:

• these dependencies should be installed via your OS package manager, where possible. On Mac OSX, I strongly recommend Homebrew.
• On Windows, do not use the Neo4J executable installer as it is seemingly impossible to configure. The zip distribution is a better choice.

Configuration

Ensure "auto indexing" is enabled in Neo4J for the properties "name", "package" and "typename". These are set in the neo4j.properties file, as follows:

node_auto_indexing=true
node_keys_indexable=name,package,typename

As of Neo4J v2.2, you also need to disable security for the server. This is specified in the neo4j-server.properties file, as follows:

dbms.security.auth_enabled=false

Installation

Download the latest release and unzip the zip file somewhere convenient.

Running / usage

$ ./atv -h
 ---------------------------+-------------------------------+--------------------------------------------------------
  Parameter                 | Default Value                 | Description
 ---------------------------+-------------------------------+--------------------------------------------------------
  -s, --source SOURCE                                        Source folder (mandatory)
  -b, --binaries BINARIES                                    Binary folder or archive (mandatory)
  -n, --neo4j-url NEO4J_URL  http://localhost:7474/db/data/  URL of the Neo4J server to use (optional - see default)
  -w, --word-file FILE_NAME                                  Produce output as a Word document in the specified file
  -e, --edn-file FILE_NAME                                   Produce EDN output in the specified file
  -j, --json-file FILE_NAME                                  Produce JSON output in the specified file
  -h, --help                                                 This message
  At least one of -w, -e, or -j must be provided.
 ---------------------------+-------------------------------+--------------------------------------------------------
$

or on Windows:

C:\atv> atv -h
 ---------------------------+-------------------------------+--------------------------------------------------------
  Parameter                 | Default Value                 | Description
 ---------------------------+-------------------------------+--------------------------------------------------------
  -s, --source SOURCE                                        Source folder (mandatory)
  -b, --binaries BINARIES                                    Binary folder or archive (mandatory)
  -n, --neo4j-url NEO4J_URL  http://localhost:7474/db/data/  URL of the Neo4J server to use (optional - see default)
  -w, --word-file FILE_NAME                                  Produce output as a Word document in the specified file
  -e, --edn-file FILE_NAME                                   Produce EDN output in the specified file
  -j, --json-file FILE_NAME                                  Produce JSON output in the specified file
  -h, --help                                                 This message
  At least one of -w, -e, or -j must be provided.
 ---------------------------+-------------------------------+--------------------------------------------------------
C:\atv>

The tool will write a lot of data to the Neo4J database specified in the command line parameters - it is strongly recommended that that database be empty prior to each run of the tool (see resources/cleanNeo4j.sh). It will also write the report file(s) to disk. Other than that it will not modify anything else on the machine its run on (most especially the source code or binaries of your extension - they are only read).

Programmatic Access to the Tool

If you wish to use the tool as a library, it's available as a Maven artifact from Clojars:

The library's functionality is provided in the alfresco-technical-validation.core namespace, specifically this function:

user=> (require '[alfresco-technical-validation.core :as atv])
nil
user=> (doc atv/validate)
-------------------------
alfresco-technical-validation.core/validate
([source binaries neo4j-url] [source binaries neo4j-url status-fn] [indexes status-fn])
  Validates the given source and binaries, using the neo4j database as a working area.
  The result is a list of maps, with each map representing the result of validating a single criteria.
nil

Please note that during the beta period the data structure returned by this function is subject to change from version to version.

As of v0.4.0, preliminary Java access has been added to the tool - please see this worked example for details.

Developer Information

Build Instructions

Leinengen is a build tool for Clojure that makes it easy to set up a development environment. It can output Maven POMs.

The lein-bin plugin for leinengen makes it easy to build an executable that contains all dependencies. If you do not install the module, you can still build uberjars that (./lein uberjar) only need Java to run.

On Linux:

• git clone https://github.com/AlfrescoLabs/technical-validation
• cd technical-validation
• wget https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein
• chmod u+x lein
• ./lein
• ./lein plugin install lein-bin
• echo "{:user {:plugins [[lein-bin "0.3.4"]]}}" >> ~/.lein/profiles.clj
• ./lein bin

On Windows:

• Download the lein.bat file from https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein.bat

• Add the path where lein.bat is downloaded to the end of PATH env variable.

• Set JAVA_CMD env variable to the path of your JDK java executable (e.g. JAVA_CMD="C:\Program Files\Java\jdk1.8.0_60\bin\java.exe")

• Open Windows Power Shell and run "lein self-install" command. This command should create a jar file in $USER_HOME.lein\self-installs dir($USER_HOME is your home directory on windows)

• In the $USER_HOME\.lein create a profiles.clj file and add {:user {:plugins [[lein-bin "0.3.4"]]}} in the file. If you already have this file add lein-bin "0.3.4" as a plugin. This plugin helps to make the jar file an executable one.

   ex: {:user {:plugins [[lein-difftest "1.3.8"]
                 [lein-bin "0.3.4"] ]}}
  

• In powershell, go to the dir where you have downloaded the technical-validation project and run "lein bin" (project.clj file should be present in the path). This should create a atv file in the target directory.

• Copy the resulting atv file to the same location where you have atv.cmd file and execute atv from the command line.

Step by step instructions on how to set up, configure and runn ATV on Windows [is here] (https://github.com/AlfrescoLabs/technical-validation/blob/master/setup_run_steps_windows.md)

Architecture

• Most checks of Java code are done by using ASM to analyze the object files.
• The ASM output is loaded in to a Neo4J database. (See pmonks/depends)
• The checks of JavaScript need to be done on source code.
• Source code checks are done with regular expressions in memory. (See source_indexes.clj)

GitHub project

Bug Tracker

License

Copyright © 2013,2014,2015 Peter Monks (pmonks@gmail.com)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of an unsupported extension to Alfresco.