@npm-safe/core-dsh 1.0.5

package/dist/registry/validator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure string-parsing validators for npm package names, semver versions,
+ * and registry/repository domains.
+ *
+ * This module contains no network calls and no side effects — every
+ * function is a pure transformation of its string input into a typed
+ * validation result. Inputs are treated as untrusted: empty strings,
+ * non-string values (rejected by the type system at compile time, but
+ * defended against at runtime via narrowing), and Unicode homograph
+ * attacks are all handled explicitly.
+ *
+ * @module registry/validator
+ */
+import type { ValidationResult } from './types.js';
+/**
+ * Validate an npm package name according to the public registry's naming
+ * rules. Accepts both unscoped (`lodash`) and scoped (`@babel/core`)
+ * names.
+ *
+ * Rules enforced:
+ * - Must be a non-empty string.
+ * - Maximum length of 214 characters.
+ * - Must be entirely lowercase (no uppercase letters).
+ * - Must not contain spaces.
+ * - Must not begin with a dot (`.`) or underscore (`_`).
+ * - Scoped names use the `@scope/name` syntax; both `scope` and `name`
+ *   segments must independently satisfy the segment naming rules.
+ * - Rejects Unicode homograph look-alikes by restricting to ASCII
+ *   lowercase letters, digits, hyphen, underscore, and dot.
+ *
+ * @param name - Candidate package name to validate.
+ * @returns A {@link ValidationResult} indicating validity and, when
+ *   invalid, a human-readable reason.
+ */
+export declare function validatePackageName(name: string): ValidationResult;
+/**
+ * Validate that a string is a compliant semantic version (semver 2.0.0).
+ *
+ * Accepts strings of the form `MAJOR.MINOR.PATCH` with optional pre-release
+ * (`-prerelease`) and build metadata (`+build`) identifiers. Numeric
+ * components with leading zeros (e.g. `01.2.3`) are rejected, matching the
+ * semver specification.
+ *
+ * @param version - Candidate version string to validate.
+ * @returns `true` when the string is a valid semver version, `false`
+ *   otherwise.
+ */
+export declare function validateVersion(version: string): boolean;
+/**
+ * Result of {@link validateDomain}. The `domain` field is always present
+ * (empty string when parsing fails) so callers can destructure safely.
+ */
+export interface DomainValidationResult {
+    /** `true` when the input parsed into a URL with a usable hostname. */
+    readonly valid: boolean;
+    /** Lowercased hostname extracted from the URL, or empty string on failure. */
+    readonly domain: string;
+}
+/**
+ * Validate a URL string and extract its hostname.
+ *
+ * Handles edge cases including:
+ * - Missing protocol (defaults to `https://`).
+ * - Relative URLs (rejected — no hostname).
+ * - Invalid URL syntax (rejected).
+ * - Unicode hostnames (returned as-is, lowercased; punycode conversion is
+ *   the caller's responsibility).
+ *
+ * @param url - Candidate URL string to parse.
+ * @returns A {@link DomainValidationResult} with the parsed hostname
+ *   (lowercased) when valid, or an empty domain when parsing fails.
+ */
+export declare function validateDomain(url: string): DomainValidationResult;
+/**
+ * Check whether a domain is a known npm registry or source-control host.
+ *
+ * The whitelist includes `npmjs.com`, `registry.npmjs.org`, `github.com`,
+ * `bitbucket.org`, and `gitlab.com`. Comparison is case-insensitive and
+ * exact — subdomains are not automatically trusted (callers must normalise
+ * or extend the check if wildcard matching is desired).
+ *
+ * @param domain - Hostname to check against the known-domain whitelist.
+ * @returns `true` when the domain (case-insensitively) matches a known
+ *   registry/repository host, `false` otherwise.
+ */
+export declare function isKnownRegistryDomain(domain: string): boolean;
+//# sourceMappingURL=validator.d.ts.map

package/dist/registry/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/registry/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA6CnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CA6ElE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKxD;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,CA0BlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAK7D"}

package/dist/registry/validator.js

