# Rule v1beta1

This is the first revision of Rules for LSP analyzers in Konveyor.

## Rule

A Rule consists of conditions, actions and metadata. It instructs analyzer to take specified actions when given conditions match.

Metadata fields of a rule are:

# id must be unique among all provided rules
ruleId: "unique_id"
# violations have pre-defined categories
category: "potential|information|mandatory"
# links point to external hyperlinks
# rule authors are expected to provide
# relevant hyperlinks for quick fixes, docs etc
links:
  - url: "konveyor.io"
    title: "title to be shown in report"
# labels provide metadata about the rule
# can be used to find / filter rules
labels:
  - "label1"
  - "label2"
# effort is an integer value to indicate level of 
# effort needed to fix this issue
effort: 1

Actions of a rule are:

# when a match is found, analyzer generates a violation with this message
message: "helpful message about the violation"
# when a match is found, analyzer generates these tags for the application
tag:
  - "tag1"
  - "tag2"

Finally, a rule contains a `when` block to specify one or more conditions:

when:
  <conditions>

### When

`When` consists of one or more conditions.

#### Provider Conditions

A "provider" knows how to analyse code for a specific language. It publishes what it can do with the source code in terms of "capabilities".

A provider condition instructs the analyzer to invoke a specific "provider" and use one of its "capabilities". In general, it is of the form `<provider_name>.<capability>`:

when:
  <provider>.<capability>: "input"

See [providers](#Providers) section for comprehensive guide on writing provider specific conditions.

#### Logical Conditions

Analyzers provide two basic logical conditions that are useful in making more complex queries by aggregating results of other conditions.

##### And Condition

The `And` condition takes an array of conditions and performs a logical
"and" operation on their results:

when:
  and:
    - <condition1>
    - <condition2>

##### Or Condition

The `Or` condition takes an array of other conditions and performs a logical "or" operation on their results:

when:
  or:
    - <condition1>
    - <condition2>

## Ruleset

A set of Rules form a Ruleset. This is the only abstraction provided by Analyzers to organize Rules.

Each Ruleset will be stored in its own directory with a `ruleset.yaml` file at the directory root that stores metadata of the Ruleset.

# name has to be unique within the provided rulesets
# doesn't necessarily has to be unique globally
name: "Name of the ruleset"
description: "Describes the ruleset"
# source technology this ruleset applies to
source: 
  id: "tech1"
  versionRange: "versionRange"
# target technology this ruleset applies to
target:
  id: "tech2"
  versionRange: "versionRange"
# additional tags for ruleset
tags:
  - awesome_rules1

## Providers

Analyzer currently supports `builtin`, `java` and `go` providers.

### Builtin

Builtin provider has `file`, `filecontent`, `xml`, `json` and `hasTags` capabilities.

#### file

`file` capability enables the provider to find files in the source code that match a given pattern:

when:
  builtin.file: "<regex_to_match_filenames>"

#### filecontent

`filecontent` capability enables the provider to search for content that matches a given pattern:

when:
  builtin.filecontent: "<regex_to_match_filecontent>"

#### xml

`xml` capability enables the provider to query XPath expressions on a list of provided XML files. Unlike providers discussed so far, `xml` takes two input parameters:

when:
  builtin.xml:
    # xpath must be a valid xpath expression
    xpath: "<xpath_expressions>"
    # filepaths is a list of files to scope xpath query to
    filepaths:
      - "/src/file1.xml"
      - "/src/file2.xml"

#### json

`json` capability enables the provider to query XPath expressions on a list of provided JSON files. Ulike `xml`, currently `json` only takes xpath as input and performs the search on all json files in the codebase:

when:
  builtin.json:
    # xpath must be a valid xpath expression
    xpath: "<xpath_expressions>"

#### hasTags

`hasTags` enables the provider to query application tags. It doesn't deal with the source code, instead it queries the internal data structure to check whether given tags are present for the application:

when:
  # when more than one tags are given, a logical AND is implied
  hasTags:
    - "tag1"
    - "tag2"

### Java

Java provider can work with Java source code and provides capabilities `referenced` and `dependency`.

#### referenced

`referenced` capability enables the provider to find references in the source code. It takes two input parameters:

when:
  java.referenced:
    # regex pattern to match
    pattern: "<pattern>"
    # location defines the exact location where
    # pattern should be matched
    location: CONTRUCTOR_CALL

The supported locations are:
- CONSTRUCTOR_CALL
- TYPE
- INHERITANCE
- METHOD_CALL
- ANNOTATION
- IMPLEMENTS_TYPE
- ENUM_CONSTANT
- RETURN_TYPE
- IMPORT
- VARIABLE_DECLARATION