@mirasen/license-gate 1.0.0

package/dist/policy/allowed-packages.js

@@ -0,0 +1,137 @@
+/**
+ * Parser for `licenses/allowed-packages.txt`.
+ *
+ * Pure: takes the file contents and a path (for error reporting), returns
+ * either a list of validated rules or throws a `LicenseGateConfigError` with
+ * `kind: 'invalid-package-override-rule'` carrying the offending line.
+ *
+ * Accepted rule forms (and ONLY these):
+ *   1. `@scope/*`                   trusted internal namespace
+ *   2. `package-name@version`       exact installed unscoped package version
+ *   3. `@scope/package@version`     exact installed scoped package version
+ *   4. `package-name@*`             package-name wildcard (any version),
+ *                                   unscoped — narrowly scoped escape hatch
+ *                                   for manually reviewed packages whose
+ *                                   version bumps should not require
+ *                                   re-editing this file.
+ *   5. `@scope/package@*`           package-name wildcard (any version),
+ *                                   scoped — same intent as form 4.
+ *
+ * Everything else is rejected, including:
+ *   - bare `package-name` (no version)
+ *   - bare `@scope/package` (no version, no `*`)
+ *   - semver ranges: `^1.2.3`, `~1.2.3`, `1.x`, `>=1.0.0`, ...
+ *   - `@scope/*@*`, `*@*`
+ *   - regex, generic glob, prefix wildcard, bare `*`
+ *   - any whitespace inside the rule
+ */
+import { LicenseGateConfigError } from '../types.js';
+// Unscoped package name: lowercase letters, digits, '.', '_', '-', no leading dot or underscore.
+// We are conservative — npm itself allows more, but policy files are author-edited so a tight
+// pattern catches typos rather than letting them through.
+const UNSCOPED_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+const SCOPE = /^@[a-z0-9][a-z0-9._-]*$/;
+// Strict semver-like version: digits.digits.digits with optional pre-release/build.
+// We do NOT accept ranges, partials, or `*` here — those are rejected.
+const EXACT_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function rejectWith(path, lineNumber, line, hint) {
+    throw new LicenseGateConfigError({ kind: 'invalid-package-override-rule', path, lineNumber, line }, `license-gate: ${path}:${lineNumber}: invalid package override rule "${line}". ${hint} Accepted forms: "@scope/*", "package@version", "@scope/package@version", "package@*", "@scope/package@*".`);
+}
+function parseRule(path, lineNumber, raw) {
+    const trimmed = raw.trim();
+    // Whitespace inside the rule is invalid.
+    if (/\s/.test(trimmed)) {
+        rejectWith(path, lineNumber, trimmed, 'rule must not contain internal whitespace.');
+    }
+    // Form 1: @scope/*
+    if (trimmed.endsWith('/*')) {
+        const scope = trimmed.slice(0, -2);
+        if (!SCOPE.test(scope)) {
+            rejectWith(path, lineNumber, trimmed, 'scope rules must be exactly `@scope/*` with a valid scope.');
+        }
+        return { kind: 'scope', scope, ruleText: trimmed };
+    }
+    // Forms 4 and 5: package-name wildcard `name@*` / `@scope/name@*`.
+    // The `*` is allowed ONLY as the trailing version sentinel; the head must
+    // be a valid (scoped or unscoped) package name with no other `*`.
+    if (trimmed.endsWith('@*')) {
+        const head = trimmed.slice(0, -2);
+        // Reject if `*` appears anywhere in the head — covers `@scope/*@*`,
+        // `*@*`, `pkg*@*`, etc.
+        if (head.length === 0 || head.includes('*')) {
+            rejectWith(path, lineNumber, trimmed, 'package-name wildcard must be `package@*` or `@scope/package@*`.');
+        }
+        if (head.startsWith('@')) {
+            const slash = head.indexOf('/');
+            if (slash <= 1 || slash === head.length - 1) {
+                rejectWith(path, lineNumber, trimmed, 'scoped package-name wildcard must be `@scope/name@*`.');
+            }
+            const scope = head.slice(0, slash);
+            const subname = head.slice(slash + 1);
+            if (!SCOPE.test(scope) || !UNSCOPED_NAME.test(subname)) {
+                rejectWith(path, lineNumber, trimmed, 'scope or package name is malformed.');
+            }
+            return { kind: 'scoped-package-name', scope, name: head, ruleText: trimmed };
+        }
+        if (!UNSCOPED_NAME.test(head)) {
+            rejectWith(path, lineNumber, trimmed, 'package name is malformed.');
+        }
+        return { kind: 'package-name', name: head, ruleText: trimmed };
+    }
+    // Reject genuinely glob/regex-like characters early. We deliberately do
+    // NOT include `+` here because `+` is a valid SemVer build-metadata
+    // separator (e.g. `pkg@1.2.3+build.42`); the head/version regexes below
+    // still reject `+` if it appears in the package-name part. Likewise `-`
+    // is a valid SemVer pre-release separator.
+    if (trimmed === '*' || trimmed.includes('*') || /[\\(){}|^$?]/.test(trimmed)) {
+        rejectWith(path, lineNumber, trimmed, 'wildcards, regex, and glob syntax are not allowed.');
+    }
+    // Must contain `@` separating name and version (for the version-bearing forms).
+    // For scoped names the version `@` is the LAST `@`.
+    const lastAt = trimmed.lastIndexOf('@');
+    if (lastAt <= 0) {
+        rejectWith(path, lineNumber, trimmed, 'missing version. Override rules must pin an exact version.');
+    }
+    const head = trimmed.slice(0, lastAt);
+    const version = trimmed.slice(lastAt + 1);
+    if (!EXACT_VERSION.test(version)) {
+        rejectWith(path, lineNumber, trimmed, `version must be an exact semver (got "${version}"). Semver ranges, "*" and partial versions are not allowed.`);
+    }
+    if (head.startsWith('@')) {
+        // Scoped: @scope/name
+        const slash = head.indexOf('/');
+        if (slash <= 1 || slash === head.length - 1) {
+            rejectWith(path, lineNumber, trimmed, 'scoped package must be `@scope/name@version`.');
+        }
+        const scope = head.slice(0, slash);
+        const subname = head.slice(slash + 1);
+        if (!SCOPE.test(scope) || !UNSCOPED_NAME.test(subname)) {
+            rejectWith(path, lineNumber, trimmed, 'scope or package name is malformed.');
+        }
+        return {
+            kind: 'scoped-package-version',
+            scope,
+            name: head,
+            version,
+            ruleText: trimmed
+        };
+    }
+    if (!UNSCOPED_NAME.test(head)) {
+        rejectWith(path, lineNumber, trimmed, 'package name is malformed.');
+    }
+    return { kind: 'package-version', name: head, version, ruleText: trimmed };
+}
+export function parseAllowedPackages(contents, path) {
+    const out = [];
+    let lineNumber = 0;
+    for (const rawLine of contents.split(/\r?\n/)) {
+        lineNumber++;
+        const trimmed = rawLine.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith('#'))
+            continue;
+        out.push(parseRule(path, lineNumber, trimmed));
+    }
+    return out;
+}

