@dependably/npm-check 1.7.0 → 1.7.1

package/README.md

@@ -60,11 +60,7 @@ for every command, flag, and exit code.
 
 - **[CLI reference](https://github.com/dependably/npm-check/blob/main/docs/CLI.md)** — all commands, flags, exit codes, JSON output
 - **[API guide](https://github.com/dependably/npm-check/blob/main/docs/API.md)** — using it as a library
-- [Performance](https://github.com/dependably/npm-check/blob/main/docs/PERFORMANCE.md) ·
-  [Testing](https://github.com/dependably/npm-check/blob/main/docs/TESTING.md)
-- [Changelog](https://github.com/dependably/npm-check/blob/main/CHANGELOG.md) ·
-  [Contributing](https://github.com/dependably/npm-check/blob/main/CONTRIBUTING.md) ·
-  [Security](https://github.com/dependably/npm-check/blob/main/SECURITY.md)
+- [Changelog](https://github.com/dependably/npm-check/blob/main/CHANGELOG.md)
 
 ## License
 

package/bin/cli.js

@@ -11,7 +11,7 @@ import { migrateToVersion } from '../src/migrator.js';
 import { upgradeIntegrityHashes, deduplicatePackages } from '../src/updater.js';
 import { fixPackageLock } from '../src/fixer.js';
 import { createBackup, listBackups, restoreFromLatestBackup, cleanOldBackups, BackupError } from '../src/backup.js';
-import { createProgressBar } from '../src/progress-reporter.js';
+import { formatCliProgressUpdate } from '../src/progress-reporter.js';
 import { checkIntegrity, checkLicenses } from '../src/checker.js';
 import { checkVulnerabilities, vulnEnvelope } from '../src/vuln.js';
 import { checkDeprecations, deprecationEnvelope } from '../src/deprecation.js';
@@ -82,11 +82,14 @@ Report Options:
   --no-vuln                  Skip the known-vulnerability scan
   --no-deprecated            Skip the deprecation scan
   --no-license               Skip the license check
-  --config <file>            Suite config (.dependably-check), discovered by walking
-                             up to the repo root; .npm-checkrc.json is a fallback
+  --config <file>            Suite config (.dependably; .dependably-check is a
+                             deprecated alias), discovered by walking up to the
+                             repo root; .npm-checkrc.json is a fallback
   --format human|json        Output format (default: human; json emits the shared finding schema)
   --allow-unresolved         Don't fail when a registry-backed scan can't complete
                              (registry down / endpoint unsupported). Default: FAIL CLOSED
+  --verbose                  List every "Remote-URL deps" package individually instead of
+                             the default grouped-by-host cross-reference against "Resolved URLs"
   --concurrency / --timeout / --registry / --licenses-csv   (as in Check Options)
 
 Check Options:
@@ -145,11 +148,13 @@ Unused Options:
   --format human|json        Output format (default: human; json is machine-readable)
 
 Audit Options:
-  --config <file>            Suite config (.dependably-check), discovered by walking
-                             up to the repo root; .npm-checkrc.json is a fallback
+  --config <file>            Suite config (.dependably; .dependably-check is a
+                             deprecated alias), discovered by walking up to the
+                             repo root; .npm-checkrc.json is a fallback
   --rule <id>:<severity>     Override a rule severity (error|warn|off); repeatable
   --fail-on count=<N>        Fail when the warning count exceeds N (count=0 fails on
                              any warning; --max-warnings / --strict are deprecated aliases)
+  --show-suppressed          List findings suppressed by .dependably exceptions
   --format stylish|json      Report format (default: stylish)
 
 General Options:
@@ -266,15 +271,16 @@ function handleError(error, context = '') {
   process.exit(2);
 }
 
-// Build a progress callback that redraws the bar only when the percentage
-// changes, to avoid flicker. Each caller keeps its own `lastProgress` state.
+// Build a progress callback that writes to stderr (stdout stays report-only).
+// On a real TTY it redraws an animated `\r` bar in place; when stdout is NOT a
+// TTY (piped, redirected, `tee`, CI logs) it degrades to periodic one-line
+// milestones instead — see formatCliProgressUpdate() for why.
 function makeProgressReporter() {
-  let lastProgress = null;
+  const isTTY = Boolean(process.stdout.isTTY);
+  const state = { lastPercentage: -1, lastMilestone: -1 };
   return (progress) => {
-    if (!lastProgress || progress.percentage !== lastProgress.percentage) {
-      process.stderr.write(`\r${createProgressBar(progress)} ${progress.stage}`);
-      lastProgress = progress;
-    }
+    const line = formatCliProgressUpdate(progress, state, isTTY);
+    if (line) process.stderr.write(line);
   };
 }
 
@@ -325,7 +331,8 @@ const VALUED_OPTIONS = new Set([
 const BOOLEAN_OPTIONS = new Set([
   '--offline', '--allow-unresolved',
   '--no-integrity', '--no-vuln', '--no-deprecated', '--no-license',
-  '--include-dev', '--include-peer', '--write', '--local-fallback',
+  '--include-dev', '--include-peer', '--write', '--local-fallback', '--verbose',
+  '--show-suppressed',
   '--version', '--help', '-h',
   // deprecated boolean aliases (still parsed)
   '--strict', '--fail-on-deprecated'
@@ -496,8 +503,11 @@ function registryOption(defaultRegistry) {
   return defaultRegistry ? { defaultRegistry } : {};
 }
 
-// Clear the in-progress progress bar line.
+// Clear the in-progress progress bar line. Only meaningful on a real TTY —
+// the non-TTY reporter never draws an in-place line to begin with, so this
+// would otherwise just emit a stray blank-ish line into piped/CI output.
 function clearProgressLine() {
+  if (!process.stdout.isTTY) return;
   process.stderr.write('\r' + ' '.repeat(80) + '\r');
 }
 
@@ -610,6 +620,9 @@ function parseReportOptions() {
     strict,
     maxWarnings,
     format: parseFormatFlag(['human', 'json'], 'human'),
+    // List every duplicated "Remote-URL deps" package individually instead of
+    // the default grouped-by-host cross-reference against "Resolved URLs".
+    verbose: argv.includes('--verbose'),
     // Network/integrity + license toggles.
     integrity: !argv.includes('--offline') && !argv.includes('--no-integrity'),
     license: !argv.includes('--no-license'),
@@ -650,7 +663,7 @@ async function runReportCommand() {
         auditConfig: opts.config, integrity: opts.integrity, license: opts.license, vuln: opts.vuln,
         deprecated: opts.deprecated, failOnDeprecated: opts.failOnDeprecated, minSeverity: opts.minSeverity,
         strict: opts.strict, maxWarnings: opts.maxWarnings, concurrency: opts.concurrency,
-        timeoutMs: opts.timeoutMs, failOnUnresolved: opts.failOnUnresolved, onProgress,
+        timeoutMs: opts.timeoutMs, failOnUnresolved: opts.failOnUnresolved, verbose: opts.verbose, onProgress,
         ...registryOption(opts.defaultRegistry),
         ...(opts.licensesCsv ? { licensesCsv: opts.licensesCsv } : {})
       }
@@ -980,6 +993,24 @@ function runUnusedCommand() {
   }
 }
 
+// Print .dependably config notices (deprecated filename/section, unknown keys)
+// to stderr. Never affects exit codes or the JSON payload on stdout.
+function emitConfigWarnings(warnings, format) {
+  if (format === 'json' || !Array.isArray(warnings)) return;
+  for (const w of warnings) console.error(`.dependably: ${w.message}`);
+}
+
+// Print unused / expired exception notices to stderr (spec §6.4/§6.5).
+function emitExceptionWarnings(meta, format) {
+  if (format === 'json' || !meta) return;
+  for (const ex of meta.expired || []) {
+    console.error(`.dependably: exception expired ${ex.expires} for rule "${ex.rule}" — ${ex.reason}`);
+  }
+  for (const ex of meta.unused || []) {
+    console.error(`.dependably: unused exception for rule "${ex.rule}" — ${ex.reason}`);
+  }
+}
+
 function runAuditCommand() {
   const filePath = getFilePath(positionals()[0]);
   // The audit command gates on warning/finding count, not severity level.
@@ -998,13 +1029,18 @@ function runAuditCommand() {
     applyRuleOverrides(config);
     applyMaxWarnings(config);
     const format = parseFormatFlag(['stylish', 'json'], 'stylish');
+    const showSuppressed = argv.includes('--show-suppressed');
+
+    // Surface .dependably deprecation / unknown-key notices (never gating).
+    emitConfigWarnings(config.warnings, format);
 
     const lockfile = parseLockfile(filePath);
     // package.json is optional; the pinned-versions rule degrades gracefully
     const packageJson = loadSiblingPackageJson(filePath);
 
     report = runAudit({ lockfile, packageJson, filePath: path.relative(process.cwd(), filePath) || filePath }, config);
-    console.log('\n' + formatAuditReport(report, { format }));
+    emitExceptionWarnings(report.exceptionsMeta, format);
+    console.log('\n' + formatAuditReport(report, { format, showSuppressed }));
   } catch (error) {
     console.error(`\nAudit error: ${error.message}`);
     process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dependably/npm-check",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "A comprehensive tool for validating, migrating, and updating npm package-lock.json files across versions 1, 2, and 3.",
   "main": "src/index.js",
   "type": "module",

package/src/audit-config.js

@@ -1,6 +1,7 @@
 // src/audit-config.js
 import fs from 'fs';
 import path from 'path';
+import { parseExceptions } from './exceptions.js';
 
 export class AuditConfigError extends Error {
   constructor(message, code, context = {}) {
@@ -14,9 +15,30 @@ export class AuditConfigError extends Error {
 export const CONFIG_FILENAMES = ['.npm-checkrc.json', 'npm-check.config.json'];
 
 // Shared, cross-tool config file (JSON, no extension) discovered by walking up
-// from the working directory. Its `common`/`npm` `allowedRegistryHosts` extend
-// the secure-resolved trusted-host allowlist additively (public npm stays trusted).
-export const SHARED_CONFIG_FILENAME = '.dependably-check';
+// from the working directory. `.dependably` is canonical; `.dependably-check` is
+// a deprecated alias kept for the migration window (docs/dependably-config-spec.md §7).
+export const SHARED_CONFIG_FILENAME = '.dependably';
+export const DEPRECATED_SHARED_CONFIG_FILENAME = '.dependably-check';
+// Checked in this order at each directory level (canonical wins).
+export const SHARED_CONFIG_FILENAMES = [SHARED_CONFIG_FILENAME, DEPRECATED_SHARED_CONFIG_FILENAME];
+
+// Canonical section key for npm-check, plus the deprecated ecosystem alias.
+export const SECTION_KEY = 'npm-check';
+export const DEPRECATED_SECTION_KEY = 'npm';
+
+// Highest .dependably format version this build understands.
+export const SUPPORTED_CONFIG_VERSION = 1;
+
+// Exception selectors an npm-check finding can carry (spec §6.7). `path`/`symbol`
+// are code-location selectors used by the C# tools; they are errors in npm-check's
+// own section but tolerated (ignored) in `common`.
+export const APPLICABLE_SELECTORS = ['package', 'id'];
+
+// Keys npm-check recognizes inside `common` / its own section. Unknown keys warn.
+const KNOWN_SECTION_KEYS = new Set([
+  'rules', 'exceptions', 'exclude', 'failOn',
+  'allowedRegistryHosts', 'allowedLocalFeeds', 'maxWarnings'
+]);
 
 export const SEVERITIES = ['error', 'warn', 'off'];
 
@@ -92,18 +114,10 @@ export function normalizeRuleEntry(entry) {
 }
 
 /**
- * Resolve the effective audit config: built-in defaults overlaid by a
- * discovered or explicitly-given JSON config file.
- * Rule options merge over the defaults for that rule; severity replaces.
- *
- * @param {string} cwd - Directory to search for config files
- * @param {string|null} explicitPath - Path passed via --config (wins over discovery)
- * @returns {{maxWarnings, rules: {[id]: {severity, options}}, configPath}}
- */
-/**
- * Walk up from `cwd` to the filesystem root looking for the shared
- * `.dependably-check` config file. Stops at the first hit, at a directory
- * containing a `.git` entry (the repo root), or at the filesystem root.
+ * Walk up from `cwd` to the filesystem root looking for a shared config file.
+ * At each level `.dependably` is preferred over the deprecated `.dependably-check`.
+ * Stops at the first hit, at a directory containing a `.git` entry (the repo
+ * root), or at the filesystem root.
  *
  * @param {string} cwd - Directory to start the search from
  * @returns {string|null} Absolute path to the shared config, or null when absent
@@ -111,8 +125,10 @@ export function normalizeRuleEntry(entry) {
 export function findSharedConfig(cwd = process.cwd()) {
   let dir = path.resolve(cwd);
   for (;;) {
-    const candidate = path.join(dir, SHARED_CONFIG_FILENAME);
-    if (fs.existsSync(candidate)) return candidate;
+    for (const name of SHARED_CONFIG_FILENAMES) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
 
     // Stop at the repo root: a directory containing `.git`.
     if (fs.existsSync(path.join(dir, '.git'))) return null;
@@ -123,38 +139,132 @@ export function findSharedConfig(cwd = process.cwd()) {
   }
 }
 
-// Union of `common.allowedRegistryHosts` and `npm.allowedRegistryHosts` from a
-// parsed shared config (deduped, common first). Other sections are ignored.
+// Deprecation warnings for the selected shared-config file (§2.2/§2.3).
+function filenameWarnings(sharedPath) {
+  if (!sharedPath) return [];
+  const dir = path.dirname(sharedPath);
+  const base = path.basename(sharedPath);
+  const warnings = [];
+  if (base === DEPRECATED_SHARED_CONFIG_FILENAME) {
+    if (fs.existsSync(path.join(dir, SHARED_CONFIG_FILENAME))) {
+      // Both present but findSharedConfig preferred canonical — should not reach
+      // here; keep the guard for direct callers.
+      warnings.push({ code: 'BOTH_FILES_PRESENT', message: `both ${SHARED_CONFIG_FILENAME} and ${DEPRECATED_SHARED_CONFIG_FILENAME} found in ${dir}; using ${SHARED_CONFIG_FILENAME}` });
+    } else {
+      warnings.push({ code: 'DEPRECATED_FILENAME', message: `${DEPRECATED_SHARED_CONFIG_FILENAME} is deprecated; rename it to ${SHARED_CONFIG_FILENAME}` });
+    }
+  } else if (fs.existsSync(path.join(dir, DEPRECATED_SHARED_CONFIG_FILENAME))) {
+    warnings.push({ code: 'BOTH_FILES_PRESENT', message: `both ${SHARED_CONFIG_FILENAME} and ${DEPRECATED_SHARED_CONFIG_FILENAME} found in ${dir}; using ${SHARED_CONFIG_FILENAME} (${DEPRECATED_SHARED_CONFIG_FILENAME} is ignored — delete it)` });
+  }
+  return warnings;
+}
+
+// Bare hostnames from a section's allowedRegistryHosts (lowercased, filtered).
+function sectionHosts(section) {
+  const hosts = section && section.allowedRegistryHosts;
+  if (!Array.isArray(hosts)) return [];
+  return hosts.filter((h) => typeof h === 'string').map((h) => h.trim().toLowerCase()).filter(Boolean);
+}
+
+// Union of `common` and the npm-check section's allowedRegistryHosts (deduped,
+// case-insensitive, common first). The canonical section is preferred; the `npm`
+// alias is read only when the canonical section is absent.
 function collectSharedHosts(parsed) {
-  const collect = (section) => {
-    const hosts = section && section.allowedRegistryHosts;
-    return Array.isArray(hosts) ? hosts.filter((h) => typeof h === 'string') : [];
-  };
-  return [...new Set([...collect(parsed.common), ...collect(parsed.npm)])];
+  const tool = parsed[SECTION_KEY] !== undefined ? parsed[SECTION_KEY] : parsed[DEPRECATED_SECTION_KEY];
+  return [...new Set([...sectionHosts(parsed && parsed.common), ...sectionHosts(tool)])];
 }
 
-// Pull npm-check's audit settings (`rules`, `maxWarnings`) out of a shared
-// `.dependably-check` object: the `common` section is the base, the `npm`
-// section overrides it. Mirrors how the other suite tools read their section.
-function extractSharedAuditSettings(parsed) {
-  const pick = (section) => {
-    const out = {};
-    if (section && typeof section === 'object') {
-      if (section.rules !== undefined) out.rules = section.rules;
-      if (section.maxWarnings !== undefined) out.maxWarnings = section.maxWarnings;
+// Union two arrays (ordinal dedupe), tolerating non-arrays.
+function unionList(a, b) {
+  const out = [];
+  const seen = new Set();
+  for (const v of [...(Array.isArray(a) ? a : []), ...(Array.isArray(b) ? b : [])]) {
+    if (!seen.has(v)) { seen.add(v); out.push(v); }
+  }
+  return out;
+}
+
+// Merge the `rules` maps of two sections per rule-id: the tool entry for a given
+// id replaces common's wholesale (no cross-section option deep-merge, §B.3).
+function mergeRuleMaps(commonRules, toolRules) {
+  if (!commonRules && !toolRules) return undefined;
+  return { ...(commonRules && typeof commonRules === 'object' ? commonRules : {}),
+    ...(toolRules && typeof toolRules === 'object' ? toolRules : {}) };
+}
+
+// Warn about keys npm-check does not recognize inside a read section (§8).
+function unknownKeyWarnings(section, label, warnings) {
+  if (!section || typeof section !== 'object') return;
+  for (const key of Object.keys(section)) {
+    if (!KNOWN_SECTION_KEYS.has(key)) {
+      warnings.push({ code: 'UNKNOWN_KEY', message: `unknown key "${label}.${key}" in shared config — ignoring` });
     }
-    return out;
-  };
-  return { ...pick(parsed && parsed.common), ...pick(parsed && parsed.npm) };
+  }
 }
 
-// True when a parsed config is the shared `.dependably-check` shape (sectioned
-// by tool) rather than the legacy flat tool-config shape (top-level rules/maxWarnings).
+/**
+ * Resolve npm-check's settings from a parsed shared-config object: merge `common`
+ * under the npm-check section per the single merge rule (§5). Returns the audit
+ * settings plus parsed exceptions and any warnings.
+ */
+function resolveToolSection(parsed, warnings) {
+  const common = parsed && parsed.common;
+  const canonical = parsed && parsed[SECTION_KEY];
+  const alias = parsed && parsed[DEPRECATED_SECTION_KEY];
+  const tool = canonical !== undefined ? canonical : alias;
+  if (canonical === undefined && alias !== undefined) {
+    warnings.push({ code: 'DEPRECATED_ALIAS_SECTION', message: `section "${DEPRECATED_SECTION_KEY}" is deprecated; rename it to "${SECTION_KEY}"` });
+  } else if (canonical !== undefined && alias !== undefined) {
+    warnings.push({ code: 'DEPRECATED_ALIAS_SECTION', message: `both "${SECTION_KEY}" and "${DEPRECATED_SECTION_KEY}" sections present; using "${SECTION_KEY}"` });
+  }
+
+  unknownKeyWarnings(common, 'common', warnings);
+  unknownKeyWarnings(tool, SECTION_KEY, warnings);
+
+  const settings = {};
+  const rules = mergeRuleMaps(common && common.rules, tool && tool.rules);
+  if (rules) settings.rules = rules;
+
+  // Scalars: tool overrides common. failOn merges per key.
+  const failOn = pickFailOn(common && common.failOn, tool && tool.failOn);
+  if (failOn) settings.failOn = failOn;
+
+  const pickMax = (s) => (s && s.maxWarnings !== undefined ? s.maxWarnings : undefined);
+  const toolMax = pickMax(tool);
+  const commonMax = pickMax(common);
+  if (toolMax !== undefined) settings.maxWarnings = toolMax;
+  else if (commonMax !== undefined) settings.maxWarnings = commonMax;
+
+  settings.exclude = unionList(common && common.exclude, tool && tool.exclude);
+
+  // Exceptions: common (tolerant) + own section (strict selector/rule checks).
+  const commonEx = parseExceptions(common && common.exceptions, {
+    source: 'common', applicableSelectors: APPLICABLE_SELECTORS
+  });
+  const ownEx = parseExceptions(tool && tool.exceptions, {
+    source: 'own', applicableSelectors: APPLICABLE_SELECTORS, knownRules: KNOWN_RULES
+  });
+  settings.exceptions = [...commonEx, ...ownEx];
+
+  return settings;
+}
+
+// Merge two failOn objects per key (tool wins). Returns undefined if neither set.
+function pickFailOn(commonFailOn, toolFailOn) {
+  const c = commonFailOn && typeof commonFailOn === 'object' ? commonFailOn : {};
+  const t = toolFailOn && typeof toolFailOn === 'object' ? toolFailOn : {};
+  const merged = { ...c, ...t };
+  if (merged.severity === undefined && merged.count === undefined) return undefined;
+  return merged;
+}
+
+// True when a parsed config is the shared (sectioned) shape rather than the
+// legacy flat tool-config shape (top-level rules/maxWarnings).
 function isSharedShape(configPath, parsed) {
-  if (path.basename(configPath) === SHARED_CONFIG_FILENAME) return true;
+  if (SHARED_CONFIG_FILENAMES.includes(path.basename(configPath))) return true;
   if (!parsed || typeof parsed !== 'object') return false;
   const hasToolKeys = 'rules' in parsed || 'maxWarnings' in parsed;
-  const hasSharedSections = 'common' in parsed || 'npm' in parsed;
+  const hasSharedSections = 'common' in parsed || SECTION_KEY in parsed || DEPRECATED_SECTION_KEY in parsed;
   return !hasToolKeys && hasSharedSections;
 }
 
@@ -173,17 +283,35 @@ function readJsonConfig(configPath) {
   }
 }
 
+// Validate the top-level shape + version of a shared-config object (§3, §8).
+function validateSharedShape(parsed, sharedPath) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new AuditConfigError(`Shared config must be a JSON object: ${sharedPath}`, 'CONFIG_SHAPE', { sharedPath });
+  }
+  if (parsed.version !== undefined) {
+    if (typeof parsed.version !== 'number' || !Number.isInteger(parsed.version) || parsed.version > SUPPORTED_CONFIG_VERSION) {
+      throw new AuditConfigError(
+        `Unsupported .dependably version ${JSON.stringify(parsed.version)} (this build supports up to ${SUPPORTED_CONFIG_VERSION})`,
+        'CONFIG_VERSION',
+        { sharedPath }
+      );
+    }
+  }
+}
+
 /**
- * Read and parse the shared `.dependably-check` file, returning its registry-host
- * allowlist and npm-check audit settings (`rules`/`maxWarnings`). Other tool
- * sections and unknown keys are ignored.
+ * Read and parse the shared config file, returning npm-check's registry-host
+ * allowlist, audit settings (`rules`/`maxWarnings`/`failOn`/`exclude`),
+ * parsed exceptions, and any deprecation/unknown-key warnings.
  *
  * @param {string} cwd - Directory to start discovery from
- * @returns {{ allowedRegistryHosts: string[], sharedPath: string|null, auditSettings: object }}
+ * @returns {{ allowedRegistryHosts, sharedPath, auditSettings, exceptions, exclude, failOn, warnings }}
  */
 export function loadSharedConfig(cwd = process.cwd()) {
   const sharedPath = findSharedConfig(cwd);
-  if (!sharedPath) return { allowedRegistryHosts: [], sharedPath: null, auditSettings: {} };
+  if (!sharedPath) {
+    return { allowedRegistryHosts: [], sharedPath: null, auditSettings: {}, exceptions: [], exclude: [], failOn: null, warnings: [] };
+  }
 
   let raw;
   try {
@@ -199,23 +327,31 @@ export function loadSharedConfig(cwd = process.cwd()) {
     throw new AuditConfigError(`Invalid JSON in ${sharedPath}: ${e.message}`, 'SHARED_CONFIG_PARSE', { sharedPath });
   }
 
+  validateSharedShape(parsed, sharedPath);
+  const warnings = filenameWarnings(sharedPath);
+  const settings = resolveToolSection(parsed, warnings);
+
   return {
     allowedRegistryHosts: collectSharedHosts(parsed),
     sharedPath,
-    auditSettings: extractSharedAuditSettings(parsed)
+    auditSettings: { ...(settings.rules ? { rules: settings.rules } : {}), ...(settings.maxWarnings !== undefined ? { maxWarnings: settings.maxWarnings } : {}) },
+    exceptions: settings.exceptions,
+    exclude: settings.exclude,
+    failOn: settings.failOn || null,
+    warnings
   };
 }
 
 export function loadAuditConfig(cwd = process.cwd(), explicitPath = null) {
-  // The shared `.dependably-check` (discovered by walking up to the repo root)
-  // is the PRIMARY config source — its `common`/`npm` sections supply the base
-  // audit settings and the registry-host allowlist. A tool-specific
-  // `.npm-checkrc.json` (or an explicit `--config`) overrides it.
+  // The shared `.dependably` (discovered by walking up to the repo root) is the
+  // PRIMARY config source. A tool-specific `.npm-checkrc.json` (or an explicit
+  // `--config`) overrides it.
   const shared = loadSharedConfig(cwd);
 
   let toolConfig = {};
   let configPath = null;
   let explicitSharedHosts = [];
+  let explicitExtras = null; // { exceptions, exclude, failOn } from an explicit shared-shape file
 
   if (explicitPath) {
     configPath = path.resolve(explicitPath);
@@ -224,17 +360,20 @@ export function loadAuditConfig(cwd = process.cwd(), explicitPath = null) {
     }
     const parsed = readJsonConfig(configPath);
     if (isSharedShape(configPath, parsed)) {
-      // `--config` points at a `.dependably-check`: read npm-check's settings
-      // from its common/npm sections and take its registry-host allowlist too.
-      toolConfig = extractSharedAuditSettings(parsed);
+      validateSharedShape(parsed, configPath);
+      const warnings = [];
+      const settings = resolveToolSection(parsed, warnings);
+      shared.warnings.push(...warnings);
+      toolConfig = { ...(settings.rules ? { rules: settings.rules } : {}), ...(settings.maxWarnings !== undefined ? { maxWarnings: settings.maxWarnings } : {}) };
       explicitSharedHosts = collectSharedHosts(parsed);
+      explicitExtras = { exceptions: settings.exceptions, exclude: settings.exclude, failOn: settings.failOn || null };
     } else {
       // Legacy flat tool-config (.npm-checkrc.json shape) given explicitly.
       toolConfig = parsed;
     }
   } else {
     // Discover a tool-specific config in the working directory (fallback for
-    // back-compat; the shared `.dependably-check` above is the primary source).
+    // back-compat; the shared `.dependably` above is the primary source).
     for (const name of CONFIG_FILENAMES) {
       const candidate = path.join(cwd, name);
       if (fs.existsSync(candidate)) {
@@ -249,13 +388,29 @@ export function loadAuditConfig(cwd = process.cwd(), explicitPath = null) {
   const userConfig = { ...shared.auditSettings, ...toolConfig };
   const config = mergeConfig(userConfig, configPath || shared.sharedPath);
 
-  // Layer the shared `.dependably-check` hosts ADDITIVELY onto whatever
-  // secure-resolved.allowedHosts resolved to (built-in default or a
-  // tool-config replacement) — public npm always stays trusted.
+  // Layer the shared allowlist ADDITIVELY onto secure-resolved / no-remote-deps
+  // (public npm always stays trusted).
   const hosts = [...new Set([...shared.allowedRegistryHosts, ...explicitSharedHosts])];
   if (hosts.length > 0) {
     extendAllowedHosts(config, hosts);
   }
+
+  // failOn.count is the standard form of maxWarnings; a legacy maxWarnings in a
+  // tool-config still wins if it was set (it flowed through mergeConfig above).
+  const failOn = explicitExtras ? explicitExtras.failOn : shared.failOn;
+  if (failOn) {
+    if (failOn.count !== undefined && toolConfig.maxWarnings === undefined && shared.auditSettings.maxWarnings === undefined) {
+      if (typeof failOn.count !== 'number' || !Number.isInteger(failOn.count) || failOn.count < 0) {
+        throw new AuditConfigError(`failOn.count must be a non-negative integer, got: ${JSON.stringify(failOn.count)}`, 'INVALID_FAIL_ON');
+      }
+      config.maxWarnings = failOn.count;
+    }
+    config.failOnSeverity = failOn.severity || null;
+  }
+
+  config.exceptions = explicitExtras ? explicitExtras.exceptions : shared.exceptions;
+  config.exclude = explicitExtras ? explicitExtras.exclude : shared.exclude;
+  config.warnings = shared.warnings;
   config.sharedConfigPath = shared.sharedPath;
 
   return config;
@@ -265,11 +420,9 @@ export function loadAuditConfig(cwd = process.cwd(), explicitPath = null) {
  * Add the given hosts to every host-based rule's `allowedHosts`, deduplicated,
  * without replacing the existing entries. No-op for rules that are absent.
  *
- * BOTH `secure-resolved` (which registries are trusted for HTTPS resolution) and
- * `no-remote-deps` (which registry hosts count as a registry rather than a
- * remote/git dep) consult `allowedHosts`. The shared `.dependably-check`
- * allowlist must reach both — otherwise a private-registry project silences one
- * rule but still trips the other, breaking the documented `--fail-on` CI gate.
+ * BOTH `secure-resolved` and `no-remote-deps` consult `allowedHosts`; the shared
+ * allowlist must reach both or a private-registry project silences one rule but
+ * still trips the other.
  *
  * @param {object} config - A merged audit config (from mergeConfig)
  * @param {string[]} hosts - Bare hostnames to add to the allowlist