Repository files navigation

Run CWTools on your Clausewitz mod PDXScript code in parallel to your builds.

If CWTools finds errors, warnings or suggestions in the mod code then they will be output.

It will also insert them as inline feedback into your PRs ("Files changed" tab):

GitHub: Can't use GitHub? Clickhere for GitLab installation instructions .

In most cases, no setup is required beyond adding the following workflow yml file to your project (.github/workflows folder) and setting the correct game. See below for advanced configuration and an explanation of the tools used.

The following games require no further setup:

• HOI4
• Stellaris

name:CWTools CIon:[pull_request, push]# other events may work but are not supportedjobs:cwtools_job:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v1# required    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}# required, secret is automatically set by github

This action will create a new job called "CWTools", which will be used to annotate your code. Its success or failure state depends on the CWTools output.

The fulloutput.json log is saved to$GITHUB_WORKSPACE, and can be recovered withactions/upload-artifact.

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}    -name:Upload artifactif:always()# so even if the check fails, the log is uploadeduses:actions/upload-artifact@v1.1.0with:name:cwtools_outputpath:output.json

What game to use. Allowed values:hoi4,ck2,eu4,ir,stellaris,vic2.

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}

Path to the mod folder in$GITHUB_WORKSPACE (root of repository). (Default: "" - root of repository itself)

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4modPath:"mod_folder"env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}

Path to the full cache file (cwb.bz2) in$GITHUB_WORKSPACE (root of repository). Use an empty string to use metadata from cwtools/cwtools-cache-files (Default: use metadata)

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4cache:"cache/hoi4.cwb.bz2"env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}

Which languages to check localisation for, space separated, lowercase (eg.english spanish russian). Note: May be different from game to game. (Default:english)

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4locLanguages:"english spanish russian"env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}

Whether to not use cache, and instead treat the project as a vanilla game installation folder - if you are a modder, you probably should not be using this. If True, cache input will be ignored (Default: False, set to anything other than 0 or blank for True)

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4vanillaMode:"1"env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}

What rules repository to use (Default:https://github.com/cwtools/cwtools-$INPUT_GAME-config.git)

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4rules:"https://github.com/Yard1/cwtools-hoi4-config.git"env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}

What ref on rules repo to checkout (Default:master)

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4rulesRef:"1.0.0"env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}

By default will only annotate changed files in a push or a pull request. In order to annotate all files setchangedFilesOnly input to"0".

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4changedFilesOnly:"0"env:GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}

You can choose to suppress annotations with chosen CWTools offence category IDs (CW###) per GitHub severity type (failure, warning, notice).

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4suppressedOffenceCategories:'{"failure":["CW110", "CW210"], "warning":[], "notice":[]}'# will suppress CW110 and CW210 category failures, but will show those for warnings and noticesenv:default:${{ secrets.GITHUB_TOKEN }}

You can choose to suppress annotations completely in certain files. Use paths from root of repository, make sure to have no trailing whitespace. Globbing is not supported.

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4suppressedFiles:'["common/scripted_effects/my_effects.txt", "events/EventFile.txt"]'# will completely suppress any annotations in those two filesenv:default:${{ secrets.GITHUB_TOKEN }}

Which CWTools.CLI version to use (Default: latest stable).

    -uses:cwtools/cwtools-action@v1.1.0with:game:hoi4CWToolsCLIVersion:'0.0.7'env:default:${{ secrets.GITHUB_TOKEN }}

Due to limitations with GitLab, this currently only works for merge requests to master

Running this action on GitLab is a bit more involved, requiring the creation of a bot account. It is also limited to providing comments on pull requests as shown here:

1. Create a new GitLab account for this "bot" and give it "Reporter" access to your project.
2. Log into the account, browse tothe Personal Access Token page and generate a PAT with "api" scope. Make a note of the token.
3. Log back into your primary account.
4. Browse to your Project and go to "Settings", "CI / CD", and open the section "Variables".
5. Create a variable called "REVIEWDOG_GITLAB_API_TOKEN". Put the PAT generated above as the Value, then set it as "Masked" butnot Protected.
6. Press "Save variables".

Please note: This PAT gives access to all projects the bot can access. If somebody gets access to your pipeline logs, it's possible (although not likely) that they could access the token.

1. In the root of your project create a file called.gitlab-ci.yml
2. Copy the contents of the example fileGitLab_CWToolsCI.yml, found in /examples, into it.
3. Configure the variables if desired (see above).
4. Create a merge request and check it works!

If you're running your own instance of GitLab, you'll need to set the following two variables in addition to those in the default template:

 - GITLAB_API: "https://example.gitlab.com/api/v4" - REVIEWDOG_INSECURE_SKIP_VERIFY: true

CWTools is a .NET library that provides features to analyse and manipulate the scripting language used in Paradox Development Studio's games (PDXScript). This is mainly used in a VS Code extension,cwtools-vscode. CWTools also provides a CLI toolCWTools.CLI to allow automated anaylsis, which is what this action relies on.

This action relies on two things:

1. A set of valiation rules written for the game your mod is for
2. A cache file containing key information from vanilla files

The validation rules are taken from the master branch of the public repository for the game, e.g.https://github.com/cwtools/cwtools-hoi4-config. The settingsrules andrulesRef can be used to specify an alternative repo, or to stay on an old version of the rules.

In order to validate correctly, CWTools requires certain data from the vanilla game files such as defined localisation, variables, etc. There are two formats of cache file:

The metadata format contains a limited set of information from vanilla, enough to run the main validator. For convenience CWTools automatically generates these metadata cache files for the latest public rules and latest version of each game. These are foundhere and are used by default in this action (please note that not all games may be supported yet).

The full format contains a more details, processed, version of the vanilla script files. This is required in order to provide accurate validation taking load order and file overrides into account. This is the same format used by cwtools-vscode. We do not provide these files, however this action can be configured to use them.

Created by Antoni Baum (Yard1).

Usingtboby/cwtools.

Based ongimenete/rubocop-action by Alberto Gimeno.