{"id":13647984,"url":"https://github.com/open-policy-agent/vscode-opa","last_synced_at":"2025-04-05T00:07:19.881Z","repository":{"id":43124451,"uuid":"125096565","full_name":"open-policy-agent/vscode-opa","owner":"open-policy-agent","description":"An extension for VS Code which provides support for OPA and the Rego policy language","archived":false,"fork":false,"pushed_at":"2025-03-31T10:10:29.000Z","size":2304,"stargazers_count":115,"open_issues_count":22,"forks_count":31,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-01T17:55:08.624Z","etag":null,"topics":["opa","open-policy-agent","policy-as-code","rego","vscode-extension"],"latest_commit_sha":null,"homepage":"https://openpolicyagent.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-policy-agent.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2018-03-13T18:25:52.000Z","updated_at":"2025-03-22T10:15:47.000Z","dependencies_parsed_at":"2024-01-14T10:17:22.084Z","dependency_job_id":"f3d9f8a5-bb17-44c3-aa4f-22aaec37d551","html_url":"https://github.com/open-policy-agent/vscode-opa","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-policy-agent%2Fvscode-opa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-policy-agent%2Fvscode-opa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-policy-agent%2Fvscode-opa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-policy-agent%2Fvscode-opa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-policy-agent","download_url":"https://codeload.github.com/open-policy-agent/vscode-opa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"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":["opa","open-policy-agent","policy-as-code","rego","vscode-extension"],"created_at":"2024-08-02T01:03:52.829Z","updated_at":"2025-04-05T00:07:19.860Z","avatar_url":"https://github.com/open-policy-agent.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# vscode-opa\n\nThis plugin provides a number of features to help you work with [Open Policy Agent](https://www.openpolicyagent.org)\n(OPA) policies in Visual Studio Code.\n\n\n## Features\n\n- Evaluate Packages\n- Evaluate Selections\n- Partially Evaluate Selections\n- Trace Selections\n- Profile Selections\n- Run Tests in Workspace\n- Toggle Coverage in Workspace\n- Toggle Coverage of Selections\n\nAdditionally, users may choose to install [Regal](https://docs.styra.com/regal), which adds the following features via the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP):\n\n- Diagnostics (linting)\n- Hover / tooltips (for inline docs on built-in functions)\n- Go to definition (ctrl/cmd + click on a reference to go to definition)\n- Folding ranges (expand/collapse blocks, imports, comments)\n- Document and workspace symbols (navigate to rules, functions, packages)\n- Inlay hints (show names of built-in function arguments next to their values)\n- Formatting (`opa fmt`, `opa fmt --rego-v1` or `regal fix`, see [Configuration](#configuration) below)\n- Code actions (quick fixes for linting issues)\n- Code completions\n- Code lenses (click to evaluate any package or rule in the editor, and have the result displayed directly on the same line)\n\nTo learn more about each language server feature, see the Regal [language server](https://docs.styra.com/regal/language-server) documentation.\n\n![Use of the extension to lint and eval Rego code](https://raw.githubusercontent.com/open-policy-agent/vscode-opa/main/eval.gif)\n\nRegal also adds the ability to debug Rego modules via the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) (DAP):\n\n- Launching `eval` debug sessions\n- Setting and halting on breakpoints\n- Stepping over, into, and out of rules, functions, every-statements, and comprehensions\n- Inspecting the `data` and `input` documents\n- Inspecting local variable values\n- Inspecting values in the Virtual Cache (global results of rule and function evaluations)\n\n\n## Requirements\n\n- This plugin requires the [Open Policy Agent](https://github.com/open-policy-agent/opa) executable (`opa`) to be installed in your $PATH. Alternatively, you can configure the `opa.dependency_paths.opa` setting to point to the executable. If you do not have OPA installed, the plugin will prompt you to install the executable the first time you evaluate a policy, run tests, etc.\n\n\n## Installation\n\nTo install the extension, visit the\n[Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=tsandall.opa)\nor search for \"Open Policy Agent\" in the 'Extensions' panel.\n\n\u003e [!TIP]\n\u003e This extension has built-in support for linting and hover tooltips\n\u003e through a native integration with [Regal](https://docs.styra.com/regal). See the\n\u003e ['Getting Started'](https://docs.styra.com/regal#getting-started) guide for more\n\u003e information about installing Regal.\n\n\n## Configuration\n\n| Field | Default | Description |\n| --- | --- | --- |\n| `opa.dependency_paths.opa` | `null` | Set path of OPA executable. If the path contains the string `${workspaceFolder}` it will be replaced with the current workspace root. E.g., if the path is set to `${workspaceFolder}/bin/opa` and the current workspace root is `/home/alice/project`, the OPA executable path will resolve to `/home/alice/project/bin/opa`. |\n| `opa.checkOnSave` | `false` | Enable automatic checking of .rego files on save. |\n| `opa.strictMode` | `false` | Enable [strict-mode](https://www.openpolicyagent.org/docs/latest/policy-language/#strict-mode) for the `OPA: Check File Syntax command`. |\n| `opa.roots` | `[${workspaceFolder}]` | List of paths to load as bundles for policy and data. Defaults to a single entry which is the current workspace root. The variable `${workspaceFolder}` will be resolved as the current workspace root. The variable `${fileDirname}` will be resolved as the directory of the file currently opened in the active window. |\n| `opa.bundleMode`  | `true`  | Enable treating the workspace as a bundle to avoid loading erroneous data JSON/YAML files. It is _NOT_ recommended to disable this. |\n| `opa.schema` | `null` | Path to the [schema](https://www.openpolicyagent.org/docs/latest/policy-language/#using-schemas-to-enhance-the-rego-type-checker) file or directory. If set to `null`, schema evaluation is disabled. As for `opa.roots`, `${workspaceFolder}` and `${fileDirname}` variables can be used in the path. |\n| `opa.languageServers` | `null` | An array of enabled language servers (currently `[\"regal\"]` is supported) |\n| `opa.env` | `{}` | Object of environment variables passed to the process running OPA (e.g. `{\"key\": \"value\"}`) |\n| `opa.formatter` | `opa-fmt` | Name of the OPA formatter to use. Requires Regal. One of `opa-fmt`, `opa-fmt-rego-v1` and `regal-fix`. This value is sent as an initialization option to the language server, so the change won't take effect before the project (or VS Code) is reloaded. See the documentation for the [regal fix](https://docs.styra.com/regal/fixing) command for more information |\n\nNote that the `${workspaceFolder}` variable will expand to a full URI of the workspace, as expected by most VS Code commands. The `${workspacePath}` variable may additionally be used where only the path component (i.e. without the `file://` schema component) of the workspace URI is required.\n\n\u003e For bundle documentation refer to [https://www.openpolicyagent.org/docs/latest/management/#bundle-file-format](https://www.openpolicyagent.org/docs/latest/management-bundles/#bundle-file-format).\n  Note that data files _MUST_ be named either `data.json` or `data.yaml`.\n\n\n### Using `opa.env` to set OPA command line flags\n\nFrom OPA v0.62.0 and onwards, it's possible to set any command line flag via environment variables as an alternative to arguments to the various `opa` commands. This allows using the `opa.env` object for setting any flag to the commmands executed by the extension. The format of the environment variables follows the pattern `OPA_\u003cCOMMAND\u003e_\u003cFLAG\u003e` where `COMMAND` is the command name in uppercase (like `EVAL`) and `FLAG` is the flag name in uppercase (like `IGNORE`). For example, to set the `--capabilities` flag for the `opa check` and `opa eval` command, use the following configuration in your `.vscode/settings.json` file:\n\n```json\n{\n    \"opa.env\": {\n        \"OPA_CHECK_CAPABILITIES\": \"${workspacePath}/misc/capabilities.json\",\n        \"OPA_EVAL_CAPABILITIES\": \"${workspacePath}/misc/capabilities.json\"\n    }\n}\n```\n\n\n## Tips\n\n\n### Set the `input` document by creating `input.json`\n\nThe extension will look for a file called `input.json` in the current directory of the policy file being evaluated, or at the root of the workspace, and will use it as the `input` document when evaluating policies. If you modify this file and re-run evaluation you will see the affect of the changes.\n\nThe [code lens evaluation](https://github.com/StyraInc/regal/blob/main/docs/language-server.md#code-lenses-evaluation) feature (with Regal installed) shows an \"Evaluate\" button over any package or rule declaration, which when clicked displays the result of evaluation directly on the same line as the package or rule. Providing input for this type of evaluation is done the same way, i.e. via an `input.json` file.\n\nWe recommend adding `input.json` to the `.gitignore` file of your project, so that you can evaluate policy anywhere without the risk of accidentally committing the input.\n\n\n### Bind keyboard shortcuts for frequently used commands\n\nOpen the keyboard shortcuts file (`keybindings.json`) for VS Code (⌘ Shift p → `Preferences: Open Keyboard Shortcuts File`) and add the following JSON snippets.\n\nBind the `OPA: Evaluate Selection` command to a keyboard shortcut (e.g., ⌘ e) to quickly evaluate visually selected blocks in the policy.\n\n```json\n{\n    \"key\": \"cmd+e\",\n    \"command\": \"opa.eval.selection\",\n    \"when\": \"editorLangId == rego\"\n}\n```\n\nBind the `OPA: Evaluate Package` command to a keyboard shortcut (e.g., ⌘ Shift a) to quickly evaluate the entire package and see all of the decisions.\n\n```json\n{\n    \"key\": \"shift+cmd+a\",\n    \"command\": \"opa.eval.package\",\n    \"when\": \"editorLangId == rego\"\n}\n```\n\n\n### Loading arbitrary JSON/YAML as data\n\nIf unable to use `data.json` or `data.yaml` files with `opa.bundleMode` enabled\nyou can disable the configuration option and _ALL_ `*.json` and `*.yaml` files\nwill be loaded from the workspace.\n\n\n### Disabling linting\n\nIf you want to disable linting for a specific workspace while retaining the other features Regal provides — for example when working with code that you can't change — you can do so by providing a `.regal/config.yaml` file at the root of the workspace. To disable linting entirely, your config file could look like this:\n\n```yaml\nrules:\n  default:\n    level: ignore\n```\n\nRegal additionally scans for a `.regal/config.yaml` file _above_ the workspace, which can be used to disable linting for all workspaces that inherit from it, or to use a common configuration file across multiple workspaces.\n\n\n## Debugging OPA command evaluation\n\nIn case some command isn't behaving as you expect, you can see exactly what command was executed by opening the developer tools from the **Help** menu and check the **Console** tab.\n\n\n## Development\n\nIf you want to hack on the extension itself, you should clone this repository, install the dependencies (`npm install --include=dev`) and use Visual Studio Code's Debugger (F5) to test your changes.\n\n\n## ROADMAP\n\n- [x] highlight syntax errors in file (available when using Regal language server)\n- [ ] run `opa test` on package instead of entire workspace\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-policy-agent%2Fvscode-opa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-policy-agent%2Fvscode-opa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-policy-agent%2Fvscode-opa/lists"}