package/dist/policy/evaluate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Policy evaluator — pure: maps records + allowlists → decisions.
+ *
+ * Per design D5/D5a + add-package-wildcard-overrides:
+ *   1. license == "could not determine":
+ *        override matches  → allowed-by-{scope|package-version|package-name}-rule
+ *        else              → violation { reason: "package-not-in-allowlist" }
+ *   2. literal license string in allowed-hard.txt:
+ *        → allowed-by-license   (override is ignored: license-allow wins)
+ *   3. otherwise SPDX evaluation (with WITH-exception leaves reduced to
+ *      "<id> WITH <exc>" composite literals):
+ *        satisfied                  → allowed-by-license
+ *        unsatisfied + override     → allowed-by-{scope|package-version|package-name}-rule
+ *        unsatisfied + no override  → license-not-in-allowlist
+ *                                      / spdx-expression-not-satisfied
+ *        unparseable + override     → allowed-by-{scope|package-version|package-name}-rule
+ *        unparseable + no override  → license-not-in-allowlist
+ *                                      / literal-not-allowed-and-spdx-unparseable
+ *
+ * Override precedence when multiple `allowed-packages.txt` rules match the
+ * same installed package (most-specific wins, license-allow already short-
+ * circuits earlier):
+ *   (a) exact `package@version` / `@scope/package@version`
+ *   (b) `package@*` / `@scope/package@*`
+ *   (c) `@scope/*`
+ */
+import { type AllowedHardList, type AllowedPackages, type Decision, type InstalledPackageRecord } from '../types.js';
+export declare function evaluateRecord(record: InstalledPackageRecord, allowedHard: AllowedHardList, allowedPackages: AllowedPackages): Decision;
+/** Evaluate a list of records, returning all decisions in the same order. */
+export declare function evaluateAll(records: InstalledPackageRecord[], allowedHard: AllowedHardList, allowedPackages: AllowedPackages): Decision[];

