periapsis 0.0.0

package/README.md

@@ -0,0 +1,65 @@
+# Periapsis (draft)
+
+License compliance radar for Node dependencies. Reads `package-lock.json` + installed `node_modules`, emits a full SBOM JSON, and fails CI when licenses violate your allowlist. Supports exceptions and traces upstream chains for each violation.
+
+## Install / Run
+
+Local clone:
+
+```sh
+npm install  # only needed if you add dependencies later; currently none
+npx periapsis --allowed ../allowed-licenses.example.json --violations-out ../sbom-violations.json
+```
+
+When published to npm (recommended):
+
+```sh
+npx periapsis --allowed .sbom-allowlist.json --violations-out sbom-violations.json
+```
+
+Initialize an allowlist based on SPDX categories:
+
+```sh
+npx periapsis init --preset strict
+```
+
+## Options
+
+- `--root <path>`: project root (defaults to `cwd`)
+- `--lock <file>`: lockfile (default `package-lock.json`)
+- `--out <file>`: SBOM JSON output (default `sbom-licenses.json`)
+- `--allowed <file>`: allowlist JSON
+- `--violations-out <file>`: write violations JSON (includes upstream chains)
+- `--quiet`: suppress summary output
+- `init --preset <level>`: write `allowedConfig.json` (strict | standard | permissive)
+- `init --force`: overwrite existing `allowedConfig.json`
+
+Allowlist file schema:
+
+```json
+{
+  "allowedCategories": ["A", "B"],
+  "allowedLicenses": ["MIT", "Apache-2.0"],
+  "exceptions": ["package-name", "name@1.2.3"]
+}
+```
+
+## GitHub Action (example)
+
+```yaml
+- uses: actions/checkout@v4
+- uses: actions/setup-node@v4
+  with:
+    node-version: 20
+    cache: npm
+- run: npm ci
+- run: npx periapsis --allowed .sbom-allowlist.json --violations-out sbom-violations.json
+- run: |
+    node -e "const fs=require('fs');const p='sbom-violations.json';if(!fs.existsSync(p))process.exit(1);const d=JSON.parse(fs.readFileSync(p,'utf8'));const c=Array.isArray(d)?d.length:Array.isArray(d.violations)?d.violations.length:0;if(c>0){console.error(`Found ${c} license violations`);process.exit(1);}console.log('No license violations');"
+```
+
+## Publish checklist
+
+- Update `package.json` name/version, remove `"private": true` when ready.
+- Add CI (lint/test) and changelog.
+- Tag a release and publish to npm: `npm publish`.

