macaron.parsers package

Subpackages

• macaron.parsers.yaml package

Submodules

macaron.parsers.actionparser module

This module contains the parser for GitHub Actions Workflow files.

macaron.parsers.actionparser.parse(workflow_path)

Parse the GitHub Actions workflow YAML file.

Parameters:

workflow_path (str) – Path to the GitHub Actions.

Returns:

The parsed workflow.

Return type:

Workflow

Raises:

ParseError – When parsing fails with errors.

macaron.parsers.actionparser.get_run_step(step)

Get the parsed GitHub Action run step for inlined shell scripts.

If the run step cannot be validated this function returns None.

Parameters:

step (Step) – The parsed step object.

Returns:

The inlined run script or None if the run step cannot be validated.

Return type:

str | None

macaron.parsers.actionparser.get_step_input(step, key)

Get an input value from a GitHub Action step.

If the input value cannot be found or the step inputs cannot be validated this function returns None.

Parameters:

• step (Step) – The parsed step object.

• key (str) – The key to be looked up.

Returns:

The input value or None if it doesn’t exist or the parsed object validation fails.

Return type:

str | None

macaron.parsers.bashparser module

This module is a Python wrapper for the compiled bashparser binary.

The bashparser Go module is based on the github.com/mvdan/sh Go module and is distributed together with Macaron as a compiled binary.

See Also https://github.com/mvdan/sh.

class macaron.parsers.bashparser.BashScriptType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

This class is used for different bash script types.

NONE = 'None'

INLINE = 'inline'

FILE = 'file'

class macaron.parsers.bashparser.BashNode(name, node_type, source_path, parsed_step_obj, parsed_bash_obj, **kwargs)

Bases: BaseNode

This class represents a callgraph node for bash commands.

__init__(name, node_type, source_path, parsed_step_obj, parsed_bash_obj, **kwargs)

Initialize instance.

Parameters:

• name (str) – Name of the bash script file or the step name if the script is inlined.

• node_type (BashScriptType) – The type of the script.

• source_path (str) – The path of the script.

• parsed_step_obj (Step | None) – The parsed step object.

• parsed_bash_obj (dict) – The parsed bash script object.

macaron.parsers.bashparser.parse_file(file_path, macaron_path=None)

Parse a bash script file.

Parameters:

• file_path (str) – Bash script file path.

• macaron_path (str | None) – Macaron’s root path (optional).

Returns:

The parsed bash script in JSON (dict) format.

Return type:

dict

Raises:

ParseError – When parsing fails with errors.

macaron.parsers.bashparser.parse(bash_content, macaron_path=None)

Parse a bash script’s content.

Parameters:

• bash_content (str) – Bash script content

• macaron_path (str | None) – Macaron’s root path (optional).

Returns:

The parsed bash script in JSON (dict) format.

Return type:

dict

Raises:

ParseError – When parsing fails with errors.

macaron.parsers.bashparser.create_bash_node(name, node_id, node_type, source_path, ci_step_ast, repo_path, caller, recursion_depth, macaron_path=None)

Create a callgraph node for a bash script.

A bash node can have the following types:

• BashScriptType.INLINE when it is inlined in a CI workflow.

• BashScriptType.FILE when it is a bash script file.

Parameters:

• name (str) – A name to be used as the identifier of the node.

• node_id (str | None) – The node ID if defined.

• node_type (BashScriptType) – The type of the node.

• source_path (str) – The file that contains the bash script.

• ci_step_ast (Step | None) – The AST of the CI step that runs a bash script.

• repo_path (str) – The path to the target repo.

• caller (BaseNode) – The caller node.

• recursion_depth (int) – The number of times this function is called recursively.

• macaron_path=None – The path to the Macaron module.

Returns:

A bash node object.

Return type:

BashNode

Raises:

CallGraphError – When unable to create a bash node.

macaron.parsers.github_workflow_model module

class macaron.parsers.github_workflow_model.Inputs

Bases: TypedDict

description: NotRequired[str]

deprecationMessage: NotRequired[str]

required: NotRequired[bool]

type: Literal['boolean', 'number', 'string']

default: NotRequired[Union[bool, float, str]]

class macaron.parsers.github_workflow_model.Secrets

Bases: TypedDict

description: NotRequired[str]

required: bool

class macaron.parsers.github_workflow_model.WorkflowCall

Bases: TypedDict

inputs: NotRequired[dict[str, Inputs]]

secrets: NotRequired[dict[str, Secrets]]

class macaron.parsers.github_workflow_model.Inputs1

Bases: TypedDict

description: str

deprecationMessage: NotRequired[str]

required: NotRequired[bool]

default: NotRequired[Any]

type: NotRequired[Literal['string', 'choice', 'boolean', 'number', 'environment']]

options: NotRequired[list[str]]

