Skip to content

Latest commit

 

History

History
271 lines (230 loc) · 9.46 KB

ep-lh-0003.md

File metadata and controls

271 lines (230 loc) · 9.46 KB
Raw

linterhub: engine arguments

Metadata
EP ep-lh-0003
Version 1
Title linterhub: engine arguments
Authors xferra, svoboda-rabsvto, GlebBerjoskin
Status Draft

Abstract

This document describes the structure of engine arguments used in linterhub as mentioned in ep-lh-0001.

Motivation

There are a lot of engines of different types, distributed in different ways and they may require specific runtime environment and complex configuration for execution. This enhancement will unify how engine command line arguments are described.

Proposal

Each engine must have args.json file in JSON Schema format which should describe:

  • arguments - all available command line arguments, theirs data types, etc.; it allows to understand how engine could be configured before execution
  • section - an object structure where arguments could be stored; it's define how to store concrete setup of arguments

The visual representation of that file is the following:

.
├── id
├── name
├── delimeters
└── definitions/
    ├── arguments/
    |   ├── type
    |   ├── description
    |   └── properties/
    |       ├── argument1/
    |       |   ├── id
    |       |   ├── type
    |       |   ├── description
    |       |   ├── enum
    |       |   └── default
    |       ├── argument2/
    |       |   ├── id
    |       |   ├── type
    |       |   ├── description
    |       |   ├── enum
    |       |   └── default
    |       └── ...
    └── section

The corresponding schema is located at ./schema/args.json.

Schema

Property Type Required Description
id string - Engine id, case insensitive unique identifier, required only if the engine name is not unique
name string + Case sensitive official engine name, may not be unique
delimeters string + String containing delimeters used between command-line options and their arguments, the most commonly used delimeters are " "(space) and "="
definitions object + The complex object which describe sub-schemas

This is information that allows identifying engine. As for definitions property - it's the place where arguments, section and environment are defined:

Definitions

Property Type Required Description
arguments object + Schema of command line arguments
section object + Schema of configuration section for those arguments

Arguments

This is a sub-schema :

"arguments": {
    "type": "object",
    "description": "The engine command line arguments",
    "properties": {
        "--argument1": {
            "id": "--argument1",
            "type": "number",
            "description": "This is used for something",
            "default": 0
        },
        "argument2": {
            "id": "prefix:argument2",
            "type": "string",
            "description": "This is used for anything",
            "enum": [
                 "value1",
                 "value2"
            ],
            "default": "value1"
        },
        "argument3":{
            "type": "null",
            "description": "This argument is not used.",
        },
    }

Each named command line argument is defined as a named property (original argument name is used for that) and it is a JSON Schema object with the following properties:

Property Type Required Description
id string - The name of the argument from the original tool, may have prefix depending on the purpose; if not set then assumed that argument is not used
hideName boolean - Hide orignal name. Used when engine have multiple arguments without prefix. false by default.
type string + The value type of the argument. Example: null, number, string
description string + Help text from the original tool for that argument, two sentences maximum
default any - The default value for that argument; if argument is readonly and default is not set then 0, "" or null is used
enum array - Need to use if the argument value has a limited list. Type of argument must be string

A prefix in argument id is used internally to identify the argument purpose:

Prefix Example Meaning
"" argumentName There is no prefix, readonly argument and it's value could not be changed
"arg" arg:argumentName Influence the analysis and it's allowed to change the value
"linterhub" linterhub:postfix Reserved argument and it's value could not be changed, it's computed on the fly.

A prefix linterhub need use if argument describes one of this properties:

Postfix Type Meaning
config string Path to config file of linter
stdin string Read source from standard input
filename string A filename to assign stdin input
version null Show version of linter
path string Path to file or folder to analyze

Example:

"properties": {
    "--version": {
        "id": "linterhub:version",
        "type": "null",
        "description": "Show version of linter"
    },
    "":{
        "id": "linterhub:path",
        "type": "string",
        "description": "Path for analysis"
    }
}

Section

This is an object, which is introduced due to some limitations in JSON Schemas. It describes how engine configuration could be stored and normally only engine name should be changed in this template:

"section": {
    "type": "object",
    "description": "The engine configuration section",
    "properties": {
        "name": {
            "type": "string",
            "description": "The engine name",
            "enum": [
                "engine name"
            ]
        },
        "options": {
            "type": "object",
            "description": "The engine configuration",
            "$ref": "#/definitions/arguments"
        }
    }
}

Note: It allows to have an array of configurations for different engines and explicitly determine which engine has the corresponding schema.

Example

Note: already implemented args can be found in the linterhub repository.

Here is the full example for engine enginename:

{
    "$schema": "https://repometric.github.io/linterhub/schema/args.json",
    "id": "enginename",
    "name": "enginename",
    "delimeters":"=",
    "type": "object",
    "allOf": [
        {
            "$ref": "#/definitions/arguments"
        }
    ],
    "definitions": {
        "arguments": {
            "type": "object",
            "properties": {
                "--configurable": {
                    "id": "arg:--configurable",
                    "type": "null",
                    "description": "configurable argument"
                },
                "--readonly": {
                    "type": "string",
                    "description": "not configurable argument",
                    "default": "string value"
                },
                "--version": {
                    "id": "linterhub:version",
                    "type": "null",
                    "description": "reserved argument"
                },
                "--format": {
                    "id": "arg:--format",
                    "type": "string",
                    "description": "Use a specific output format",
                    "default": "json",
                    "enum": [
                        "json",
                        "string",
                        "html"
                    ]
                },
                "": {
                    "id": "linterhub:path",
                    "type": "string",
                    "description": "reserved unnamed argument"
                }
            }
        },
        "section": {
            "type": "object",
            "description": "The engine configuration section",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "The engine name",
                    "enum": [
                        "enginename"
                    ]
                },
                "options": {
                    "type": "object",
                    "description": "The engine configuration",
                    "$ref": "#/definitions/arguments"
                }
            }
        }
    }
}

Unresolved

  • the structure of section object is complicated and unclear
  • positional arguments are not described
  • path argument and argument without a name are not described
  • configuration via files is not described
  • unclear situation with filename masks

Related

  1. ep-lh-0001 - linterhub

References

  1. Args schema https://github.com/repometric/linterhub/tree/master/schema/args.json
  2. Engines https://github.com/repometric/linterhub/blob/master/engine/