@mirasen/license-gate 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# @mirasen/license-gate
+
+## 1.0.0
+
+### Major Changes
+
+- 6169add: Initial implementation of `@mirasen/license-gate` — a strict, local, default-deny license
+  policy gate for npm projects (single-package, workspaces, monorepos).
+  - Two CLI commands: `license-gate check` (gate the installed graph against
+    `licenses/allowed-hard.txt` and `licenses/allowed-packages.txt`) and `license-gate
+collect` (enumerate installed package/license metadata, no policy I/O).
+  - Project root is always `process.cwd()` — no walk-up rescue, no `--cwd`.
+  - Graph discovery via `@npmcli/arborist.loadActual()` + `tree.inventory`. Captures
+    non-hoisted workspace installs and transitive duplicates.
+  - `--workspace <name|path>` narrows the evaluation set via reachability over
+    `node.edgesOut` (never by realpath prefix, never by re-pointing Arborist).
+  - License detection is non-inferential: only a non-empty string `package.json#license`
+    is read. Object/array shapes and missing fields map to `could not determine`.
+  - Literal-first matching: the full license string is searched in `allowed-hard.txt`
+    before any SPDX parsing.
+  - SPDX boolean shape (OR/AND/parens) is supported via `spdx-expression-parse`. Each
+    leaf — including WITH-exception leaves rendered as `"<license-id> WITH <exception-id>"`
+    composites — is a literal allowlist lookup. No normalisation, no `spdx-correct`, no
+    `spdx-satisfies`.
+  - Two top-level violation reasons (`license-not-in-allowlist`,
+    `package-not-in-allowlist`) with two diagnostic detail codes
+    (`literal-not-allowed-and-spdx-unparseable`, `spdx-expression-not-satisfied`).
+  - `check --out` is rejected with exit 2; output flags are `check --json <path>` and
+    `collect --out <path>` / `collect --json <path>`.
+  - Programmatic API exported from `@mirasen/license-gate` (`runCheck`, `runCollect`).
+  - Engines tightened to Node ≥22.9.0.
+  - Public package records (`InstalledPackageRecord`, `CollectedRecord`, every JSON
+    decision/record emitted by `check --json` / `collect --json`) intentionally do NOT
+    carry a `workspace` field. Physical placement of an installed copy (hoisted vs.
+    workspace-local) is communicated entirely through the relative `path` field —
+    `node_modules/foo` for hoisted deps, `apps/web/node_modules/foo` for non-hoisted
+    workspace-local copies. The `--workspace <name|path>` CLI flag still narrows the
+    evaluation set to a workspace's reachable graph; that behavior is unchanged.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Contributors](https://github.com/mirasen-io/license-gate/graphs/contributors)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+[![NPM Version](https://img.shields.io/npm/v/%40mirasen%2Flicense-gate)](https://www.npmjs.com/package/@mirasen/license-gate)
+[![CI](https://github.com/mirasen-io/license-gate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mirasen-io/license-gate/actions/workflows/ci.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=mirasen-io_license-gate&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=mirasen-io_license-gate)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=mirasen-io_license-gate&metric=coverage)](https://sonarcloud.io/summary/new_code?id=mirasen-io_license-gate)
+[![License](https://img.shields.io/npm/l/@mirasen/license-gate)](./LICENSE)
+
+# @mirasen/license-gate
+
+A strict, local, default-deny license policy gate for npm projects — single-package, npm
+workspaces, and monorepos.
+
+`license-gate` reads your installed dependency graph (via `@npmcli/arborist`), checks every
+package against a literal license allowlist you control, and exits non-zero when anything
+fails. It is intentionally small and refuses to guess.
+
+It is a strict alternative to generic npm license checkers: instead of guessing licenses
+or hiding exceptions, it enforces your local policy file and shows every override.
+
+## Install
+
+```bash
+npm install -D @mirasen/license-gate
+```
+
+Requires **Node ≥ 22.9.0**.
+
+Run `license-gate` after `npm ci` (or after any install that produces the `node_modules`
+layout you intend to ship). The gate evaluates what is **physically installed**.
+
+## Usage
+
+```bash
+# Full project graph (project root = process.cwd())
+npx license-gate check
+
+# Run from any directory; --cwd selects the project root explicitly
+npx license-gate check --cwd /path/to/project
+
+# Narrow to one workspace
+npx license-gate check --workspace apps/web
+
+# Combine: explicit project root + workspace narrow
+npx license-gate check --cwd /path/to/monorepo --workspace apps/web
+
+# Enumerate all installed packages with their licenses (no policy I/O)
+npx license-gate collect
+```
+
+You can also invoke without local install:
+
+```bash
+npx @mirasen/license-gate check
+npx @mirasen/license-gate collect
+```
+
+Or as an npm script:
+
+```json
+{
+	"scripts": {
+		"lint:licenses": "license-gate check"
+	}
+}
+```
+
+### Commands
+
+```
+license-gate check   [--cwd <path>] [--workspace <name|path>] [--json <path>]
+license-gate collect [--cwd <path>] [--workspace <name|path>] [--out <path>] [--json <path>]
+```
+
+`check` requires `licenses/allowed-hard.txt` at the project root. `collect` does not.
+
+### Project root
+
+The project root is `--cwd <path>` if provided, otherwise `process.cwd()`. `package.json`
+must exist directly at that path — `license-gate` does **not** walk upward to find a
+parent project. All project-relative paths (`licenses/allowed-hard.txt`,
+`licenses/allowed-packages.txt`, `--workspace` relative paths, `--out`, `--json`) resolve
+against the project root.
+
+When `--workspace` is used together with `--cwd`, Arborist still loads the graph at the
+project root (never at the workspace path); narrowing is performed inside that already
+loaded tree.
+
+### Exit codes
+
+| Code | Meaning                                                |
+| ---- | ------------------------------------------------------ |
+| `0`  | clean: no violations (`check`) / completed (`collect`) |
+| `1`  | one or more policy violations                          |
+| `2`  | usage / config / runtime error                         |
+
+`check` always collects every violation before exiting; it never fails fast.
+
+## Policy files
+
+`license-gate` reads two fixed files relative to the **selected project root**
+(`--cwd` if provided, otherwise `process.cwd()`):
+
+- `licenses/allowed-hard.txt` — **required for `check`**. The literal license allowlist.
+- `licenses/allowed-packages.txt` — optional. Visible package overrides.
+
+These paths are not configurable. There is no `--allowed`, no `package.json` config, no
+environment variable. A configurable hard gate is a relaxable hard gate.
+
+### `licenses/allowed-hard.txt`
+
+```
+# One literal accepted license string per line.
+# Blank lines and `#` comments are ignored. No regex, no glob, no normalisation.
+
+MIT
+Apache-2.0
+BSD-3-Clause
+ISC
+0BSD
+```
+
+A package's `license` string must appear **verbatim** on a line above. SPDX expressions
+(`(MIT OR Apache-2.0)`, `(MIT AND BSD-3-Clause)`) are evaluated literally per leaf — each
+leaf must appear verbatim above.
+
+### `licenses/allowed-packages.txt`
+
+```
+# Package overrides. Five forms accepted, anything else is a config error (exit 2):
+#
+#   @scope/*                  trusted internal namespace
+#   package-name@version      exact installed unscoped package version
+#   @scope/package@version    exact installed scoped package version
+#   package-name@*            any installed version of exact unscoped package
+#   @scope/package@*          any installed version of exact scoped package
+
+@mirasen/*
+internal-tool@1.2.3
+@types/node@22.0.0
+spawndamnit@*
+@scope/weird-package@*
+```
+
+Override matches are **always visible** in the report (`matchedPackageRule`); they are
+never silent excludes. When several rules match the same package, the most specific rule
+wins in the audit trail, with this strict precedence: license-allow first, then exact
+`package@version`, then `package@*` / `@scope/package@*`, then `@scope/*`. When a package
+is in `allowed-hard.txt`, `allowed-by-license` wins — overrides are escape hatches, not
+the default story.
+
+**When to use which form** (most-precise to least-precise, prefer the narrower form):
+
+- `package-name@version` / `@scope/package@version` — highest precision; pin exactly
+  one version of one package. Use this for one-off, manually-reviewed packages whose
+  license terms you accept at a specific version.
+- `package-name@*` / `@scope/package@*` — same package, any version. Use this when you
+  intentionally approve the package at the package-name level rather than pinning every
+  installed version, for example to avoid repeated Dependabot allowlist edits after
+  routine version bumps. **Not** the default first choice — prefer the exact-version
+  form unless version bumps would routinely force allowlist edits.
+- `@scope/*` — broadest. Reserve for trusted internal namespaces such as `@mirasen/*`.
+  Do not use for unrelated third-party packages that happen to share a namespace.
+
+All five forms are escape hatches and remain audit-visible. The JSON report's
+`matchedPackageRule` field carries the matching rule verbatim so reviewers can see at
+a glance which override was applied.
+
+## Strict by design — what `license-gate` will NOT do
+
+- **No license file reading.** `LICENSE`, `LICENCE`, `COPYING`, `README` are never opened.
+- **No license inference or normalisation.** `Apache 2.0` (with space) is **not** the
+  same as `Apache-2.0`. `UNLICENSED`, `SEE LICENSE IN LICENSE.md` are literal strings.
+- **No `spdx-correct`. No `spdx-satisfies`.** SPDX support is exclusively about parsing
+  the boolean shape of npm's `license` field — each leaf is a literal allowlist lookup.
+- **No deprecated `license` shape unwrapping.** A package whose `package.json` has
+  `license: { type: "MIT" }` or `licenses: [...]` is treated as `could not determine`.
+- **No clarification system, no checksum-based evidence, no `licenseStart`/`licenseEnd`.**
+- **No project-root walk-up.** The project root is `--cwd` if provided, otherwise
+  `process.cwd()`. `license-gate` never walks upward to rescue a wrong working directory.
+- **No `--root`, `--project`, `--allowed`, `--allowed-packages`** flags. `--cwd <path>` is
+  the only way to point the gate at a different project root, and it is an explicit
+  project root, not a search starting point.
+- **No silent excludes.** Every package the gate considered is accounted for. The JSON
+  report (`check --json <path>`) contains a `Decision` entry for **every** evaluated
+  package — allowed and violating alike. The human report on stdout summarises the
+  allowed-by-license bucket as a count and lists every package override
+  (`matchedPackageRule`) and every violation in full; nothing is dropped.
+- **No denylist file** — strict allowlist only.
+- **No pnpm, yarn, Gradle, or Maven support in v1.** `license-gate` currently targets
+  npm projects and npm workspaces.
+- **No bundle-level analysis.** Vite/Rollup/etc. are out of scope.
+- **No markdown/tree visualisers, no SaaS upload modes, no enterprise tiers.**
+
+## Violation model
+
+There are exactly **two** top-level violation reasons:
+
+| `reason`                   | When                                                                                  |
+| -------------------------- | ------------------------------------------------------------------------------------- |
+| `license-not-in-allowlist` | Package has a usable `license` string that does not satisfy the allowlist             |
+| `package-not-in-allowlist` | Package's license is `could not determine` and no `allowed-packages.txt` rule matches |
+
+`license-not-in-allowlist` carries an optional `detailCode`:
+
+| `detailCode`                               | When                                                                                     |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `literal-not-allowed-and-spdx-unparseable` | Literal license is not allowed, and SPDX parsing failed                                  |
+| `spdx-expression-not-satisfied`            | SPDX parsed successfully but the expression was not satisfied; carries `offendingLeaves` |
+
+## SPDX semantics in plain words
+
+1. The full literal license string is checked against `allowed-hard.txt` first.
+2. If it is not literally listed, the string is parsed as an SPDX expression
+   (OR / AND / parens; WITH-exception leaves).
+3. Each leaf is compared literally against `allowed-hard.txt`. A WITH-exception leaf is
+   reduced to one composite literal `"<license-id> WITH <exception-id>"` and that whole
+   string must be in the allowlist; the bare licence id is not considered separately.
+4. AND requires every leaf to be allowed; OR requires any one leaf.
+
+## FAQ
+
+**Why does `Apache 2.0` (with a space) fail when `Apache-2.0` is allowed?**
+Because they are different strings. `license-gate` does not normalise — that's the
+point. Add `Apache 2.0` to your allowlist if you intentionally accept that exact form.
+
+**Why is `UNLICENSED` not automatically rejected?**
+It is a literal string, not a parsed SPDX value. If you want to allow `UNLICENSED` for
+some private dependency, add it to `allowed-packages.txt` (preferred) or, if your policy
+genuinely accepts it everywhere, add `UNLICENSED` to `allowed-hard.txt`.
+
+**How do I allow my own internal packages?**
+Add your scope to `allowed-packages.txt`: `@my-co/*`. The override will be visible in
+every report.
+
+**Why does it refuse to walk up to my workspace root?**
+Because doing so would silently change which project is being gated, and we want the
+project under check to be exactly what the user typed. `cd` to the workspace root and
+run `license-gate check --workspace apps/web`, or pass `--cwd <workspace-root>
+--workspace apps/web` from anywhere.
+
+**Why is `check --out` rejected?**
+The check verdict belongs in stdout / CI logs. Use `--json <path>` for a structured
+report; use shell redirection if you need a copy of the human output.
+
+## Programmatic API
+
+```ts
+import { runCheck, runCollect } from '@mirasen/license-gate';
+
+const result = await runCheck({ workspace: 'apps/web', jsonPath: 'report.json' });
+if (result.exitCode === 1) {
+	console.error(`license-gate found ${result.violations.length} violation(s).`);
+}
+```
+
+The library never calls `process.exit`. Callers control exit. See `src/index.ts` for the
+full set of exported types (`Decision`, `ViolationReason`, `InstalledPackageRecord`,
+`LicenseGateConfigError`, etc.).
+
+## License
+
+[MIT](./LICENSE) © Mirasen

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * `license-gate` CLI entry.
+ *
+ * Thin: parse argv with node:util.parseArgs, dispatch to command modules,
+ * map LicenseGateConfigError to exit code 2 with a stderr message. All
+ * business logic lives in src/commands/.
+ */
+type ExitCode = 0 | 1 | 2;
+export declare function main(argv: string[]): Promise<ExitCode>;
+export {};

package/dist/cli.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * `license-gate` CLI entry.
+ *
+ * Thin: parse argv with node:util.parseArgs, dispatch to command modules,
+ * map LicenseGateConfigError to exit code 2 with a stderr message. All
+ * business logic lives in src/commands/.
+ */
+import { realpathSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { runCheck } from './commands/check.js';
+import { runCollect } from './commands/collect.js';
+import { LicenseGateConfigError } from './types.js';
+function usageString() {
+    return [
+        'Usage:',
+        '  license-gate check   [--cwd <path>] [--workspace <name|path>] [--json <path>]',
+        '  license-gate collect [--cwd <path>] [--workspace <name|path>] [--out <path>] [--json <path>]',
+        '',
+        'Reads policy from licenses/allowed-hard.txt (required for check) and',
+        'licenses/allowed-packages.txt (optional), resolved relative to the project root.',
+        'The project root is --cwd if provided, otherwise process.cwd(). license-gate',
+        'never walks upward — package.json must exist directly at the chosen root.',
+        '',
+        'Exit codes: 0 clean | 1 violations | 2 usage/config error.'
+    ].join('\n');
+}
+function fail(message) {
+    process.stderr.write(`license-gate: ${message}\n`);
+    return 2;
+}
+function failConfig(err) {
+    process.stderr.write(`${err.message}\n`);
+    return 2;
+}
+async function dispatchCheck(rest) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest,
+            strict: true,
+            allowPositionals: false,
+            options: {
+                cwd: { type: 'string' },
+                workspace: { type: 'string' },
+                json: { type: 'string' }
+            }
+        });
+    }
+    catch (err) {
+        return fail(`${err.message}\n${usageString()}`);
+    }
+    const cwd = parsed.values.cwd ?? undefined;
+    const workspace = parsed.values.workspace ?? null;
+    const jsonPath = parsed.values.json ?? null;
+    try {
+        const result = await runCheck({ cwd, workspace, jsonPath });
+        process.stdout.write(result.humanReport);
+        return result.exitCode;
+    }
+    catch (err) {
+        if (err instanceof LicenseGateConfigError)
+            return failConfig(err);
+        throw err;
+    }
+}
+async function dispatchCollect(rest) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest,
+            strict: true,
+            allowPositionals: false,
+            options: {
+                cwd: { type: 'string' },
+                workspace: { type: 'string' },
+                out: { type: 'string' },
+                json: { type: 'string' }
+            }
+        });
+    }
+    catch (err) {
+        return fail(`${err.message}\n${usageString()}`);
+    }
+    const cwd = parsed.values.cwd ?? undefined;
+    const workspace = parsed.values.workspace ?? null;
+    const outPath = parsed.values.out ?? null;
+    const jsonPath = parsed.values.json ?? null;
+    try {
+        const result = await runCollect({ cwd, workspace, outPath, jsonPath });
+        if (result.stdoutSummary) {
+            process.stdout.write(result.stdoutSummary);
+        }
+        else {
+            process.stdout.write(result.humanReport);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof LicenseGateConfigError)
+            return failConfig(err);
+        throw err;
+    }
+}
+export async function main(argv) {
+    const [subcommand, ...rest] = argv;
+    if (!subcommand) {
+        process.stderr.write(`${usageString()}\n`);
+        return 2;
+    }
+    switch (subcommand) {
+        case '-h':
+        case '--help':
+            process.stdout.write(`${usageString()}\n`);
+            return 0;
+        case 'check': {
+            // Reject `check --out` explicitly with invalid-usage (do this before
+            // parseArgs, because parseArgs would simply mark `--out` as unknown).
+            if (rest.some((a) => a === '--out' || a.startsWith('--out='))) {
+                return failConfig(new LicenseGateConfigError({
+                    kind: 'invalid-usage',
+                    message: '`check` does not support --out. Use --json <path> for machine-readable output.'
+                }, 'license-gate: `check` does not support --out. Use --json <path> for machine-readable output.'));
+            }
+            return dispatchCheck(rest);
+        }
+        case 'collect':
+            return dispatchCollect(rest);
+        default:
+            return fail(`unknown command "${subcommand}".\n${usageString()}`);
+    }
+}
+// Entrypoint guard: only run main() when this file is the program entry,
+// not when it's imported as a module by a test. We resolve `process.argv[1]`
+// through `realpathSync` so that the comparison works when the binary was
+// installed as a symlink in `node_modules/.bin`.
+const isDirectRun = (() => {
+    try {
+        const argv1 = process.argv[1];
+        if (!argv1)
+            return false;
+        const resolved = realpathSync(argv1);
+        const url = new URL(`file://${resolved}`);
+        return import.meta.url === url.href;
+    }
+    catch {
+        return false;
+    }
+})();
+if (isDirectRun) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exit(code);
+    }, (err) => {
+        process.stderr.write(`license-gate: unexpected error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+        process.exit(2);
+    });
+}

package/dist/commands/_shared.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared command-layer helpers: writing output files, resolving allowlist
+ * paths, and re-exporting the project-owned scope resolver.
+ *
+ * Arborist types live in the graph layer; this module never sees them.
+ */
+import { resolveScope, type ResolvedScope } from '../graph/scope.js';
+export { resolveScope };
+export type { ResolvedScope };
+/** Write a string to a path, raising LicenseGateConfigError on failure. */
+export declare function writeOutputFile(path: string, contents: string, cwd: string): Promise<void>;
+/** Resolve fixed allowlist paths relative to cwd. */
+export declare function resolveAllowlistPaths(cwd: string): {
+    allowedHard: string;
+    allowedPackages: string;
+};
+export declare function fileExists(path: string): boolean;

package/dist/commands/_shared.js

@@ -0,0 +1,33 @@
+/**
+ * Shared command-layer helpers: writing output files, resolving allowlist
+ * paths, and re-exporting the project-owned scope resolver.
+ *
+ * Arborist types live in the graph layer; this module never sees them.
+ */
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { resolveScope } from '../graph/scope.js';
+import { LicenseGateConfigError } from '../types.js';
+export { resolveScope };
+/** Write a string to a path, raising LicenseGateConfigError on failure. */
+export async function writeOutputFile(path, contents, cwd) {
+    const absolute = resolve(cwd, path);
+    try {
+        await writeFile(absolute, contents, 'utf8');
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        throw new LicenseGateConfigError({ kind: 'output-path-unwritable', path: absolute, cause }, `license-gate: could not write to ${absolute}: ${cause}`);
+    }
+}
+/** Resolve fixed allowlist paths relative to cwd. */
+export function resolveAllowlistPaths(cwd) {
+    return {
+        allowedHard: resolve(cwd, 'licenses', 'allowed-hard.txt'),
+        allowedPackages: resolve(cwd, 'licenses', 'allowed-packages.txt')
+    };
+}
+export function fileExists(path) {
+    return existsSync(path);
+}

package/dist/commands/check.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `check` command — orchestrates discovery → policy → reporting → exit code.
+ */
+import { type CheckResult } from '../types.js';
+export type CheckOptions = {
+    cwd?: string;
+    workspace?: string | null;
+    /** When provided, JSON report is written to this path (relative to cwd). */
+    jsonPath?: string | null;
+};
+export type CheckCliResult = CheckResult & {
+    humanReport: string;
+    exitCode: 0 | 1;
+};
+/**
+ * Programmatic + CLI-shared check. Returns the decisions and the rendered
+ * human report; the caller (CLI or library consumer) decides what to do
+ * with stdout and the exit code.
+ */
+export declare function runCheck(opts?: CheckOptions): Promise<CheckCliResult>;

package/dist/commands/check.js

@@ -0,0 +1,51 @@
+/**
+ * `check` command — orchestrates discovery → policy → reporting → exit code.
+ */
+import { readFile } from 'node:fs/promises';
+import { evaluateAll } from '../policy/evaluate.js';
+import { parseAllowedHard } from '../policy/allowed-hard.js';
+import { parseAllowedPackages } from '../policy/allowed-packages.js';
+import { renderCheckHuman } from '../report/human.js';
+import { renderCheckJson } from '../report/json.js';
+import { LicenseGateConfigError } from '../types.js';
+import { fileExists, resolveAllowlistPaths, resolveScope, writeOutputFile } from './_shared.js';
+/**
+ * Programmatic + CLI-shared check. Returns the decisions and the rendered
+ * human report; the caller (CLI or library consumer) decides what to do
+ * with stdout and the exit code.
+ */
+export async function runCheck(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const workspace = opts.workspace ?? null;
+    const scope = await resolveScope({ cwd, workspace });
+    const paths = resolveAllowlistPaths(cwd);
+    if (!fileExists(paths.allowedHard)) {
+        throw new LicenseGateConfigError({ kind: 'missing-allowed-hard-file', path: paths.allowedHard }, `license-gate: required allowlist file not found: ${paths.allowedHard}`);
+    }
+    const allowedHardContents = await readFile(paths.allowedHard, 'utf8');
+    const allowedHard = parseAllowedHard(allowedHardContents);
+    const allowedPackages = fileExists(paths.allowedPackages)
+        ? parseAllowedPackages(await readFile(paths.allowedPackages, 'utf8'), paths.allowedPackages)
+        : [];
+    // Collect-all-then-exit: never throw mid-evaluation.
+    const decisions = evaluateAll(scope.evaluationRecords, allowedHard, allowedPackages);
+    const violations = decisions.filter((d) => d.outcome === 'violation');
+    const humanReport = renderCheckHuman({
+        decisions,
+        skippedProjectRoot: scope.skippedProjectRoot
+    });
+    if (opts.jsonPath) {
+        const jsonReport = renderCheckJson({
+            decisions,
+            skippedProjectRoot: scope.skippedProjectRoot
+        });
+        await writeOutputFile(opts.jsonPath, jsonReport, cwd);
+    }
+    return {
+        decisions,
+        violations,
+        skippedProjectRoot: scope.skippedProjectRoot,
+        humanReport,
+        exitCode: violations.length > 0 ? 1 : 0
+    };
+}

package/dist/commands/collect.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `collect` command — orchestrates discovery → flat record list → reporting.
+ *
+ * Performs NO policy I/O: never reads `allowed-hard.txt` or
+ * `allowed-packages.txt`. Output is human-readable by default; `--out <path>`
+ * writes to a file (and stdout shrinks to a one-line summary); `--json
+ * <path>` writes machine-readable JSON.
+ */
+import type { CollectResult } from '../types.js';
+export type CollectOptions = {
+    cwd?: string;
+    workspace?: string | null;
+    /** When provided, human report is written to this path. */
+    outPath?: string | null;
+    /** When provided, JSON report is written to this path. */
+    jsonPath?: string | null;
+};
+export type CollectCliResult = CollectResult & {
+    /** Human report. Always rendered; the CLI decides whether to print. */
+    humanReport: string;
+    /** When --out was provided, this is the one-line stdout summary. */
+    stdoutSummary: string | null;
+};
+export declare function runCollect(opts?: CollectOptions): Promise<CollectCliResult>;

package/dist/commands/collect.js

@@ -0,0 +1,31 @@
+/**
+ * `collect` command — orchestrates discovery → flat record list → reporting.
+ *
+ * Performs NO policy I/O: never reads `allowed-hard.txt` or
+ * `allowed-packages.txt`. Output is human-readable by default; `--out <path>`
+ * writes to a file (and stdout shrinks to a one-line summary); `--json
+ * <path>` writes machine-readable JSON.
+ */
+import { renderCollectHuman } from '../report/human.js';
+import { renderCollectJson } from '../report/json.js';
+import { resolveScope, writeOutputFile } from './_shared.js';
+export async function runCollect(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const workspace = opts.workspace ?? null;
+    const scope = await resolveScope({ cwd, workspace });
+    const records = scope.allCollectedRecords;
+    const humanReport = renderCollectHuman(records);
+    let stdoutSummary = null;
+    if (opts.outPath) {
+        await writeOutputFile(opts.outPath, humanReport, cwd);
+        stdoutSummary = `wrote ${records.length} records to ${opts.outPath}\n`;
+    }
+    if (opts.jsonPath) {
+        await writeOutputFile(opts.jsonPath, renderCollectJson(records), cwd);
+    }
+    return {
+        records,
+        humanReport,
+        stdoutSummary
+    };
+}