package/dist/policy/evaluate.js

@@ -0,0 +1,151 @@
+/**
+ * Policy evaluator — pure: maps records + allowlists → decisions.
+ *
+ * Per design D5/D5a + add-package-wildcard-overrides:
+ *   1. license == "could not determine":
+ *        override matches  → allowed-by-{scope|package-version|package-name}-rule
+ *        else              → violation { reason: "package-not-in-allowlist" }
+ *   2. literal license string in allowed-hard.txt:
+ *        → allowed-by-license   (override is ignored: license-allow wins)
+ *   3. otherwise SPDX evaluation (with WITH-exception leaves reduced to
+ *      "<id> WITH <exc>" composite literals):
+ *        satisfied                  → allowed-by-license
+ *        unsatisfied + override     → allowed-by-{scope|package-version|package-name}-rule
+ *        unsatisfied + no override  → license-not-in-allowlist
+ *                                      / spdx-expression-not-satisfied
+ *        unparseable + override     → allowed-by-{scope|package-version|package-name}-rule
+ *        unparseable + no override  → license-not-in-allowlist
+ *                                      / literal-not-allowed-and-spdx-unparseable
+ *
+ * Override precedence when multiple `allowed-packages.txt` rules match the
+ * same installed package (most-specific wins, license-allow already short-
+ * circuits earlier):
+ *   (a) exact `package@version` / `@scope/package@version`
+ *   (b) `package@*` / `@scope/package@*`
+ *   (c) `@scope/*`
+ */
+import { LICENSE_COULD_NOT_DETERMINE } from '../types.js';
+import { evaluateSpdx } from './spdx-shape.js';
+/** Find the override rule that matches a record. When several match (e.g.
+ *  both `@scope/*`, `@scope/foo@*`, and `@scope/foo@1.2.3`), apply the
+ *  precedence: exact version > package-name wildcard > scope wildcard. */
+function findMatchingOverride(record, rules) {
+    let scopeMatch = null;
+    let nameMatch = null;
+    let exactMatch = null;
+    for (const rule of rules) {
+        switch (rule.kind) {
+            case 'package-version':
+                if (rule.name === record.name && rule.version === record.version) {
+                    exactMatch = rule;
+                }
+                break;
+            case 'scoped-package-version':
+                if (rule.name === record.name && rule.version === record.version) {
+                    exactMatch = rule;
+                }
+                break;
+            case 'package-name':
+                if (rule.name === record.name) {
+                    nameMatch = rule;
+                }
+                break;
+            case 'scoped-package-name':
+                if (rule.name === record.name) {
+                    nameMatch = rule;
+                }
+                break;
+            case 'scope':
+                if (record.name.startsWith(`${rule.scope}/`)) {
+                    scopeMatch = rule;
+                }
+                break;
+            default: {
+                const _never = rule;
+                throw new Error(`unreachable rule: ${JSON.stringify(_never)}`);
+            }
+        }
+    }
+    return exactMatch ?? nameMatch ?? scopeMatch;
+}
+function overrideToDecision(record, rule) {
+    switch (rule.kind) {
+        case 'scope':
+            return {
+                record,
+                outcome: 'allowed-by-scope-rule',
+                matchedPackageRule: rule.ruleText
+            };
+        case 'package-version':
+        case 'scoped-package-version':
+            return {
+                record,
+                outcome: 'allowed-by-package-version-rule',
+                matchedPackageRule: rule.ruleText
+            };
+        case 'package-name':
+        case 'scoped-package-name':
+            return {
+                record,
+                outcome: 'allowed-by-package-name-rule',
+                matchedPackageRule: rule.ruleText
+            };
+        default: {
+            const _never = rule;
+            throw new Error(`unreachable rule: ${JSON.stringify(_never)}`);
+        }
+    }
+}
+export function evaluateRecord(record, allowedHard, allowedPackages) {
+    // Step 1 — could not determine.
+    if (record.license === LICENSE_COULD_NOT_DETERMINE) {
+        const override = findMatchingOverride(record, allowedPackages);
+        if (override)
+            return overrideToDecision(record, override);
+        return {
+            record,
+            outcome: 'violation',
+            reason: { kind: 'package-not-in-allowlist' }
+        };
+    }
+    const licenseString = record.license;
+    // Step 2 — literal full-string match wins, ignores any override.
+    if (allowedHard.has(licenseString)) {
+        return { record, outcome: 'allowed-by-license' };
+    }
+    // Step 3 — SPDX evaluation.
+    const spdx = evaluateSpdx(licenseString, allowedHard);
+    if (spdx.kind === 'satisfied') {
+        return { record, outcome: 'allowed-by-license' };
+    }
+    // Both unsatisfied and unparseable can be rescued by an override.
+    const override = findMatchingOverride(record, allowedPackages);
+    if (override)
+        return overrideToDecision(record, override);
+    if (spdx.kind === 'unparseable') {
+        return {
+            record,
+            outcome: 'violation',
+            reason: {
+                kind: 'license-not-in-allowlist',
+                raw: licenseString,
+                detailCode: 'literal-not-allowed-and-spdx-unparseable'
+            }
+        };
+    }
+    // spdx.kind === 'unsatisfied'
+    return {
+        record,
+        outcome: 'violation',
+        reason: {
+            kind: 'license-not-in-allowlist',
+            raw: licenseString,
+            detailCode: 'spdx-expression-not-satisfied',
+            offendingLeaves: spdx.offendingLeaves
+        }
+    };
+}
+/** Evaluate a list of records, returning all decisions in the same order. */
+export function evaluateAll(records, allowedHard, allowedPackages) {
+    return records.map((r) => evaluateRecord(r, allowedHard, allowedPackages));
+}