package/bin/periapsis.mjs

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function parseArgs(argv) {
+  const args = {};
+  let i = 0;
+  if (argv[0] && !argv[0].startsWith('-')) {
+    args.command = argv[0];
+    i = 1;
+  }
+  for (; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      args.help = true;
+    } else if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`Usage: periapsis [options]
+       periapsis init [options]
+
+Options:
+  --root <path>             Project root (default: cwd)
+  --lock <file>             Lockfile to read (default: package-lock.json)
+  --out <file>              SBOM JSON output (default: sbom-licenses.json)
+  --allowed <file>          JSON file containing allowed licenses and optional exceptions
+  --violations-out <file>   Where to write violating packages (optional)
+  --quiet                   Suppress summary output
+  -h, --help                Show this help
+
+Init options:
+  --preset <level>          strict | standard | permissive (default: strict)
+  --force                   Overwrite existing allowedConfig.json
+
+Allowed licenses file:
+  Can be an array of strings or an object like:
+    {
+      "allowedCategories": ["A", "B"],
+      "allowedLicenses": ["MIT", "Apache-2.0"],
+      "exceptions": ["package-name", "other@1.2.3"]
+    }
+`);
+}
+
+function loadJson(filePath, description) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    console.error(`Failed to read ${description} at ${filePath}: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function loadAllowedConfig(filePath) {
+  const raw = loadJson(filePath, 'allowed licenses file');
+  const list = Array.isArray(raw) ? raw : raw?.allowedLicenses || [];
+  if (!Array.isArray(list)) {
+    console.error(
+      'Allowed licenses file must be an array or contain { "allowedLicenses": [] }'
+    );
+    process.exit(1);
+  }
+  const allowedCategoriesRaw = Array.isArray(raw?.allowedCategories)
+    ? raw.allowedCategories
+    : [];
+  if (raw?.allowedCategories && !Array.isArray(raw.allowedCategories)) {
+    console.error('allowedCategories must be an array like ["A", "B"]');
+    process.exit(1);
+  }
+  const allowedLicenses = new Set(list.map((l) => String(l).trim()).filter(Boolean));
+  const allowedCategories = new Set(
+    allowedCategoriesRaw.map((c) => String(c).trim().toUpperCase()).filter(Boolean)
+  );
+  const exceptions = new Set(
+    (raw?.exceptions || []).map((e) => String(e).trim()).filter(Boolean)
+  );
+  return { allowedLicenses, allowedCategories, exceptions };
+}
+
+function extractLicense(pkgJson) {
+  if (!pkgJson) return null;
+  const lic = pkgJson.license || pkgJson.licenses;
+  if (!lic) return null;
+  if (typeof lic === 'string') return lic;
+  if (Array.isArray(lic)) {
+    return lic
+      .map((entry) => (typeof entry === 'string' ? entry : entry?.type || entry?.name))
+      .filter(Boolean)
+      .join(' OR ');
+  }
+  if (typeof lic === 'object') return lic.type || lic.name || null;
+  return null;
+}
+
+function licenseTokens(license) {
+  if (!license) return ['UNKNOWN'];
+  return license
+    .split(/\s*(?:\(|\)|\+|\/|\s+OR\s+|\s+AND\s+|,|;|\||\s+with\s+)/i)
+    .map((t) => t.trim())
+    .filter(Boolean);
+}
+
+function loadSpdxCategories() {
+  const spdxPath = path.resolve(__dirname, '..', 'spdx_licenses_with_categories.json');
+  if (!fs.existsSync(spdxPath)) {
+    return new Map();
+  }
+  const list = loadJson(spdxPath, 'SPDX licenses with categories');
+  const map = new Map();
+  if (Array.isArray(list)) {
+    for (const entry of list) {
+      if (!entry) continue;
+      const id = entry.identifier ? String(entry.identifier).trim() : '';
+      const category = entry.defaultCategory ? String(entry.defaultCategory).trim() : '';
+      if (id && category) map.set(id, category.toUpperCase());
+    }
+  }
+  return map;
+}
+
+function resolveDepPath(packages, parentKey, depName) {
+  const nested = parentKey ? path.posix.join(parentKey, 'node_modules', depName) : `node_modules/${depName}`;
+  if (packages[nested]) return nested;
+  const top = `node_modules/${depName}`;
+  if (packages[top]) return top;
+  return null;
+}
+
+function buildSbom({ root, lockPath }) {
+  if (!fs.existsSync(lockPath)) {
+    console.error(`Lockfile not found at ${lockPath}`);
+    process.exit(1);
+  }
+  const lock = loadJson(lockPath, 'lockfile');
+  const packages = lock.packages || {};
+  const seen = new Set();
+  const results = [];
+  const pathMap = new Map();
+  const reverseDeps = new Map(); // childPath -> Set<parentPath>
+
+  function addReverse(child, parent) {
+    if (!reverseDeps.has(child)) reverseDeps.set(child, new Set());
+    reverseDeps.get(child).add(parent);
+  }
+
+  // Build SBOM entries and reverse dependency edges
+  for (const [key, meta] of Object.entries(packages)) {
+    if (key === '' || !key.startsWith('node_modules')) continue;
+    const absPath = path.join(root, key);
+    const pkgJsonPath = path.join(absPath, 'package.json');
+    let pkgJson = null;
+    if (fs.existsSync(pkgJsonPath)) {
+      try {
+        pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+      } catch {
+        // ignore parse errors, fallback to lock data
+      }
+    }
+    const name =
+      meta.name ||
+      pkgJson?.name ||
+      key.replace('node_modules/', '').split('node_modules/').pop();
+    const version = meta.version || pkgJson?.version || 'UNKNOWN';
+    const id = `${name}@${version}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+
+    const license = extractLicense(pkgJson) || meta.license || 'UNKNOWN';
+    const repository = pkgJson?.repository || null;
+    const entry = { name, version, license, path: key, repository };
+    results.push(entry);
+    pathMap.set(key, entry);
+
+    const deps = meta.dependencies ? Object.keys(meta.dependencies) : [];
+    for (const depName of deps) {
+      const depPath = resolveDepPath(packages, key, depName);
+      if (depPath) addReverse(depPath, key);
+    }
+  }
+
+  results.sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version));
+  // Add root-level edges
+  const rootDeps = packages['']?.dependencies ? Object.keys(packages['']?.dependencies) : [];
+  for (const depName of rootDeps) {
+    const depPath = resolveDepPath(packages, '', depName);
+    if (depPath) addReverse(depPath, '__root__');
+  }
+
+  return { sbom: results, pathMap, reverseDeps };
+}
+
+function isLicenseAllowed(token, allowedConfig, spdxCategories) {
+  if (!allowedConfig) return true;
+  const { allowedLicenses, allowedCategories } = allowedConfig;
+  if (allowedLicenses.has(token)) return true;
+  if (allowedCategories.size === 0) return false;
+  const category = spdxCategories.get(token);
+  if (!category) return false;
+  return allowedCategories.has(category);
+}
+
+function evaluateCompliance(sbom, allowedConfig, spdxCategories) {
+  if (!allowedConfig) return { violations: [] };
+  if (
+    allowedConfig.allowedLicenses.size === 0 &&
+    allowedConfig.allowedCategories.size === 0
+  ) {
+    return { violations: [] };
+  }
+  const { exceptions } = allowedConfig;
+  const violations = [];
+  for (const item of sbom) {
+    const id = `${item.name}@${item.version}`;
+    if (exceptions.has(item.name) || exceptions.has(id)) continue;
+    const tokens = licenseTokens(item.license);
+    const allowed = tokens.some((t) => isLicenseAllowed(t, allowedConfig, spdxCategories));
+    if (!allowed) violations.push(item);
+  }
+  return { violations };
+}
+
+function getUpstreamChains(targetPath, reverseDeps, pathMap, { limit = 30 } = {}) {
+  const memo = new Map();
+  function dfs(node, trail = []) {
+    if (memo.has(node)) return memo.get(node);
+    const parents = reverseDeps.get(node);
+    if (!parents || parents.size === 0) return [[node]];
+    const chains = [];
+    for (const parent of parents) {
+      if (trail.includes(parent)) continue; // avoid cycles
+      const parentChains = dfs(parent, [...trail, node]);
+      for (const chain of parentChains) {
+        chains.push([...chain, node]);
+        if (chains.length >= limit) break;
+      }
+      if (chains.length >= limit) break;
+    }
+    memo.set(node, chains);
+    return chains;
+  }
+  const rawChains = dfs(targetPath);
+  // Convert to labels and strip root marker
+  const toLabel = (p) => {
+    if (p === '__root__') return null;
+    const entry = pathMap.get(p);
+    return entry ? `${entry.name}@${entry.version}` : p;
+  };
+  return rawChains
+    .map((chain) => chain.map(toLabel).filter(Boolean))
+    .filter((chain) => chain.length > 0);
+}
+
+function writeJson(filePath, data) {
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+
+function summarize(sbom, violations) {
+  const counts = new Map();
+  for (const { license } of sbom) {
+    const key = license || 'UNKNOWN';
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+  console.log(`Total packages: ${sbom.length}`);
+  console.log('Top licenses:');
+  for (const [lic, count] of sorted.slice(0, 8)) {
+    console.log(`  ${lic}: ${count}`);
+  }
+  if (violations.length === 0) {
+    console.log('All packages comply with allowed licenses.');
+    return;
+  }
+  console.log(`Violations (${violations.length}):`);
+  const rows = violations.map((v) => [`${v.name}@${v.version}`, v.license || 'UNKNOWN']);
+  const colWidths = [0, 0];
+  for (const [pkg, lic] of rows) {
+    colWidths[0] = Math.max(colWidths[0], pkg.length);
+    colWidths[1] = Math.max(colWidths[1], lic.length);
+  }
+  const divider = '-'.repeat(colWidths[0] + colWidths[1] + 5);
+  console.log(divider);
+  console.log(
+    `${'Package'.padEnd(colWidths[0])} | ${'License'.padEnd(colWidths[1])}`
+  );
+  console.log(divider);
+  for (const [pkg, lic] of rows) {
+    console.log(`${pkg.padEnd(colWidths[0])} | ${lic.padEnd(colWidths[1])}`);
+  }
+  console.log(divider);
+}
+
+function resolveAllowedConfigPath(root, allowedArg) {
+  if (allowedArg) {
+    return path.resolve(allowedArg.startsWith('.') ? path.join(root, allowedArg) : allowedArg);
+  }
+  return path.resolve(root, 'allowedConfig.json');
+}
+
+function initAllowedConfig({ root, allowedPath, preset, force }) {
+  const categories =
+    preset === 'standard'
+      ? ['A', 'B']
+      : preset === 'permissive'
+      ? ['A', 'B', 'C']
+      : ['A'];
+  if (fs.existsSync(allowedPath) && !force) {
+    console.error(`Allowed config already exists at ${allowedPath}. Use --force to overwrite.`);
+    process.exit(1);
+  }
+  const payload = {
+    allowedCategories: categories,
+    allowedLicenses: [],
+    exceptions: []
+  };
+  writeJson(allowedPath, payload);
+  console.log(`Wrote allowed config to ${allowedPath}`);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const root = args.root ? path.resolve(args.root) : process.cwd();
+  if (args.command === 'init') {
+    const preset = args.preset ? String(args.preset).toLowerCase() : 'strict';
+    if (!['strict', 'standard', 'permissive'].includes(preset)) {
+      console.error('Invalid preset. Use strict, standard, or permissive.');
+      process.exit(1);
+    }
+    const allowedPath = resolveAllowedConfigPath(root, args.allowed);
+    initAllowedConfig({ root, allowedPath, preset, force: Boolean(args.force) });
+    return;
+  }
+
+  const lockPath = path.resolve(root, args.lock || 'package-lock.json');
+  const outPath = path.resolve(root, args.out || 'sbom-licenses.json');
+  const violationsOut = args['violations-out']
+    ? path.resolve(root, args['violations-out'])
+    : null;
+  const allowedPath = args.allowed
+    ? path.resolve(args.allowed.startsWith('.') ? path.join(root, args.allowed) : args.allowed)
+    : null;
+
+  const allowedConfig = allowedPath ? loadAllowedConfig(allowedPath) : null;
+  const spdxCategories =
+    allowedConfig && allowedConfig.allowedCategories.size > 0 ? loadSpdxCategories() : new Map();
+  const { sbom, pathMap, reverseDeps } = buildSbom({ root, lockPath });
+
+  const { violations } = evaluateCompliance(sbom, allowedConfig, spdxCategories);
+  // Decorate violations with upstream chains
+  const violationsWithUpstream = violations.map((v) => {
+    const upstream = getUpstreamChains(v.path, reverseDeps, pathMap, { limit: 50 });
+    return { ...v, upstream };
+  });
+
+  writeJson(outPath, sbom);
+  if (violationsOut) {
+    writeJson(violationsOut, violationsWithUpstream);
+  }
+
+  if (!args.quiet) {
+    console.log(`Wrote SBOM to ${outPath}`);
+    if (allowedConfig) {
+      if (allowedConfig.allowedCategories.size) {
+        console.log(
+          `Allowed categories: ${[...allowedConfig.allowedCategories].sort().join(', ')}`
+        );
+      }
+      if (allowedConfig.allowedLicenses.size) {
+        console.log(`Allowed licenses: ${[...allowedConfig.allowedLicenses].join(', ')}`);
+      }
+      if (allowedConfig.exceptions.size) {
+        console.log(
+          `Exceptions (${allowedConfig.exceptions.size}): ${[...allowedConfig.exceptions].join(', ')}`
+        );
+      }
+    }
+    if (violationsOut && violations) {
+      console.log(`Wrote violations to ${violationsOut}`);
+    }
+    if (violationsWithUpstream.length) {
+      summarize(sbom, violationsWithUpstream || []);
+      // print a brief upstream view
+      console.log('Upstream chains (first path per violation):');
+      for (const v of violationsWithUpstream) {
+        const chain = v.upstream?.[0] || [];
+        console.log(
+          `  ${v.name}@${v.version}: ${chain.length ? chain.join(' -> ') : 'no upstream (direct)'}`
+        );
+      }
+    } else {
+      summarize(sbom, violations || []);
+    }
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "periapsis",
+  "version": "0.0.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "periapsis": "bin/periapsis.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "description": "Lightweight SBOM/license checker with allowlist, exceptions, and upstream chains.",
+  "license": "MIT"
+}