From 971788909a6e82f62f070b43348c93655abc22c4 Mon Sep 17 00:00:00 2001 From: Tyler Jang Date: Tue, 10 Oct 2023 12:29:13 -0700 Subject: [PATCH] Repo cleanup (#509) Handles a number of cleanup tasks - Fixes autopep8 issue conditions originating from pinning an `extra_packages` field (see #404). This should fix the issue identified in https://github.com/trunk-io/plugins/issues/507. I will also fix the underlying CLI bug separately. - Updates action descriptions and comments to be clearer and more standardized (follow-up to #505). - Rename all repo readme files to all caps. This helps them stand out more to new users. - Update the readme instructions to fix broken links and modernize the instructions with Trunk Tools and other practices. - Run `trunk upgrade` --- .github/filters.yaml | 2 +- .github/workflows/repo_tests.reusable.yaml | 2 +- .trunk/trunk.yaml | 5 +- contributing.md => CONTRIBUTING.md | 70 ++++++++++++++----- readme.md => README.md | 26 ++++--- actions/buf/{readme.md => README.md} | 0 actions/buf/plugin.yaml | 3 +- actions/commitlint/{readme.md => README.md} | 0 actions/commitlint/plugin.yaml | 2 + .../{readme.md => README.md} | 0 actions/git-blame-ignore-revs/plugin.yaml | 2 +- .../{readme.md => README.md} | 0 actions/go-mod-tidy-vendor/plugin.yaml | 2 +- actions/go-mod-tidy/{readme.md => README.md} | 0 actions/go-mod-tidy/plugin.yaml | 2 +- .../python/{readme.md => README.md} | 0 actions/hello-world/python/plugin.yaml | 2 +- actions/npm-check-pre-push/plugin.yaml | 1 + actions/npm-check/{readme.md => README.md} | 0 actions/npm-check/plugin.yaml | 1 + actions/yarn-check/{readme.md => README.md} | 0 actions/yarn-check/plugin.yaml | 1 + linters/ansible-lint/{readme.md => README.md} | 0 linters/ansible-lint/ansible_lint.test.ts | 2 +- linters/autopep8/plugin.yaml | 6 +- ...mt.shot => autopep8_v2.0.4_basic.fmt.shot} | 0 .../nancy/test_data/{readme.md => README.md} | 0 linters/pragma-once/{readme.md => README.md} | 0 .../pre-commit-hooks/{Readme.md => README.md} | 0 linters/sourcery/{readme.md => README.md} | 0 linters/trufflehog/plugin.yaml | 7 +- repo-tools/linter-test-helper/generate | 2 +- runtimes/{readme.md => README.md} | 0 tests/{readme.md => README.md} | 29 ++++---- tests/repo_tests/readme_inclusion.test.ts | 8 +-- tests/repo_tests/test_coverage.test.ts | 2 +- tests/utils/index.ts | 4 +- 37 files changed, 118 insertions(+), 63 deletions(-) rename contributing.md => CONTRIBUTING.md (62%) rename readme.md => README.md (95%) rename actions/buf/{readme.md => README.md} (100%) rename actions/commitlint/{readme.md => README.md} (100%) rename actions/git-blame-ignore-revs/{readme.md => README.md} (100%) rename actions/go-mod-tidy-vendor/{readme.md => README.md} (100%) rename actions/go-mod-tidy/{readme.md => README.md} (100%) rename actions/hello-world/python/{readme.md => README.md} (100%) rename actions/npm-check/{readme.md => README.md} (100%) rename actions/yarn-check/{readme.md => README.md} (100%) rename linters/ansible-lint/{readme.md => README.md} (100%) rename linters/autopep8/test_data/{autopep8_v1.5.7_basic.fmt.shot => autopep8_v2.0.4_basic.fmt.shot} (100%) rename linters/nancy/test_data/{readme.md => README.md} (100%) rename linters/pragma-once/{readme.md => README.md} (100%) rename linters/pre-commit-hooks/{Readme.md => README.md} (100%) rename linters/sourcery/{readme.md => README.md} (100%) rename runtimes/{readme.md => README.md} (100%) rename tests/{readme.md => README.md} (86%) diff --git a/.github/filters.yaml b/.github/filters.yaml index bade808ec..0f3a4ca91 100644 --- a/.github/filters.yaml +++ b/.github/filters.yaml @@ -38,7 +38,7 @@ repo-tests: - linters/** - actions/** - tools/** - - readme.md + - README.md - .trunk/trunk.yaml - package.json - package-lock.json diff --git a/.github/workflows/repo_tests.reusable.yaml b/.github/workflows/repo_tests.reusable.yaml index 036210784..b0508d6e2 100644 --- a/.github/workflows/repo_tests.reusable.yaml +++ b/.github/workflows/repo_tests.reusable.yaml @@ -1,5 +1,5 @@ # Runs tests to verify: -# 1. All linters are specified in the readme.md +# 1. All linters are specified in the README.md # 2. All linters have test coverage. # 3. Plugin has a healthy composite config name: Repo Tests diff --git a/.trunk/trunk.yaml b/.trunk/trunk.yaml index d10e4bd36..723e287a1 100644 --- a/.trunk/trunk.yaml +++ b/.trunk/trunk.yaml @@ -2,7 +2,7 @@ version: 0.1 # version used for local trunk runs and testing cli: - version: 1.16.1-beta.14 + version: 1.16.3-beta.8 api: address: api.trunk-staging.io:8443 @@ -19,7 +19,6 @@ plugins: lint: # enabled linters inherited from github.com/trunk-io/configs plugin - enabled: [] disabled: - pylint # pylint diagnostics are too strict @@ -31,6 +30,8 @@ lint: - "**/test_data/**" actions: + # Uncomment to enable more verbose action logs + # output_level: verbose definitions: - id: repo-tests display_name: Repo Tests diff --git a/contributing.md b/CONTRIBUTING.md similarity index 62% rename from contributing.md rename to CONTRIBUTING.md index 581e681e9..9d1ad2355 100644 --- a/contributing.md +++ b/CONTRIBUTING.md @@ -6,13 +6,14 @@ Thanks for contributing to trunk's default plugins! Read on to learn more. - [Release process](#releases) - [Adding new linters](#linters) - [Adding new actions](#actions) +- [Adding new tools](#tools) - [Guidelines](#guidelines) - [Docs](https://docs.trunk.io) ## Overview -We use this repository to provide our users with default linters and actions. trunk automatically -adds the following to users' trunk.yaml: +We use this repository to provide our users with default linters, actions, and tools. Trunk +automatically adds the following to users' trunk.yaml: ```yaml plugins: @@ -49,7 +50,7 @@ plugins: sources: - id: trunk uri: https://github.com/trunk-io/plugins - ref: v0.0.8 # will change to v0.0.9 on next `trunk upgrade` + ref: v1.2.5 # will change to the latest release on next `trunk upgrade` ``` We recommend only setting the above `ref` field to be our released tags, but if you need a linter or @@ -64,32 +65,34 @@ load a plugin source until they have upgraded to a compliant CLI version. To add a new linter: -1. Create a directory inside `linters/` with the name of your new linter. -2. Inside this new directory, create the following structure. If you ran `trunk check` in this - repository recently, some of these files should be automatically created for you: +1. Run `trunk check` to start up Trunk in the background. +2. Create a directory inside `linters/` with the name of your new linter. +3. Inside this new directory, create the following structure. Most of these files will be + automatically created for you: ```text linters/ └─my-linter/ │ plugin.yaml │ my_linter.test.ts - │ readme.md (optional) + │ README.md (optional) │ my-config.json (optional) └─test_data/ └─basic.in.py (with appropriate extension) ``` -3. Add your linter definition to `plugin.yaml` (consult the docs for [custom linters] and [custom - parsers] to understand how it should be defined). -4. Making sure the plugin in [`.trunk/trunk.yaml`](.trunk/trunk.yaml) is pointing to your local +4. Add your linter definition to `plugin.yaml` (consult the docs for [custom linters] and [custom + parsers] to understand how it should be defined). Most linters in this repository are defined as + tools as well, so that they can be easily run manually from the command line. +5. Making sure the plugin in [`.trunk/trunk.yaml`](.trunk/trunk.yaml) is pointing to your local repository, run `trunk check enable ` to enable your linter, and run `trunk check` to verify that the configuration is valid and that you get desired diagnostics. Running `trunk check --verbose` can help provide greater insights when debugging. -5. Add a few simple test cases to `my_linter.test.ts` to exercise your linter and generate - snapshots. Refer to [Testing Guidelines](tests/readme.md) for more information on writing and +6. Add a few simple test cases to `my_linter.test.ts` to exercise your linter and generate + snapshots. Refer to [Testing Guidelines](tests/README.md) for more information on writing and running tests. -6. Run `trunk check` to lint your changes. -7. Open a PR! +7. Run `trunk check` to lint your changes. +8. Open a PR! [custom linters]: https://docs.trunk.io/docs/check-custom-linters [custom parsers]: https://docs.trunk.io/docs/custom-parsers @@ -105,7 +108,7 @@ To add a new action: actions/ └─my-action/ │ plugin.yaml - └─readme.md + └─README.md ``` 3. Add your action definition to `plugin.yaml` (consult the docs on [actions] to understand how it @@ -116,17 +119,50 @@ To add a new action: verify that the configuration is valid and that you get desired results. Running `trunk actions history ` can help provide greater insights when debugging. 6. We have not yet defined a testing framework for plugin actions, but we are working to add one - soon! Please briefly document your action in its readme.md and in your PR. + soon! Please briefly document your action in its README.md and in your PR. 7. Run `trunk check` to lint your changes. 8. Open a PR! [actions]: https://docs.trunk.io/docs/actions +## Tools + +If the tool you intend to add functions primarily as a linter, please follow the instruction in +[linters](#linters). If it functions more as a standalone tool, please add it in the `tools/` +directory and follow the instructions below. + +To add a new tool: + +1. Run `trunk check` to start up Trunk in the background. +2. Create a directory inside `tools/` with the name of your new linter. +3. Inside this new directory, create the following structure. Most of these files will be + automatically created for you: + + ```text + tests/ + └─my-tool/ + │ plugin.yaml + │ my_tool.test.ts + └─README.md (optional) + ``` + +4. Add your tool definition to `plugin.yaml` (consult the docs for + [custom tools](https://docs.trunk.io/tools/configuration#tool-definitions) to understand how it + should be defined). +5. Making sure the plugin in [`.trunk/trunk.yaml`](.trunk/trunk.yaml) is pointing to your local + repository, run `trunk tools enable ` to enable your tool, and access its shim(s) to run + it from `.trunk/tools/`. +6. Add a `toolInstallTest` to `my_tool.test.ts` to verify your tool's installation. If neccessary, + use `toolTest` instead. Refer to [Testing Guidelines](tests/README.md) for more information on + writing and running tests. +7. Run `trunk check` to lint your changes. +8. Open a PR! + ## Guidelines Please follow the guidelines below when contributing: -- After defining a new linter or action, please add it to [`readme.md`](readme.md). +- After defining a new linter or action, please add it to [`README.md`](README.md). - If you run into any problems while defining new linters or actions, feel free to reach out on our [Slack](https://slack.trunk.io/). We are continuously working to improve the process of integrating with trunk, and all feedback is appreciated! diff --git a/readme.md b/README.md similarity index 95% rename from readme.md rename to README.md index 64920f128..7a7109f12 100644 --- a/readme.md +++ b/README.md @@ -18,12 +18,13 @@ plugins: sources: - id: trunk uri: https://github.com/trunk-io/plugins - ref: v0.0.21 + ref: v1.2.5 ``` This repo is open to contributions! See our [contribution guidelines](https://github.com/trunk-io/plugins/blob/main/contributing.md) and join -our [slack community][slack] for help. +our [slack community][slack] for help. **If you're adding new tools, please see our +[testing guide](tests/README.md) as well!** ### Supported Linters, Formatters, and Security Tools @@ -130,7 +131,7 @@ trunk check enable {linter} [perlcritic]: https://metacpan.org/pod/Perl::Critic [perltidy]: https://metacpan.org/dist/Perl-Tidy/view/bin/perltidy [pmd]: https://pmd.github.io/ -[pragma-once]: linters/pragma-once/readme.md +[pragma-once]: linters/pragma-once/README.md [prettier]: https://github.com/prettier/prettier#readme [pre-commit-hooks]: https://pre-commit.com/hooks.html [prisma]: https://github.com/prisma/prisma#readme @@ -200,19 +201,24 @@ trunk actions enable {action} | action | description | | -------------------------------------------------------------------- | ---------------------------------------------------------- | -| [`buf-gen`](actions/buf/readme.md) | run `buf` on .proto file change | +| [`buf-gen`](actions/buf/README.md) | run `buf` on .proto file change | | [`commitlint`](https://github.com/conventional-changelog/commitlint) | enforce conventional commit message for your local commits | -| [`go-mod-tidy`](actions/go-mod-tidy/readme.md) | automatically tidy go.mod file | -| [`go-mod-tidy-vendor`](actions/go-mod-tidy-vendor/readme.md) | automatically tidy and vendor go.mod file | -| [`git-blame-ignore-revs`](actions/git-blame-ignore-revs/readme.md) | automatically configure git to use .git-blame-ignore-revs | -| [`npm-check`](actions/npm-check/readme.md) | check whether NPM installation is up to date | -| [`yarn-check`](actions/yarn-check/readme.md) | check whether Yarn installation is up to date | +| [`go-mod-tidy`](actions/go-mod-tidy/README.md) | automatically tidy go.mod file | +| [`go-mod-tidy-vendor`](actions/go-mod-tidy-vendor/README.md) | automatically tidy and vendor go.mod file | +| [`git-blame-ignore-revs`](actions/git-blame-ignore-revs/README.md) | automatically configure git to use .git-blame-ignore-revs | +| [`npm-check`](actions/npm-check/README.md) | check whether NPM installation is up to date | +| [`yarn-check`](actions/yarn-check/README.md) | check whether Yarn installation is up to date | + +### Supported Tools + +This repository also defines configuration for Trunk Tools, which provides hermetic management of +different CLI tools. You can read more about it in our [docs](https://docs.trunk.io/tools). ### Mission Our goal is to make engineering faster, more efficient and dare we say - more fun. This repository will hopefully allow our community to share ideas on the best tools and best practices/workflows to -make everyone's job of building code a little bit easier, a little bit faster and maybe in the +make everyone's job of building code a little bit easier, a little bit faster, and maybe in the process - a little bit more fun. ### Additional Reference diff --git a/actions/buf/readme.md b/actions/buf/README.md similarity index 100% rename from actions/buf/readme.md rename to actions/buf/README.md diff --git a/actions/buf/plugin.yaml b/actions/buf/plugin.yaml index af7928a23..4b24f2b38 100644 --- a/actions/buf/plugin.yaml +++ b/actions/buf/plugin.yaml @@ -4,8 +4,7 @@ actions: - id: buf-gen display_name: Buf generate description: - Run 'buf generate' anytime a .proto file changes. Must have a buf.work.yaml to work - properly. + Run 'buf generate' anytime a .proto file changes. Must have a buf.work.yaml to work properly run: buf generate triggers: - files: ["**/*.proto", buf.gen.yaml, buf.work.yaml] diff --git a/actions/commitlint/readme.md b/actions/commitlint/README.md similarity index 100% rename from actions/commitlint/readme.md rename to actions/commitlint/README.md diff --git a/actions/commitlint/plugin.yaml b/actions/commitlint/plugin.yaml index 858138fc5..f25599c3e 100644 --- a/actions/commitlint/plugin.yaml +++ b/actions/commitlint/plugin.yaml @@ -2,6 +2,8 @@ version: 0.1 actions: definitions: - id: commitlint + display_name: Commitlint + description: Enforce git commit message standards runtime: node packages_file: package.json run: commitlint --edit ${1} diff --git a/actions/git-blame-ignore-revs/readme.md b/actions/git-blame-ignore-revs/README.md similarity index 100% rename from actions/git-blame-ignore-revs/readme.md rename to actions/git-blame-ignore-revs/README.md diff --git a/actions/git-blame-ignore-revs/plugin.yaml b/actions/git-blame-ignore-revs/plugin.yaml index 904d66b61..5d5fe38b7 100644 --- a/actions/git-blame-ignore-revs/plugin.yaml +++ b/actions/git-blame-ignore-revs/plugin.yaml @@ -3,7 +3,7 @@ actions: definitions: - id: git-blame-ignore-revs display_name: Auto-enable .git-blame-ignore-revs - description: Automatically configure git to use .git-blame-ignore-revs while the file exists. + description: Automatically configure git to use .git-blame-ignore-revs while the file exists run: bash ${cwd}/update_config.sh triggers: - files: [.git-blame-ignore-revs] diff --git a/actions/go-mod-tidy-vendor/readme.md b/actions/go-mod-tidy-vendor/README.md similarity index 100% rename from actions/go-mod-tidy-vendor/readme.md rename to actions/go-mod-tidy-vendor/README.md diff --git a/actions/go-mod-tidy-vendor/plugin.yaml b/actions/go-mod-tidy-vendor/plugin.yaml index fff1544e7..5d9c13818 100644 --- a/actions/go-mod-tidy-vendor/plugin.yaml +++ b/actions/go-mod-tidy-vendor/plugin.yaml @@ -3,7 +3,7 @@ actions: definitions: - id: go-mod-tidy-vendor display_name: Go Mod Tidy & Vendor - description: Runs go mod tidy followed by go mod vendor. + description: Runs go mod tidy followed by go mod vendor runtime: go run: bash ${plugin}/actions/go-mod-tidy-vendor/go-mod-tidy-vendor.sh triggers: diff --git a/actions/go-mod-tidy/readme.md b/actions/go-mod-tidy/README.md similarity index 100% rename from actions/go-mod-tidy/readme.md rename to actions/go-mod-tidy/README.md diff --git a/actions/go-mod-tidy/plugin.yaml b/actions/go-mod-tidy/plugin.yaml index 9b7c60fb3..0c968c457 100644 --- a/actions/go-mod-tidy/plugin.yaml +++ b/actions/go-mod-tidy/plugin.yaml @@ -3,7 +3,7 @@ actions: definitions: - id: go-mod-tidy display_name: Go Mod Tidy - description: Runs go mod tidy when changes are detected to go.mod. + description: Runs go mod tidy when changes are detected to go.mod runtime: go run: go mod tidy triggers: diff --git a/actions/hello-world/python/readme.md b/actions/hello-world/python/README.md similarity index 100% rename from actions/hello-world/python/readme.md rename to actions/hello-world/python/README.md diff --git a/actions/hello-world/python/plugin.yaml b/actions/hello-world/python/plugin.yaml index 1ecb17c2d..8f728e01e 100644 --- a/actions/hello-world/python/plugin.yaml +++ b/actions/hello-world/python/plugin.yaml @@ -3,7 +3,7 @@ actions: definitions: - id: hello-world-python display_name: Hello World - description: prints 'Hello World' to the terminal during pre-commit trigger + description: Prints 'Hello World' to the terminal during pre-commit trigger runtime: python packages_file: requirements.txt run: python3 ${cwd}/hello # {cwd} resolves to current directory containing this plugin.yaml file diff --git a/actions/npm-check-pre-push/plugin.yaml b/actions/npm-check-pre-push/plugin.yaml index 4d8505d15..73fa1ad6a 100644 --- a/actions/npm-check-pre-push/plugin.yaml +++ b/actions/npm-check-pre-push/plugin.yaml @@ -3,6 +3,7 @@ actions: definitions: - id: npm-check-pre-push display_name: NPM Check + description: Generate notifications if node_modules are out of date as a pre-push hook runtime: node packages_file: package.json triggers: diff --git a/actions/npm-check/readme.md b/actions/npm-check/README.md similarity index 100% rename from actions/npm-check/readme.md rename to actions/npm-check/README.md diff --git a/actions/npm-check/plugin.yaml b/actions/npm-check/plugin.yaml index 08e8c0258..d55a6fcb2 100644 --- a/actions/npm-check/plugin.yaml +++ b/actions/npm-check/plugin.yaml @@ -3,6 +3,7 @@ actions: definitions: - id: npm-check display_name: NPM Check + description: Generate notifications if node_modules are out of date runtime: node packages_file: package.json triggers: diff --git a/actions/yarn-check/readme.md b/actions/yarn-check/README.md similarity index 100% rename from actions/yarn-check/readme.md rename to actions/yarn-check/README.md diff --git a/actions/yarn-check/plugin.yaml b/actions/yarn-check/plugin.yaml index 02f86ea57..296aa58d3 100644 --- a/actions/yarn-check/plugin.yaml +++ b/actions/yarn-check/plugin.yaml @@ -3,6 +3,7 @@ actions: definitions: - id: yarn-check display_name: Yarn Check + description: Generate notifications if node_modules are out of date runtime: node packages_file: package.json triggers: diff --git a/linters/ansible-lint/readme.md b/linters/ansible-lint/README.md similarity index 100% rename from linters/ansible-lint/readme.md rename to linters/ansible-lint/README.md diff --git a/linters/ansible-lint/ansible_lint.test.ts b/linters/ansible-lint/ansible_lint.test.ts index 31620c210..896f5cba6 100644 --- a/linters/ansible-lint/ansible_lint.test.ts +++ b/linters/ansible-lint/ansible_lint.test.ts @@ -24,7 +24,7 @@ const preCheck = driver.moveFile(path.join(TEST_DATA, "jboss-standalone"), "jboss-standalone"); - // See linters/ansible-lint/readme.md for details on non-FQCN support + // See linters/ansible-lint/README.md for details on non-FQCN support if (!fqcn) { const configFile = "jboss-standalone/demo-aws-launch.yml"; driver.writeFile( diff --git a/linters/autopep8/plugin.yaml b/linters/autopep8/plugin.yaml index 324418ba2..97bcffcbd 100644 --- a/linters/autopep8/plugin.yaml +++ b/linters/autopep8/plugin.yaml @@ -4,9 +4,9 @@ tools: - name: autopep8 runtime: python package: autopep8 - extra_packages: [pycodestyle@2.10.0] + extra_packages: [pycodestyle] shims: [autopep8] - known_good_version: 1.5.7 + known_good_version: 2.0.4 lint: definitions: - name: autopep8 @@ -29,7 +29,7 @@ lint: - setup.cfg - tox.ini issue_url_format: https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes - known_good_version: 1.5.7 + known_good_version: 2.0.4 version_command: parse_regex: autopep8 ${semver} run: autopep8 --version diff --git a/linters/autopep8/test_data/autopep8_v1.5.7_basic.fmt.shot b/linters/autopep8/test_data/autopep8_v2.0.4_basic.fmt.shot similarity index 100% rename from linters/autopep8/test_data/autopep8_v1.5.7_basic.fmt.shot rename to linters/autopep8/test_data/autopep8_v2.0.4_basic.fmt.shot diff --git a/linters/nancy/test_data/readme.md b/linters/nancy/test_data/README.md similarity index 100% rename from linters/nancy/test_data/readme.md rename to linters/nancy/test_data/README.md diff --git a/linters/pragma-once/readme.md b/linters/pragma-once/README.md similarity index 100% rename from linters/pragma-once/readme.md rename to linters/pragma-once/README.md diff --git a/linters/pre-commit-hooks/Readme.md b/linters/pre-commit-hooks/README.md similarity index 100% rename from linters/pre-commit-hooks/Readme.md rename to linters/pre-commit-hooks/README.md diff --git a/linters/sourcery/readme.md b/linters/sourcery/README.md similarity index 100% rename from linters/sourcery/readme.md rename to linters/sourcery/README.md diff --git a/linters/trufflehog/plugin.yaml b/linters/trufflehog/plugin.yaml index 8e1f142cb..c8dd95d05 100644 --- a/linters/trufflehog/plugin.yaml +++ b/linters/trufflehog/plugin.yaml @@ -75,11 +75,16 @@ lint: parse_regex: trufflehog ${semver} run: trufflehog --version +# This action runs trufflehog-git as a pre-commit hook in order to make sure that secrets don't show up in individual commits, +# as opposed to the primary trufflehog linter integration, which is not git-aware. In order to run this action, you must also run +# 'trunk check enable trufflehog-git' actions: definitions: - id: trufflehog-pre-commit - description: Don't allow secrets in commits (via Trufflehog) display_name: Trufflehog Pre-Commit Hook + description: + Don't allow secrets in commits (via Trufflehog). Enable linter 'trufflehog-git' before + running run: trunk check -t "git-commit" --upstream=HEAD --filter=trufflehog-git interactive: optional triggers: diff --git a/repo-tools/linter-test-helper/generate b/repo-tools/linter-test-helper/generate index ac86a4ec8..d8cb01f5c 100755 --- a/repo-tools/linter-test-helper/generate +++ b/repo-tools/linter-test-helper/generate @@ -52,7 +52,7 @@ INITIAL_TEST_CONTENTS = """import { linterCheckTest, linterFmtTest } from "tests // - By default, linters and formatters will only run on files with syntax `.in.` // - You can customize test setup using the `preCheck` callback (see git_diff_check.test.ts and golangci_lint.test.ts) // - You can specify additional customization using the `customLinterCheckTest and customLinterFmtTest` helpers -// - Additional information on test setup can be found in tests/readme.md +// - Additional information on test setup can be found in tests/README.md // // If you are unable to write a test for this linter, please document why in your PR, and add // it to the list in tests/repo_tests/test_coverage_test.ts diff --git a/runtimes/readme.md b/runtimes/README.md similarity index 100% rename from runtimes/readme.md rename to runtimes/README.md diff --git a/tests/readme.md b/tests/README.md similarity index 86% rename from tests/readme.md rename to tests/README.md index d945a59be..507d8e8b9 100644 --- a/tests/readme.md +++ b/tests/README.md @@ -1,5 +1,7 @@ # Testing +To run tests and generate snapshots, run `npm install` and `npm test `. + ## Overview We ask that all new linter definitions in this repository add some basic testing. This should be a @@ -15,13 +17,13 @@ linters/ └─my-linter/ │ plugin.yaml │ my_linter.test.ts - │ readme.md (optional) + │ README.md (optional) │ my-config.json (optional) └─test_data/ └─basic.in.py (with appropriate extension) ``` -- Specify a `readme.md` if your linter integration requires additional explanation or configuration. +- Specify a `README.md` if your linter integration requires additional explanation or configuration. - Specify a `my-config.json` (or whatever `direct_configs` item applies) ONLY if providing this config file is sufficient to enable your linter in ALL cases. This will be created whenever someone enables your linter. @@ -33,14 +35,14 @@ linters/ the tests will run the following command against your input file: ```bash - trunk check ${path_to_input_file} --force --filter=${my_linter} --output=json + trunk check --force --filter= --output=json ``` - For formatters, specify a sample input file (with an appropriate file extension). For reference, the tests will essentially run the following command against your input file: ```bash - cat ${path_to_input_file} | trunk format-stdin ${path_to_input_file} --filter=${my_linter} + trunk fmt --force --filter= ``` Refer to [sqlfluff](../linters/sqlfluff) or [pragma-once](../linters/pragma-once) as testing @@ -57,7 +59,7 @@ npm test To run an individual test, run: ```bash -npm test ${path_to_linter_subdir} +npm test ``` Then, verify that the generated snapshot file includes the results you would expect (e.g. an Object @@ -80,7 +82,7 @@ specified (See [Environment Overrides](#environment-overrides)). If this causes the test to fail when run with the latest version, this is most likely because there are discrepancies in the linter output across versions. Rather than running `npm test -- -u`, -**instead run** `PLUGINS_TEST_UPDATE_SNAPSHOTS=true npm test ${path_to_failing_test}`. This will +**instead run** `PLUGINS_TEST_UPDATE_SNAPSHOTS=true npm test `. This will create an additional snapshot for the latest version and is used to track historical test behavior and ensure compatibility with trunk across multiple linter versions. @@ -94,8 +96,8 @@ The process of resolving snapshots for asserting output correctness is as follow 2. If `PLUGINS_TEST_UPDATE_SNAPSHOTS` is truthy, the enabled version of the linter is used, and if a snapshot with this version does not exist, a new snapshot is created. 3. Otherwise, use the most recent snapshot version that precedes the enabled version of the linter. - If such a snapshot does not exist, a new snapshot is created with the enabled version of the - linter (use [debug logging](#debugging) to see what version was enabled). + If no such snapshot exists, a new snapshot is created with the enabled version of the linter (use + [debug logging](#debugging) to see what version was enabled). The reasoning for this setup is threefold: @@ -114,9 +116,10 @@ The reasoning for this setup is threefold: ### System Prereqs -trunk is [compatible](https://docs.trunk.io/docs/compatibility) with most versions of Linux and -macOS. If your linter only runs on certain OSs, refer to the example of -[stringslint](linters/stringslint/stringslint.test.ts) to skip OS-dependent test runs. +Trunk is [compatible](https://docs.trunk.io/cli/compatibility) with Linux and macOS. Trunk is also +in beta on [Windows](https://docs.trunk.io/cli/windows-beta). If your linter only runs on certain +OSs, refer to the example of [stringslint](linters/stringslint/stringslint.test.ts) to skip +OS-dependent test runs. ### Test Configuration @@ -142,7 +145,7 @@ include: ### CI -PRs will run 5 types of tests across both ubuntu and macOS as applicable: +PRs will run 5 types of tests across all platforms as applicable: 1. Enable and test all linters with their `known_good_version`, if applicable. To replicate this behavior, run: `PLUGINS_TEST_LINTER_VERSION=KnownGoodVersion npm test`. If the @@ -152,7 +155,7 @@ PRs will run 5 types of tests across both ubuntu and macOS as applicable: run: `npm test`. 3. Assert that all linters pass config validation. This is also validated while running: `npm test`. 4. Assert that all linters have test coverage. -5. Assert that all linters are included in the [`readme.md`](../readme.md). +5. Assert that all linters are included in the [`README.md`](../README.md). ### Debugging diff --git a/tests/repo_tests/readme_inclusion.test.ts b/tests/repo_tests/readme_inclusion.test.ts index 33841d1d4..c6a6dd452 100644 --- a/tests/repo_tests/readme_inclusion.test.ts +++ b/tests/repo_tests/readme_inclusion.test.ts @@ -5,23 +5,23 @@ import { REPO_ROOT } from "tests/utils"; const excludedLinters: string[] = []; const abbreviationMapping = new Map([["iwyu", "include-what-you-use"]]); -const readmeContents = fs.readFileSync(path.resolve(REPO_ROOT, "readme.md"), { encoding: "utf-8" }); +const readmeContents = fs.readFileSync(path.resolve(REPO_ROOT, "README.md"), { encoding: "utf-8" }); const readmeTableContents = readmeContents.substring( readmeContents.indexOf("### Supported Linters"), readmeContents.indexOf("### Supported Trunk Actions"), ); const reducedReadmeContents = readmeTableContents ? readmeTableContents : readmeContents; -// This test asserts that all linters are included in the root readme.md. This does not cover subcommands, and it assumes one +// This test asserts that all linters are included in the root README.md. This does not cover subcommands, and it assumes one // directory per linter. Name mapping can be achieved through `abbreviationMapping`. -describe("All linters must be included in readme.md", () => { +describe("All linters must be included in README.md", () => { // Find all linter subdirectories const linterDir = path.resolve(REPO_ROOT, "linters"); const linters = fs .readdirSync(linterDir) .filter((file) => fs.lstatSync(path.resolve(linterDir, file)).isDirectory()); - // Assert that each linter subdirectory is included in the repo's readme.md + // Assert that each linter subdirectory is included in the repo's README.md linters .filter((linter) => !excludedLinters.includes(linter)) .forEach((linter) => { diff --git a/tests/repo_tests/test_coverage.test.ts b/tests/repo_tests/test_coverage.test.ts index 99579f1df..a74e1d051 100644 --- a/tests/repo_tests/test_coverage.test.ts +++ b/tests/repo_tests/test_coverage.test.ts @@ -8,7 +8,7 @@ import { REPO_ROOT } from "tests/utils"; const excludedLinters: string[] = []; // This test asserts that all linters have at least one test. All new linters are expected to have -// test coverage. Review tests/readme.md for testing guidelines. Prefer using npm test for indirection +// test coverage. Review tests/README.md for testing guidelines. Prefer using npm test for indirection // in this test so that we get an accurate list of all tests, regardless of any changes to the test spec // in jest.config.json. describe("All linters must have tests", () => { diff --git a/tests/utils/index.ts b/tests/utils/index.ts index 054ecea39..56a2cceaf 100644 --- a/tests/utils/index.ts +++ b/tests/utils/index.ts @@ -80,7 +80,7 @@ if ( * - linterName is required because a user could define multiple linters and have them run on the same target * - prefix is required because a user could have a linter run on multiple targets (the driver currently is one target each) * - checkType is required because a linter could have lint and fix subcommands and run on the same target - * - linterVersion is required because of linter changes (see tests/readme.md) + * - linterVersion is required because of linter changes (see tests/README.md) * In the future we may want to segment these by directories for each test case/target, but for now we keep everything * proximally located for clarity and simplicity. * The check and fmt versions may not have the same count, since formatters tend to be more stable than linter diagnostics. @@ -207,7 +207,7 @@ export const getVersionsForTest = ( // Check if no snapshots exist yet. If this is the case, run with KnownGoodVersion and Latest, and print advisory text. if (!matchExists && !ARGS.linterVersion) { console.log( - `No snapshots detected for ${linterName} ${prefix} ${checkType} test. Running test against KnownGoodVersion. See tests/readme.md for more information.`, + `No snapshots detected for ${linterName} ${prefix} ${checkType} test. Running test against KnownGoodVersion. See tests/README.md for more information.`, ); return ["KnownGoodVersion"]; }