package/dist/policy/spdx-shape.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SPDX expression evaluation — boolean shape only.
+ *
+ * Wraps `spdx-expression-parse`. We never use `spdx-correct`, never use
+ * `spdx-satisfies`, never normalise license ids or exception ids.
+ *
+ * AST shapes returned by `spdx-expression-parse`:
+ *   { license: "MIT" }                                         // bare leaf
+ *   { license: "GPL-2.0-only", exception: "Classpath-..." }    // WITH-leaf
+ *   { left: <node>, conjunction: "or"|"and", right: <node> }   // boolean
+ *
+ * Per design D5/D5a, a WITH-exception leaf reduces to ONE literal string of
+ * the form "<license-id> WITH <exception-id>" joined with a single ASCII
+ * space, and that composite is the literal compared against allowed-hard.txt.
+ * The bare license id is NOT considered separately.
+ */
+import type { AllowedHardList } from '../types.js';
+type LeafNode = {
+    license: string;
+    exception?: string;
+};
+/** Render an AST leaf back to the literal string used for allowlist lookup. */
+export declare function renderLeafLiteral(leaf: LeafNode): string;
+export type SpdxOutcome = {
+    kind: 'unparseable';
+} | {
+    kind: 'satisfied';
+} | {
+    kind: 'unsatisfied';
+    offendingLeaves: string[];
+};
+/** Evaluate a license string as an SPDX expression against an allowlist. */
+export declare function evaluateSpdx(licenseString: string, allowed: AllowedHardList): SpdxOutcome;
+export {};

