{"id":19626105,"url":"https://github.com/deepsourcecorp/scatr","last_synced_at":"2025-04-28T05:33:12.685Z","repository":{"id":65051796,"uuid":"554238136","full_name":"DeepSourceCorp/SCATR","owner":"DeepSourceCorp","description":"Static Code Analysis Testing Framework which just works! ","archived":false,"fork":false,"pushed_at":"2023-08-28T10:56:19.000Z","size":75,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-05T11:59:09.267Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeepSourceCorp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-19T13:31:51.000Z","updated_at":"2024-10-28T16:48:11.000Z","dependencies_parsed_at":"2024-06-20T05:42:54.535Z","dependency_job_id":"d21be5e9-5cec-435d-9c0b-48471e76c247","html_url":"https://github.com/DeepSourceCorp/SCATR","commit_stats":null,"previous_names":["deepsourcecorp/scatr","deepsourcelabs/scatr"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepSourceCorp%2FSCATR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepSourceCorp%2FSCATR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepSourceCorp%2FSCATR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepSourceCorp%2FSCATR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeepSourceCorp","download_url":"https://codeload.github.com/DeepSourceCorp/SCATR/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224098460,"owners_count":17255506,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T11:44:58.986Z","updated_at":"2024-11-11T11:45:00.543Z","avatar_url":"https://github.com/DeepSourceCorp.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SCATR\n\nStatic Code Analysis Testing Framework which just works!\n\nSCATR is a simple framework to test static analyzers and Autofixers.\n\n[![DeepSource](https://deepsource.io/gh/deepsourcelabs/SCATR.svg/?label=active+issues\u0026show_trend=true\u0026token=l9MSP_TWMIT2_-Lr5cW4YdBl)](https://deepsource.io/gh/deepsourcelabs/SCATR/?ref=repository-badge)\n[![DeepSource](https://deepsource.io/gh/deepsourcelabs/SCATR.svg/?label=resolved+issues\u0026show_trend=true\u0026token=l9MSP_TWMIT2_-Lr5cW4YdBl)](https://deepsource.io/gh/deepsourcelabs/SCATR/?ref=repository-badge)\n\n## Getting Started\n\n### Installation\n\nIf you are on platforms where binaries are supported feel free to use the ones, provided in the releases.\n\nIn case you would like to install from source,\n\n```sh\n# make sure to install go from `go.dev`\n# clone the repo \ngit clone https://github.com/deepsourcelabs/SCATR\n\n# cd into the directory\ncd SCATR\n\n# build and install manually or use go install\ngo install ./cmd/scatr\n\n# ensure that $GOPATH is added to your paths\n# the default $GOPATH=/home/\u003cuser\u003e/go\n```\n\n### Usage\n\n`scatr` accepts a `.scatr.toml` as its configuration file.\n\n```toml\nfiles = \"*.go\"\ncomment_prefix = [\"//\"]\ncode_path = \"\"\nexcluded_dirs = []\n\n[checks]\nscript = \"\"\"\ngo run ./cmd/runner --output-file=./analysis_result.json\n\"\"\"\ninterpreter = \"sh\"\noutput_file = \"analysis_result.json\"\n\n[processor]\nskip_processing = false\nscript = \"process-results $INPUT_FILE\"\ninterpreter = \"sh\"\n\n[autofix]\nscript = \"\"\"\ngo run ./cmd/autofix\n\"\"\"\ninterpreter = \"sh\"\n```\n\n### `code_path`\n\nSCATR optionally accepts a configuration item `code_path` which is absolute,\nor a path relative to the `cwd`. When the `code_path` is specified, the runner\nexpects the file paths in the `analysis_results.json` (output from the\nprocessor) to either be absolute, or to be relative to the `code_path`. Same\ngoes for the `files` flag. Only the files in the `code_path` are tested.\n\n### `excluded_dirs`\n\nSCATR optionally also accepts a list of directories (absolute or relative to the\n`cwd`) from which results are excluded. Say, for example, an issue was raised\nin one of the excluded directories. SCATR will ignore matching any files inside\nthe `excluded_dirs`. The same applies to Autofix.\n\n## Testing Checks\n\nSCATR has two stages,\n\n1. The `run` stage which runs the provided script using the provided interpreter\n2. The `processor` stage which takes the `run` output and converts it into the\n   format compatible with SCATR\n\n### The `processor`\n\nThe processor is expected to convert the `run` `output_file` to a JSON-based\nformat `scatr` expects. It is expected to print the JSON to `stdout`. Just like\nthe runner, SCATR accepts an arbitrary script as a processor. The `output_file`\nfrom the `run` stage is passed as the `INPUT_FILE` environment variable.\n\nThe format that `scatr` expects is as follows:\n\n```json\n{\n  \"issues\": [\n    {\n      \"code\": \"ISSUE-CODE\",\n      \"title\": \"issue occurrence title\",\n      \"position\": {\n        \"file\": \"file.go\",\n        \"start\": {\n          \"line\": 9,\n          \"column\": 10\n        }\n      }\n    }\n  ]\n}\n```\n\nThe column numbers are optional.\n\n### Expected result pragma\n\nThe runner uses pragmas in comments to get a set of issues which are\nexpected to be raised. The pragmas are of the following format:\n\n```go\n// [ISSUE-CODE]: col-num \"title\"\n```\n\nHere the `col-num` (column number) and the `title` is optional. Pragmas\ncan be on the same line, or the previous line. Here is an example:\n\n```go\npackage main\n\nfunc main() {\n\ta := 10\n\t// [VET-V0002]: \"Useless assignment\"\n\ta = a\n\n\ta = a // [VET-V0002]: \"Useless assignment\"\n}\n```\n\nYou can chain multiple occurrences of the same issue by using a `,`.\nFor example,\n\n```go\n// [VET-V0002]: 9 \"Useless assignment (occurrence 1)\", \"occurrence 2\"\n```\n\nYou can also chain multiple issues in the same line using `;`. For\nexample,\n\n```go\npackage main\n\n// [VET-V0002]: \"Useless assignment\"; [SCC-U1000]: \"func foo is unused\"\nfunc foo() {}\n```\n\nPragma comments can optionally be split into multiple lines assuming that there\nare no other comments between the lines. For example, the following pragmas have\nthe same meaning:\n\n- ```javascript\n  const foo = true;\n  \n  // [JS-W0126]: \"Variables should not be initialized to undefined\"; [JS-0345]\n  const bar = foo === false ? undefined : \"baz\";\n  ```\n\n- ```javascript\n  const foo = true;\n  \n  // [JS-W0126]: \"Variables should not be initialized to undefined\"\n  // [JS-0345]\n  const bar = foo === false ? undefined : \"baz\";\n  ```\n\n- ```javascript\n  const foo = true;\n  \n  // [JS-W0126]: \"Variables should not be initialized to undefined\"\n  const bar = foo === false ? undefined : \"baz\"; // [JS-0345]\n  ```\n\nThe `comment_prefix` in the configuration file is used by the runner\nto determine the comments. It accepts a list of prefixes to use for pragma\nextraction. For example, it can be `//` for Go files, or `#` for Python files.\n\nThe `files` field is used by the runner to get a list of files to\nextract the pragmas from.\n\n## Testing Autofix\n\nSCATR uses \"golden files\" to test for Autofix. It is similar to how testing\nchecks work, although there is no `processor` stage involved as this Autofix'ed\nfiles are directly compared with \"golden files\", which basically are files that\ncontain the expected output after performing Autofix.\n\nGolden files use the same name as the test file, with the `.golden` suffix\nappended. For example, the golden file for `main.go` will be `main.go.golden`,\nand for `main.py`, it will be `main.py.golden`.\n\nSCATR uses the `files` glob pattern defined in the config along with the\n`.gitignore` in the directory root to create a snapshot of the current state\nin the `autofix-dir` (optionally provided as a flag). In case no `autofix-dir`\nflag is provided, SCATR expects the script to modify the files **in-place** and\nrestores the snapshot after the results have been calculated. After the snapshot\nhas been created, it runs the provided Autofix `script`. After the script is\ncompleted, SCATR calculates a `diff` from their `.golden` counterparts.\n\nIn case no `autofix-dir` has been provided, the snapshot and is only done\nagainst the `files` glob pattern, so the Autofix tool should be sure to not\nmodify something else, or it might lead to incorrect results and the modified\nfiles not being restored.\n\n## Running\n\nAfter creating a `.scatr.toml` file, you can simply run `scatr run`\nfor the test runner to run.\n\nSCATR sets the `CODE_PATH` environment variable to the provided `cwd` to SCATR\n(defaults to the OS current working directory) before running the `check` and\n`autofix` script. This is always an absolute path.\n\n### Flags\n\n- `-c`, or `--cwd`: used to set the current working directory of the runner.\n  All paths in other flags are relative to this. If not set, \".\" is used.\n- `-p`, or `--pretty`: enables or disable pretty printing. It defaults to\n  `false` for non-interactive environments.\n- `-v` or `--verbose`: enables verbose logging on `stderr`\n- `-f` or `--files`: an array of files to run the tests on. All other files\n  in the glob pattern specified in `.scatr.toml` are ignored. This should\n  be a subset of the glob pattern.\n- `-a` or `--autofix-dir`: specify the directory for Autofix tests. This is\n  where the Autofix tool is expected to produce its output. An absolute path\n  to the Autofix directory is exposed to the run script in the `OUTPUT_PATH`\n  environment variable. In the case where the Autofix directory is not\n  specified, it uses the current working directory. In this case, SCATR\n  creates a snapshot of the current working directory using the `files` glob\n  pattern and the root `.gitignore` and restores it after the results have\n  been calculated.\n\n## Development\n\nSCATR is built using [Go](https://go.dev). To hack on SCATR, you need a working\ninstallation of Go.\n\n### Directory Structure\n\n- `cmd` - The entrypoint for the CLI application\n- `pragma` - The pragma parser and the file reader\n- `runner` - Actual test runner responsible for running the `checks`,\n  `processor` and `autofix`, and for the result calculation\n  - `runner/testdata` - Data for testing the runner's capabilities\n    - `runner/testdata/checks` - Used for testing the `checks` result\n      calculation\n    - `runner/testdata/autofix` - Used for testing the `autofix` result\n      calculation\n    - `runner/testdata/backup` - Used for testing the backing up of Autofix'able\n      files\n    - `runner/testdata/backup_autofixdir` - Used for testing the backing up of\n      Autofix'able files when the `--autofix-dir` flag is specified\n    - `runner/testdata/config` - Used for testing the configuration handling and\n      the configuration defaults\n\n## License\n\nSCATR is licensed under the [MIT license](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepsourcecorp%2Fscatr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeepsourcecorp%2Fscatr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepsourcecorp%2Fscatr/lists"}