@beast-oe/appjson v1.0.0-beta.1

Beast Application.JSON Checker

OpenEdge dependency manager application.json checker.

This application provides a generic functionality to check if an application.json file is valid or not.

Also, this application provides a CLI interface to run the checker in a folder where an application.json file is located. Run: beast-check

Project file specifications

To be able to develop correctly an OpenEdge project that uses dependencies installed through the Beast Repository (beast) system, a specification for the file that defines what is needed, as well as what is the name, version and description of the project is required.

The name of the standard file has to be: application.json

The file must be a vaild JSON file.

Content

• Top
• Content
• File definition
  • name *
  • version *
  • private
  • description
  • keywords
  • author
  • contributors
  • license
  • bugs
  • repository
  • homepage
  • dependencies
  • devDependencies
  • openEdgeVersion
  • scripts
  • propath

File definition

The file definition should contain the elements described below. Some of these elements are required, like the name and the version, while others are optional, like description, author, contributors etc. Each element will provide additional information.

To denote which elements are required and which aren't, an asterisk (*) was added at the end of the title line.

name : String *

The name of the project is one of the two most important elements of the project definition. Together with version it forms an unique pair that identifies your project in the repository.

The name should only contain:

• alphanumeric characters
• at sign (@)
• slash (/)
• underscore (_)
• dash (-)
• dot (.)

Restrictions:

• it should start with @ or an alphanumeric character
• after @ the name of the team/organization should be used
• the name of the organization should be at least 3 characters long
• the slash is allowed only to separate the name of the organization from the name of the package
• the name of the package should be at least 2 characters long

Example: @wayfare/fast-query, fastquery-public

version : String *

The version of the project is the second most important elements of the project definition. Together with name it forms an unique pair that identifies your project in the repository. So, when you update something in your code, you should update the version of the project.

The version of the project must follow the semver specification.

Example: 1.2.3, 30.1.1-alpha.3

private : Boolean

Denotes if the project can be published or not. If this is set to true, the CLI application will throw an error when you try to publish it.

description : String

In the description field you should write some information about your project, like what is its purpose, what it provieds etc.

Example: This package provieds a way to build dynamic queries fast.

keywords : String/Array\<String>

The role of the keywords is to enable the project repository to easily identify the project when a developer wants to search for a solution for his problem. Also, when some looks over a project, the keywords may be used to suggest additional projects that can help him or offer a better sollution.

Example: query, dynamic query, temp-tables, query builder

author : String/Object\<String,String>

The main author of the application. It can be a company, a team, an individiual etc. For this element you can fill the information in 2 ways:

• an object with the following structure:

• a string (shortend version of the object one: "Name \<email>"

The role of the author element is to provide the developer who will use your project with a way to contact you when they enconter issues or need assistance.

Example:

Object version:

String version: "Wayfare \development@wayfare.ro\"

contributors : Array\<String/Object\<String,String>>

The contributors element holds an array of elements similar to the author element. Its role is to show a list of people, teams, companies that contributed with something to the project, like development, testing, documentation etc.

For this element you can fill the information in 2 ways:

• an object with the following structure:

• a string (shortend version of the object one: "Name \<email> (https://company.com)"

Example:

license : String

Any project that you develop should be protected by a license agreement: either a open-source one or a closed-source one. In this element you can specify either a SPDX Identifier license or provide one in a license file and specify here the name of the file, using the following template: "SEE LICENSE IN \<filename>".

Example: BSD-3-Clause, (ISC OR GPL-3.0), SEE LICENSE IN License.md

bugs : String

This should store a link to the location of the bug/issue tracking system used for this project.

Example: https://something.atlassian.com/, https://github.com/someTeam/someProject/issues

repository : String

This should store a link to the location where the code repository used for this project is. It can be a git link, svn link, cvs link etc.

Example: https://github.com/someTeam/someProject.git

homepage : String

This should store a link to the home page of the project. This page should contain more information about the project, link to various versions or change version notes etc.

Example: https://wayfare.ro

dependencies : Object\<String,String>

The dependencies element is used to define which packages are required by your project to be able to work properly.

A dependency is a source or a collection of sources, grouped under a package, that provide some functionality.

The dependencies elements holds a dictionary/map with the name of the package you need and either one of the following: version string, that follows the semver specification; URL to a tarball; URL to a git repository or path to a local folder.

For more on version specification please have a look at this document.

• version Must match version exactly
• >version Must be greater than version
• >=version etc
• <version
• <=version
• ~version Approximately equivalent to version
• \^version Compatible with version
• 1.2.x 1.2.0, 1.2.1, etc., but not 1.3.0
• http://... See URLs as Dependencies below
• * Matches any version
• "" (An empty string). Same as *
• version1 - version2 Same as >=version1 <=version2.
• range1 || range2 Passes if either range1 or range2 are satisfied.
• git... See Git URLs as Dependencies below
• path See Local Paths below

Example:

URLs as Dependencies

You may specify a tarball URL in place of a version range. This tarball will be downloaded and installed locally to your package at install time.

Git URLs as Dependencies

Git urls are of the form:

\<protocol> is one of git, git+ssh, git+http, git+https, or git+file.

Example: git+https://oerepo@github.com/oerepo/docs.git

Local Paths

To use a local path, you should use the following form:

\<path> can be either a relative path or an absolute path.

This feature is helpful when you are developing offline, creating test or developing multiple projects locally and they are interdependent, but should not be used when publishing packages to the public registry.

Example:

• file:/var/www/application/test
• file:../tests

devDependencies : Object\<String,String>

The devDependencies element is similar to the dependencies element. The only difference between these two is the fact that the devDependencies is used to list all dependencies needed only in the development environment. They won't be installed in the production environment.

Use this element for dependencies that help you speed the development of the application, like unit testing framework, database designer, business entity designer etc.

openEdgeVersion : String/Array\<String>

If the project you are developing can run only on legacy versions of OpenEdge or you are using features introduced in the latest versions of OpenEdge, then you should fill the openEdgeVersion element with the correct version string. You can provide the versions for which the project runs using one of the following constructions:

• An array with versions that can be used: "11.3", "11.3.2", "11.4"
• An array with versions that have constraints on them: ">11.3", "<=11.6.3"
• A string denoting a specific version: "11.3.0"
• A string denoting a class of versions: "11.x", "11.7.x", "~11.7"
• A string denoting constraints for versions: ">11.3 <=12"

The CLI tool will parse this whenever you want to install a library or when you want to run the application through the run scripts.

scripts : Object\<String,String>

Under the scripts map/dictionary, you, the developer, should put some commands or scripts that will help you and other people perform some tasks more quickly. For example, if you have some command that will start all tests or will run some code linting and checking you should add them to the scripts element with an easy to remember name.

These scripts will only be ran by the CLI tool.

To run any of these scripts from the CLI tool you should use the following statement:

There are some predefined script names that will provide some predefined commands:

• start = beast start == beast run start
• test = beast test == beast run test
• build = beast build == beast run build
• compile = beast compile == beast run compile

To be able to run any of the predefined scripts, you need to specify the action done by them.

Example:

propath : Array\<String>

If, for any reason, your application needs some custom ProPath items set to be able to work, then you should fill the propath element with a list of absolute or relative paths. The order in which you fill this element will reflect which sources will be taken in consideration first.

Example: