/**

* Provides classes for working with YAML data.

*

* YAML documents are represented as abstract syntax trees whose nodes

* are either YAML values or alias nodes referring to another YAML value.

*/

overlay[local?]

module;

/** Provides the input specification of YAML implementation. */

signature module InputSig {

class Container {

string getAbsolutePath();

Container getParentContainer();

}

class File extends Container;

class Location {

File getFile();

}

class LocatableBase {

/**

* Gets the `Location` of this node.

*

* Typically `yaml_locations(this, result)`.

*/

Location getLocation();

}

/**

* A base class for Nodes.

*

* Typically `@yaml_node`.

*/

class NodeBase extends LocatableBase {

/**

* Gets the `i`th child node of this node.

*

* Typically `yaml(result, _, this, i, _, _)`.

*/

NodeBase getChildNode(int i);

/**

* Gets the tag of this node.

*

* Typically `yaml(this, _, _, _, result, _)`.

*/

string getTag();

/**

* Gets the anchor associated with this node, if any.

*

* Typically `yaml_anchors(this, result)`.

*/

string getAnchor();

/**

* Gets a textual representation of this node.

*

* Typically `yaml(this, _, _, _, _, result)`.

*/

string toString();

}

/**

* A base class for scalar nodes.

*

* Typically `@yaml_scalar_node`.

*/

class ScalarNodeBase extends NodeBase {

/**

* Gets the style of this scalar.

*

* Typically `yaml_scalars(this, result, _)`.

*/

int getStyle();

/**

* Gets the value of this scalar, as a string.

*

* Typically `yaml_scalars(this, _, result)`.

*/

string getValue();

}

/**

* A base class for collections.

*

* Typically `@yaml_collection_node`.

*/

class CollectionNodeBase extends NodeBase;

/**

* A base class for objects.

*

* Typically `@yaml_mapping_node`.

*/

class MappingNodeBase extends CollectionNodeBase;

/**

* A base class for arrays.

*

* Typically `@yaml_sequence_node`.

*/

class SequenceNodeBase extends CollectionNodeBase;

/**

* A base class for aliases.

*

* Typically `@yaml_alias_node`.

*/

class AliasNodeBase extends NodeBase {

/**

* Gets the target anchor this alias refers to.

*

* Typically `yaml_aliases(this, result)`.

*/

string getTarget();

}

/**

* A base class for parse errors.

*

* Typically `@yaml_parse_error`.

*/

class ParseErrorBase extends LocatableBase {

/**

* Gets the message of this parse error.

*

* Typically `yaml_errors(this, result)`.

*/

string getMessage();

}

}

/** Provides a class hierarchy for working with YAML files. */