package/dist/policy/spdx-shape.js

@@ -0,0 +1,76 @@
+/**
+ * SPDX expression evaluation — boolean shape only.
+ *
+ * Wraps `spdx-expression-parse`. We never use `spdx-correct`, never use
+ * `spdx-satisfies`, never normalise license ids or exception ids.
+ *
+ * AST shapes returned by `spdx-expression-parse`:
+ *   { license: "MIT" }                                         // bare leaf
+ *   { license: "GPL-2.0-only", exception: "Classpath-..." }    // WITH-leaf
+ *   { left: <node>, conjunction: "or"|"and", right: <node> }   // boolean
+ *
+ * Per design D5/D5a, a WITH-exception leaf reduces to ONE literal string of
+ * the form "<license-id> WITH <exception-id>" joined with a single ASCII
+ * space, and that composite is the literal compared against allowed-hard.txt.
+ * The bare license id is NOT considered separately.
+ */
+import spdxParse from 'spdx-expression-parse';
+/** Render an AST leaf back to the literal string used for allowlist lookup. */
+export function renderLeafLiteral(leaf) {
+    if (typeof leaf.exception === 'string' && leaf.exception.length > 0) {
+        return `${leaf.license} WITH ${leaf.exception}`;
+    }
+    return leaf.license;
+}
+function isLeaf(node) {
+    return typeof node.license === 'string';
+}
+/** Walk an AST; satisfied iff every leaf reachable through the boolean
+ *  semantics is in the allowlist. */
+function walk(node, allowed, collected) {
+    if (isLeaf(node)) {
+        const literal = renderLeafLiteral(node);
+        if (allowed.has(literal))
+            return true;
+        collected.add(literal);
+        return false;
+    }
+    const leftCollected = new Set();
+    const rightCollected = new Set();
+    const leftOk = walk(node.left, allowed, leftCollected);
+    const rightOk = walk(node.right, allowed, rightCollected);
+    if (node.conjunction === 'and') {
+        // Both must satisfy. Bubble up offending leaves from any side that
+        // failed (only meaningful when AND is unsatisfied).
+        if (leftOk && rightOk)
+            return true;
+        for (const l of leftCollected)
+            collected.add(l);
+        for (const l of rightCollected)
+            collected.add(l);
+        return false;
+    }
+    // OR: either side satisfying is enough.
+    if (leftOk || rightOk)
+        return true;
+    for (const l of leftCollected)
+        collected.add(l);
+    for (const l of rightCollected)
+        collected.add(l);
+    return false;
+}
+/** Evaluate a license string as an SPDX expression against an allowlist. */
+export function evaluateSpdx(licenseString, allowed) {
+    let ast;
+    try {
+        ast = spdxParse(licenseString);
+    }
+    catch {
+        return { kind: 'unparseable' };
+    }
+    const offending = new Set();
+    const ok = walk(ast, allowed, offending);
+    if (ok)
+        return { kind: 'satisfied' };
+    return { kind: 'unsatisfied', offendingLeaves: Array.from(offending) };
+}

