periapsis 1.0.2 → 1.0.4

package/.github/workflows/periapsis-license-check.yml

@@ -1,4 +1,4 @@
-name: Periapsis License Check
+name: Periapsis PR Gate
 
 on:
   workflow_dispatch:
@@ -9,9 +9,29 @@ permissions:
   contents: read
 
 jobs:
-  periapsis:
+  test-suite:
     if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
     runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run automated test suite
+        run: npm run test:ci
+
+  policy-gate:
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    needs: test-suite
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -28,7 +48,7 @@ jobs:
       - name: Run Periapsis policy check
         id: periapsis
         continue-on-error: true
-        run: npx periapsis --violations-out sbom-violations.json
+        run: npm run policy:check
 
       - name: Enforce zero violations
         if: always()

package/.github/workflows/publish-package.yml

@@ -0,0 +1,123 @@
+name: Publish Package
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: Semver increment to publish
+        required: true
+        type: choice
+        default: patch
+        options:
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-package
+  cancel-in-progress: false
+
+jobs:
+  authorize-release:
+    name: Authorize Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require default branch
+        env:
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          if [ "${GITHUB_REF_NAME}" != "${DEFAULT_BRANCH}" ]; then
+            echo "Manual publishing is only allowed from ${DEFAULT_BRANCH}."
+            exit 1
+          fi
+
+      - name: Require repository admin permission
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const actor = context.actor;
+
+            if (owner.toLowerCase() === actor.toLowerCase()) {
+              core.info(`Actor ${actor} matches the repository owner and is treated as admin.`);
+              return;
+            }
+
+            const response = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner,
+              repo,
+              username: actor,
+            });
+
+            const { permission, role_name: roleName } = response.data;
+            core.info(`Actor ${actor} permission=${permission}, role_name=${roleName}`);
+
+            if (permission !== "admin" && roleName !== "admin") {
+              core.setFailed(`Only repository admins can publish packages. ${actor} has ${roleName || permission}.`);
+            }
+
+  publish-package:
+    name: Publish Package
+    needs: authorize-release
+    runs-on: ubuntu-latest
+    environment:
+      # Configure this environment in GitHub with required reviewers for an
+      # extra approval gate, and use the same name in npm trusted publisher
+      # settings if you want npm to bind publishing to this environment.
+      name: package-publish
+    permissions:
+      # Required because this workflow commits the bumped version, creates a
+      # release tag, and pushes both back to the repository.
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run automated test suite
+        run: npm run test:ci
+
+      - name: Bump package version
+        run: npm version "${{ inputs.release_type }}" --no-git-tag-version
+
+      - name: Read new version
+        id: version
+        run: |
+          echo "value=$(node -p 'require(\"./package.json\").version')" >> "$GITHUB_OUTPUT"
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Commit release version
+        env:
+          VERSION: ${{ steps.version.outputs.value }}
+        run: |
+          git add package.json package-lock.json
+          git commit -m "chore(release): v${VERSION}"
+          git tag "v${VERSION}"
+
+      - name: Publish to npm with trusted publishing
+        run: npm publish
+
+      - name: Push release commit and tag
+        env:
+          VERSION: ${{ steps.version.outputs.value }}
+        run: git push --atomic origin "HEAD:${GITHUB_REF_NAME}" "refs/tags/v${VERSION}"

package/README.md

@@ -17,6 +17,22 @@ npx periapsis init --preset strict
 
 `init` now asks which dependency types should be checked by default (unless provided via flags).
 
+## Testing
+
+Run the regression suite:
+
+```sh
+npm test
+```
+
+Run the repository policy gate locally:
+
+```sh
+npm run policy:check
+```
+
+Testing layers and PR gate guidance live in `docs/testing-strategy.md`.
+
 ## Commands
 
 - `periapsis`: run SBOM + license gate

package/bin/periapsis.mjs

@@ -233,11 +233,9 @@ function loadPolicyOrThrow(policyDir) {
   return loadPolicyFromNewFiles(policyDir);
 }
 
