@vibe-agent-toolkit/cli 0.1.41-rc.7 → 0.1.41-rc.8

package/dist/commands/audit.js

@@ -11,12 +11,13 @@ import { detectFormat } from '@vibe-agent-toolkit/discovery';
 import { findProjectRoot, gitFindRoot, GitTracker, isAbsolutePath, isGitUrl, issueLocation, parseGitUrl, resetProjectRootCaches, safePath, } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import picomatch from 'picomatch';
-import { resetSkillDiscoveryCache, resolveSkillPackagingConfig, stripValidationAllowForDisplay, } from '../skill-resolution/packaging-config.js';
+import { resetSkillDiscoveryCache, resolveProjectDeclaredEvalSuites, resolveSkillPackagingConfig, stripValidationAllowForDisplay, } from '../skill-resolution/packaging-config.js';
 import { handleCommandError } from '../utils/command-error.js';
 import { ConfigLoadError, loadConfig, resetLoadedConfigCache, } from '../utils/config-loader.js';
-import { formatIssueAnchor } from '../utils/issue-anchor.js';
+import { formatIssueLines, formatSeverityBreakdown, issuesToRenderAtVerbosity, } from '../utils/issue-rendering.js';
 import { createLogger } from '../utils/logger.js';
 import { writeYamlOutput } from '../utils/output.js';
+import { relativizePathEntries } from '../utils/relativize-paths.js';
 import { mergeSkillPackagingConfig } from '../utils/skill-packaging-config.js';
 import { renderSkillQualityFooter } from '../utils/skill-quality-footer.js';
 import { computeConfigVerdicts } from '../utils/verdict-helpers.js';