package/dist/report/human.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Human-readable reporters for `check` and `collect`.
+ * Pure functions returning strings; the command layer prints/writes them.
+ */
+import type { CollectedRecord, Decision, InstalledPackageRecord } from '../types.js';
+/** Render the `check` result as readable text. */
+export declare function renderCheckHuman(input: {
+    decisions: Decision[];
+    skippedProjectRoot: InstalledPackageRecord | null;
+}): string;
+/** Render the `collect` result as readable text. */
+export declare function renderCollectHuman(records: CollectedRecord[]): string;

package/dist/report/human.js

@@ -0,0 +1,117 @@
+/**
+ * Human-readable reporters for `check` and `collect`.
+ * Pure functions returning strings; the command layer prints/writes them.
+ */
+function fmtViolationReason(reason) {
+    switch (reason.kind) {
+        case 'package-not-in-allowlist':
+            return 'package-not-in-allowlist (no usable package.json#license string and no allowed-packages.txt rule matched)';
+        case 'license-not-in-allowlist': {
+            const head = `license-not-in-allowlist (raw: "${reason.raw}")`;
+            if (reason.detailCode === 'literal-not-allowed-and-spdx-unparseable') {
+                return `${head} — literal not allowed; SPDX expression unparseable`;
+            }
+            if (reason.detailCode === 'spdx-expression-not-satisfied') {
+                const leaves = reason.offendingLeaves?.join(', ') ?? '';
+                return `${head} — SPDX expression parsed but not satisfied; offending leaves: [${leaves}]`;
+            }
+            return head;
+        }
+        default: {
+            // Exhaustiveness check.
+            const _never = reason;
+            return `unknown violation (${JSON.stringify(_never)})`;
+        }
+    }
+}
+/** Render the `check` result as readable text. */
+export function renderCheckHuman(input) {
+    const { decisions, skippedProjectRoot } = input;
+    const lines = [];
+    const allowedByLicense = [];
+    const allowedByScope = [];
+    const allowedByPackageVersion = [];
+    const allowedByPackageName = [];
+    const violations = [];
+    for (const d of decisions) {
+        switch (d.outcome) {
+            case 'allowed-by-license':
+                allowedByLicense.push(d);
+                break;
+            case 'allowed-by-scope-rule':
+                allowedByScope.push(d);
+                break;
+            case 'allowed-by-package-version-rule':
+                allowedByPackageVersion.push(d);
+                break;
+            case 'allowed-by-package-name-rule':
+                allowedByPackageName.push(d);
+                break;
+            case 'violation':
+                violations.push(d);
+                break;
+            default: {
+                const _never = d;
+                throw new Error(`unreachable decision: ${JSON.stringify(_never)}`);
+            }
+        }
+    }
+    lines.push('license-gate check');
+    if (skippedProjectRoot) {
+        lines.push(`  (skipped: project root) ${skippedProjectRoot.packageId} [${skippedProjectRoot.path}]`);
+    }
+    lines.push(`  evaluated:                  ${decisions.length}`);
+    lines.push(`  allowed by license:         ${allowedByLicense.length}`);
+    lines.push(`  allowed by scope rule:      ${allowedByScope.length}`);
+    lines.push(`  allowed by package@version: ${allowedByPackageVersion.length}`);
+    lines.push(`  allowed by package@*:       ${allowedByPackageName.length}`);
+    lines.push(`  violations:                 ${violations.length}`);
+    lines.push('');
+    if (allowedByScope.length > 0 ||
+        allowedByPackageVersion.length > 0 ||
+        allowedByPackageName.length > 0) {
+        lines.push('Package overrides applied:');
+        for (const d of [...allowedByPackageVersion, ...allowedByPackageName, ...allowedByScope]) {
+            if (d.outcome !== 'allowed-by-scope-rule' &&
+                d.outcome !== 'allowed-by-package-version-rule' &&
+                d.outcome !== 'allowed-by-package-name-rule')
+                continue;
+            lines.push(`  ✓ ${d.record.packageId} — ${d.matchedPackageRule}`);
+        }
+        lines.push('');
+    }
+    if (violations.length > 0) {
+        lines.push('Violations:');
+        for (const v of violations) {
+            lines.push(`  ✗ ${v.record.packageId}`);
+            lines.push(`      ${fmtViolationReason(v.reason)}`);
+            lines.push(`      path: ${v.record.path}`);
+        }
+        lines.push('');
+        lines.push('FAILED: at least one license policy violation.');
+    }
+    else {
+        lines.push('PASSED: no license policy violations.');
+    }
+    return lines.join('\n') + '\n';
+}
+/** Render the `collect` result as readable text. */
+export function renderCollectHuman(records) {
+    const lines = [];
+    lines.push('license-gate collect');
+    lines.push(`  records: ${records.length}`);
+    lines.push('');
+    for (const r of records) {
+        const tag = r.isProjectRoot ? ' (project root)' : '';
+        lines.push(`  ${r.packageId}${tag}`);
+        lines.push(`    license: ${r.license}`);
+        lines.push(`    path:    ${r.path}`);
+        if (r.repository)
+            lines.push(`    repo:    ${r.repository}`);
+        if (r.publisher || r.email) {
+            const author = [r.publisher, r.email ? `<${r.email}>` : null].filter(Boolean).join(' ');
+            lines.push(`    author:  ${author}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/report/json.d.ts

@@ -0,0 +1,27 @@
+/**
+ * JSON reporters for `check` and `collect`. Stable, machine-readable.
+ *
+ * The shape is intentionally explicit so consumers can rely on it across
+ * v1.x without surprises.
+ */
+import type { CollectedRecord, Decision, InstalledPackageRecord } from '../types.js';
+export type CheckJsonReport = {
+    skippedProjectRoot: InstalledPackageRecord | null;
+    counts: {
+        evaluated: number;
+        allowedByLicense: number;
+        allowedByScopeRule: number;
+        allowedByPackageVersionRule: number;
+        allowedByPackageNameRule: number;
+        violations: number;
+    };
+    decisions: Decision[];
+};
+export declare function renderCheckJson(input: {
+    decisions: Decision[];
+    skippedProjectRoot: InstalledPackageRecord | null;
+}): string;
+export type CollectJsonReport = {
+    records: CollectedRecord[];
+};
+export declare function renderCollectJson(records: CollectedRecord[]): string;

package/dist/report/json.js

@@ -0,0 +1,53 @@
+/**
+ * JSON reporters for `check` and `collect`. Stable, machine-readable.
+ *
+ * The shape is intentionally explicit so consumers can rely on it across
+ * v1.x without surprises.
+ */
+export function renderCheckJson(input) {
+    let allowedByLicense = 0;
+    let allowedByScopeRule = 0;
+    let allowedByPackageVersionRule = 0;
+    let allowedByPackageNameRule = 0;
+    let violations = 0;
+    for (const d of input.decisions) {
+        switch (d.outcome) {
+            case 'allowed-by-license':
+                allowedByLicense++;
+                break;
+            case 'allowed-by-scope-rule':
+                allowedByScopeRule++;
+                break;
+            case 'allowed-by-package-version-rule':
+                allowedByPackageVersionRule++;
+                break;
+            case 'allowed-by-package-name-rule':
+                allowedByPackageNameRule++;
+                break;
+            case 'violation':
+                violations++;
+                break;
+            default: {
+                const _never = d;
+                throw new Error(`unreachable decision: ${JSON.stringify(_never)}`);
+            }
+        }
+    }
+    const report = {
+        skippedProjectRoot: input.skippedProjectRoot,
+        counts: {
+            evaluated: input.decisions.length,
+            allowedByLicense,
+            allowedByScopeRule,
+            allowedByPackageVersionRule,
+            allowedByPackageNameRule,
+            violations
+        },
+        decisions: input.decisions
+    };
+    return JSON.stringify(report, null, 2) + '\n';
+}
+export function renderCollectJson(records) {
+    const report = { records };
+    return JSON.stringify(report, null, 2) + '\n';
+}