-async function cmdExceptionsAdd(root, policyDirArg) {
+async function cmdExceptionsAdd(root, policyDirArg, args) {
   const policyDir = path.resolve(root, policyDirArg || 'policy');
   const policy = loadPolicyOrThrow(policyDir);
-  const args = parseArgs(process.argv.slice(2));
-
   const writeExceptions = (record, { editExisting = false } = {}) => {
     const sameScope = policy.exceptions.filter(
       (entry) => entry.package === record.package && scopeKey(entry.scope) === scopeKey(record.scope)
@@ -384,12 +382,10 @@ async function cmdExceptionsAdd(root, policyDirArg) {
   });
 }
 
-async function cmdLicensesAllowAdd(root, policyDirArg) {
+async function cmdLicensesAllowAdd(root, policyDirArg, args) {
   const policyDir = path.resolve(root, policyDirArg || 'policy');
   const policy = loadPolicyOrThrow(policyDir);
   const spdx = loadSpdxCatalog(SPDX_PATH);
-  const args = parseArgs(process.argv.slice(2));
-
   const writeLicenses = (record) => {
     if (policy.licenses.some((entry) => entry.identifier === record.identifier)) {
       console.warn(
@@ -656,8 +652,8 @@ function cmdCheck(root, args) {
   }
 }
 
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
+export async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
   const root = resolveRoot(args);
 
   if (args.help) {
@@ -682,12 +678,12 @@ async function main() {
   }
 
   if (cmd1 === 'exceptions' && cmd2 === 'add') {
-    await cmdExceptionsAdd(root, args['policy-dir']);
+    await cmdExceptionsAdd(root, args['policy-dir'], args);
     return;
   }
 
   if (cmd1 === 'licenses' && cmd2 === 'allow' && cmd3 === 'add') {
-    await cmdLicensesAllowAdd(root, args['policy-dir']);
+    await cmdLicensesAllowAdd(root, args['policy-dir'], args);
     return;
   }
 
@@ -700,7 +696,9 @@ async function main() {
   cmdCheck(root, args);
 }
 
-main().catch((err) => {
-  console.error(err.message);
-  process.exit(1);
-});
+if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
+  main().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
+}

package/docs/testing-strategy.md

@@ -0,0 +1,113 @@
+# Testing Strategy
+
+Periapsis now has an in-repo regression strategy designed to make dependency, policy, and vulnerability response work safer to ship. The goal is to catch behavior changes before they merge and to keep policy governance reviewable over time.
+
+## Goals
+
+- Prevent regressions in CLI behavior, policy evaluation, and dependency-scope handling.
+- Keep tests self-contained in this repository with no live registry or SaaS dependency.
+- Make policy behavior explicit for common governance modes:
+  - permissive-only / open license defaults
+  - weak copyleft allowed
+  - all dependencies versus runtime-only dependencies
+  - expiring exceptions and follow-up approvals
+- Turn the suite into a required PR gate through GitHub Actions branch protection.
+
+## Test Layers
+
+### 1. Core policy unit tests
+
+File: `test/policy.test.mjs`
+
+Covers pure library logic such as:
+
+- SPDX expression parsing
+- category mapping
+- dependency-type parsing
+- exception range matching
+- active versus expired policy records
+
+These are the fastest tests and should grow whenever policy logic changes.
+
+### 2. CLI workflow tests
+
+Files:
+
+- `test/cli.test.mjs`
+- `test/commands.test.mjs`
+
+Covers command behavior and file-writing flows such as:
+
+- `licenses allow add`
+- `exceptions add`
+- `init`
+- `policy migrate`
+- policy-driven dependency-type defaults
+
+These protect user-facing commands from accidental flag or file-format regressions.
+
+### 3. Fixture-driven regression gate tests
+
+File: `test/regression-gate.test.mjs`
+
+These tests model governed dependency scenarios end to end using temporary fixture projects:
+
+- strict runtime-only policy should ignore disallowed dev dependencies
+- all-dependency policy should fail on the same dev dependency
+- standard policy should allow weak copyleft
+- expired exceptions should fail
+- active follow-up exceptions should pass
+
+This is the highest-value layer for future updates to license logic, policy schemas, or dependency traversal.
+
+## NPM Scripts
+
+Use the following scripts locally and in CI:
+
+- `npm test`: full Node test suite
+- `npm run test:unit`: core policy engine tests
+- `npm run test:cli`: CLI and fixture-driven regression tests
+- `npm run policy:check`: run Periapsis against this repository and write `sbom-violations.json`
+- `npm run test:ci`: CI entrypoint, currently equivalent to `npm test`
+
+## CI Gate
+
+The GitHub Action should run on `pull_request` and enforce two checks:
+
+1. `test-suite`
+   Runs the full automated test suite.
+
+2. `policy-gate`
+   Runs Periapsis against the repository itself and uploads `sbom-violations.json`.
+
+Recommended branch protection:
+
+1. Require status checks to pass before merging.
+2. Mark `test-suite` as required.
+3. Mark `policy-gate` as required.
+4. Optionally require the branch to be up to date before merging.
+
+## Dependency Separation
+
+Periapsis runtime code should stay in `dependencies`. Any future tooling used only for verification should stay in `devDependencies` so the shipping package remains small and auditable.
+
+Suggested future additions, if wanted:
+
+- coverage reporting
+- linting
+- JSON schema fixture validation
+- scheduled policy-audit workflow for upcoming exception expirations
+
+Those can be added later without changing the runtime surface area of the CLI.
+
+## Policy Maintenance Rules
+
+When updating dependencies or handling a vulnerability:
+
+1. Change the dependency.
+2. Run `npm test`.
+3. Run `npm run policy:check`.
+4. If policy changes are required, update only the governed files in `policy/`.
+5. Prefer adding follow-up license or exception records instead of mutating history in place.
+
+That keeps remediation work auditable and lowers the risk of silently loosening policy.

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "periapsis",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "private": false,
   "type": "module",
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "test:unit": "node --test test/policy.test.mjs",
+    "test:cli": "node --test test/cli.test.mjs test/commands.test.mjs test/regression-gate.test.mjs",
+    "test:ci": "npm run test",
+    "policy:check": "node ./bin/periapsis.mjs --violations-out sbom-violations.json"
   },
   "bin": {
     "periapsis": "bin/periapsis.mjs"

package/test/cli.test.mjs

@@ -1,55 +1,18 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'fs';
-import os from 'os';
 import path from 'path';
-import { execFileSync } from 'child_process';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const BIN = path.resolve(__dirname, '..', 'bin', 'periapsis.mjs');
+import { createTempDir, runCli, writePolicyBundle } from '../testing/helpers.mjs';
 
 function setupTempProject() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'periapsis-test-'));
-  fs.mkdirSync(path.join(dir, 'policy'), { recursive: true });
-  fs.writeFileSync(
-    path.join(dir, 'policy', 'policy.json'),
-    JSON.stringify(
-      {
-        allowedCategories: ['Permissive Licenses'],
-        failOnUnknownLicense: true,
-        timezone: 'UTC',
-        dependencyTypes: ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies', 'bundledDependencies']
-      },
-      null,
-      2
-    ) + '\n'
-  );
-  fs.writeFileSync(path.join(dir, 'policy', 'licenses.json'), '[]\n');
-  fs.writeFileSync(path.join(dir, 'policy', 'exceptions.json'), '[]\n');
+  const dir = createTempDir('periapsis-test-');
+  writePolicyBundle(dir);
   return dir;
 }
 
-function runCli(cwd, args, { expectFail = false } = {}) {
-  try {
-    const out = execFileSync('node', [BIN, ...args], {
-      cwd,
-      encoding: 'utf8'
-    });
-    if (expectFail) {
-      assert.fail(`Expected command to fail: ${args.join(' ')}`);
-    }
-    return out;
-  } catch (err) {
-    if (!expectFail) throw err;
-    return `${err.stdout || ''}${err.stderr || ''}`;
-  }
-}
-
-test('licenses allow add supports non-interactive mode', () => {
+test('licenses allow add supports non-interactive mode', async () => {
   const cwd = setupTempProject();
-  runCli(cwd, [
+  await runCli(cwd, [
     'licenses',
     'allow',
     'add',
@@ -72,9 +35,9 @@ test('licenses allow add supports non-interactive mode', () => {
   assert.equal(licenses[0].approvedBy[0], 'security');
 });
 
-test('exceptions add supports non-interactive mode', () => {
+test('exceptions add supports non-interactive mode', async () => {
   const cwd = setupTempProject();
-  runCli(cwd, [
+  await runCli(cwd, [
     'exceptions',
     'add',
     '--non-interactive',
@@ -100,9 +63,9 @@ test('exceptions add supports non-interactive mode', () => {
   assert.equal(exceptions[0].scope.type, 'exact');
 });
 
-test('non-interactive mode enforces required fields', () => {
+test('non-interactive mode enforces required fields', async () => {
   const cwd = setupTempProject();
-  const output = runCli(
+  const output = await runCli(
     cwd,
     ['licenses', 'allow', 'add', '--non-interactive', '--identifier', 'MIT'],
     { expectFail: true }
@@ -111,7 +74,7 @@ test('non-interactive mode enforces required fields', () => {
   assert.match(output, /--approved-by is required/);
 });
 
-test('checker respects --dep-types filter', () => {
+test('checker respects --dep-types filter', async () => {
   const cwd = setupTempProject();
   fs.writeFileSync(
     path.join(cwd, 'package.json'),
@@ -150,7 +113,7 @@ test('checker respects --dep-types filter', () => {
   fs.mkdirSync(path.join(cwd, 'node_modules', 'a'), { recursive: true });
   fs.mkdirSync(path.join(cwd, 'node_modules', 'b'), { recursive: true });
 
-  runCli(cwd, [
+  await runCli(cwd, [
     'licenses',
     'allow',
     'add',
@@ -167,8 +130,8 @@ test('checker respects --dep-types filter', () => {
     'JIRA-300'
   ]);
 
-  runCli(cwd, ['--dep-types', 'dependencies', '--quiet']);
-  const failOutput = runCli(cwd, ['--dep-types', 'devDependencies'], {
+  await runCli(cwd, ['--dep-types', 'dependencies', '--quiet']);
+  const failOutput = await runCli(cwd, ['--dep-types', 'devDependencies'], {
     expectFail: true
   });
   assert.match(failOutput, /license-not-allowed/);

package/test/commands.test.mjs

@@ -0,0 +1,98 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'fs';
+import path from 'path';
+import { createTempDir, runCli, writeJson, writePolicyBundle } from '../testing/helpers.mjs';
+
+test('init writes strict runtime-only policy when requested', async () => {
+  const cwd = createTempDir('periapsis-init-');
+
+  await runCli(cwd, ['init', '--preset', 'strict', '--production-only']);
+
+  const policy = JSON.parse(fs.readFileSync(path.join(cwd, 'policy', 'policy.json'), 'utf8'));
+  assert.deepEqual(policy.allowedCategories, ['Permissive Licenses']);
+  assert.deepEqual(policy.dependencyTypes, ['dependencies']);
+});
+
+test('init writes standard policy with explicit dependency types', async () => {
+  const cwd = createTempDir('periapsis-init-deps-');
+
+  await runCli(cwd, [
+    'init',
+    '--preset',
+    'standard',
+    '--dep-types',
+    'dependencies,peerDependencies'
+  ]);
+
+  const policy = JSON.parse(fs.readFileSync(path.join(cwd, 'policy', 'policy.json'), 'utf8'));
+  assert.deepEqual(policy.allowedCategories, [
+    'Permissive Licenses',
+    'Weak Copyleft Licenses'
+  ]);
+  assert.deepEqual(policy.dependencyTypes, ['dependencies', 'peerDependencies']);
+});
+
+test('policy migrate converts legacy config to governed policy files', async () => {
+  const cwd = createTempDir('periapsis-migrate-');
+  writeJson(path.join(cwd, 'allowedConfig.json'), {
+    allowedLicenses: ['MIT'],
+    allowedCategories: ['B'],
+    exceptions: ['left-pad@1.3.0', 'uuid']
+  });
+
+  await runCli(cwd, ['policy', 'migrate', '--from', 'allowedConfig.json']);
+
+  const policy = JSON.parse(fs.readFileSync(path.join(cwd, 'policy', 'policy.json'), 'utf8'));
+  const licenses = JSON.parse(fs.readFileSync(path.join(cwd, 'policy', 'licenses.json'), 'utf8'));
+  const exceptions = JSON.parse(fs.readFileSync(path.join(cwd, 'policy', 'exceptions.json'), 'utf8'));
+
+  assert.deepEqual(policy.allowedCategories, ['Weak Copyleft Licenses']);
+  assert.equal(licenses.length, 1);
+  assert.equal(licenses[0].identifier, 'MIT');
+  assert.equal(exceptions.length, 2);
+  assert.deepEqual(exceptions[0].scope, { type: 'exact', version: '1.3.0' });
+  assert.deepEqual(exceptions[1].scope, { type: 'any' });
+});
+
+test('checker honors policy dependencyTypes when no CLI override is provided', async () => {
+  const cwd = createTempDir('periapsis-policy-scope-');
+  writePolicyBundle(cwd, {
+    settings: {
+      allowedCategories: ['Permissive Licenses'],
+      failOnUnknownLicense: true,
+      timezone: 'UTC',
+      dependencyTypes: ['dependencies']
+    },
+    licenses: [],
+    exceptions: []
+  });
+  writeJson(path.join(cwd, 'package.json'), {
+    name: 'scope-app',
+    version: '1.0.0',
+    dependencies: { a: '1.0.0' },
+    devDependencies: { b: '1.0.0' }
+  });
+  writeJson(path.join(cwd, 'package-lock.json'), {
+    name: 'scope-app',
+    version: '1.0.0',
+    lockfileVersion: 3,
+    packages: {
+      '': {
+        name: 'scope-app',
+        version: '1.0.0',
+        dependencies: { a: '1.0.0' },
+        devDependencies: { b: '1.0.0' }
+      },
+      'node_modules/a': { version: '1.0.0', license: 'MIT' },
+      'node_modules/b': { version: '1.0.0', license: 'GPL-3.0', dev: true }
+    }
+  });
+  fs.mkdirSync(path.join(cwd, 'node_modules', 'a'), { recursive: true });
+  fs.mkdirSync(path.join(cwd, 'node_modules', 'b'), { recursive: true });
+
+  await runCli(cwd, ['--quiet']);
+
+  const sbom = JSON.parse(fs.readFileSync(path.join(cwd, 'sbom-licenses.json'), 'utf8'));
+  assert.deepEqual(sbom.map((entry) => entry.name), ['a']);
+});

package/test/regression-gate.test.mjs

@@ -0,0 +1,188 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'fs';
+import path from 'path';
+import { createFixtureProject, runCli } from '../testing/helpers.mjs';
+
+function readViolations(root) {
+  return JSON.parse(fs.readFileSync(path.join(root, 'violations.json'), 'utf8'));
+}
+
+test('runtime-only strict policy ignores disallowed dev dependency', async () => {
+  const cwd = createFixtureProject({
+    prefix: 'periapsis-runtime-only-',
+    packageJson: {
+      name: 'runtime-only-app',
+      version: '1.0.0',
+      dependencies: { runtimeok: '1.0.0' },
+      devDependencies: { buildgpl: '1.0.0' }
+    },
+    lockPackages: {
+      'node_modules/runtimeok': { version: '1.0.0', license: 'MIT' },
+      'node_modules/buildgpl': { version: '1.0.0', license: 'GPL-3.0', dev: true }
+    },
+    policy: {
+      settings: {
+        allowedCategories: ['Permissive Licenses'],
+        failOnUnknownLicense: true,
+        timezone: 'UTC',
+        dependencyTypes: ['dependencies']
+      }
+    }
+  });
+
+  await runCli(cwd, ['--violations-out', 'violations.json', '--quiet']);
+
+  assert.deepEqual(readViolations(cwd), []);
+});
+
+test('all-dependency policy blocks disallowed dev dependency regressions', async () => {
+  const cwd = createFixtureProject({
+    prefix: 'periapsis-all-deps-',
+    packageJson: {
+      name: 'all-deps-app',
+      version: '1.0.0',
+      dependencies: { runtimeok: '1.0.0' },
+      devDependencies: { buildgpl: '1.0.0' }
+    },
+    lockPackages: {
+      'node_modules/runtimeok': { version: '1.0.0', license: 'MIT' },
+      'node_modules/buildgpl': { version: '1.0.0', license: 'GPL-3.0', dev: true }
+    },
+    policy: {
+      settings: {
+        allowedCategories: ['Permissive Licenses'],
+        failOnUnknownLicense: true,
+        timezone: 'UTC',
+        dependencyTypes: ['dependencies', 'devDependencies']
+      }
+    }
+  });
+
+  await runCli(cwd, ['--violations-out', 'violations.json'], {
+    expectFail: true
+  });
+
+  const violations = readViolations(cwd);
+  assert.equal(violations.length, 1);
+  assert.equal(violations[0].name, 'buildgpl');
+  assert.equal(violations[0].reasonType, 'license-not-allowed');
+});
+
+test('standard policy allows weak copyleft licenses', async () => {
+  const cwd = createFixtureProject({
+    prefix: 'periapsis-weak-copyleft-',
+    packageJson: {
+      name: 'weak-copyleft-app',
+      version: '1.0.0',
+      dependencies: { liblgpl: '1.0.0' }
+    },
+    lockPackages: {
+      'node_modules/liblgpl': { version: '1.0.0', license: 'LGPL-2.1-only' }
+    },
+    policy: {
+      settings: {
+        allowedCategories: ['Permissive Licenses', 'Weak Copyleft Licenses'],
+        failOnUnknownLicense: true,
+        timezone: 'UTC',
+        dependencyTypes: ['dependencies']
+      }
+    }
+  });
+
+  await runCli(cwd, ['--violations-out', 'violations.json', '--quiet']);
+
+  assert.deepEqual(readViolations(cwd), []);
+});
+
+test('expired exception is surfaced as a policy regression', async () => {
+  const cwd = createFixtureProject({
+    prefix: 'periapsis-expired-exception-',
+    packageJson: {
+      name: 'expired-exception-app',
+      version: '1.0.0',
+      dependencies: { vendorpkg: '1.4.0' }
+    },
+    lockPackages: {
+      'node_modules/vendorpkg': { version: '1.4.0', license: 'LicenseRef-Vendor' }
+    },
+    policy: {
+      settings: {
+        allowedCategories: ['Permissive Licenses'],
+        failOnUnknownLicense: true,
+        timezone: 'UTC',
+        dependencyTypes: ['dependencies']
+      },
+      exceptions: [
+        {
+          package: 'vendorpkg',
+          scope: { type: 'range', range: '^1.2.0' },
+          detectedLicenses: ['LicenseRef-Vendor'],
+          reason: 'Temporary approval',
+          notes: null,
+          approvedBy: ['legal'],
+          approvedAt: '2025-01-01T00:00:00Z',
+          expiresAt: '2025-12-31T00:00:00Z',
+          evidenceRef: 'JIRA-EX-1'
+        }
+      ]
+    }
+  });
+
+  await runCli(cwd, ['--violations-out', 'violations.json'], {
+    expectFail: true
+  });
+
+  const violations = readViolations(cwd);
+  assert.equal(violations[0].reasonType, 'expired-exception');
+});
+
+test('active follow-up exception keeps previously-expired package compliant', async () => {
+  const cwd = createFixtureProject({
+    prefix: 'periapsis-followup-exception-',
+    packageJson: {
+      name: 'followup-exception-app',
+      version: '1.0.0',
+      dependencies: { vendorpkg: '1.4.0' }
+    },
+    lockPackages: {
+      'node_modules/vendorpkg': { version: '1.4.0', license: 'LicenseRef-Vendor' }
+    },
+    policy: {
+      settings: {
+        allowedCategories: ['Permissive Licenses'],
+        failOnUnknownLicense: true,
+        timezone: 'UTC',
+        dependencyTypes: ['dependencies']
+      },
+      exceptions: [
+        {
+          package: 'vendorpkg',
+          scope: { type: 'range', range: '^1.2.0' },
+          detectedLicenses: ['LicenseRef-Vendor'],
+          reason: 'Temporary approval',
+          notes: null,
+          approvedBy: ['legal'],
+          approvedAt: '2025-01-01T00:00:00Z',
+          expiresAt: '2025-12-31T00:00:00Z',
+          evidenceRef: 'JIRA-EX-1'
+        },
+        {
+          package: 'vendorpkg',
+          scope: { type: 'range', range: '^1.2.0' },
+          detectedLicenses: ['LicenseRef-Vendor'],
+          reason: 'Renewed approval',
+          notes: null,
+          approvedBy: ['legal', 'security'],
+          approvedAt: '2026-01-15T00:00:00Z',
+          expiresAt: '2026-12-31T00:00:00Z',
+          evidenceRef: 'JIRA-EX-2'
+        }
+      ]
+    }
+  });
+
+  await runCli(cwd, ['--violations-out', 'violations.json', '--quiet']);
+
+  assert.deepEqual(readViolations(cwd), []);
+});

package/testing/helpers.mjs

@@ -0,0 +1,121 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { main } from '../bin/periapsis.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const REPO_ROOT = path.resolve(__dirname, '..');
+export const BIN = path.join(REPO_ROOT, 'bin', 'periapsis.mjs');
+
+export function createTempDir(prefix = 'periapsis-test-') {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+export function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function writePolicyBundle(
+  root,
+  {
+    settings = {
+      allowedCategories: ['Permissive Licenses'],
+      failOnUnknownLicense: true,
+      timezone: 'UTC',
+      dependencyTypes: [
+        'dependencies',
+        'devDependencies',
+        'peerDependencies',
+        'optionalDependencies',
+        'bundledDependencies'
+      ]
+    },
+    licenses = [],
+    exceptions = []
+  } = {}
+) {
+  writeJson(path.join(root, 'policy', 'policy.json'), settings);
+  writeJson(path.join(root, 'policy', 'licenses.json'), licenses);
+  writeJson(path.join(root, 'policy', 'exceptions.json'), exceptions);
+}
+
+export function writeProject(root, { packageJson, lockPackages }) {
+  writeJson(path.join(root, 'package.json'), packageJson);
+  writeJson(path.join(root, 'package-lock.json'), {
+    name: packageJson.name || 'fixture-app',
+    version: packageJson.version || '1.0.0',
+    lockfileVersion: 3,
+    packages: {
+      '': {
+        name: packageJson.name || 'fixture-app',
+        version: packageJson.version || '1.0.0',
+        dependencies: packageJson.dependencies || {},
+        devDependencies: packageJson.devDependencies || {},
+        peerDependencies: packageJson.peerDependencies || {},
+        optionalDependencies: packageJson.optionalDependencies || {},
+        bundledDependencies: packageJson.bundledDependencies || packageJson.bundleDependencies || []
+      },
+      ...lockPackages
+    }
+  });
+
+  for (const pkgPath of Object.keys(lockPackages)) {
+    if (!pkgPath.startsWith('node_modules/')) continue;
+    fs.mkdirSync(path.join(root, pkgPath), { recursive: true });
+  }
+}
+
+export function createFixtureProject({
+  packageJson,
+  lockPackages,
+  policy,
+  prefix
+}) {
+  const root = createTempDir(prefix);
+  writePolicyBundle(root, policy);
+  writeProject(root, { packageJson, lockPackages });
+  return root;
+}
+
+export async function runCli(cwd, args, { expectFail = false } = {}) {
+  const originalCwd = process.cwd();
+  const originalExitCode = process.exitCode;
+  const captured = [];
+  const originalLog = console.log;
+  const originalWarn = console.warn;
+  const originalError = console.error;
+
+  console.log = (...parts) => captured.push(`${parts.join(' ')}\n`);
+  console.warn = (...parts) => captured.push(`${parts.join(' ')}\n`);
+  console.error = (...parts) => captured.push(`${parts.join(' ')}\n`);
+
+  try {
+    process.chdir(cwd);
+    process.exitCode = 0;
+
+    await main(args);
+
+    const output = captured.join('');
+    if (!expectFail && process.exitCode && process.exitCode !== 0) {
+      throw new Error(output || `Command failed with exit code ${process.exitCode}`);
+    }
+    if (expectFail && process.exitCode !== 1) {
+      throw new Error(`Expected command to fail: ${args.join(' ')}`);
+    }
+    return output;
+  } catch (err) {
+    const output = `${captured.join('')}${err.message ? `${err.message}\n` : ''}`;
+    if (!expectFail) throw err;
+    return output;
+  } finally {
+    process.chdir(originalCwd);
+    process.exitCode = originalExitCode;
+    console.log = originalLog;
+    console.warn = originalWarn;
+    console.error = originalError;
+  }
+}