{"_id":"@aligntrue/checks","_rev":"5-5e3559718a18f1b358155292201018dc","name":"@aligntrue/checks","dist-tags":{"next":"0.1.0-alpha.2","latest":"0.1.1-alpha.3"},"versions":{"0.1.0-alpha.2":{"name":"@aligntrue/checks","version":"0.1.0-alpha.2","_id":"@aligntrue/checks@0.1.0-alpha.2","maintainers":[{"name":"gmays","email":"gabriel.mays@gmail.com"}],"dist":{"shasum":"edb43dd398385956d8085c902c89082c8297618b","tarball":"https://registry.npmjs.org/@aligntrue/checks/-/checks-0.1.0-alpha.2.tgz","fileCount":46,"integrity":"sha512-R20TrtYL54nhePzH+LCFR9CW+S2mgEJ1ZjNIMVRkmlLl+VwC4PpH1IW5hWWlQi+RwKLES6pjcYiCBVYwPsdQJA==","signatures":[{"sig":"MEUCIDBYA9bVhlb+mS1I3EhgRiqwc1VWgh9tMDdaNY6EvqMcAiEAzS0Oxi1AKEWOhVxme6JqEjVJcuhS8m5/bmwWkqM8cNQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":74929},"main":"./dist/index.js","type":"module","_from":"file:aligntrue-checks-0.1.0-alpha.2.tgz","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","run-checks":"tsx scripts/run-checks.ts","test:watch":"vitest"},"_npmUser":{"name":"gmays","email":"gabriel.mays@gmail.com"},"_resolved":"/private/var/folders/qn/kzm93p190txc1rg4_9b9nx340000gn/T/41a9b4f8a9749efa314aba56cd75251d/aligntrue-checks-0.1.0-alpha.2.tgz","_integrity":"sha512-R20TrtYL54nhePzH+LCFR9CW+S2mgEJ1ZjNIMVRkmlLl+VwC4PpH1IW5hWWlQi+RwKLES6pjcYiCBVYwPsdQJA==","_npmVersion":"11.6.0","description":"Check runner engine for AlignTrue Align packs","directories":{},"_nodeVersion":"23.11.0","dependencies":{"fast-glob":"^3.3.2","@aligntrue/schema":"0.1.0-alpha.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","vitest":"^4.0.4","minimatch":"^10.0.1","typescript":"^5.3.3","@types/node":"^24.9.1"},"_npmOperationalInternal":{"tmp":"tmp/checks_0.1.0-alpha.2_1761668971296_0.18759099970158633","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package has been removed from AlignTrue. It is no longer maintained."},"0.1.1-alpha.3":{"name":"@aligntrue/checks","version":"0.1.1-alpha.3","_id":"@aligntrue/checks@0.1.1-alpha.3","maintainers":[{"name":"gmays","email":"gabriel.mays@gmail.com"}],"dist":{"shasum":"dff181ec1adf1f45aa46992ab1e70afef39a51fc","tarball":"https://registry.npmjs.org/@aligntrue/checks/-/checks-0.1.1-alpha.3.tgz","fileCount":47,"integrity":"sha512-JMiwFmpQNDTrBBfXLKEbXKThlSHiS42fji8EtCu/VmpNmmS9x+3DGf68prfhYVGp3AvIKm09HUAYHbDWo7LqMA==","signatures":[{"sig":"MEUCIQDm/Oopi9VkhMgs2B+PZvjxvZMvlE0w9fK1e1zq+UC9QgIgMpCLi0jjlptJYxiVaGStQJ3n4I4C8vWJqlaYRLbIdOM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":83918},"main":"./dist/index.js","type":"module","_from":"file:aligntrue-checks-0.1.1-alpha.3.tgz","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","run-checks":"tsx scripts/run-checks.ts","test:watch":"vitest"},"_npmUser":{"name":"gmays","email":"gabriel.mays@gmail.com"},"_resolved":"/private/var/folders/qn/kzm93p190txc1rg4_9b9nx340000gn/T/ebc980fe6f4d64ddd353a14eee7b0eec/aligntrue-checks-0.1.1-alpha.3.tgz","_integrity":"sha512-JMiwFmpQNDTrBBfXLKEbXKThlSHiS42fji8EtCu/VmpNmmS9x+3DGf68prfhYVGp3AvIKm09HUAYHbDWo7LqMA==","_npmVersion":"11.6.0","description":"Check runner engine for AlignTrue Align packs","directories":{},"_nodeVersion":"23.11.0","dependencies":{"fast-glob":"^3.3.2","@aligntrue/core":"0.1.1-alpha.3","@aligntrue/schema":"0.1.1-alpha.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","minimatch":"^10.1.1"},"_npmOperationalInternal":{"tmp":"tmp/checks_0.1.1-alpha.3_1762478056136_0.8944019539366626","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package has been removed from AlignTrue. It is no longer maintained."}},"time":{"created":"2025-10-28T16:29:31.174Z","modified":"2025-11-12T17:56:22.429Z","0.1.0-alpha.1":"2025-10-28T15:50:03.361Z","0.1.0-alpha.2":"2025-10-28T16:29:31.490Z","0.1.1-alpha.3":"2025-11-07T01:14:16.342Z"},"description":"Check runner engine for AlignTrue Align packs","maintainers":[{"name":"gmays","email":"gabriel.mays@gmail.com"}],"readme":"# @aligntrue/checks\n\n**Check runner engine for AlignTrue Align packs.**\n\nExecutes machine-checkable rules from Align packs and emits findings in SARIF 2.1.0 or JSON format for CI and editor integration.\n\n## Features\n\n- **5 check types**: file_presence, path_convention, manifest_policy, regex, command_runner\n- **SARIF 2.1.0 output**: compatible with GitHub Code Scanning, VS Code, and other SARIF consumers\n- **JSON output**: simple format for scripting and programmatic consumption\n- **Abstract file provider**: testable, extensible, works with in-memory or remote file systems\n- **Gated command execution**: command_runner checks require explicit opt-in for security\n- **Deterministic**: reproducible results across machines\n\n## Installation\n\n```bash\npnpm add @aligntrue/checks\n```\n\n## Usage\n\n### Programmatic API\n\n```typescript\nimport { runChecks, emitSarif, emitJson } from \"@aligntrue/checks\";\nimport { parseYamlToJson } from \"@aligntrue/schema\";\nimport { readFileSync } from \"fs\";\n\n// Load and parse Align pack\nconst alignYaml = readFileSync(\"pack.aligntrue.yaml\", \"utf8\");\nconst alignPack = parseYamlToJson(alignYaml);\n\n// Run checks\nconst results = await runChecks(alignPack, {\n  workingDir: \"/path/to/project\",\n  allowExec: false, // Set to true to enable command_runner checks\n});\n\n// Emit SARIF for CI\nconst sarif = emitSarif(results);\nconsole.log(JSON.stringify(sarif, null, 2));\n\n// Or emit JSON for scripting\nconst json = emitJson(results);\nconsole.log(`Passed: ${json.summary.passed}, Failed: ${json.summary.failed}`);\n```\n\n### CLI Script\n\n```bash\n# Run checks and output text summary\npnpm run-checks pack.aligntrue.yaml /path/to/project\n\n# Output SARIF\npnpm run-checks pack.aligntrue.yaml /path/to/project --format sarif > results.sarif\n\n# Output JSON\npnpm run-checks pack.aligntrue.yaml /path/to/project --format json > results.json\n\n# Enable command execution (use with caution)\npnpm run-checks pack.aligntrue.yaml /path/to/project --allow-exec\n```\n\n## Check Types\n\n### file_presence\n\nVerifies that files matching a glob pattern exist.\n\n```yaml\n- id: require-tests\n  severity: MUST\n  check:\n    type: file_presence\n    inputs:\n      pattern: \"**/*.test.ts\"\n      must_exist_for_changed_sources: true\n    evidence: \"Missing test file for changed source\"\n```\n\n### path_convention\n\nValidates that file paths follow a naming convention (regex).\n\n```yaml\n- id: kebab-case-components\n  severity: SHOULD\n  check:\n    type: path_convention\n    inputs:\n      pattern: \"^[a-z0-9-]+\\\\.tsx$\"\n      include: [\"src/components/**\"]\n      message: \"Component files must use kebab-case\"\n    evidence: \"File name violates path convention\"\n```\n\n### manifest_policy\n\nValidates dependency management files (package.json, lockfiles).\n\n```yaml\n- id: pinned-deps\n  severity: MUST\n  check:\n    type: manifest_policy\n    inputs:\n      manifest: \"package.json\"\n      lockfile: \"pnpm-lock.yaml\"\n      require_pinned: true\n    evidence: \"New dependency is not pinned in lockfile\"\n```\n\n### regex\n\nPattern matching against file contents.\n\n```yaml\n- id: no-todos\n  severity: SHOULD\n  check:\n    type: regex\n    inputs:\n      include: [\"**/*.ts\"]\n      pattern: \"\\\\bTODO\\\\b\"\n      allow: false\n    evidence: \"TODO present in file\"\n```\n\n### command_runner\n\nExecutes a shell command and validates exit code.\n\n**Requires explicit `allowExec: true` option.**\n\n```yaml\n- id: typecheck\n  severity: MUST\n  check:\n    type: command_runner\n    inputs:\n      command: \"pnpm exec tsc --noEmit\"\n      timeout_ms: 60000\n      expect_exit_code: 0\n    evidence: \"Type check failed\"\n```\n\n## API Reference\n\n### `runChecks(alignPack, options)`\n\nRuns all checks in an Align pack.\n\n**Parameters:**\n\n- `alignPack: AlignPack` - Validated Align pack object\n- `options: RunChecksOptions` - Execution options\n  - `fileProvider?: FileProvider` - Custom file provider (defaults to DiskFileProvider)\n  - `workingDir?: string` - Working directory (defaults to `process.cwd()`)\n  - `allowExec?: boolean` - Allow command execution (default: `false`)\n  - `envWhitelist?: string[]` - Environment variables to pass to commands\n  - `changedFiles?: string[]` - List of changed files for incremental checks\n  - `defaultTimeout?: number` - Default command timeout in ms\n\n**Returns:** `Promise<CheckResult[]>` - Array of check results (one per rule)\n\n### `emitSarif(results, toolVersion?)`\n\nConverts check results to SARIF 2.1.0 format.\n\n**Parameters:**\n\n- `results: CheckResult[]` - Check results from `runChecks`\n- `toolVersion?: string` - Tool version string (default: `'0.1.0'`)\n\n**Returns:** `SarifLog` - SARIF 2.1.0 log object\n\n### `emitJson(results)`\n\nConverts check results to simple JSON format.\n\n**Parameters:**\n\n- `results: CheckResult[]` - Check results from `runChecks`\n\n**Returns:** `JsonFindings` - JSON findings object with summary and findings array\n\n### `FileProvider` Interface\n\nAbstract interface for file access. Implement this to use custom file sources.\n\n```typescript\ninterface FileProvider {\n  glob(pattern: string, options?: GlobOptions): Promise<string[]>;\n  readFile(path: string): Promise<string>;\n  exists(path: string): Promise<boolean>;\n  readJson(path: string): Promise<unknown>;\n}\n```\n\n**Implementations:**\n\n- `DiskFileProvider` - Reads from local filesystem\n- Custom implementations for zip files, Git repos, remote storage, etc.\n\n## Command Execution Safety\n\nThe `command_runner` check type is **disabled by default** for security.\n\nTo enable:\n\n1. Pass `allowExec: true` to `runChecks`\n2. Optionally provide `envWhitelist` to restrict environment variables\n3. All commands run with configurable timeout (default 30s)\n\nCommands are executed in a shell with:\n\n- Working directory set via `working_dir` input or context `workingDir`\n- Only whitelisted environment variables (if provided)\n- Timeout enforcement (kills process after timeout)\n\n**Best practices:**\n\n- Only enable `allowExec` in trusted CI environments\n- Use `envWhitelist` to limit exposed secrets\n- Set appropriate `timeout_ms` for each command\n- Validate command inputs in pack YAML\n\n## Integration Examples\n\n### GitHub Actions\n\n```yaml\n- name: Run AlignTrue checks\n  run: |\n    pnpm run-checks pack.aligntrue.yaml . --format sarif > results.sarif\n\n- name: Upload SARIF results\n  uses: github/codeql-action/upload-sarif@v2\n  with:\n    sarif_file: results.sarif\n```\n\n### VS Code Extension\n\n```typescript\nimport { runChecks, emitSarif } from \"@aligntrue/checks\";\n\n// Run checks and convert to SARIF\nconst results = await runChecks(pack, { workingDir: workspace.rootPath });\nconst sarif = emitSarif(results);\n\n// Display in Problems panel\ndiagnosticCollection.clear();\nfor (const result of sarif.runs[0].results) {\n  // Convert SARIF result to VS Code Diagnostic\n  // ...\n}\n```\n\n### Custom File Provider (Testing)\n\n```typescript\nimport { MemoryFileProvider } from \"@aligntrue/checks/tests/providers/memory\";\n\nconst provider = new MemoryFileProvider();\nprovider.addFiles({\n  \"src/foo.ts\": \"const x = 42;\",\n  \"package.json\": JSON.stringify({ dependencies: {} }),\n});\n\nconst results = await runChecks(pack, { fileProvider: provider });\n```\n\n## Testing\n\n```bash\n# Run unit tests\npnpm test\n\n# Run tests in watch mode\npnpm test:watch\n\n# Type check\npnpm typecheck\n```\n\n## Related Packages\n\n- `@aligntrue/schema` - JSON Schema, canonicalization, and validation\n- `@aligntrue/cli` - CLI tool for managing Align packs\n\n## License\n\nMIT\n","readmeFilename":"README.md"}