@@ -0,0 +1,214 @@
+/**
+ * Pure string-parsing validators for npm package names, semver versions,
+ * and registry/repository domains.
+ *
+ * This module contains no network calls and no side effects — every
+ * function is a pure transformation of its string input into a typed
+ * validation result. Inputs are treated as untrusted: empty strings,
+ * non-string values (rejected by the type system at compile time, but
+ * defended against at runtime via narrowing), and Unicode homograph
+ * attacks are all handled explicitly.
+ *
+ * @module registry/validator
+ */
+/**
+ * Maximum length of an npm package name, enforced by the public registry.
+ *
+ * @see https://github.com/npm/validate-npm-package-name#naming-rules
+ */
+const MAX_PACKAGE_NAME_LENGTH = 214;
+/**
+ * Regular expression matching a single path segment of an npm package name
+ * (the part after an optional `@scope/` prefix). Per the registry naming
+ * rules, segments must be lowercase, must not contain leading dots or
+ * underscores, and may contain ASCII letters, digits, hyphens, underscores,
+ * and dots — but no spaces or other special characters.
+ */
+const PACKAGE_NAME_SEGMENT_PATTERN = /^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$/;
+/**
+ * Regular expression matching a semver version string with optional
+ * pre-release and build-metadata identifiers, per the semver 2.0.0 spec.
+ *
+ * - Major.minor.patch: three dot-separated non-negative integer groups.
+ * - Pre-release: hyphen followed by dot-separated alphanumeric identifiers.
+ * - Build metadata: plus sign followed by dot-separated alphanumeric
+ *   identifiers.
+ *
+ * @see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+ */
+const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+/**
+ * Immutable whitelist of registry/repository domains recognised by the
+ * tool. Used by {@link isKnownRegistryDomain} to gate trust decisions
+ * without performing any network lookups.
+ */
+const KNOWN_REGISTRY_DOMAINS = new Set([
+    'npmjs.com',
+    'registry.npmjs.org',
+    'github.com',
+    'bitbucket.org',
+    'gitlab.com',
+]);
+/**
+ * Validate an npm package name according to the public registry's naming
+ * rules. Accepts both unscoped (`lodash`) and scoped (`@babel/core`)
+ * names.
+ *
+ * Rules enforced:
+ * - Must be a non-empty string.
+ * - Maximum length of 214 characters.
+ * - Must be entirely lowercase (no uppercase letters).
+ * - Must not contain spaces.
+ * - Must not begin with a dot (`.`) or underscore (`_`).
+ * - Scoped names use the `@scope/name` syntax; both `scope` and `name`
+ *   segments must independently satisfy the segment naming rules.
+ * - Rejects Unicode homograph look-alikes by restricting to ASCII
+ *   lowercase letters, digits, hyphen, underscore, and dot.
+ *
+ * @param name - Candidate package name to validate.
+ * @returns A {@link ValidationResult} indicating validity and, when
+ *   invalid, a human-readable reason.
+ */
+export function validatePackageName(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+        return { valid: false, reason: 'Package name must be a non-empty string.' };
+    }
+    if (name.length > MAX_PACKAGE_NAME_LENGTH) {
+        return {
+            valid: false,
+            reason: `Package name must not exceed ${MAX_PACKAGE_NAME_LENGTH} characters.`,
+        };
+    }
+    // Reject any uppercase letters outright — npm names are case-sensitive
+    // and the registry only permits lowercase.
+    if (name !== name.toLowerCase()) {
+        return { valid: false, reason: 'Package name must be lowercase.' };
+    }
+    if (name.includes(' ')) {
+        return { valid: false, reason: 'Package name must not contain spaces.' };
+    }
+    // Scoped package: @scope/name
+    if (name.startsWith('@')) {
+        const slashIndex = name.indexOf('/');
+        if (slashIndex === -1) {
+            return {
+                valid: false,
+                reason: 'Scoped package name must contain a "/" separator.',
+            };
+        }
+        const scope = name.slice(1, slashIndex);
+        const rest = name.slice(slashIndex + 1);
+        if (scope.length === 0) {
+            return { valid: false, reason: 'Package scope must not be empty.' };
+        }
+        if (rest.length === 0) {
+            return { valid: false, reason: 'Package name segment must not be empty.' };
+        }
+        // Scope must not itself be scoped (no nested @s).
+        if (scope.startsWith('@')) {
+            return { valid: false, reason: 'Package scope must not be nested.' };
+        }
+        if (!PACKAGE_NAME_SEGMENT_PATTERN.test(scope)) {
+            return {
+                valid: false,
+                reason: `Package scope "${scope}" contains invalid characters or a leading dot/underscore.`,
+            };
+        }
+        if (!PACKAGE_NAME_SEGMENT_PATTERN.test(rest)) {
+            return {
+                valid: false,
+                reason: `Package name segment "${rest}" contains invalid characters or a leading dot/underscore.`,
+            };
+        }
+        return { valid: true };
+    }
+    // Unscoped package.
+    if (name.startsWith('.') || name.startsWith('_')) {
+        return {
+            valid: false,
+            reason: 'Package name must not begin with a dot or underscore.',
+        };
+    }
+    if (!PACKAGE_NAME_SEGMENT_PATTERN.test(name)) {
+        return {
+            valid: false,
+            reason: `Package name "${name}" contains invalid characters.`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate that a string is a compliant semantic version (semver 2.0.0).
+ *
+ * Accepts strings of the form `MAJOR.MINOR.PATCH` with optional pre-release
+ * (`-prerelease`) and build metadata (`+build`) identifiers. Numeric
+ * components with leading zeros (e.g. `01.2.3`) are rejected, matching the
+ * semver specification.
+ *
+ * @param version - Candidate version string to validate.
+ * @returns `true` when the string is a valid semver version, `false`
+ *   otherwise.
+ */
+export function validateVersion(version) {
+    if (typeof version !== 'string' || version.length === 0) {
+        return false;
+    }
+    return SEMVER_PATTERN.test(version);
+}
+/**
+ * Validate a URL string and extract its hostname.
+ *
+ * Handles edge cases including:
+ * - Missing protocol (defaults to `https://`).
+ * - Relative URLs (rejected — no hostname).
+ * - Invalid URL syntax (rejected).
+ * - Unicode hostnames (returned as-is, lowercased; punycode conversion is
+ *   the caller's responsibility).
+ *
+ * @param url - Candidate URL string to parse.
+ * @returns A {@link DomainValidationResult} with the parsed hostname
+ *   (lowercased) when valid, or an empty domain when parsing fails.
+ */
+export function validateDomain(url) {
+    if (typeof url !== 'string' || url.length === 0) {
+        return { valid: false, domain: '' };
+    }
+    // Reject relative URLs early: a usable registry/repository URL must have
+    // a scheme. If none is present, prepend `https://` as a convenience for
+    // inputs like `github.com/user/repo`.
+    let candidate = url;
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(candidate)) {
+        candidate = `https://${candidate}`;
+    }
+    let parsed;
+    try {
+        parsed = new URL(candidate);
+    }
+    catch {
+        return { valid: false, domain: '' };
+    }
+    const hostname = parsed.hostname;
+    if (hostname.length === 0) {
+        return { valid: false, domain: '' };
+    }
+    return { valid: true, domain: hostname.toLowerCase() };
+}
+/**
+ * Check whether a domain is a known npm registry or source-control host.
+ *
+ * The whitelist includes `npmjs.com`, `registry.npmjs.org`, `github.com`,
+ * `bitbucket.org`, and `gitlab.com`. Comparison is case-insensitive and
+ * exact — subdomains are not automatically trusted (callers must normalise
+ * or extend the check if wildcard matching is desired).
+ *
+ * @param domain - Hostname to check against the known-domain whitelist.
+ * @returns `true` when the domain (case-insensitively) matches a known
+ *   registry/repository host, `false` otherwise.
+ */
+export function isKnownRegistryDomain(domain) {
+    if (typeof domain !== 'string' || domain.length === 0) {
+        return false;
+    }
+    return KNOWN_REGISTRY_DOMAINS.has(domain.toLowerCase());
+}
+//# sourceMappingURL=validator.js.map

package/dist/registry/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/registry/validator.ts"],"names":[],"mappings":"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"}

package/dist/scanner/ci-scan.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure CI dependency-scan helpers extracted from the legacy `ci` CLI command.
+ *
+ * This module is intentionally free of CLI concerns: no `commander` option
+ * parsing, no i18n (`t()`), no telemetry recording, and no console output.
+ * The {@link NpmSafeEngine.ciScan} method composes these helpers with the
+ * engine to produce a {@link CiReport}; rendering and exit-code mapping are
+ * the caller's responsibility.
+ *
+ * @module scanner/ci-scan
+ */
+import { SecurityLevel } from './types.js';
+/**
+ * Severity ordering used for the failure gate: lower rank = more severe.
+ *
+ * Exported so the engine's `ciScan` method can evaluate the fail gate without
+ * re-declaring this mapping.
+ */
+export declare const LEVEL_RANK: Readonly<Record<string, number>>;
+/**
+ * Display order of security levels (used for option help text in the CLI).
+ */
+export declare const LEVEL_ORDER: readonly string[];
+/** A dependency name extracted from a manifest or lockfile. */
+export interface Dependency {
+    readonly name: string;
+}
+/** Per-package result within a {@link CiReport}. */
+export interface PackageResult {
+    readonly name: string;
+    readonly exists: boolean;
+    readonly version: string;
+    readonly level: string;
+    readonly score: number;
+    readonly findingCount: number;
+    readonly error?: string;
+}
+/** Aggregated CI scan report for a project directory. */
+export interface CiReport {
+    readonly dir: string;
+    readonly scannedAt: string;
+    readonly dependencyCount: number;
+    readonly failLevel: string;
+    readonly failed: boolean;
+    readonly summary: Readonly<Record<string, number>>;
+    readonly packages: readonly PackageResult[];
+}
+/** Options accepted by {@link NpmSafeEngine.ciScan}. */
+export interface CiScanOptions {
+    /** Project directory containing `package.json`. @default process.cwd() */
+    readonly dir?: string;
+    /** Fail when any dependency reaches this level. @default SecurityLevel.Dangerous */
+    readonly failLevel?: SecurityLevel;
+    /** Scan every dependency in `package-lock.json` (including transitive). */
+    readonly lockfile?: boolean;
+    /** Only scan `dependencies` (skip devDependencies). */
+    readonly prod?: boolean;
+    /** Optional external abort signal for cooperative cancellation. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Read direct dependencies (and optionally devDependencies) from a manifest.
+ *
+ * @param dir - Project directory containing a `package.json` file.
+ * @param includeDev - When `true`, also include `devDependencies`.
+ * @returns A list of dependency names (deduplicated, insertion-ordered).
+ * @throws {Error} When `package.json` cannot be read or parsed.
+ */
+export declare function readDependencies(dir: string, includeDev: boolean): Dependency[];
+/**
+ * Read every package (including transitive dependencies) from a
+ * `package-lock.json` (npm lockfile v2/v3 `packages` map, with a fallback to
+ * the v1 `dependencies` tree). When `includeDev` is `false`, the result is
+ * restricted to the direct `dependencies` declared in `package.json` (`--prod`).
+ *
+ * @param dir - Project directory containing a `package-lock.json` file.
+ * @param includeDev - When `false`, restrict to `dependencies` from `package.json`.
+ * @returns A list of dependency names (deduplicated).
+ * @throws {Error} When `package-lock.json` cannot be read or parsed.
+ */
+export declare function readLockfileDependencies(dir: string, includeDev: boolean): Dependency[];
+//# sourceMappingURL=ci-scan.d.ts.map

package/dist/scanner/ci-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-scan.d.ts","sourceRoot":"","sources":["../../src/scanner/ci-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKvD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAKxC,CAAC;AAEF,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,yDAAyD;AACzD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,OAAO,GAClB,UAAU,EAAE,CAoBd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,OAAO,GAClB,UAAU,EAAE,CA6Dd"}

package/dist/scanner/ci-scan.js

@@ -0,0 +1,130 @@
+/**
+ * Pure CI dependency-scan helpers extracted from the legacy `ci` CLI command.
+ *
+ * This module is intentionally free of CLI concerns: no `commander` option
+ * parsing, no i18n (`t()`), no telemetry recording, and no console output.
+ * The {@link NpmSafeEngine.ciScan} method composes these helpers with the
+ * engine to produce a {@link CiReport}; rendering and exit-code mapping are
+ * the caller's responsibility.
+ *
+ * @module scanner/ci-scan
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { SecurityLevel } from './types.js';
+/**
+ * Severity ordering used for the failure gate: lower rank = more severe.
+ *
+ * Exported so the engine's `ciScan` method can evaluate the fail gate without
+ * re-declaring this mapping.
+ */
+export const LEVEL_RANK = {
+    [SecurityLevel.Dangerous]: 1,
+    [SecurityLevel.Unknown]: 2,
+    [SecurityLevel.Suspicious]: 3,
+    [SecurityLevel.Safe]: 4,
+};
+/**
+ * Display order of security levels (used for option help text in the CLI).
+ */
+export const LEVEL_ORDER = [
+    SecurityLevel.Safe,
+    SecurityLevel.Suspicious,
+    SecurityLevel.Dangerous,
+    SecurityLevel.Unknown,
+];
+/**
+ * Read direct dependencies (and optionally devDependencies) from a manifest.
+ *
+ * @param dir - Project directory containing a `package.json` file.
+ * @param includeDev - When `true`, also include `devDependencies`.
+ * @returns A list of dependency names (deduplicated, insertion-ordered).
+ * @throws {Error} When `package.json` cannot be read or parsed.
+ */
+export function readDependencies(dir, includeDev) {
+    const manifestPath = path.join(dir, 'package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch {
+        throw new Error(`No package.json found in ${dir}`);
+    }
+    const names = new Set();
+    for (const key of ['dependencies', ...(includeDev ? ['devDependencies'] : [])]) {
+        const section = manifest[key];
+        if (section && typeof section === 'object') {
+            for (const name of Object.keys(section)) {
+                if (name !== 'optionalDependencies')
+                    names.add(name);
+            }
+        }
+    }
+    return [...names].map((name) => ({ name }));
+}
+/**
+ * Read every package (including transitive dependencies) from a
+ * `package-lock.json` (npm lockfile v2/v3 `packages` map, with a fallback to
+ * the v1 `dependencies` tree). When `includeDev` is `false`, the result is
+ * restricted to the direct `dependencies` declared in `package.json` (`--prod`).
+ *
+ * @param dir - Project directory containing a `package-lock.json` file.
+ * @param includeDev - When `false`, restrict to `dependencies` from `package.json`.
+ * @returns A list of dependency names (deduplicated).
+ * @throws {Error} When `package-lock.json` cannot be read or parsed.
+ */
+export function readLockfileDependencies(dir, includeDev) {
+    const lockPath = path.join(dir, 'package-lock.json');
+    let lock;
+    try {
+        lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    }
+    catch {
+        throw new Error(`No package-lock.json found in ${dir}`);
+    }
+    const names = new Set();
+    const packages = lock.packages;
+    if (packages && typeof packages === 'object') {
+        for (const key of Object.keys(packages)) {
+            if (key === '')
+                continue; // root project entry
+            // "node_modules/a" -> "a"; "node_modules/@scope/c" -> "@scope/c";
+            // "node_modules/a/node_modules/d" -> "d" (the innermost package).
+            const stripped = key.replace(/^node_modules\//, '');
+            const parts = stripped.split('/node_modules/');
+            const name = parts[parts.length - 1];
+            if (name.length > 0)
+                names.add(name);
+        }
+    }
+    // npm lockfile v1 fallback: nested dependencies tree.
+    const collect = (section) => {
+        if (!section || typeof section !== 'object')
+            return;
+        for (const [name, entry] of Object.entries(section)) {
+            if (name === 'optionalDependencies')
+                continue;
+            names.add(name);
+            if (entry && typeof entry === 'object') {
+                collect(entry.dependencies);
+            }
+        }
+    };
+    collect(lock.dependencies);
+    if (!includeDev) {
+        // --prod: restrict to the direct dependencies declared in package.json.
+        const manifestPath = path.join(dir, 'package.json');
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+            const prod = new Set(Object.keys(manifest.dependencies ?? {}));
+            return [...names]
+                .filter((name) => prod.has(name))
+                .map((name) => ({ name }));
+        }
+        catch {
+            // No package.json — fall through to the full lockfile set.
+        }
+    }
+    return [...names].map((name) => ({ name }));
+}
+//# sourceMappingURL=ci-scan.js.map

package/dist/scanner/ci-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-scan.js","sourceRoot":"","sources":["../../src/scanner/ci-scan.ts"],"names":[],"mappings":"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"}

package/dist/scanner/rule-config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Per-rule configuration: enable/disable, severity overrides, and free-form
+ * options. Configuration is persisted as JSON (default
+ * `~/.npm-safe/rules.json`) and can be managed at runtime through the
+ * {@link RuleConfigManager}.
+ */
+import { Severity } from './types.js';
+/** Free-form options passed to a rule at match time. */
+export type RuleOptions = Readonly<Record<string, unknown>>;
+/** Per-rule configuration overrides. */
+export interface RuleConfig {
+    /** Whether the rule is enabled. Defaults to the rule's own default. */
+    readonly enabled?: boolean;
+    /** Severity override applied to findings produced by the rule. */
+    readonly severity?: Severity;
+    /** Free-form options made available to the rule implementation. */
+    readonly options?: RuleOptions;
+}
+/** Shape of the persisted rules configuration file. */
+export interface RuleConfigFile {
+    /** Per-rule overrides keyed by rule id. */
+    readonly rules: Readonly<Record<string, RuleConfig>>;
+}
+/** Default location of the rules configuration file. */
+export declare function getDefaultRulesConfigPath(): string;
+/**
+ * Loads, mutates, and persists per-rule configuration. Thread-safe per
+ * instance; concurrent instances may race on the file, which is acceptable
+ * for a single-user desktop tool.
+ */
+export declare class RuleConfigManager {
+    private readonly filePath;
+    private config;
+    /**
+     * @param filePath - Path to the JSON config file.
+     */
+    constructor(filePath?: string);
+    /** Load (or initialize) the config file. */
+    private load;
+    /** Persist the current configuration to disk. */
+    private save;
+    /** Get the configuration for a single rule, or `undefined` if unset. */
+    getRule(ruleId: string): RuleConfig | undefined;
+    /** Whether a rule is enabled, honoring config overrides. */
+    isEnabled(ruleId: string, defaultEnabled: boolean): boolean;
+    /** Severity override for a rule, or `undefined` if not overridden. */
+    getSeverityOverride(ruleId: string): Severity | undefined;
+    /** Options for a rule, or `{}` if none are configured. */
+    getOptions(ruleId: string): RuleOptions;
+    /** Enable or disable a rule (persisted). */
+    setEnabled(ruleId: string, enabled: boolean): void;
+    /** Override a rule's severity (persisted). `undefined` clears the override. */
+    setSeverity(ruleId: string, severity: Severity | undefined): void;
+    /** Set a rule's options (persisted). */
+    setOptions(ruleId: string, options: RuleOptions): void;
+    /** All configured rule ids. */
+    getConfiguredRuleIds(): string[];
+    /** Mutable view of the rules map for writing. */
+    private mutableRules;
+}
+//# sourceMappingURL=rule-config.d.ts.map

package/dist/scanner/rule-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-config.d.ts","sourceRoot":"","sources":["../../src/scanner/rule-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE5D,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAChC;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;CACtD;AAED,wDAAwD;AACxD,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,MAAM,CAAiB;IAE/B;;OAEG;gBACS,QAAQ,CAAC,EAAE,MAAM;IAK7B,4CAA4C;IAC5C,OAAO,CAAC,IAAI;IAUZ,iDAAiD;IACjD,OAAO,CAAC,IAAI;IASZ,wEAAwE;IACxE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C,4DAA4D;IAC5D,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO;IAK3D,sEAAsE;IACtE,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAIzD,0DAA0D;IAC1D,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW;IAIvC,4CAA4C;IAC5C,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAOlD,+EAA+E;IAC/E,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI;IAYjE,wCAAwC;IACxC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAOtD,+BAA+B;IAC/B,oBAAoB,IAAI,MAAM,EAAE;IAIhC,iDAAiD;IACjD,OAAO,CAAC,YAAY;CAGrB"}