@dependably/npm-check 1.7.0 → 1.7.1

package/src/audit.js

@@ -12,6 +12,7 @@ import { walkOverrides } from './overrides.js';
 import { findOrphanedPackages } from './pruner.js';
 import { findUnusedDependencies } from './usage-scanner.js';
 import { mergeConfig } from './audit-config.js';
+import { matchException, isExpired } from './exceptions.js';
 
 export class AuditError extends Error {
   constructor(message, code, context = {}) {
@@ -723,6 +724,43 @@ function summarizeByRule(findings) {
   return byRule;
 }
 
+// The package name an npm-check finding is about, from its lockfile path (the
+// segment after the last `node_modules/`). Used to match `package` exceptions.
+function deriveFindingPackage(packagePath) {
+  if (!packagePath) return undefined;
+  const marker = 'node_modules/';
+  const idx = packagePath.lastIndexOf(marker);
+  const tail = idx >= 0 ? packagePath.slice(idx + marker.length) : packagePath;
+  return tail || undefined;
+}
+
+// Partition audit findings by the resolved `.dependably` exceptions. Kept
+// findings are returned untouched (same object refs); suppressed ones are copies
+// stamped with `suppressed`/`suppressedBy`. Expired entries never suppress.
+function applyAuditExceptions(findings, exceptions) {
+  if (!Array.isArray(exceptions) || exceptions.length === 0) {
+    return { kept: findings, suppressed: [], unused: [], expired: [] };
+  }
+  const live = [];
+  const expired = [];
+  for (const ex of exceptions) (isExpired(ex) ? expired : live).push(ex);
+
+  const used = new Set();
+  const kept = [];
+  const suppressed = [];
+  for (const finding of findings) {
+    const probe = { ruleId: finding.ruleId, package: deriveFindingPackage(finding.packagePath) };
+    const hit = live.find((ex) => matchException(ex, probe));
+    if (hit) {
+      used.add(hit);
+      suppressed.push({ ...finding, suppressed: true, suppressedBy: hit.reason });
+    } else {
+      kept.push(finding);
+    }
+  }
+  return { kept, suppressed, unused: live.filter((ex) => !used.has(ex)), expired };
+}
+
 export function runAudit(target, config = {}) {
   const { lockfile, packageJson = null, filePath = 'package-lock.json' } = target;
   if (!lockfile || typeof lockfile !== 'object') {
@@ -732,7 +770,7 @@ export function runAudit(target, config = {}) {
   const resolved = resolveAuditConfig(config);
   const flavor = detectLockfileFlavor(lockfile);
 
-  const findings = [];
+  const raw = [];
   for (const rule of rules) {
     // Flavor gating: a rule only runs against the lockfile flavors it supports
     // (npm-shape rules no-op on pnpm-lock.yaml; pnpm rules no-op on npm).
@@ -742,9 +780,13 @@ export function runAudit(target, config = {}) {
     if (!ruleConfig || ruleConfig.severity === 'off') continue;
 
     const context = { lockfile, packageJson, options: ruleConfig.options || {}, filePath, flavor };
-    findings.push(...collectRuleFindings(rule, ruleConfig, context));
+    raw.push(...collectRuleFindings(rule, ruleConfig, context));
   }
 
+  // Suppress findings named by `.dependably` exceptions: they no longer gate but
+  // are reported separately (spec §6). Kept findings drive errors/warnings/pass.
+  const { kept: findings, suppressed, unused, expired } = applyAuditExceptions(raw, config.exceptions);
+
   const errors = findings.filter((f) => f.severity === 'error').length;
   const warnings = findings.filter((f) => f.severity === 'warn').length;
   const byRule = summarizeByRule(findings);
@@ -754,9 +796,11 @@ export function runAudit(target, config = {}) {
 
   return {
     findings,
-    summary: { errors, warnings, total: findings.length, byRule },
+    suppressed,
+    summary: { errors, warnings, total: findings.length, byRule, suppressed: suppressed.length },
     pass,
-    filePath
+    filePath,
+    exceptionsMeta: { unused, expired }
   };
 }
 
@@ -767,14 +811,20 @@ export function runAudit(target, config = {}) {
  * @returns {string}
  */
 export function formatAuditReport(report, options = {}) {
-  const { format = 'stylish' } = options;
+  const { format = 'stylish', showSuppressed = false } = options;
+  const suppressed = report.suppressed || [];
 
   if (format === 'json') {
     return JSON.stringify({
       filePath: report.filePath,
       pass: report.pass,
       summary: report.summary,
-      findings: report.findings
+      findings: report.findings,
+      suppressed,
+      exceptionsMeta: {
+        unused: (report.exceptionsMeta && report.exceptionsMeta.unused || []).map((e) => e._raw),
+        expired: (report.exceptionsMeta && report.exceptionsMeta.expired || []).map((e) => e._raw)
+      }
     }, null, 2);
   }
 
@@ -786,7 +836,8 @@ export function formatAuditReport(report, options = {}) {
   lines.push(report.filePath);
 
   if (report.findings.length === 0) {
-    lines.push('  no problems found');
+    lines.push(suppressed.length > 0 ? `  no problems found (${suppressed.length} suppressed by .dependably)` : '  no problems found');
+    appendSuppressed(lines, suppressed, showSuppressed);
     return lines.join('\n');
   }
 
@@ -799,7 +850,21 @@ export function formatAuditReport(report, options = {}) {
 
   const { errors, warnings, total } = report.summary;
   const problemWord = total === 1 ? 'problem' : 'problems';
+  const suffix = suppressed.length > 0 ? ` — ${suppressed.length} suppressed by .dependably` : '';
   lines.push('');
-  lines.push(`${total} ${problemWord} (${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'})`);
+  lines.push(`${total} ${problemWord} (${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'})${suffix}`);
+  appendSuppressed(lines, suppressed, showSuppressed);
   return lines.join('\n');
 }
+
+// Optionally list the suppressed findings (with their exception reason) below the
+// summary, so `--show-suppressed` keeps the audit trail visible.
+function appendSuppressed(lines, suppressed, showSuppressed) {
+  if (!showSuppressed || suppressed.length === 0) return;
+  lines.push('');
+  lines.push('suppressed by .dependably:');
+  for (const f of suppressed) {
+    const loc = f.packagePath ? `${f.packagePath}   ` : '';
+    lines.push(`  ${f.ruleId}  ${loc}${f.message}  (${f.suppressedBy})`);
+  }
+}

package/src/exceptions.js

@@ -0,0 +1,281 @@
+// src/exceptions.js
+//
+// Reference implementation of the `.dependably` exception grammar
+// (docs/dependably-config-spec.md §6). This is the module the C# and Python
+// ports mirror; keep it behavior-compatible with the conformance fixtures under
+// conformance/dependably/.
+//
+// An exception suppresses SPECIFIC findings so a run does not fail on them,
+// without excluding whole files (`exclude`) or disabling a rule globally
+// (`rules: {id: "off"}`). Each entry is:
+//
+//   { rule, package?, path?, symbol?, id?, reason, expires? }
+//
+// `rule` + `reason` are mandatory; at least one selector is required; all
+// selectors present on an entry must match a finding (AND within an entry,
+// OR across entries). Suppressed findings are still counted and reported.
+
+export class ExceptionConfigError extends Error {
+  constructor(message, code, context = {}) {
+    super(message);
+    this.name = 'ExceptionConfigError';
+    this.code = code;
+    this.context = context;
+  }
+}
+
+// The four finding selectors, in a stable order for messages.
+export const SELECTORS = ['package', 'path', 'symbol', 'id'];
+
+const EXPIRES_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+// --- glob (portable subset: ** any depth, * within a segment, ? one char) ---
+
+function globToRegExp(glob) {
+  let re = '';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      if (glob[i + 2] === '/') {
+        // `**/` — zero or more leading path segments.
+        re += '(?:.*/)?';
+        i += 3;
+      } else if (re.endsWith('/')) {
+        // `foo/**` at the end — match `foo` and `foo/anything`.
+        re = `${re.slice(0, -1)}(?:/.*)?`;
+        i += 2;
+      } else {
+        // bare `**` — any number of characters including separators.
+        re += '.*';
+        i += 2;
+      }
+    } else if (c === '*') {
+      // `*` — anything except a path separator.
+      re += '[^/]*';
+      i++;
+    } else if (c === '?') {
+      re += '[^/]';
+      i++;
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+      i++;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/** Match a POSIX-style path against a portable glob (`**`, `*`, `?`). */
+export function matchGlob(glob, value) {
+  if (typeof value !== 'string') return false;
+  return globToRegExp(glob).test(value.replace(/\\/g, '/'));
+}
+
+// --- parsing / validation ---
+
+function ensureArray(raw, context) {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) {
+    throw new ExceptionConfigError(
+      'exceptions must be an array',
+      'INVALID_EXCEPTIONS',
+      context
+    );
+  }
+  return raw;
+}
+
+// Split a `package` selector into { name, version } (version optional, from an
+// `@<version>` suffix). Scoped names keep their leading `@`.
+function splitPackageSelector(pkg) {
+  const at = pkg.lastIndexOf('@');
+  if (at > 0) {
+    return { name: pkg.slice(0, at).toLowerCase(), version: pkg.slice(at + 1) };
+  }
+  return { name: pkg.toLowerCase(), version: null };
+}
+
+/**
+ * Parse and validate a raw `exceptions` array into normalized entries.
+ *
+ * @param {*} raw - the raw `exceptions` value from a config section
+ * @param {object} opts
+ * @param {'own'|'common'} [opts.source] - `own` enforces selector applicability
+ *        (§6.7); `common` tolerates selectors this tool never emits.
+ * @param {string[]} [opts.applicableSelectors] - selectors this tool's findings
+ *        can carry (e.g. npm-check: ['package','id']). Required for `own`.
+ * @param {string[]} [opts.knownRules] - if given, an unknown `rule` in an `own`
+ *        entry throws UNKNOWN_RULE (spec §8); in `common` it is tolerated.
+ * @param {string} [opts.configPath]
+ * @returns {Array<{rule, reason, expires, source, selectors, _raw}>}
+ */
+export function parseExceptions(raw, opts = {}) {
+  const { source = 'own', applicableSelectors = SELECTORS, knownRules = null, configPath = null } = opts;
+  const entries = ensureArray(raw, { configPath });
+  const out = [];
+
+  entries.forEach((entry, index) => {
+    const at = { configPath, source, index };
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new ExceptionConfigError(`exception #${index} must be an object`, 'INVALID_EXCEPTIONS', at);
+    }
+    if (typeof entry.rule !== 'string' || entry.rule.trim() === '') {
+      throw new ExceptionConfigError(`exception #${index} is missing "rule"`, 'EXCEPTION_MISSING_RULE', at);
+    }
+    if (typeof entry.reason !== 'string' || entry.reason.trim() === '') {
+      throw new ExceptionConfigError(
+        `exception for rule "${entry.rule}" is missing a non-empty "reason"`,
+        'EXCEPTION_MISSING_REASON',
+        at
+      );
+    }
+
+    const present = SELECTORS.filter((s) => entry[s] !== undefined);
+    if (present.length === 0) {
+      throw new ExceptionConfigError(
+        `exception for rule "${entry.rule}" needs at least one selector (${SELECTORS.join(', ')})`,
+        'EXCEPTION_NO_SELECTOR',
+        at
+      );
+    }
+    for (const sel of present) {
+      if (typeof entry[sel] !== 'string' || entry[sel].trim() === '') {
+        throw new ExceptionConfigError(
+          `exception selector "${sel}" for rule "${entry.rule}" must be a non-empty string`,
+          'EXCEPTION_BAD_SELECTOR',
+          at
+        );
+      }
+      // A selector this tool's findings never carry is an error in the tool's
+      // OWN section but is tolerated in `common` (it simply never matches).
+      if (source === 'own' && !applicableSelectors.includes(sel)) {
+        throw new ExceptionConfigError(
+          `exception selector "${sel}" is not applicable to this tool (applicable: ${applicableSelectors.join(', ')})`,
+          'EXCEPTION_BAD_SELECTOR',
+          at
+        );
+      }
+    }
+
+    if (entry.expires !== undefined) {
+      if (typeof entry.expires !== 'string' || !EXPIRES_RE.test(entry.expires) || Number.isNaN(Date.parse(entry.expires))) {
+        throw new ExceptionConfigError(
+          `exception "expires" for rule "${entry.rule}" must be a valid YYYY-MM-DD date`,
+          'EXCEPTION_BAD_EXPIRES',
+          at
+        );
+      }
+    }
+
+    if (source === 'own' && knownRules && !knownRules.includes(entry.rule)) {
+      throw new ExceptionConfigError(
+        `Unknown rule "${entry.rule}" in exception (known rules: ${knownRules.join(', ')})`,
+        'UNKNOWN_RULE',
+        at
+      );
+    }
+
+    const selectors = { rule: entry.rule };
+    if (entry.package !== undefined) selectors.package = splitPackageSelector(entry.package);
+    if (entry.path !== undefined) selectors.path = entry.path;
+    if (entry.symbol !== undefined) selectors.symbol = entry.symbol;
+    if (entry.id !== undefined) selectors.id = entry.id;
+
+    out.push({
+      rule: entry.rule,
+      reason: entry.reason,
+      expires: entry.expires || null,
+      source,
+      selectors,
+      _raw: entry
+    });
+  });
+
+  return out;
+}
+
+// --- matching ---
+
+function toDate(today) {
+  if (today instanceof Date) return today;
+  if (typeof today === 'string') return new Date(`${today}T00:00:00Z`);
+  return new Date();
+}
+
+/** True when an exception's `expires` date is strictly before `today`. */
+export function isExpired(exception, today = new Date()) {
+  if (!exception.expires) return false;
+  const exp = new Date(`${exception.expires}T00:00:00Z`);
+  return toDate(today).getTime() > exp.getTime();
+}
+
+function matchPackage(sel, finding) {
+  const name = (finding.package || '').toLowerCase();
+  if (name !== sel.name) return false;
+  if (sel.version === null) return true;
+  return finding.version !== undefined && finding.version !== null && String(finding.version) === sel.version;
+}
+
+function matchSymbol(selSymbol, findingSymbol) {
+  if (typeof findingSymbol !== 'string') return false;
+  // `Type` matches `Type` and any `Type.Member`; `Type.Member` matches exactly.
+  return findingSymbol === selSymbol || findingSymbol.startsWith(`${selSymbol}.`);
+}
+
+/**
+ * True when every selector on `exception` matches `finding` (AND). Expiry is
+ * NOT consulted here — callers skip expired entries via isExpired().
+ *
+ * A finding is `{ rule|ruleId, package?, version?, path?, symbol?, id? }`.
+ */
+export function matchException(exception, finding) {
+  const s = exception.selectors;
+  const findingRule = finding.rule !== undefined ? finding.rule : finding.ruleId;
+  if (s.rule !== findingRule) return false;
+  if (s.package !== undefined && !matchPackage(s.package, finding)) return false;
+  if (s.path !== undefined && !matchGlob(s.path, finding.path)) return false;
+  if (s.symbol !== undefined && !matchSymbol(s.symbol, finding.symbol)) return false;
+  if (s.id !== undefined && s.id !== finding.id) return false;
+  return true;
+}
+
+/**
+ * Partition findings by the exceptions, returning suppression bookkeeping.
+ *
+ * @param {Array} findings - normalized findings (see matchException)
+ * @param {Array} exceptions - parsed exceptions (from parseExceptions)
+ * @param {object} [opts]
+ * @param {Date|string} [opts.today] - clock for expiry (tests pass a fixed date)
+ * @returns {{
+ *   kept: Array,          // findings that still gate
+ *   suppressed: Array,    // findings matched by a live exception (each carries `suppressed:true` + `suppressedBy`)
+ *   unused: Array,        // exceptions that matched no finding
+ *   expired: Array        // exceptions past their `expires` date (never suppress)
+ * }}
+ */
+export function applyExceptions(findings, exceptions, opts = {}) {
+  const today = opts.today;
+  const live = [];
+  const expired = [];
+  for (const ex of exceptions) {
+    if (isExpired(ex, today)) expired.push(ex);
+    else live.push(ex);
+  }
+
+  const used = new Set();
+  const kept = [];
+  const suppressed = [];
+
+  for (const finding of findings) {
+    const hit = live.find((ex) => matchException(ex, finding));
+    if (hit) {
+      used.add(hit);
+      suppressed.push({ ...finding, suppressed: true, suppressedBy: hit.reason });
+    } else {
+      kept.push(finding);
+    }
+  }
+
+  const unused = live.filter((ex) => !used.has(ex));
+  return { kept, suppressed, unused, expired };
+}

package/src/progress-reporter.js

@@ -237,9 +237,41 @@ export function createProgressBar(progress, width = 40) {
   return `[${bar}] ${percentage}%`;
 }
 
+/**
+ * Decide what (if anything) a CLI progress reporter should write to the
+ * terminal for this update, given whether stdout is attached to a real TTY.
+ *
+ * On a TTY, redrawing an animated `\r` bar in place is fine — the terminal
+ * overwrites the previous frame. When stdout is NOT a TTY (piped, redirected,
+ * `tee`'d, CI logs) there is nowhere for `\r` to redraw: every frame lands as
+ * its own line and floods the log (a real run emitted ~35KB of redraw frames
+ * this way). So the non-TTY case degrades to periodic one-line milestones
+ * (0/25/50/75/100%) instead of an animated bar — callers should still write
+ * this to stderr so stdout stays report-only either way.
+ *
+ * @param {ProgressInfo} progress
+ * @param {object} state - Caller-owned, mutated in place across calls:
+ *   `{ lastPercentage, lastMilestone }` (both start at -1/null).
+ * @param {boolean} isTTY - Whether the target stream is a real TTY.
+ * @returns {string|null} The line to write, or null to write nothing this update.
+ */
+export function formatCliProgressUpdate(progress, state, isTTY) {
+  if (!isTTY) {
+    const milestone = Math.floor(progress.percentage / 25) * 25;
+    if (milestone === state.lastMilestone) return null;
+    state.lastMilestone = milestone;
+    return `${progress.stage}: ${progress.percentage}%\n`;
+  }
+
+  if (state.lastPercentage === progress.percentage) return null;
+  state.lastPercentage = progress.percentage;
+  return `\r${createProgressBar(progress)} ${progress.stage}`;
+}
+
 export default {
   ProgressReporter,
   createProgressReporter,
   formatProgress,
-  createProgressBar
+  createProgressBar,
+  formatCliProgressUpdate
 };