class macaron.parsers.github_workflow_model.WorkflowDispatch

Bases: TypedDict

inputs: NotRequired[dict[str, Inputs1]]

class macaron.parsers.github_workflow_model.ScheduleItem

Bases: TypedDict

cron: NotRequired[str]

class macaron.parsers.github_workflow_model.Credentials

Bases: TypedDict

username: NotRequired[str]

password: NotRequired[str]

class macaron.parsers.github_workflow_model.Environment

Bases: TypedDict

name: str

url: NotRequired[str]

class macaron.parsers.github_workflow_model.RunsOn

Bases: TypedDict

group: NotRequired[str]

labels: NotRequired[Union[list[str], str]]

class macaron.parsers.github_workflow_model.Step1

Bases: TypedDict

uses: str

class macaron.parsers.github_workflow_model.Step2

Bases: TypedDict

run: str

class macaron.parsers.github_workflow_model.Defaults

Bases: TypedDict

run: NotRequired[Run]

class macaron.parsers.github_workflow_model.On

Bases: TypedDict

branch_protection_rule: NotRequired[Optional[dict[str, Any]]]

check_run: NotRequired[Optional[dict[str, Any]]]

check_suite: NotRequired[Optional[dict[str, Any]]]

create: NotRequired[Optional[dict[str, Any]]]

delete: NotRequired[Optional[dict[str, Any]]]

deployment: NotRequired[Optional[dict[str, Any]]]

deployment_status: NotRequired[Optional[dict[str, Any]]]

discussion: NotRequired[Optional[dict[str, Any]]]

discussion_comment: NotRequired[Optional[dict[str, Any]]]

fork: NotRequired[Optional[dict[str, Any]]]

gollum: NotRequired[Optional[dict[str, Any]]]

issue_comment: NotRequired[Optional[dict[str, Any]]]

issues: NotRequired[Optional[dict[str, Any]]]

label: NotRequired[Optional[dict[str, Any]]]

merge_group: NotRequired[Optional[dict[str, Any]]]

milestone: NotRequired[Optional[dict[str, Any]]]

page_build: NotRequired[Optional[dict[str, Any]]]

project: NotRequired[Optional[dict[str, Any]]]

project_card: NotRequired[Optional[dict[str, Any]]]

project_column: NotRequired[Optional[dict[str, Any]]]

public: NotRequired[Optional[dict[str, Any]]]

pull_request: NotRequired[Ref1]

pull_request_review: NotRequired[Optional[dict[str, Any]]]

pull_request_review_comment: NotRequired[Optional[dict[str, Any]]]

pull_request_target: NotRequired[Ref1]

push: NotRequired[Ref1]

registry_package: NotRequired[Optional[dict[str, Any]]]

release: NotRequired[Optional[dict[str, Any]]]

status: NotRequired[Optional[dict[str, Any]]]

watch: NotRequired[Optional[dict[str, Any]]]

workflow_call: NotRequired[WorkflowCall]

workflow_dispatch: NotRequired[WorkflowDispatch]

workflow_run: NotRequired[Optional[dict[str, Any]]]

repository_dispatch: NotRequired[Optional[dict[str, Any]]]

schedule: NotRequired[list[ScheduleItem]]

class macaron.parsers.github_workflow_model.Container

Bases: TypedDict

image: str

credentials: NotRequired[Credentials]

env: NotRequired[Union[dict[str, Union[str, float, bool]], str]]

ports: NotRequired[list[float | str]]

volumes: NotRequired[list[str]]

options: NotRequired[str]

class macaron.parsers.github_workflow_model.ReusableWorkflowCallJob

Bases: dict

name: NotRequired[str]

needs: NotRequired[Union[list[str], str]]

permissions: NotRequired[Union[Literal['read-all', 'write-all'], PermissionsEvent]]

if: NotRequired[Union[bool, float, str]]

uses: str

with: NotRequired[Union[dict[str, Union[str, float, bool]], str]]

secrets: NotRequired[Union[dict[str, Union[str, float, bool]], str, Literal['inherit']]]

strategy: NotRequired[Strategy]

concurrency: NotRequired[Union[str, Concurrency]]

class macaron.parsers.github_workflow_model.Identified(id, obj)

Bases: Generic[T]

id: str

obj: TypeVar(T)

__init__(id, obj)

macaron.parsers.github_workflow_model.is_normal_job(job)

Return type:

TypeGuard[NormalJob]

macaron.parsers.github_workflow_model.is_reusable_workflow_call_job(job)

Return type:

TypeGuard[ReusableWorkflowCallJob]

macaron.parsers.github_workflow_model.is_run_step(step)

Return type:

TypeGuard[Step5]

macaron.parsers.github_workflow_model.is_action_step(step)

Return type:

TypeGuard[Step4]