module Make<InputSig Input> {

/**

* A node in the AST representation of a YAML file, which may either be

* a YAML value (such as a scalar or a collection) or an alias node

* referring to some other YAML value.

*

* Examples:

*

* ```

* # a mapping

* x: 1

* << : *DEFAULTS # an alias node referring to anchor `DEFAULTS`

* ```

*/

class YamlNode instanceof Input::NodeBase {

/** Gets the file this node comes from. */

Input::File getFile() { result = this.getLocation().getFile() }

/**

* Gets the `Location` of this node.

*/

Input::Location getLocation() { result = super.getLocation() }

/**

* Gets the parent node of this node, which is always a collection.

*/

YamlCollection getParentNode() { this = result.getChildNode(_) }

/**

* Gets the `i`th child node of this node.

*

* _Note_: The index of a child node relative to its parent is considered

* an implementation detail and may change between versions of the extractor.

*/

YamlNode getChildNode(int i) { result = super.getChildNode(i) }

/**

* Gets a child node of this node.

*/

YamlNode getAChildNode() { result = this.getChildNode(_) }

/**

* Gets the number of child nodes of this node.

*/

int getNumChild() { result = count(this.getAChildNode()) }

/**

* Gets the `i`th child of this node, as a YAML value.

*/

YamlValue getChild(int i) { result = this.getChildNode(i).eval() }

/**

* Gets a child of this node, as a YAML value.

*/

YamlValue getAChild() { result = this.getChild(_) }

/**

* Gets the tag of this node.

*/

string getTag() { result = super.getTag() }

/**

* Holds if this node is tagged with a standard type tag of the form

* `tag:yaml.org,2002:<t>`.

*/

predicate hasStandardTypeTag(string t) {

t = this.getTag().regexpCapture("tag:yaml.org,2002:(.*)", 1)

}

/** Gets a textual representation of this node. */

string toString() { result = super.toString() }

/**

* Gets the anchor associated with this node, if any.

*/

string getAnchor() { result = super.getAnchor() }

/**

* Gets the toplevel document to which this node belongs.

*/

YamlDocument getDocument() { result = this.getParentNode*() }

/**

* Gets the YAML value this node corresponds to after resolving aliases and includes.

*/

YamlValue eval() { result = this }

/**

* Gets the primary QL class for this node.

*/

string getAPrimaryQlClass() { result = "YamlNode" }

}

/**

* A YAML value; that is, either a scalar or a collection.

*

* Examples:

*

* ```

* ---

* "a string"

* ---

* - a

* - sequence

* ```

*/

abstract class YamlValue extends YamlNode { }

/**

* A YAML scalar.

*

* Examples:

*

* ```

* 42

* 1.0

* 2001-12-15T02:59:43.1Z

* true

* null

* "hello"

* ```

*/

class YamlScalar extends YamlValue instanceof Input::ScalarNodeBase {

/**

* Gets the style of this scalar, which is one of the following:

*

* - `""` (empty string): plain style

* - `"\""` (double quote): double quoted style

* - `"'"` (single quote): single quoted style

* - `">"` (greater-than): folded style

* - `"|"` (pipe): literal style

*/

string getStyle() {

exists(int s | s = super.getStyle() |

s = 0 and result = ""

or

s = 34 and result = "\""

or

s = 39 and result = "'"

or

s = 62 and result = ">"

or

s = 124 and result = "|"

)

}

/**

* Gets the value of this scalar, as a string.

*/

string getValue() { result = super.getValue() }

override string getAPrimaryQlClass() { result = "YamlScalar" }

}

/**

* A YAML scalar representing an integer value.

*

* Examples:

*

* ```

* 42

* 0xffff

* ```

*/

class YamlInteger extends YamlScalar {

YamlInteger() { this.hasStandardTypeTag("int") }

/**

* Gets the value of this scalar, as an integer.

*/

int getIntValue() { result = this.getValue().toInt() }

}

/**

* A YAML scalar representing a floating point value.

*

* Examples:

*

* ```

* 1.0

* 6.626e-34

* ```

*/

class YamlFloat extends YamlScalar {

YamlFloat() { this.hasStandardTypeTag("float") }

/**

* Gets the value of this scalar, as a floating point number.

*/

float getFloatValue() { result = this.getValue().toFloat() }

}

/**

* A YAML scalar representing a time stamp.

*

* Example:

*

* ```

* 2001-12-15T02:59:43.1Z

* ```

*/

class YamlTimestamp extends YamlScalar {

YamlTimestamp() { this.hasStandardTypeTag("timestamp") }

/**

* Gets the value of this scalar, as a date.

*/

date getDateValue() { result = this.getValue().toDate() }

}

/**

* A YAML scalar representing a Boolean value.

*

* Example:

*

* ```

* true

* ```

*/

class YamlBool extends YamlScalar {

YamlBool() { this.hasStandardTypeTag("bool") }

/**

* Gets the value of this scalar, as a Boolean.

*/

boolean getBoolValue() { if this.getValue() = "true" then result = true else result = false }

}

/**

* A YAML scalar representing the null value.

*

* Example:

*

* ```

* null

* ```

*/

class YamlNull extends YamlScalar {

YamlNull() { this.hasStandardTypeTag("null") }

}

/**

* A YAML scalar representing a string value.

*

* Example:

*

* ```

* "hello"

* ```

*/

class YamlString extends YamlScalar {

YamlString() { this.hasStandardTypeTag("str") }

}

/**

* A YAML scalar representing a merge key.

*

* Example:

*

* ```

* x: 1

* << : *DEFAULTS # merge key

* ```

*/

class YamlMergeKey extends YamlScalar {

YamlMergeKey() { this.hasStandardTypeTag("merge") }

}

/**

* A YAML scalar representing an `!include` directive.

*

* ```

* !include common.yaml

* ```

*/

class YamlInclude extends YamlScalar {

YamlInclude() { this.getTag() = "!include" }

override YamlValue eval() {

exists(YamlDocument targetDoc |

targetDoc.getLocation().getFile().getAbsolutePath() = this.getTargetPath() and

result = targetDoc.eval()

)

}

/**

* Gets the absolute path of the file included by this directive.

*/

private string getTargetPath() {

result = this.getAbsolutePath()

or

result =

this.getDocument().getLocation().getFile().getParentContainer().getAbsolutePath() + "/" +

this.getRelativePath()

}

/** Join-order helper for `getTargetPath`. Gets the path but only if it is an absolute path. */

private string getAbsolutePath() {

result = this.getValue() and

result.matches("/%")

}

/** Join-order helper for `getTargetPath`. Gets the path, but only if it is a relative path. */

pragma[noinline]

private string getRelativePath() {

result = this.getValue() and

not result.matches("/%")

}

}

/**

* A YAML collection, that is, either a mapping or a sequence.

*

* Examples:

*

* ```

* ---

* # a mapping

* x: 0

* y: 1

* ---

* # a sequence

* - red

* - green

* - -blue

* ```

*/

class YamlCollection extends YamlValue instanceof Input::CollectionNodeBase {

override string getAPrimaryQlClass() { result = "YamlCollection" }

}

/**

* A YAML mapping.

*

* Example:

*

* ```

* x: 0

* y: 1

* ```

*/

class YamlMapping extends YamlCollection instanceof Input::MappingNodeBase {

/**

* Gets the `i`th key of this mapping.

*/

YamlNode getKeyNode(int i) {

i >= 0 and

exists(int j | i = j - 1 and result = this.getChildNode(j))

}

/**

* Gets the `i`th value of this mapping.

*/

YamlNode getValueNode(int i) {

i >= 0 and

exists(int j | i = -j - 1 and result = this.getChildNode(j))

}

/**

* Gets the `i`th key of this mapping, as a YAML value.

*/

YamlValue getKey(int i) { result = this.getKeyNode(i).eval() }

/**

* Gets the `i`th value of this mapping, as a YAML value.

*/

YamlValue getValue(int i) { result = this.getValueNode(i).eval() }

/**

* Holds if this mapping maps `key` to `value`.

*/

predicate maps(YamlValue key, YamlValue value) {

exists(int i | key = this.getKey(i) and value = this.getValue(i))

or

exists(YamlMergeKey merge, YamlMapping that | this.maps(merge, that) | that.maps(key, value))

}

/**

* Gets the value that this mapping maps `key` to.

*/

YamlValue lookup(string key) {

exists(YamlScalar s | s.getValue() = key | this.maps(s, result))

}

override string getAPrimaryQlClass() { result = "YamlMapping" }

}

/**

* A YAML sequence.

*

* Example:

*

* ```

* - red

* - green

* - blue

* ```

*/

class YamlSequence extends YamlCollection instanceof Input::SequenceNodeBase {

/**

* Gets the `i`th element in this sequence.

*/

YamlNode getElementNode(int i) { result = this.getChildNode(i) }

/**

* Gets the `i`th element in this sequence, as a YAML value.

*/

YamlValue getElement(int i) { result = this.getElementNode(i).eval() }

override string getAPrimaryQlClass() { result = "YamlSequence" }

}

/**

* A YAML alias node referring to a target anchor.

*

* Example:

*

* ```

* *DEFAULTS

* ```

*/

class YamlAliasNode extends YamlNode instanceof Input::AliasNodeBase {

override YamlValue eval() {

result.getAnchor() = this.getTarget() and

result.getDocument() = this.getDocument()

}

/**

* Gets the target anchor this alias refers to.

*/

string getTarget() { result = super.getTarget() }

override string getAPrimaryQlClass() { result = "YamlAliasNode" }

}

/**

* A YAML document.

*

* Example:

*

* ```

* ---

* x: 0

* y: 1

* ```

*/

class YamlDocument extends YamlNode {

YamlDocument() { not exists(this.getParentNode()) }

}

/**

* An error message produced by the YAML parser while processing a YAML file.

*/

class YamlParseError instanceof Input::ParseErrorBase {

/**

* Gets the `Location` of this error.

*/

Input::Location getLocation() { result = super.getLocation() }

/**

* Gets the message of this error.

*/

string getMessage() { result = super.getMessage() }

/**

* Get the string representation of this error.

*/

string toString() { result = super.getMessage() }

}

/**

* A YAML node that may contain sub-nodes that can be identified by a name.

* I.e. a mapping, sequence, or scalar.

*

* Is used in e.g. GithHub Actions, which is quite flexible in parsing YAML.

*

* For example:

* ```

* on: pull_request

* ```

* and

* ```

* on: [pull_request]

* ```

* and

* ```

* on:

* pull_request:

* ```

*

* are equivalent.

*/

class YamlMappingLikeNode extends YamlNode {

YamlMappingLikeNode() {

this instanceof YamlMapping

or

this instanceof YamlSequence

or

this instanceof YamlScalar

}

/** Gets sub-name identified by `name`. */

YamlNode getNode(string name) {

exists(YamlMapping mapping |

mapping = this and

result = mapping.lookup(name)

)

or

exists(YamlSequence sequence, YamlNode node |

sequence = this and

sequence.getAChildNode() = node and

node.eval().toString() = name and

result = node

)

or

exists(YamlScalar scalar |

scalar = this and

scalar.getValue() = name and

result = scalar

)

}

/** Gets the number of elements in this mapping or sequence. */

int getElementCount() {

exists(YamlMapping mapping |

mapping = this and

result = mapping.getNumChild() / 2

)

or

exists(YamlSequence sequence |

sequence = this and

result = sequence.getNumChild()

)

or

exists(YamlScalar scalar |

scalar = this and

result = 1

)

}

}

}