{"id":50939106,"url":"https://github.com/vltpkg/policies","last_synced_at":"2026-06-17T12:01:54.770Z","repository":{"id":340904718,"uuid":"1168109931","full_name":"vltpkg/policies","owner":"vltpkg","description":"GitHub Action to gate CI with dependency selectors powered by vlt","archived":false,"fork":false,"pushed_at":"2026-06-10T15:42:03.000Z","size":360,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T17:20:20.621Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/vltpkg.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-27T02:48:48.000Z","updated_at":"2026-06-10T15:46:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vltpkg/policies","commit_stats":null,"previous_names":["vltpkg/query-deps","vltpkg/action-query-deps","vltpkg/policies"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/vltpkg/policies","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fpolicies","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fpolicies/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fpolicies/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fpolicies/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vltpkg","download_url":"https://codeload.github.com/vltpkg/policies/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vltpkg%2Fpolicies/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34447266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2026-06-17T12:01:54.076Z","updated_at":"2026-06-17T12:01:54.763Z","avatar_url":"https://github.com/vltpkg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dependency Policies Action\n\nA GitHub Action for enforcing dependency policies with vlt. Gate your CI pipeline by checking for malware, outdated packages, license compliance, and more using powerful CSS-like selectors.\n\n![Policies Action](https://img.shields.io/badge/Policies-by%20vlt-purple)\n[![CI](https://github.com/vltpkg/policies/actions/workflows/ci.yml/badge.svg)](https://github.com/vltpkg/policies/actions/workflows/ci.yml)\n[![Integration Tests](https://github.com/vltpkg/policies/actions/workflows/test.yml/badge.svg)](https://github.com/vltpkg/policies/actions/workflows/test.yml)\n\n## Quick Start\n\n```yaml\n- name: Setup Node.js 22+\n  uses: actions/setup-node@v4\n  with:\n    node-version: '22'\n\n- name: Setup vlt\n  uses: vltpkg/setup-vlt@v1\n\n- name: Enforce Dependency Policies\n  uses: vltpkg/policies@v2\n  with:\n    queries: |\n      :malware --expect-results=0\n      :outdated --view=json\n      *:license(copyleft) --expect-results=0\n```\n\n## Features\n\n✅ **Security Gates** — Block malware and verify package integrity  \n✅ **License Compliance** — Ensure no copyleft or forbidden licenses  \n✅ **Dependency Health** — Check for outdated, deprecated, or vulnerable packages  \n✅ **Custom Queries** — Use CSS-like selectors for precise dependency filtering  \n✅ **Rich Output** — JSON, human-readable, count, or Mermaid diagrams  \n✅ **Multi-Query Support** — Run multiple checks in a single action  \n✅ **GitHub Integration** — Beautiful summary tables and detailed output\n\n## Use Cases\n\n### Security Scanning\n\n```yaml\n- name: Security scan\n  uses: vltpkg/policies@v2\n  with:\n    queries: |\n      # Block any malware\n      :malware --expect-results=0\n      \n      # Check for packages with known vulnerabilities\n      :vulnerable --view=json\n      \n      # Ensure no deprecated packages\n      :deprecated --expect-results=0\n```\n\n### License Compliance\n\n```yaml\n- name: License compliance\n  uses: vltpkg/policies@v2\n  with:\n    queries: |\n      # No copyleft licenses allowed\n      *:license(copyleft) --expect-results=0\n      \n      # No GPL licenses\n      *:license(gpl) --expect-results=0\n      \n      # List all unique licenses for review\n      *:license(*) --view=json\n```\n\n### Dependency Management\n\n```yaml\n- name: Dependency health\n  uses: vltpkg/policies@v2\n  with:\n    queries: |\n      # Check for outdated packages\n      :outdated --view=json\n      \n      # Ensure we don't have too many direct dependencies\n      :root \u003e * --view=count --expect-results=\u003c=20\n      \n      # Find packages with specific scripts\n      *:attr(scripts, [build]) --view=count\n```\n\n### Workspace Management\n\n```yaml\n- name: Workspace analysis\n  uses: vltpkg/policies@v2\n  with:\n    queries: |\n      # Count workspace packages\n      :workspace --view=count\n      \n      # Find workspace deps with build scripts\n      :workspace \u003e *:attr(scripts, [build]) --view=json\n      \n      # Check for cross-workspace dependencies\n      :workspace \u003e *:workspace --view=count\n```\n\n### Package-Specific Checks\n\n```yaml\n- name: Specific package checks\n  uses: vltpkg/policies@v2\n  with:\n    queries: |\n      # Ensure lodash is present\n      #lodash --expect-results=\u003e=1\n      \n      # Check React version\n      #react:semver(\u003e=18.0.0) --expect-results=\u003e=1\n      \n      # Find all @types packages\n      #@types/* --view=count\n```\n\n## Inputs\n\n| Input | Description | Required | Default |\n|-------|-------------|----------|---------|\n| `query` | Single query selector (e.g. `:malware`) | No* | |\n| `queries` | Multi-line query selectors with flags | No* | |\n| `expect-results` | Expected result count for single query | No | |\n| `view` | Output format: `human`, `json`, `mermaid`, `count` | No | `human` |\n| `scope` | Scope query selector | No | |\n| `target` | Target query selector (alternative to `query`) | No | |\n| `working-directory` | Directory to run queries in | No | Repository root |\n\n*Either `query` or `queries` must be provided.\n\n### Expect Results Format\n\nThe `expect-results` parameter supports flexible comparisons:\n\n- `0` — Exactly 0 results\n- `5` — Exactly 5 results  \n- `\u003e0` — More than 0 results\n- `\u003e=1` — 1 or more results\n- `\u003c5` — Fewer than 5 results\n- `\u003c=10` — 10 or fewer results\n\n## Outputs\n\n| Output | Description |\n|--------|-------------|\n| `results` | JSON array of all query results |\n| `passed` | `true` if all queries passed expectations |\n| `result-0`, `result-1`, etc. | Individual query results as JSON |\n\n## Query Selectors\n\nPolicies uses vlt's powerful CSS-like selectors. Here are common patterns:\n\n| Selector | Description |\n|----------|-------------|\n| `:malware` | Packages flagged as malware |\n| `:outdated` | Packages with newer versions available |\n| `:deprecated` | Packages marked as deprecated |\n| `:vulnerable` | Packages with known vulnerabilities |\n| `:workspace` | Workspace packages |\n| `:root` | Root package |\n| `:peer` | Peer dependencies |\n| `#package-name` | Specific package by name |\n| `#@scope/*` | All packages in a scope |\n| `*:license(mit)` | Packages with MIT license |\n| `*:license(copyleft)` | Packages with copyleft licenses |\n| `*:semver(\u003e=2.0.0)` | Packages matching semver range |\n| `:root \u003e *` | Direct dependencies |\n| `*:attr(scripts, [build])` | Packages with build script |\n\nFor complete selector documentation, see [vlt selector docs](https://docs.vlt.sh/cli/selectors).\n\n## Advanced Examples\n\n### Complex License Audit\n\n```yaml\n- name: License audit\n  uses: vltpkg/policies@v2\n  with:\n    queries: |\n      # Get all licenses for review\n      *:license(*) --view=json \u003e licenses.json\n      \n      # Block specific problematic licenses\n      *:license(agpl) --expect-results=0\n      *:license(gpl-2.0) --expect-results=0\n      *:license(gpl-3.0) --expect-results=0\n      \n      # Warn about copyleft (but don't fail)\n      *:license(copyleft) --view=count\n```\n\n### Security \u0026 Quality Gate\n\n```yaml\n- name: Security \u0026 quality gate\n  uses: vltpkg/policies@v2\n  with:\n    queries: |\n      # Security checks\n      :malware --expect-results=0\n      :vulnerable --expect-results=0\n      \n      # Quality checks  \n      :deprecated --expect-results=0\n      :outdated --view=count\n      \n      # Dependency limits\n      :root \u003e * --view=count --expect-results=\u003c=50\n      * --view=count --expect-results=\u003c=500\n```\n\n### Workspace Health Check\n\n```yaml\n- name: Workspace health\n  uses: vltpkg/policies@v2\n  with:\n    queries: |\n      # Workspace structure\n      :workspace --view=count --expect-results=\u003e=1\n      \n      # Cross-workspace deps (should be minimal)\n      :workspace \u003e *:workspace --view=count --expect-results=\u003c=5\n      \n      # Ensure workspace packages have required fields\n      :workspace:attr(name) --expect-results=\u003e=1\n      :workspace:attr(version) --expect-results=\u003e=1\n```\n\n## Error Handling\n\nPolicies provides clear error messages:\n\n- **vlt not installed**: Points to `vltpkg/setup-vlt@v1`\n- **Invalid selectors**: Shows vlt's error with helpful context\n- **Expectation mismatches**: Clear comparison output\n- **Syntax errors**: Detailed parsing feedback\n\n## Requirements\n\n- **Node.js 22+**: vlt requires Node.js \u003e= 22.9.0\n- **vlt installed**: Use `vltpkg/setup-vlt@v1` before this action\n- **vlt project**: Must be run in a directory with vlt configuration\n\n## Complete Workflow Example\n\n```yaml\nname: Dependency Audit\n\non:\n  push:\n    branches: [main]\n  pull_request:\n    branches: [main]\n\njobs:\n  audit:\n    runs-on: ubuntu-latest\n    \n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      \n      - name: Setup Node.js 22\n        uses: actions/setup-node@v4\n        with:\n          node-version: '22'\n      \n      - name: Setup vlt\n        uses: vltpkg/setup-vlt@v1\n      \n      - name: Install dependencies\n        run: vlt install\n      \n      - name: Security audit\n        uses: vltpkg/policies@v2\n        with:\n          queries: |\n            # Block malware and vulnerabilities\n            :malware --expect-results=0\n            :vulnerable --expect-results=0\n            \n            # License compliance\n            *:license(copyleft) --expect-results=0\n            *:license(agpl) --expect-results=0\n            \n            # Quality gates\n            :deprecated --expect-results=0\n            :root \u003e * --view=count --expect-results=\u003c=25\n      \n      - name: Generate dependency report\n        uses: vltpkg/policies@v2\n        with:\n          queries: |\n            # Detailed reports (won't fail CI)\n            :outdated --view=json\n            *:license(*) --view=json\n            :workspace --view=mermaid\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\nThis action is licensed under the [MIT License](LICENSE).\n\n---\n\n**Policies** is built by the [vlt](https://vlt.sh) team. For more vlt tools and documentation, visit [docs.vlt.sh](https://docs.vlt.sh).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvltpkg%2Fpolicies","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvltpkg%2Fpolicies","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvltpkg%2Fpolicies/lists"}