Cleanup contributing copy and streamline repo styling

.trunk/trunk.yaml

@@ -20,7 +20,27 @@ plugins:
       ref: v1.0.4
 
 lint:
-  # enabled linters inherited from github.com/trunk-io/configs plugin
+  files:
+    - name: plugin.yaml
+      filenames: [plugin.yaml]
+  definitions:
+    - name: definition-checker
+      description: Checks plugin.yaml files for repo best practices
+      files: [plugin.yaml]
+      runtime: node
+      extra_packages:
+        - ts-node
+        - yaml
+      commands:
+        - name: check
+          run: ts-node ${workspace}/repo-tools/definition-checker/check.ts ${target}
+          batch: true
+          output: regex
+          parse_regex: "((?P<path>.*) \\[(?P<severity>.*)\\]: (?P<message>.*) \\((?P<code>.*)\\))"
+          success_codes: [0]
+  enabled:
+    # enabled linters inherited from github.com/trunk-io/configs plugin
+    - definition-checker
   disabled:
     - pylint # pylint diagnostics are too strict
     - semgrep

CONTRIBUTING.md

@@ -1,18 +1,24 @@
 # Contribution
 
-Thanks for contributing to trunk's default plugins! Read on to learn more.
+Thanks for contributing to Trunk's default plugins! Read on to learn more.
 