@@ -168,15 +169,19 @@ async function validateSingleSkill(skillPath, options, logger, locationRoot, isV
     const skillConfig = fullConfig === null ? null : stripValidationAllowForDisplay(fullConfig);
     if (skillConfig !== null) {
         logger.debug(`  Using config-aware validation for: ${skillPath}`);
-        const { gitTracker } = await resolveScanContext(safePath.resolve(skillPath), locationRoot);
+        const { gitTracker } = await resolveScanContext(safePath.resolve(skillPath), locationRoot, logger);
         // Key the shared registry on the same project root the validator derives,
         // so every skill under one root parses the corpus once for the whole run
         // instead of once each.
         const skillDir = safePath.resolve(skillPath, '..');
         const projectRoot = findProjectRoot(skillDir) ?? skillDir;
+        // The project's declared eval suites, memoized per config root, so this lane
+        // predicts the same bundle the packager produces: no skill's report counts a
+        // SIBLING skill's eval suite as an ordinary bundled file.
         const sharedCtx = {
             registry: await crawlAndResolveRegistry(projectRoot),
             locationRoot,
+            projectSkills: await resolveProjectDeclaredEvalSuites(skillPath),
         };
         if (gitTracker !== null) {
             sharedCtx.gitTracker = gitTracker;
@@ -368,7 +373,7 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
     }
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
-        ? await runCompatAnalysis(results, logger) // --settings not supported in --user mode
+        ? await runCompatAnalysis(results, logger, scanRoot) // --settings not supported in --user mode
         : undefined;
     const verbose = options.verbose ?? false;
     const skillResults = results.filter((r) => SKILL_RESULT_TYPES.has(r.type));
@@ -539,7 +544,7 @@ export async function buildAuditReport(scanPath, options, startTime, logger) {
     const vatContextForCompat = await buildVATProjectContext(deriveConfigRoot(scanPath), logger);
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
-        ? await runCompatAnalysis(results, logger, effectiveSettings, vatContextForCompat)
+        ? await runCompatAnalysis(results, logger, scanRoot, effectiveSettings, vatContextForCompat)
         : undefined;
     const verbose = options.verbose ?? false;
     return {
@@ -570,7 +575,7 @@ async function runAuditAtPath(scanPath, options, overrides = {}) {
     if (verbose) {
         renderVerboseEvidence(results, document.root, logger);
     }
-    handleAuditResults(results, document, logger);
+    handleAuditResults(results, document, logger, verbose);
     logger.debug(`Audit complete in ${Date.now() - startTime}ms`);
 }
 async function runUrlAudit(rawInput, options) {
@@ -813,14 +818,11 @@ export async function getValidationResults(scanPath, recursive, options, logger,
         const stat = await fsp.stat(scanPath);
         if (stat.isDirectory()) {
             logger.debug('Scanning directory for resources');
-            // Merge resources.exclude from config with --exclude CLI flag patterns.
-            // Both use the same picomatch semantics. Do NOT mutate options.
-            const config = loadConfig(deriveConfigRoot(scanPath));
-            const configExcludes = config?.resources?.exclude ?? [];
-            const mergedOptions = configExcludes.length > 0
-                ? { ...options, exclude: [...(options.exclude ?? []), ...configExcludes] }
-                : options;
-            return scanDirectory(scanPath, recursive, mergedOptions, logger, await resolveScanContext(scanPath, locationRoot));
+            // The project's `resources.exclude` is applied by the scan context,
+            // on the project-root basis its globs were written against — NOT
+            // merged into `options.exclude`, whose patterns are relative to the
+            // directory the operator named. See resolveProjectExcludes.
+            return scanDirectory(scanPath, recursive, options, logger, await resolveScanContext(scanPath, locationRoot, logger));
         }
     }
     catch {
@@ -895,6 +897,11 @@ function resolveConfigTargetsForPlugin(pluginDir, vatContext) {
  * Non-plugin results are skipped silently.
  * When effectiveSettings is provided, also runs settings conflict detection.
  *
+ * `locationRoot` is the invocation scan root: the ONE base every emitted
+ * evidence `location.file` is relative to. One audit run spans many plugin
+ * directories, so anchoring evidence at each plugin would mix coordinate
+ * systems in a single document.
+ *
  * When vatContext is provided, config-layer `targets` declarations are
  * threaded through to the analyzer so `vat audit .` inside a VAT project
  * matches `vat skills validate` verdicts. See
@@ -902,7 +909,7 @@ function resolveConfigTargetsForPlugin(pluginDir, vatContext) {
  *
  * @internal Exported for integration testing only — not part of the public CLI API.
  */
-export async function runCompatAnalysis(results, logger, effectiveSettings, vatContext = null) {
+export async function runCompatAnalysis(results, logger, locationRoot, effectiveSettings, vatContext = null) {
     const compatMap = new Map();
     for (const result of results) {
         if (result.type !== RESOURCE_TYPE_CLAUDE_PLUGIN)
@@ -913,7 +920,7 @@ export async function runCompatAnalysis(results, logger, effectiveSettings, vatC
             const analyzeOptions = configTargets === undefined
                 ? undefined
                 : { configTargets };
-            const compat = await analyzeCompatibility(result.path, analyzeOptions);
+            const compat = await analyzeCompatibility(result.path, locationRoot, analyzeOptions);
             // Settings conflict detection (when --settings flag is used)
             if (effectiveSettings === undefined) {
                 compatMap.set(result.path, compat);
@@ -994,34 +1001,22 @@ function applyVerboseFilter(results, verbose) {
     });
 }
 /**
- * Re-base each emitted file entry's `path` onto the run root.
+ * Nested carriers inside a file entry that publish their own `path`.
  *
- * `ValidationResult.path` stays ABSOLUTE inside the pipeline on purpose: it is
- * the identity every internal map keys on (compat results, visited-path
- * de-duplication, registry caches), and unlike `location` it is trivially
- * recoverable — an absolute path plus the known root yields the relative form.
- * `location` is the opposite: it cannot be re-based here because a relative
- * string whose base was never stated is not recoverable, which is exactly why
- * the base is threaded down to the producers instead.
+ * `linkedFiles[].path` sat absolute in every document while every sibling
+ * `path` and `location` beside it was root-relative — 532 of them in a single
+ * `vat audit --user` run. Naming the carrier here is what re-bases it; a new
+ * carrier that is not named keeps shipping absolute paths.
  */
-function relativizeFileEntries(entries, root) {
-    return entries.map((entry) => {
-        const relative = issueLocation(entry.path, root);
-        // Pointing audit AT a single resource makes that resource the root, which
-        // relativizes to the empty string. Spell it `.` — the POSIX name for "the
-        // root itself" — so no consumer has to special-case an empty path, and
-        // `join(root, path)` still resolves.
-        return { ...entry, path: relative === '' ? '.' : relative };
-    });
-}
+const NESTED_PATH_CARRIERS = ['linkedFiles'];
 function calculateSummary(results, startTime, compatMap, verbose, root) {
-    const base = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(results, compatMap);
+    const { entries, ...base } = buildBaseSummary(results, startTime);
+    const withCompat = applyCompatMap(entries, compatMap);
     return {
         // Stated once, first, and the only absolute path in the document.
         root,
         ...base,
-        files: relativizeFileEntries(applyVerboseFilter(withCompat, verbose), root),
+        files: relativizePathEntries(applyVerboseFilter(withCompat, verbose), root, NESTED_PATH_CARRIERS),
     };
 }
 /**
@@ -1088,7 +1083,7 @@ function renderVerboseEvidence(results, root, logger) {
         }
     }
 }
-function handleAuditResults(results, summary, logger) {
+function handleAuditResults(results, summary, logger, verbose) {
     const { filesWithErrors: errorCount, filesWithWarnings: warningCount, filesPassed: successCount, } = summary.summary;
     // Report settings conflicts (advisory, non-blocking)
     const totalSettingsConflicts = (summary.files ?? []).reduce((sum, f) => {
@@ -1100,10 +1095,12 @@ function handleAuditResults(results, summary, logger) {
     // Audit is advisory only — always exit 0 for validation results.
     // Use vat skills validate for gated validation (exit 1 on errors).
     if (errorCount > 0) {
-        logErrors(results, errorCount, summary.root, logger);
+        logger.error(`Audit failed: ${errorCount} file(s) with errors`);
+        logFindingsForStatus(results, 'error', summary.root, logger.error.bind(logger), verbose);
     }
     else if (warningCount > 0) {
-        logWarnings(results, warningCount, summary.root, logger);
+        logger.info(`Audit passed with warnings: ${warningCount} file(s)`);
+        logFindingsForStatus(results, 'warning', summary.root, logger.info.bind(logger), verbose);
     }
     else {
         // `success` means "nothing actionable", NOT "nothing to see" — name the
@@ -1135,34 +1132,62 @@ function renderAuditFooter(results, logger) {
     }
     renderSkillQualityFooter(logger, hasSkillFindings, emittedCodes);
 }
-function logErrors(results, errorCount, root, logger) {
-    logger.error(`Audit failed: ${errorCount} file(s) with errors`);
-    const errorResults = results.filter((r) => r.status === 'error');
-    for (const result of errorResults) {
-        logger.error(`\n${issueLocation(result.path, root)}:`);
-        const errorIssues = result.issues.filter((i) => i.severity === 'error');
-        logIssues(errorIssues, logger.error.bind(logger));
+/**
+ * The stderr findings report for a set of audit results — the HUMAN channel.
+ *
+ * Deliberately NOT the YAML document. `vat audit` publishes a machine-readable
+ * report on stdout that CI and tooling parse, and that document carries every
+ * finding at every verbosity; this stream is read by a person, and on a 90-skill
+ * corpus it printed 26,480 lines, 3,480 of them occurrences of a single
+ * high-cardinality warning code. The two channels answer different questions, so
+ * only this one collapses.
+ *
+ * Which findings render in full is not decided here — it is
+ * {@link issuesToRenderAtVerbosity}, shared with the other findings-reporting
+ * verbs so `vat audit`, `vat skills validate` and `vat skills build` cannot drift
+ * onto three answers again. Errors always render; warnings and info collapse
+ * unless `verbose`; allow-listed findings never render.
+ *
+ * The severity breakdown on each file's heading is load-bearing, not decoration.
+ * For a warning-only file at default verbosity that heading is the ENTIRE report
+ * for that file, so dropping the counts would turn the collapse into silence —
+ * the failure direction `issue-rendering.ts` exists to prevent. The trailing
+ * line names the collapsed total and both ways to see it, for the same reason.
+ *
+ * Pure: takes results, returns lines. It reads `issues` and never rewrites it,
+ * because `runAuditAtPath` builds the YAML document from the very same array.
+ *
+ * @internal Exported for unit testing only — not part of the public CLI API.
+ */
+export function formatAuditFindingsLines(results, root, verbose) {
+    const lines = [];
+    let collapsed = 0;
+    for (const result of results) {
+        const rendered = issuesToRenderAtVerbosity(result.issues, verbose);
+        // What --verbose WOULD show, minus what this verbosity shows. Derived from
+        // the policy rather than re-stating it, so the count cannot contradict it.
+        collapsed += issuesToRenderAtVerbosity(result.issues, true).length - rendered.length;
+        lines.push(`\n${issueLocation(result.path, root)} — ${formatSeverityBreakdown(countBySeverity(result.issues))}:`);
+        for (const issue of rendered) {
+            lines.push(...formatIssueLines(issue, '  '));
+        }
     }
-}
-function logWarnings(results, warningCount, root, logger) {
-    logger.info(`Audit passed with warnings: ${warningCount} file(s)`);
-    const warningResults = results.filter((r) => r.status === 'warning');
-    for (const result of warningResults) {
-        logger.info(`\n${issueLocation(result.path, root)}:`);
-        const warningIssues = result.issues.filter((i) => i.severity === 'warning');
-        logIssues(warningIssues, logger.info.bind(logger));
+    if (collapsed > 0) {
+        lines.push(`\n${collapsed} warning/info finding(s) not shown — re-run with --verbose, ` +
+            'or read the YAML report on stdout, which always lists every finding.');
     }
+    return lines;
 }
-function logIssues(issues, logFn) {
-    for (const issue of issues) {
-        logFn(`  [${issue.code}] ${issue.message}`);
-        const anchor = formatIssueAnchor(issue);
-        if (anchor !== undefined) {
-            logFn(`    at: ${anchor}`);
-        }
-        if (issue.fix) {
-            logFn(`    fix: ${issue.fix}`);
-        }
+/**
+ * Write one status class's findings to stderr beneath the run banner.
+ *
+ * The banner counts FILES and the blocks below count FINDINGS; both are needed,
+ * and `logFn` picks the channel the calling branch already established.
+ */
+function logFindingsForStatus(results, status, root, logFn, verbose) {
+    const selected = results.filter((r) => r.status === status);
+    for (const line of formatAuditFindingsLines(selected, root, verbose)) {
+        logFn(line);
     }
 }
 /**
@@ -1198,9 +1223,12 @@ async function handleFileEntry(entry, fullPath, options, logger, scanCtx) {
             logger.debug(`  Using config-aware validation for: ${fullPath}`);
             // Thread the per-scan tracker into packaging validation so gitignore
             // checks in the link-graph walk stay O(1).
+            // `projectSkills`: same project-wide test-input rule as the lane above,
+            // resolved through the same per-config-root memo.
+            const projectSkills = await resolveProjectDeclaredEvalSuites(fullPath);
             const sharedCtx = scanCtx.gitTracker === null
-                ? { locationRoot }
-                : { gitTracker: scanCtx.gitTracker, locationRoot };
+                ? { locationRoot, projectSkills }
+                : { gitTracker: scanCtx.gitTracker, locationRoot, projectSkills };
             const packagingResult = await validateSkillForPackaging(fullPath, skillConfig, 'source', sharedCtx);
             return packagingResultToValidationResult(fullPath, packagingResult, skillConfig.targets, locationRoot);
         }
@@ -1237,6 +1265,52 @@ async function handleDirectoryEntry(fullPath, recursive, options, logger, baseDi
     }
     return results;
 }
+/**
+ * Compile the governing project's `resources.exclude` for a scan.
+ *
+ * The config is found by walking UP from the scan directory ({@link findProjectRoot}),
+ * not by looking in it. Looking only in the scan directory is how a path argument
+ * silently voided every exclude the project had declared: `vat audit
+ * packages/x/resources/skills/` found no config there, so a package that excludes
+ * its deliberately-broken eval fixtures had them audited as production skills the
+ * moment anyone named a subdirectory. Commit 8a466b0c fixed the same defect for
+ * `vat resources validate|scan` and `vat rag index`; this is the lane it missed.
+ * The rule is the same one that commit established: a path argument says WHICH
+ * tree to audit, and `exclude` applies either way.
+ *
+ * With one deliberate exception, mirroring the gitignore rule in
+ * {@link resolveScanContext}: when the operator points the scan AT an excluded
+ * tree, their explicit intent wins and the excludes are dropped for that run.
+ * Otherwise naming an excluded directory would report `filesScanned: 0,
+ * status: success` — a green run that scanned nothing.
+ */
+function resolveProjectExcludes(scanDir, logger) {
+    const projectRoot = findProjectRoot(scanDir);
+    if (projectRoot === null)
+        return null;
+    let patterns;
+    try {
+        patterns = loadConfig(projectRoot)?.resources?.exclude ?? [];
+    }
+    catch (err) {
+        // Audit is a bulk linter over trees it does not own; a broken governing
+        // config must not abort the scan. Say so rather than dropping it silently.
+        logger.debug(`Ignoring unreadable config at ${projectRoot}: ${String(err)}`);
+        return null;
+    }
+    if (patterns.length === 0)
+        return null;
+    // dot:true so excludes like `**/.cache/*` match through dotfile dirs;
+    // without it the exclude silently never fires.
+    const isMatch = picomatch([...patterns], { dot: true });
+    const scanRelToProject = safePath.relative(projectRoot, safePath.resolve(scanDir)).replaceAll('\\', '/');
+    if (scanRelToProject !== '' && isExcludedPath(isMatch, scanRelToProject, true)) {
+        logger.debug(`Scan root ${scanRelToProject} is excluded by the config at ${projectRoot}; ` +
+            'auditing it anyway because it was named explicitly');
+        return null;
+    }
+    return { isMatch, base: projectRoot, label: 'excluded by config' };
+}
 /** Cache of (gitRoot → initialized GitTracker) to avoid re-spawning ls-files. */
 const gitTrackerCache = new Map();
 /**
@@ -1264,10 +1338,27 @@ async function getOrCreateInventoryRegistry(projectRoot) {
 /**
  * `extractClaudePluginInventory` for a plugin directory, handing it the shared
  * inventory registry so each skill it walks does not re-parse the corpus.
+ *
+ * A PROVIDER, not an awaited registry, and only when there is a project root — the same
+ * two rules `vat inventory`'s `linkRegistryProviderFor` follows, for the same two reasons:
+ *
+ * 1. **Unresolved.** `extractClaudePluginInventory` promises "never throws — all failures
+ *    surface via parseErrors[]", and that promise holds only while the crawl runs inside
+ *    `walkLinkedFiles`'s try/catch. Awaiting it here moved the crawl outside that catch,
+ *    so one unreadable markdown file anywhere under the root aborted the WHOLE audit with
+ *    `status: error` and exit code 2 instead of degrading three link walks. The extractor
+ *    memoizes the provider and caches even a rejection, so the failed crawl is still
+ *    attempted once, not once per skill.
+ * 2. **Only a project root.** Reuse is gated on exact `registry.baseDir === projectRoot`
+ *    equality against the root `walkLinkedFiles` derives per skill
+ *    (`findProjectRoot(dirname(skillMd)) ?? dirname(skillMd)`). With no project root that
+ *    per-skill fallback is each skill's OWN directory, so a registry rooted at the plugin
+ *    matches nothing: it would be crawled, compared, discarded, and re-crawled per skill.
+ *    No root, no provider.
  */
 async function pluginInventoryAt(dir) {
-    const root = findProjectRoot(dir) ?? dir;
-    return extractClaudePluginInventory(dir, await getOrCreateInventoryRegistry(root));
+    const projectRoot = findProjectRoot(dir);
+    return extractClaudePluginInventory(dir, projectRoot === null ? undefined : () => getOrCreateInventoryRegistry(projectRoot));
 }
 /**
  * Reset all module-level audit caches. Must be called at the start of every
@@ -1303,18 +1394,19 @@ async function getOrCreateGitTracker(gitRoot) {
  * `dist/`), returns `{ gitRoot: null, gitTracker: null }` to disable gitignore
  * filtering — the user's explicit intent takes precedence over .gitignore.
  */
-async function resolveScanContext(dirPath, locationRoot) {
+async function resolveScanContext(dirPath, locationRoot, logger) {
+    const projectExcludes = resolveProjectExcludes(dirPath, logger);
     const detectedRoot = gitFindRoot(dirPath);
     if (detectedRoot === null) {
-        return { gitRoot: null, gitTracker: null, locationRoot };
+        return { gitRoot: null, gitTracker: null, locationRoot, projectExcludes };
     }
     const tracker = await getOrCreateGitTracker(detectedRoot);
     // If the scan root itself is gitignored (e.g. user targeted `dist/`), disable
     // gitignore filtering so the user's explicit intent wins.
     if (tracker.isIgnoredByActiveSet(dirPath)) {
-        return { gitRoot: null, gitTracker: null, locationRoot };
+        return { gitRoot: null, gitTracker: null, locationRoot, projectExcludes };
     }
-    return { gitRoot: detectedRoot, gitTracker: tracker, locationRoot };
+    return { gitRoot: detectedRoot, gitTracker: tracker, locationRoot, projectExcludes };
 }
 /**
  * Build the gitignore exclusion map for a set of entry paths.
@@ -1335,7 +1427,7 @@ function buildGitIgnoreMap(entryPaths, gitTracker, includeArtifacts) {
  * Check whether a directory entry should be skipped during scanning.
  * Returns a reason string for debug logging, or null if the entry should be kept.
  */
-function getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch) {
+function getSkipReason(entry, fullPath, gitIgnoredMap, excludeMatchers) {
     // Always skip .git directory (not reported by git check-ignore)
     if (entry.isDirectory() && entry.name === '.git') {
         return '.git';
@@ -1344,11 +1436,11 @@ function getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch)
     if (gitIgnoredMap !== null && gitIgnoredMap.get(fullPath) === true) {
         return `gitignored: ${entry.name}`;
     }
-    // Check user-supplied --exclude patterns
-    if (isMatch !== null) {
-        const relativePath = safePath.relative(resolvedBaseDir, fullPath).replaceAll('\\', '/');
-        if (isExcludedPath(isMatch, relativePath, entry.isDirectory())) {
-            return `excluded: ${relativePath}`;
+    // Each matcher answers against ITS OWN base — see {@link ExcludeMatcher}.
+    for (const matcher of excludeMatchers) {
+        const relativePath = safePath.relative(matcher.base, fullPath).replaceAll('\\', '/');
+        if (isExcludedPath(matcher.isMatch, relativePath, entry.isDirectory())) {
+            return `${matcher.label}: ${relativePath}`;
         }
     }
     return null;
@@ -1381,14 +1473,26 @@ async function scanDirectory(dirPath, recursive, options, logger, scanCtx, baseD
     // Compile picomatch for user-supplied --exclude patterns.
     // dot:true so excludes like `**/private/*` match through dotfile dirs
     // (`.claude/.../private/x`); without it the exclude silently never fires.
-    const isMatch = userExcludes.length > 0 ? picomatch(userExcludes, { dot: true }) : null;
+    // These are relative to the scan base; the config's excludes carry their own
+    // (project-root) base on the matcher — see {@link ExcludeMatcher}.
+    const excludeMatchers = [];
+    if (userExcludes.length > 0) {
+        excludeMatchers.push({
+            isMatch: picomatch(userExcludes, { dot: true }),
+            base: resolvedBaseDir,
+            label: 'excluded',
+        });
+    }
+    if (resolvedScanCtx.projectExcludes !== null) {
+        excludeMatchers.push(resolvedScanCtx.projectExcludes);
+    }
     const entries = await fs.readdir(dirPath, { withFileTypes: true });
     // Build full paths and batch-check gitignore status
     const entryPaths = entries.map(e => safePath.join(dirPath, e.name));
     const gitIgnoredMap = buildGitIgnoreMap(entryPaths, resolvedScanCtx.gitTracker, options.includeArtifacts ?? false);
     for (const entry of entries) {
         const fullPath = safePath.join(dirPath, entry.name);
-        const skipReason = getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch);
+        const skipReason = getSkipReason(entry, fullPath, gitIgnoredMap, excludeMatchers);
         if (skipReason !== null) {
             logger.debug(`Excluding path: ${skipReason}`);
             continue;
@@ -1441,17 +1545,45 @@ function countFilesByStatus(results) {
     };
 }
 /**
- * Build base summary structure (used by both flat and hierarchical)
+ * Build base summary structure (used by both flat and hierarchical), together
+ * with the entries the document will publish.
  *
  * `issueCounts` is named exactly as it is on every individual file entry, and
  * means the same thing at both levels: findings, by severity. `summary` only ever
  * counts files.
+ *
+ * The header total and every per-file total come from ONE traversal of the
+ * final issue set, and the entries carrying those per-file totals are returned
+ * from the same pass. Before that, the header was derived from the issue
+ * records while each file's `issueCounts` was whatever its producer had
+ * published — and a producer that appends findings after publishing (or never
+ * sets the counts at all: `validatePlugin` writes `status` and `summary` but
+ * not `issueCounts`) left the two disagreeing inside one document. A real
+ * `vat audit --user` run said 55/422/504 in the header over per-file counts
+ * summing to 55/360/405, with 91 of 614 entries declaring `{0,0,0}` above the
+ * findings they listed. Re-deriving here means the header and the sum are the
+ * same arithmetic on the same array, so they cannot drift again no matter what
+ * a producer forgets.
+ *
+ * `linkedFiles[].issues` are deliberately NOT added: every linked finding is
+ * also present in its owner's `issues`, so the nested list is a VIEW of records
+ * already counted, not extra records. `audit-report-coherence.integration.test.ts`
+ * pins that subset relation, because counting once is only correct while it holds.
  */
 function buildBaseSummary(results, startTime) {
+    const issueCounts = { errors: 0, warnings: 0, info: 0 };
+    const entries = results.map((result) => {
+        const counts = countBySeverity(result.issues);
+        issueCounts.errors += counts.errors;
+        issueCounts.warnings += counts.warnings;
+        issueCounts.info += counts.info;
+        return { ...result, issueCounts: counts };
+    });
     return {
-        status: calculateOverallStatus(results),
-        summary: countFilesByStatus(results),
-        issueCounts: countBySeverity(results.flatMap((r) => r.issues)),
+        entries,
+        status: calculateOverallStatus(entries),
+        summary: countFilesByStatus(entries),
+        issueCounts,
         duration: `${Date.now() - startTime}ms`,
     };
 }
@@ -1459,8 +1591,8 @@ function buildBaseSummary(results, startTime) {
  * Calculate summary for hierarchical output
  */
 function calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose, root) {
-    const base = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(results, compatMap);
+    const { entries, ...base } = buildBaseSummary(results, startTime);
+    const withCompat = applyCompatMap(entries, compatMap);
     return {
         root,
         ...base,
@@ -1471,7 +1603,7 @@ function calculateHierarchicalSummary(results, hierarchical, startTime, compatMa
             standalonePlugins: hierarchical.standalonePlugins.length,
             standaloneSkills: hierarchical.standaloneSkills.length,
         },
-        files: relativizeFileEntries(applyVerboseFilter(withCompat, verbose), root),
+        files: relativizePathEntries(applyVerboseFilter(withCompat, verbose), root, NESTED_PATH_CARRIERS),
         hierarchical,
     };
 }