verify-policy-tool

Policy verification CLI for TypeScript, React, and UI codebases.

Install

pnpm add -D verify-policy-tool

Usage

verify-policy
verify-policy init
verify-policy --changed
verify-policy --policy-only
verify-policy --deprecations-only
verify-policy --rules no-any,no-unknown
verify-policy --create-rules
verify-policy --structure-config config/policy-structure.json

By default the CLI runs from the current working directory and scans src. Structure rules read config/policy-structure.json when it exists. Missing structure config means those project-specific rules stay inactive.

Tests

pnpm test

The test script builds dist/verify-policy.mjs first, then runs the local CLI against temporary workspaces.

Options

• --root <dir>: project root. Defaults to the current working directory.
• --src <dir>: source directory to scan. Defaults to src. Can be repeated or comma-separated.
• --baseline <file>: baseline file. Defaults to config/policy-baseline.json.
• --deprecations-config <file>: UI deprecation config. Defaults to config/ui-deprecations.json.
• --structure-config <file>: structure config. Defaults to config/policy-structure.json.
• --rules-output <file>: output path for --create-rules. Defaults to RULES.md.

Structure Config

Run verify-policy init from a project directory to create config/policy-structure.json next to the nearest package.json. Use verify-policy init --root <dir> to target a specific project root, and verify-policy init --force to overwrite an existing config.

The generated config is intentionally generic. It includes basic roles for utils, constants, renderers, and view-configs, but leaves domain and page-group rules empty so each project can decide its own layout policy.

Structure rules include:

• file-role-placement: checks configured directory roles against AST-detected capabilities.
• page-group-placement: keeps configured page groups, such as test pages, under a required directory.
• restricted-root-files: prevents configured root directories from accumulating direct files.
• no-compat-reexport-file: flags pure compatibility re-export files outside allowed index barrels.
• domain-component-placement: checks project-defined domain component names against configured directories.
• domain-file-placement: checks project-defined domain file names in configured layers such as hooks, services, types, utils, constants, and config.

Example test page policy:

{
  "pageGroups": [
    {
      "name": "test-pages",
      "root": "src/pages",
      "requiredDir": "src/pages/test",
      "match": ["*-test.{ts,tsx,js,jsx}", "**/*Test.{ts,tsx,js,jsx}"],
      "message": "Test/debug pages must live under src/pages/test/."
    }
  ]
}

Example domain policy:

{
  "domains": [
    {
      "name": "billing",
      "paths": ["src/components/billing/**"],
      "componentNamePatterns": ["Billing*"],
      "fileNamePatterns": ["billing*", "*Billing*"],
      "requiredDirs": ["src/components/billing"],
      "sharedPaths": ["src/components/shared"],
      "allowFiles": ["src/components/BillingShell.tsx"]
    }
  ]
}

domain-component-placement is config-driven. The tool does not know project domain names; it only compares configured names, component patterns, required directories, shared paths, and explicit allow files. If domains is missing or empty, the domain placement rule stays inactive.

domain-file-placement is also config-driven and is part of the default policy rules. Add domainFilePlacement.layers to decide which shared layers should be checked and where matched domain files must live:

{
  "domainFilePlacement": {
    "layers": [
      {
        "name": "hooks",
        "roots": ["src/hooks"],
        "targetDirs": ["src/hooks/{domain}"],
        "sharedPaths": ["src/hooks/useSharedThing.ts"]
      }
    ]
  }
}

The rule uses the file basename plus each domain's fileNamePatterns; it does not infer business domains from source text or exported symbols. Missing domains or missing domainFilePlacement.layers keeps this rule inactive for projects that have not configured domains.

Ignore

Use policy-ignore near a violation to skip policy rules. Rules listed in the non-ignorable set cannot be skipped.

Publishing

Publishing is handled by .github/workflows/publish-verify-policy.yml. The workflow only publishes when tools/verify-policy/package.json changes version and npm view <name>@<version> says that version is not already published. If a first publish attempt fails after the version bump, rerun the workflow manually with publish_missing_version=true; it will still skip when npm already contains that version.

Preferred setup is npm Trusted Publishing:

1. Open the package settings on npmjs.com.
2. Add a GitHub Actions trusted publisher for this repository.
3. Set the workflow filename to publish-verify-policy.yml.
4. Leave environment empty unless the GitHub workflow is later changed to use one.

Fallback token setup:

1. Create a granular npm publish token for this package.
2. In GitHub, open Settings -> Secrets and variables -> Actions.
3. Add repository secret NPM_TOKEN with the token value.

Do not commit .npmrc files or raw npm tokens.