+- [Prerequisites](#prerequisites)
 - [Overview](#overview)
-- [Release process](#releases)
 - [Adding new linters](#linters)
-- [Adding new actions](#actions)
 - [Adding new tools](#tools)
+- [Adding new actions](#actions)
+- [Release process](#releases)
 - [Guidelines](#guidelines)
 - [Docs](https://docs.trunk.io)
 
+## Prerequisites
+
+1. Please [install the trunk CLI](https://docs.trunk.io/check/usage#install-the-cli)
+2. Run `trunk check` in this repo to quickstart git-hooks and codegen
+
 ## Overview
 
-We use this repository to provide our users with default linters, actions, and tools. Trunk
+We use this repository to provide our users with default linters, tools, and actions. Trunk
 automatically adds the following to users' trunk.yaml:
 
 ```yaml
@@ -32,43 +38,24 @@ plugins:
       local: </path/to/repo/root>
 ```
 
-Adding a plugin source lets users run `trunk check enable` or `trunk actions enable` with linters
-and actions defined in that plugin. For more information, see our
+Adding a plugin source lets users run `trunk check enable`, `trunk tools enable`, or
+`trunk actions enable` with definitions in that plugin. For more information, see our
 [docs](https://docs.trunk.io/docs/plugins).
 
+**Please review our [Testing Guide](tests/README.md) for info on writing and running tests.**
+
 If you have questions, please [stop by our community Slack](https://slack.trunk.io/), and if you
 have a feature request, you can [file it here](https://features.trunk.io/).
 
-## Releases
-
-`trunk-io/plugins` is released on a fairly regular cadence that is independent of PRs. Users will
-pick up these configuration changes by running `trunk upgrade` to automatically update their plugin
-version to the latest release.
-
-```yaml
-plugins:
-  sources:
-    - id: trunk
-      uri: https://github.com/trunk-io/plugins
-      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
-action that hasn't been released yet, you can set `ref` to be a git SHA. Do **not** set `ref` to be
-a branch name, or `HEAD`, as users will observe buggy behavior.
-
-Note that the ref and the cli version in the trunk.yaml must be compatible. This is managed by
-`required_trunk_version`, as specified in [`plugin.yaml`](plugin.yaml). Users will not be able to
-load a plugin source until they have upgraded to a compliant CLI version.
-
 ## Linters
 
 To add a new linter:
 
 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:
+2. Run `mkdir linters/<my-linter>` to start. This should autopopulate with a sample
+   [plugin.yaml](./repo-tools/linter-test-helper/linter_sample_plugin.yaml) and
+   [test file](./repo-tools/linter-test-helper/linter_sample.test.ts). If necessary, add them
+   yourself:
 
    ```text
    linters/
@@ -78,25 +65,57 @@ To add a new linter:
      │ README.md (optional)
      │ my-config.json (optional)
      └─test_data/
-        └─basic.in.py (with appropriate extension)
+        └─basic.in.foo (with appropriate extension)
    ```
 
-4. Add your linter definition to `plugin.yaml` (consult the docs for [custom linters] and [custom
+3. 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 <my-linter>` 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.
-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.
-7. Run `trunk check` to lint your changes.
-8. Open a PR!
+4. Run `trunk check enable <my-linter>` 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. You may also wish to run on your test data,
+   i.e. `trunk check --verbose --force linters/<my-linter>/test_data/basic.in.foo`.
+5. Add a few simple test cases to `my_linter.test.ts` to exercise your linter and generate
+   snapshots. View our [Testing Guide](tests/README.md) for more information on writing, running,
+   and debugging tests.
+6. Revert any `.trunk/trunk.yaml` changes, and run `trunk check` to lint your changes.
+7. Open a PR!
 
 [custom linters]: https://docs.trunk.io/check/custom-linters
 [custom parsers]: https://docs.trunk.io/check/custom-parsers
 
+## 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. Run `mkdir tools/<my-tool>` to start. This should autopopulate with a sample
+   [plugin.yaml](./repo-tools/tool-test-helper/tool_sample_plugin.yaml) and
+   [test file](./repo-tools/tool-test-helper/tool_sample.test.ts). If necessary, add them yourself:
+
+   ```text
+   tests/
+   └─my-tool/
+     │ plugin.yaml
+     │ my_tool.test.ts
+     └─README.md (optional)
+   ```
+
+3. 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).
+4. Run `trunk tools enable <my-tool>` to enable your tool, and run its shim(s) from
+   `.trunk/tools/<tool-name>`.
+5. Add a `toolInstallTest` to `my_tool.test.ts` to verify your tool's installation. If neccessary,
+   use `toolTest` instead. Refer to the [Testing Guide](tests/README.md) for more information on
+   writing, running, and debugging tests.
+6. Revert any `.trunk/trunk.yaml` changes, and run `trunk check` to lint your changes.
+7. Open a PR!
+
 ## Actions
 
 To add a new action:
@@ -118,54 +137,44 @@ To add a new action:
    `trunk actions enable <my-action>` to enable your linter, and run `trunk run <my-action>` to
    verify that the configuration is valid and that you get desired results. Running
    `trunk actions history <my-action>` 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.
+6. Please briefly document your action in its README.md as appropriate.
 7. Run `trunk check` to lint your changes.
 8. Open a PR!
 
-[actions]: https://docs.trunk.io/actions
+Testing for Trunk Actions in this repo is in early development, so we do not require testing for new
+action definitions.
 
-## Tools
+[actions]: https://docs.trunk.io/actions
 
-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.
+## Releases
 
-To add a new tool:
+`trunk-io/plugins` is released on every few weeks. Users will pick up these configuration changes by
+running `trunk upgrade` to automatically update their plugin version to the latest release.
 
-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:
+```yaml
+plugins:
+  sources:
+    - id: trunk
+      uri: https://github.com/trunk-io/plugins
+      ref: v1.2.5 # will change to the latest release on next `trunk upgrade`
+```
 
-   ```text
-   tests/
-   └─my-tool/
-     │ plugin.yaml
-     │ my_tool.test.ts
-     └─README.md (optional)
-   ```
+We recommend only setting the above `ref` field to be our released tags, but if you need a
+linter/tool/action that hasn't been released yet, you can set `ref` to be a git SHA. Do **not** set
+`ref` to be a branch name, as plugin branches are not refreshed.
 
-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 <my-tool>` to enable your tool, and access its shim(s) to run
-   it from `.trunk/tools/<tool-name>`.
-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!
+Note that the ref and the cli version in the trunk.yaml must be compatible. This is managed by
+`required_trunk_version`, as specified in [`plugin.yaml`](plugin.yaml). Users will not be able to
+load a plugin source until they have upgraded to a compliant CLI version.
 
 ## Guidelines
 
 Please follow the guidelines below when contributing:
 
 - 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!
+- If you run into any problems while defining new linters/tools/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!
 
 ## Development
 

README.md

@@ -10,20 +10,19 @@
 ### Welcome
 
 This repository is the official [Trunk.io](https://trunk.io/) repo containing Trunk's integrations
-for linters, formatters, security tools, githooks, and default configs. By default, all trunk users
+for linters, formatters, security tools, githooks, and default configs. By default, all Trunk users
 import this repo as a plugin, via this snippet in `.trunk/trunk.yaml`:
 
 ```yaml
 plugins:
   sources:
     - id: trunk
       uri: https://github.com/trunk-io/plugins
-      ref: v1.4.4
+      ref: v1.5.0
 ```
 
-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. **If you're adding new tools, please see our
+This repo is open to contributions! See our [contribution guidelines](CONTRIBUTING.md) and join 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

jest.config.json

@@ -2,5 +2,6 @@
   "preset": "ts-jest",
   "modulePaths": ["<rootDir>"],
   "setupFilesAfterEnv": ["<rootDir>/tests/jest_setup.ts"],
-  "reporters": ["<rootDir>/tests/reporter/index.js", "default"]
+  "reporters": ["<rootDir>/tests/reporter/index.js", "default"],
+  "testPathIgnorePatterns": ["<rootDir>/node_modules/", "<rootDir>/repo-tools/"]
 }

linters/pragma-once/pragma_once.test.ts

@@ -1,4 +1,4 @@
 import { linterFmtTest } from "tests";
 
-// TODO(Tyler): We will eventually need to add a couple more test cases involving failure modes and other autofixes.
+// A simple formatter test to run 'pragma-once' on 'test_data/basic.in.hh'
 linterFmtTest({ linterName: "pragma-once" });

linters/ruff/plugin.yaml

@@ -64,6 +64,7 @@ lint:
         run: ruff --version
 
     - name: ruff-nbqa
+      description: A Python linter for Jupyter notebooks
       files: [jupyter]
       commands:
         - name: lint

linters/sort-package-json/plugin.yaml

@@ -13,6 +13,7 @@ lint:
 
   definitions:
     - name: sort-package-json
+      description: Sorts package.json keys
       files: [package-json]
       commands:
         - name: format

linters/sqlfluff/sqlfluff.test.ts

@@ -1,5 +1,6 @@
 import { linterCheckTest, linterFmtTest, TestCallback } from "tests";
 
+// A simple test to run 'sqlfluff lint'
 // basic_check.out.json is the result of running:
 // trunk check linters/sqlfluff/test/basic_check.in.sql --force --filter=sqlfluff --output=json
 linterCheckTest({ linterName: "sqlfluff", namedTestPrefixes: ["basic_check"] });
@@ -11,10 +12,10 @@ const fmtCallbacks: TestCallback = (driver) => {
   const sqlfluffRegex = /- sqlfluff@(.+)\n/;
   const newContents = currentContents.replace(
     sqlfluffRegex,
-    "- sqlfluff@$1:\n        commands: [lint, fix]\n"
+    "- sqlfluff@$1:\n        commands: [lint, fix]\n",
   );
   driver.writeFile(trunkYamlPath, newContents);
 };
 
-// TODO(Tyler): We will eventually need to add a couple more test cases involving failure modes.
+// An additional test to run 'sqlfluff fmt' with some additional test setup.
 linterFmtTest({ linterName: "sqlfluff", namedTestPrefixes: ["basic_fmt"], preCheck: fmtCallbacks });

linters/trufflehog/plugin.yaml

@@ -49,6 +49,7 @@ lint:
 
     # Variant of trufflehog that scans git history.
     - name: trufflehog-git
+      description: Scan git history for secrets
       files: [ALL]
       download: trufflehog
       known_good_version: 3.59.0