dsh-standards 1.2.2 → 1.4.0

package/40-checker/src/manifest.mjs

@@ -28,6 +28,28 @@ function inside(root, target) {
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
 }
 
+/**
+ * Every local file target declared by `exports` (including conditional
+ * objects), labelled with the subpath that declares it. Wildcard patterns and
+ * non-relative targets cannot be checked statically and are skipped.
+ */
+function exportTargets(exportsValue) {
+  const targets = []
+  const visit = (node, label) => {
+    if (typeof node === 'string') { targets.push({ label, target: node }); return }
+    if (Array.isArray(node)) { for (const item of node) visit(item, label); return }
+    if (isObject(node)) { for (const item of Object.values(node)) visit(item, label) }
+  }
+  if (typeof exportsValue === 'string') {
+    visit(exportsValue, 'exports["."]')
+  } else if (isObject(exportsValue)) {
+    for (const [subpath, node] of Object.entries(exportsValue)) {
+      visit(node, subpath === '.' ? 'exports["."]' : `exports["${subpath}"]`)
+    }
+  }
+  return targets
+}
+
 export function resolveEntry(dir, manifest) {
   const candidates = []
   const exportTarget = rootExportTarget(manifest)
@@ -85,9 +107,10 @@ function checkExportShape(entry, kind) {
 
 function analyzePatch(dir, manifest) {
   const raw = manifest?.dsh?.bundle?.patch
-  if (raw === undefined) return { present: false, files: [], problems: [], enabledPluginManagerTools: false }
+  if (raw === undefined) return { present: false, files: [], problems: [], rows: [], enabledPluginManagerTools: false }
   const files = []
   const problems = []
+  const rows = []
   let enabledPluginManagerTools = false
   for (const entry of asArray(raw)) {
     if (typeof entry !== 'string' || entry.trim() === '') {
@@ -111,21 +134,27 @@ function analyzePatch(dir, manifest) {
     let text = ''
     try { text = readText(absolute) } catch { problems.push(`patch file is unreadable: ${entry}`); continue }
     const lines = text.split('\n')
+    let lastId = null
     for (let index = 0; index < lines.length; index += 1) {
       const line = lines[index]
+      const idMatch = /^\s*-?\s*id:\s*['"]?([^'"\s#]+)['"]?/.exec(line)
+      if (idMatch) lastId = idMatch[1]
       const match = /^\s*name:\s*['"]?([^'"\s#]+)['"]?/.exec(line)
       if (!match) continue
       const name = match[1]
       if (path.isAbsolute(name) || name.startsWith('~') || name.includes('$') || name.split(/[\\/]/).includes('..')) {
         problems.push(`patch row name escapes the package: ${name}`)
       }
+      const window = lines.slice(Math.max(0, index - 3), index + 6).join('\n')
+      const disabledLine = /disabled:\s*([^\n#]+)/.exec(window)
+      const disabled = disabledLine !== null && /^true\b/.test(disabledLine[1].trim())
+      rows.push({ name, id: lastId, disabled, conditional: disabledLine !== null && !disabled })
       if (name === '@deepseek-ai/dsh-plugin-manager/tools') {
-        const window = lines.slice(index, index + 4).join('\n')
         if (!/disabled:\s*true/.test(window)) enabledPluginManagerTools = true
       }
     }
   }
-  return { present: true, files, problems, enabledPluginManagerTools }
+  return { present: true, files, problems, rows, enabledPluginManagerTools }
 }
 
 function supplyChain(dir, manifest) {
@@ -180,7 +209,7 @@ export function runManifestChecks(dir, options = {}) {
   const kindInfo = inferKind(manifest, entry.exists)
   const kind = kindInfo.kind
   const patch = analyzePatch(dir, manifest)
-  const g4 = checkClientShape(manifest)
+  const g4 = checkClientShape(manifest, dir)
 
   const manifestDetails = []
   const name = manifest.name
@@ -196,10 +225,13 @@ export function runManifestChecks(dir, options = {}) {
   }
   if (entry.escape) {
     manifestDetails.push(detail('C-1.2', 'FAIL', `entry escapes the package: ${entry.target}`, ['package.json#exports']))
-  } else if (entry.declaredMissing && entry.buildHint) {
-    manifestDetails.push(detail('C-1.2', 'WARN', `exports["."] target missing; build hint exists (${entry.sourceEntry ?? 'build script'})`, ['package.json#exports']))
   } else if (entry.declaredMissing) {
-    manifestDetails.push(detail('C-1.2', 'FAIL', `exports["."] points to a missing file: ${entry.target}`, ['package.json#exports']))
+    // A declared entry that is absent is a packaging defect. A build hint only
+    // explains it; it does not make the package loadable from the tarball.
+    const hint = entry.buildHint
+      ? ` (build hint: ${entry.sourceEntry ?? 'build script'}; publish the built file)`
+      : ''
+    manifestDetails.push(detail('C-1.2', 'FAIL', `exports["."] points to a missing file: ${entry.target}${hint}`, ['package.json#exports']))
   } else if (entry.exists) {
     manifestDetails.push(detail('C-1.2', 'PASS', `entry resolves via ${entry.source}: ${entry.relative}`, [entry.relative]))
   } else if (entry.buildHint) {
@@ -216,6 +248,37 @@ export function runManifestChecks(dir, options = {}) {
   } else {
     manifestDetails.push(detail('C-1.2', 'FAIL', 'no resolvable runtime entry', ['package.json#exports', 'package.json#main']))
   }
+
+  // Declared `exports` subpaths and `main` must point at files that ship with
+  // the package. This is a pure file-existence check: it works for bundles
+  // (which may have no root entry) and for client subpaths that the host
+  // resolves through the package root.
+  const checkedTargets = new Map()
+  const missingTargetDetails = []
+  const noteTarget = (label, target, source, { allowBare = false } = {}) => {
+    if (typeof target !== 'string' || target.trim() === '') return
+    if (!allowBare && !target.startsWith('./')) return
+    if (target.includes('*')) return
+    const key = `${label}|${target}`
+    if (checkedTargets.has(key)) return
+    checkedTargets.set(key, true)
+    const absolute = path.resolve(dir, target)
+    if (!inside(dir, absolute)) {
+      missingTargetDetails.push(detail('C-1.2', 'FAIL', `${label} target escapes the package: ${target}`, [source]))
+      return
+    }
+    if (!isFile(absolute)) {
+      missingTargetDetails.push(detail('C-1.2', 'FAIL', `${label} points to a missing file: ${target}`, [source]))
+    }
+  }
+  for (const item of exportTargets(manifest.exports)) {
+    if (item.label === 'exports["."]') continue // resolveEntry() already judged the root export
+    noteTarget(item.label, item.target, 'package.json#exports')
+  }
+  if (typeof manifest.main === 'string' && manifest.main.trim() !== '') {
+    noteTarget('main', manifest.main, 'package.json#main', { allowBare: true })
+  }
+  manifestDetails.push(...missingTargetDetails.slice(0, 8))
   const shape = checkExportShape(entry, kind)
   manifestDetails.push(detail('C-1.3', shape.result, shape.reason, shape.evidence))
   if (!patch.present) {
@@ -255,7 +318,7 @@ export function runManifestChecks(dir, options = {}) {
     } else if (!validRange(dshEngine)) {
       compatDetails.push(detail('C-2.1', 'FAIL', `engines.dsh is not a SemVer range: ${dshEngine}`, ['package.json#engines.dsh']))
     } else if (!satisfies(runtimeVersion, dshEngine)) {
-      compatDetails.push(detail('C-2.2', 'FAIL', `engines.dsh ${dshEngine} does not satisfy runtime ${runtimeVersion}`, ['package.json#engines.dsh']))
+      compatDetails.push(detail('C-2.2', 'FAIL', `engines.dsh ${dshEngine} is valid but does not satisfy runtime ${runtimeVersion}`, ['package.json#engines.dsh']))
     } else {
       compatDetails.push(detail('C-2.1', 'PASS', `engines.dsh=${dshEngine}`))
       compatDetails.push(detail('C-2.2', 'PASS', `runtime ${runtimeVersion} satisfies ${dshEngine}`))
@@ -267,23 +330,33 @@ export function runManifestChecks(dir, options = {}) {
       }
     }
   } else if (dshPeers.length > 0) {
-    let failed = false
+    let invalid = false
+    let unsatisfied = false
     for (const [peer, rangeValue] of dshPeers) {
       if (typeof rangeValue !== 'string') {
         compatDetails.push(detail('C-2.1', 'FAIL', `peer ${peer} must be a string range`, [`package.json#peerDependencies.${peer}`]))
-        failed = true
+        invalid = true
         continue
       }
       const effective = /^workspace:(?:\^|~|\*)$/.test(rangeValue) ? runtimeVersion : rangeValue
       if (!validRange(effective)) {
         compatDetails.push(detail('C-2.1', 'FAIL', `peer ${peer} is not a SemVer range: ${rangeValue}`, [`package.json#peerDependencies.${peer}`]))
-        failed = true
+        invalid = true
       } else if (!satisfies(runtimeVersion, effective)) {
-        compatDetails.push(detail('C-2.2', 'FAIL', `peer ${peer} ${rangeValue} does not satisfy runtime ${runtimeVersion}`, [`package.json#peerDependencies.${peer}`]))
-        failed = true
+        // A syntactically valid range that does not cover this runtime is a
+        // compatibility finding (C-2.2), never an invalid declaration (C-2.1).
+        compatDetails.push(detail('C-2.2', 'FAIL', `peer ${peer} range ${rangeValue} is valid but does not satisfy runtime ${runtimeVersion}`, [`package.json#peerDependencies.${peer}`]))
+        unsatisfied = true
       }
     }
-    compatDetails.push(detail('C-2.1', failed ? 'FAIL' : 'WARN', failed ? 'one or more dsh peers are unsatisfied' : 'no engines.dsh; dsh peer range is the weaker alternate declaration'))
+    if (!invalid) {
+      compatDetails.push(detail('C-2.1', 'PASS', 'dsh peer range(s) are valid SemVer; no engines.dsh declared'))
+    }
+    if (invalid) {
+      compatDetails.push(detail('C-2.1', 'FAIL', 'one or more dsh peer ranges are invalid'))
+    } else if (!unsatisfied) {
+      compatDetails.push(detail('C-2.2', 'PASS', `runtime ${runtimeVersion} satisfies the dsh peer range(s)`))
+    }
   } else {
     compatDetails.push(detail('C-2.1', 'FAIL', 'neither engines.dsh nor a @deepseek-ai/dsh* peer range is declared', ['package.json#engines', 'package.json#peerDependencies']))
   }

package/40-checker/src/remediation.mjs

@@ -1,12 +1,15 @@
 /**
  * Join a dsh-conformance/1 report with the remediation rule table.
  *
- * This module is deliberately pure: it never reads files, never writes, and
- * never changes the report it receives. `buildReport()` calls it at the end so
- * every report carries additive `advice[]` entries; the checker's verdict is
- * untouched.
+ * This module is additive: it never writes, and it never changes the report it
+ * receives. Its one file access is best-effort: it reads the subject's own
+ * `package.json` to turn symbolic `package.json#field` references into a
+ * `package.json:<line>` locator. When the subject, the file, or the field is
+ * absent the reference is left exactly as the check emitted it.
  */
 
+import fs from 'node:fs'
+import path from 'node:path'
 import packageJson from '../../package.json' with { type: 'json' }
 
 /** Release-pinned guide base. `docs` in the rule table is a relative path. */
@@ -15,6 +18,13 @@ export const DOCS_BASE = 'https://github.com/PerryLink/dsh-plugin-guide/blob/v0.
 const LIVE = new Set(['FAIL', 'WARN'])
 const SEVERITY_RANK = { FAIL: 2, WARN: 1 }
 
+/**
+ * Rule pairs that can report the same literal from two different checks. When
+ * their evidence arrays are identical they are one finding: one advice entry
+ * survives (the higher severity, then the first key) and `reason` names both.
+ */
+export const EQUIVALENT_RULES = [['C-11.4', 'C-12.4']]
+
 function tableOf(rules) {
   if (!rules || typeof rules !== 'object') return {}
   // Accept either the whole spec/1 object or a bare key→rule map.
@@ -48,6 +58,94 @@ function uniqueEvidence(...lists) {
   return out.slice(0, 10)
 }
 
+/** Read the subject's package.json once; null when it cannot be located. */
+function packageJsonText(subjectPath) {
+  if (typeof subjectPath !== 'string' || subjectPath === '') return null
+  const candidates = path.extname(subjectPath).toLowerCase() === '.json'
+    ? [subjectPath]
+    : [path.join(subjectPath, 'package.json')]
+  for (const candidate of candidates) {
+    try {
+      if (fs.statSync(candidate).isFile()) return fs.readFileSync(candidate, 'utf8')
+    } catch {
+      // Best effort only: a missing/unreadable file is not an advice error.
+    }
+  }
+  return null
+}
+
+/** 1-based line of `"<leaf>":` in the manifest text, or null. */
+function fieldLine(text, ref) {
+  if (typeof text !== 'string' || !ref.startsWith('package.json#')) return null
+  const leaf = ref.slice('package.json#'.length).split('.').filter(Boolean).pop()
+  if (!leaf) return null
+  const needle = JSON.stringify(leaf)
+  let index = text.indexOf(needle)
+  while (index !== -1) {
+    if (/^\s*:/.test(text.slice(index + needle.length))) {
+      return text.slice(0, index).split('\n').length
+    }
+    index = text.indexOf(needle, index + needle.length)
+  }
+  return null
+}
+
+/**
+ * Prefix each `package.json#field` reference with a concrete
+ * `package.json:<line>` alongside it. Nothing is dropped; unresolvable
+ * references are kept verbatim.
+ */
+function withLineLocators(evidence, text) {
+  if (!text) return evidence
+  const out = []
+  const seen = new Set()
+  for (const value of evidence) {
+    if (typeof value !== 'string' || value === '' || seen.has(value)) continue
+    seen.add(value)
+    out.push(value)
+    const line = fieldLine(text, value)
+    if (line === null) continue
+    const locator = `package.json:${line}`
+    if (!seen.has(locator)) {
+      seen.add(locator)
+      out.push(locator)
+    }
+  }
+  return out.slice(0, 10)
+}
+
+function sameEvidenceSet(left, right) {
+  if (!Array.isArray(left) || !Array.isArray(right)) return false
+  if (left.length === 0 || left.length !== right.length) return false
+  const a = [...left].sort()
+  const b = [...right].sort()
+  return a.every((value, index) => value === b[index])
+}
+
+/**
+ * Collapse the pairs in EQUIVALENT_RULES when both checks reported the same
+ * evidence. The surviving entry keeps its own key/docs/severity; `reason`
+ * records the merged key, and `occurrences` sums both findings.
+ */
+function mergeEquivalentAdvice(advice) {
+  const dropped = new Set()
+  for (const [leftKey, rightKey] of EQUIVALENT_RULES) {
+    const left = advice.find(item => item.key === leftKey && !dropped.has(item))
+    const right = advice.find(item => item.key === rightKey && !dropped.has(item))
+    if (!left || !right || !sameEvidenceSet(left.evidence, right.evidence)) continue
+    const keepLeft = (SEVERITY_RANK[left.gate] ?? 0) >= (SEVERITY_RANK[right.gate] ?? 0)
+    const keep = keepLeft ? left : right
+    const drop = keepLeft ? right : left
+    keep.occurrences += drop.occurrences
+    keep.evidence = uniqueEvidence(keep.evidence, drop.evidence)
+    const aliasReason = drop.reason && drop.reason !== keep.reason ? `: ${drop.reason}` : ''
+    const note = `identical evidence to ${drop.key} (${drop.source})${aliasReason}; merged into ${keep.key}`
+    keep.reason = keep.reason ? `${keep.reason} | ${note}` : note
+    dropped.add(drop)
+  }
+  return advice.filter(item => !dropped.has(item))
+}
+
 /**
  * Build additive advice from a report.
  *
@@ -59,7 +157,8 @@ function uniqueEvidence(...lists) {
  * detail's own reason stays in `reason` for diagnostics.
  *
  * Duplicate details are merged: evidence is unioned, occurrences counted, and
- * the specific reasons are joined for diagnostics.
+ * the specific reasons are joined for diagnostics. Duplicate findings that the
+ * same literal produces from two checks are merged by EQUIVALENT_RULES.
  *
  * @param {object} report dsh-conformance/1 report
  * @param {object} rules flat key→rule map (also accepts a { rules } or { items } wrapper)
@@ -69,6 +168,8 @@ function uniqueEvidence(...lists) {
 export function joinAdvice(report, rules, docsBase = DOCS_BASE) {
   const table = tableOf(rules)
   const version = versionOf(rules)
+  const subjectPath = typeof report?.subject?.path === 'string' ? report.subject.path : null
+  const manifestText = packageJsonText(subjectPath)
   const merged = new Map()
 
   const add = (check, key, gate, reason, evidence) => {
@@ -118,7 +219,7 @@ export function joinAdvice(report, rules, docsBase = DOCS_BASE) {
       docsUrl: docsUrlOf(rule, docsBase),
       source: entry.check.id,
       version,
-      evidence: entry.evidence,
+      evidence: withLineLocators(entry.evidence, manifestText),
       reason: entry.reasons.slice(0, 3).join(' | '),
       occurrences: entry.occurrences,
       advisory: entry.check.advisory === true,
@@ -133,5 +234,5 @@ export function joinAdvice(report, rules, docsBase = DOCS_BASE) {
     || a.key.localeCompare(b.key)
     || a.source.localeCompare(b.source)
   ))
-  return advice
+  return mergeEquivalentAdvice(advice)
 }

package/40-checker/src/report.mjs

@@ -1,6 +1,7 @@
 import path from 'node:path'
 import remediationSpec from '../../spec/remediation.json' with { type: 'json' }
 import { DOCS_BASE, joinAdvice } from './remediation.mjs'
+import { parseVersion } from './semver.mjs'
 
 export const PACKAGE_MANDATORY = [
   'DSC-01', 'DSC-02', 'DSC-04', 'DSC-05', 'DSC-06', 'DSC-07', 'DSC-08', 'DSC-09', 'DSC-11', 'DSC-12', 'DSC-13',
@@ -31,6 +32,74 @@ function adjustEntryCheck(item, entryClaim) {
   return { ...item, result: 'WARN', reason: 'C-2.1 version declaration missing/invalid; entry treats it as WARN (C-2.2/C-2.3 remain blocking)' }
 }
 
+/** Declaration-class checks: a WARN here is hygiene, not a loadability defect. */
+export const DECLARATION_CHECKS = new Set(['DSC-11', 'DSC-12', 'DSC-13'])
+const DETAIL_RANK = { FAIL: 5, ERROR: 4, WARN: 3, PASS: 2, NA: 1 }
+
+function bucketRow(item, extra = {}) {
+  return {
+    id: item.id,
+    clause: item.clause ?? null,
+    result: item.result,
+    coverage: item.coverage ?? null,
+    reason: item.reason ?? '',
+    ...extra,
+  }
+}
+
+/**
+ * Explicit "how to make this check runnable" text for every row that is not
+ * fully checked. NA/ERROR findings must explain themselves; they are not
+ * silently empty.
+ */
+export function howToEnableFor(item) {
+  const id = item?.id
+  const reason = String(item?.reason ?? '')
+  if (id === 'DSC-03') return 'pass --install-spec <spec>, or --market-index <file> --plugin-name <name>'
+  if (['DSC-04', 'DSC-05', 'DSC-06', 'DSC-07', 'DSC-08', 'DSC-09'].includes(id)) {
+    if (item?.coverage === 'partial') return 'omit --no-exec; pass --treat-as-plugin --runtime <path> for L1-L3, and --host <dir> for bundle G0-G3'
+    return 'pass --runtime <path> (plugin L1-L3) or --host <dir> (bundle G0-G3); do not use --no-exec'
+  }
+  if (id === 'DSC-10') {
+    if (/truncated at \d+ files/.test(reason)) return 'raise the source scan budget with --max-files <n> / --max-bytes <n>; the entry may be outside the current scan'
+    if (/entry module/.test(reason)) return 'fix package.json exports/main so the entry is inside the package, or adjust --max-files/--max-bytes'
+    return 'provide a readable entry and sources; re-run with a larger --max-files/--max-bytes if the scan is bounded'
+  }
+  if (id === 'DSC-14') {
+    return 'pass --host <app-boot/lib/index.js> for bundle G0-G3, or --runtime <path> for a plugin; omit --no-exec and --entry-claim static'
+  }
+  if (['DSC-11', 'DSC-12', 'DSC-13'].includes(id)) {
+    if (/manifest unavailable/.test(reason)) return 'fix package.json; these declaration checks cannot run without a manifest'
+    return 'run the full profile without --no-exec; declaration checks need source files'
+  }
+  return 'run the full 14-check profile (see --help) so this check can produce a result'
+}
+
+/**
+ * `entryBlocking` is only sound when every prerequisite was actually evaluated.
+ * C-1.x always produce details; C-3.1/3.2/3.5 only produce them when an install
+ * spec or market index was supplied. Missing details must therefore make
+ * `pass` false instead of silently claiming the gate held.
+ */
+export function summarizeBlocking(checks, blocking) {
+  const seen = new Map()
+  for (const item of checks) {
+    for (const detail of item.details ?? []) {
+      if (!blocking.includes(detail.item)) continue
+      const rank = DETAIL_RANK[detail.result] ?? 0
+      if (!seen.has(detail.item) || rank > (DETAIL_RANK[seen.get(detail.item)] ?? 0)) seen.set(detail.item, detail.result)
+    }
+  }
+  const checked = blocking.filter(id => seen.has(id))
+  // C-2.3 (workspace: range) has no detail when C-2.2 was evaluated against a
+  // normal range; evaluating C-2.2 rules the workspace form out, so count it.
+  if (seen.has('C-2.2') && blocking.includes('C-2.3') && !checked.includes('C-2.3')) checked.push('C-2.3')
+  checked.sort((a, b) => blocking.indexOf(a) - blocking.indexOf(b))
+  const failed = blocking.filter(id => seen.get(id) === 'FAIL')
+  const notChecked = blocking.filter(id => !checked.includes(id))
+  return { required: blocking.length, checked, notChecked, failed, pass: failed.length === 0 && notChecked.length === 0 }
+}
+
 function allowedNa(check, scope, profile, kind) {
   if (check.result !== 'NA') return false
   if (check.id === 'DSC-03' && scope !== 'mvp' && profile === 'package') return true
@@ -39,7 +108,7 @@ function allowedNa(check, scope, profile, kind) {
   return false
 }
 
-export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true }) {
+export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true, declarations = null }) {
   const mandatory = mandatoryFor(scope, profile, staticOnly, entryClaim)
   const adjustedChecks = scope === 'entry' ? checks.map(item => adjustEntryCheck(item, entryClaim)) : checks
   const runtimeIds = new Set(['DSC-04', 'DSC-05', 'DSC-06', 'DSC-07', 'DSC-08', 'DSC-09'])
@@ -59,6 +128,17 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   const warnings = selected.filter(item => item.result === 'WARN')
   const pass = selected.filter(item => item.result === 'PASS')
 
+  // Coverage counts every check the report carries (14 in a full run), not just
+  // the mandatory subset. A report that only counts its mandatory five hides
+  // the runtime checks it never ran; that is the bug this block fixes.
+  const evaluatedAll = effectiveChecks.filter(item => ['PASS', 'WARN', 'FAIL'].includes(item.result))
+  const naAll = effectiveChecks.filter(item => item.result === 'NA')
+  const errorAll = effectiveChecks.filter(item => item.result === 'ERROR')
+  const notRunAll = effectiveChecks.filter(item => item.result !== 'NA' && (item.coverage === 'not-run' || item.coverage === 'partial'))
+  const notRunAllIds = [...new Set([...notRunAll.map(item => item.id), ...errorAll.map(item => item.id), ...missing])]
+  const entryBlockingIds = scope === 'entry' ? (entryClaim === 'static' ? ENTRY_BLOCKING : ENTRY_RUNTIME_BLOCKING) : null
+  const entryBlocking = entryBlockingIds ? summarizeBlocking(effectiveChecks, entryBlockingIds) : null
+
   let status
   let exitCode
   if (failed.length > 0) { status = 'fail'; exitCode = 1 }
@@ -81,12 +161,58 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
     level = staticOnly ? `DS-C static${status === 'warn' ? ' (warnings)' : ''}` : profile === 'listing' || profile === 'both' ? `DS-C (listing${suffix})` : `DS-C (package${suffix})`
   }
 
+  const partialIds = selected.filter(item => item.coverage === 'partial').map(item => item.id)
+  const fullyNotRun = notRunIds.filter(id => !partialIds.includes(id))
   const reasonParts = []
   if (failed.length > 0) reasonParts.push(`FAIL: ${failed.map(item => item.id).join(', ')}`)
-  if (notRunIds.length > 0) reasonParts.push(`not run: ${notRunIds.join(', ')}`)
+  if (fullyNotRun.length > 0) reasonParts.push(`not run: ${fullyNotRun.join(', ')}`)
+  if (partialIds.length > 0) reasonParts.push(`partial: ${partialIds.join(', ')}`)
   if (warnings.length > 0) reasonParts.push(`WARN: ${warnings.map(item => item.id).join(', ')}`)
   if (advisoryWarnings.length > 0) reasonParts.push(`advisory: ${advisoryWarnings.map(item => item.id).join(', ')}`)
 
+  // Findings by reader-relevant bucket. A check appears in exactly one bucket:
+  // FAIL -> blocking, WARN -> hygiene, NA/ERROR/not-run -> notChecked.
+  const blockingBucket = effectiveChecks.filter(item => item.result === 'FAIL').map(item => bucketRow(item))
+  const hygieneBucket = effectiveChecks.filter(item => item.result === 'WARN').map(item => bucketRow(item, {
+    declaration: DECLARATION_CHECKS.has(item.id),
+    advisory: item.advisory === true,
+  }))
+  const notCheckedBucket = effectiveChecks
+    .filter(item => item.result === 'NA' || item.result === 'ERROR')
+    .map(item => bucketRow(item, { howToEnable: howToEnableFor(item) }))
+  for (const id of missing) {
+    notCheckedBucket.push({ id, clause: null, result: 'NOT-RUN', coverage: 'not-run', reason: 'mandatory check missing', howToEnable: howToEnableFor({ id, reason: 'mandatory check missing' }) })
+  }
+  // A coverage view, not a verdict view: a partial check may also be blocking
+  // or hygiene. It is listed here so "what was only statically covered" is
+  // machine-readable instead of disappearing into a NA count. NA/ERROR rows
+  // already live in notChecked; do not duplicate them.
+  const partialBucket = effectiveChecks
+    .filter(item => item.coverage === 'partial' && item.result !== 'NA' && item.result !== 'ERROR')
+    .map(item => bucketRow(item, { howToEnable: howToEnableFor(item) }))
+  const partialCount = effectiveChecks.filter(item => item.coverage === 'partial').length
+  const buckets = { blocking: blockingBucket, hygiene: hygieneBucket, partial: partialBucket, notChecked: notCheckedBucket }
+  const notChecked = [...notCheckedBucket, ...partialBucket]
+    .map(row => ({
+      id: row.id,
+      clause: row.clause,
+      result: row.result,
+      coverage: row.coverage,
+      reason: row.reason || 'not checked',
+      howToEnable: row.howToEnable ?? howToEnableFor(row),
+    }))
+    .filter((row, index, list) => list.findIndex(item => item.id === row.id) === index)
+  const declaredFields = Array.isArray(declarations?.present) ? declarations.present.length : 0
+  const canMarkSuspect = anchor?.suspect === true
+
+  const metrics = {
+    checked: evaluatedAll.length,
+    total: effectiveChecks.length,
+    declaredFields,
+  }
+  const prereq = entryBlocking ? ` (prereq ${entryBlocking.checked.length}/${entryBlocking.required})` : ''
+  const headline = `${scope}/${profile} · runtime ${anchor?.dsh ?? 'unknown'}${anchor?.runtimeSource ? ` ${anchor.runtimeSource}` : ''}${canMarkSuspect ? ' SUSPECT' : ''} · blocking ${buckets.blocking.length}${prereq} · hygiene ${buckets.hygiene.length} · partial ${partialCount} · not checked ${buckets.notChecked.length}/${effectiveChecks.length}`
+
   const report = {
     schema: 'dsh-conformance/1',
     standard: { id: 'DS-C', version: '1.0.0' },
@@ -95,21 +221,24 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
     g4,
     checks: effectiveChecks,
     coverage: {
+      total: effectiveChecks.length,
       mandatory: mandatory.length,
-      pass: pass.length,
-      warn: warnings.length,
+      checked: evaluatedAll.length,
+      pass: evaluatedAll.filter(item => item.result === 'PASS').length,
+      warn: evaluatedAll.filter(item => item.result === 'WARN').length,
       advisory: advisoryWarnings.length,
-      fail: failed.length,
-      na: selected.filter(item => item.result === 'NA').length,
-      notRun: notRunIds.length,
-      error: errored.length,
-      entryBlocking: scope === 'entry' ? (() => {
-        const blocking = entryClaim === 'static' ? ENTRY_BLOCKING : ENTRY_RUNTIME_BLOCKING
-        const failedItems = effectiveChecks.flatMap(item => (item.details ?? []).filter(detail => detail.result === 'FAIL' && blocking.includes(detail.item)).map(detail => detail.item))
-        return { required: blocking.length, failed: failedItems, pass: failedItems.length === 0 }
-      })() : null,
+      fail: evaluatedAll.filter(item => item.result === 'FAIL').length,
+      na: naAll.length,
+      notRun: notRunAllIds.length,
+      partial: partialCount,
+      error: errorAll.length,
+      entryBlocking,
     },
+    buckets,
+    notChecked,
+    metrics,
     conclusion: {
+      headline,
       level,
       status,
       exitCode,
@@ -125,32 +254,80 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   // Additive only: `advice` is a sibling of `checks`, never part of a check,
   // and the verdict is computed above without reading it.
   if (advice !== false) {
-    report.advice = joinAdvice(report, remediationSpec, DOCS_BASE)
+    report.advice = retargetCompatibilityAdvice(joinAdvice(report, remediationSpec, DOCS_BASE), anchor)
   }
   return report
 }
 
+/**
+ * C-2.2 advice is a compatibility finding: the declared range is valid but does
+ * not cover the runtime the report was run against. The static spec example
+ * (`>=0.2.2-0`) can itself be outside an older host, so append the exact floor
+ * that would include this anchor. This keeps advice from contradicting the
+ * FAIL it is attached to.
+ */
+function retargetCompatibilityAdvice(advice, anchor) {
+  const version = parseVersion(anchor?.dsh)
+  if (!version) return advice
+  const floor = `${version.major}.${version.minor}.${version.patch}-0`
+  const upper = `${version.major}.${version.minor + 1}.0`
+  const hint = `当前锚是 ${anchor.dsh}：要兼容它，engines.dsh/peer 下限不得高于 ${floor}（例如 >=${floor} <${upper}），并用 --runtime-version ${anchor.dsh} 复跑。`
+  for (const item of advice) {
+    if (item.key !== 'C-2.2') continue
+    item.fix = item.fix ? `${item.fix} ${hint}` : hint
+    item.reason = item.reason ? `${item.reason} | ${hint}` : hint
+  }
+  return advice
+}
+
 const ICON = { PASS: 'PASS', WARN: 'WARN', FAIL: 'FAIL', NA: 'NA  ', ERROR: 'ERR ' }
 
+function renderBucket(lines, title, rows, byId) {
+  lines.push(`${title} (${rows.length}):`)
+  if (rows.length === 0) {
+    lines.push('  none')
+    return
+  }
+  for (const row of rows) {
+    const tags = [row.declaration ? 'declaration' : null, row.advisory ? 'advisory' : null].filter(Boolean)
+    const reason = String(row.reason ?? '').replace(/\s+/g, ' ').slice(0, 150)
+    lines.push(`  ${(ICON[row.result] ?? row.result).padEnd(4)} ${String(row.id).padEnd(7)} ${String(row.clause ?? '-').padEnd(6)} ${String(row.coverage ?? '-').padEnd(8)} ${reason}${tags.length > 0 ? ` [${tags.join(',')}]` : ''}`)
+    if (row.howToEnable) lines.push(`          enable: ${String(row.howToEnable).replace(/\s+/g, ' ').slice(0, 180)}`)
+    const item = byId.get(row.id)
+    if (!item || (row.result !== 'FAIL' && row.result !== 'WARN')) continue
+    for (const detail of item.details ?? []) {
+      if (detail.result === 'PASS') continue
+      lines.push(`          - ${detail.item}: ${detail.result} ${String(detail.reason ?? '').replace(/\s+/g, ' ').slice(0, 140)}`)
+    }
+  }
+}
+
 export function formatText(report) {
   const lines = []
-  const { subject, anchor, conclusion, coverage } = report
+  const { subject, anchor = {}, conclusion, coverage } = report
+  const byId = new Map((report.checks ?? []).map(item => [item.id, item]))
   lines.push(`DS-C check — ${subject.name ?? '<unknown>'}@${subject.version ?? '?'} (${subject.kind}${subject.kindInferred ? ', inferred' : ''})`)
-  lines.push(`anchor: repo=${anchor.repo} commit=${anchor.commit.slice(0, 12)} dsh=${anchor.dsh} cordis=${anchor.cordis}`)
+  lines.push(`anchor: repo=${anchor.repo ?? '?'} commit=${String(anchor.commit ?? '').slice(0, 12)} dsh=${anchor.dsh ?? '?'} cordis=${anchor.cordis ?? '?'}${anchor.runtimeSource ? ` source=${anchor.runtimeSource}` : ''}${anchor.suspect ? ' suspect=true' : ''}`)
   lines.push(`scope=${conclusion.scope} profile=${conclusion.profile} status=${conclusion.status} exit=${conclusion.exitCode}${conclusion.subset ? ` subset=${conclusion.subset}` : ''}${conclusion.staticOnly ? ' static-only' : ''}`)
   if (conclusion.level) lines.push(`level: ${conclusion.level}`)
+  if (conclusion.headline) lines.push(`headline: ${conclusion.headline}`)
   lines.push('')
-  lines.push('id      result  clause  layer   reason')
-  for (const item of report.checks) {
-    const reason = (item.reason || '').replace(/\s+/g, ' ').slice(0, 120)
-    lines.push(`${item.id.padEnd(7)} ${ICON[item.result] ?? item.result}  ${item.clause.padEnd(6)} ${item.layer.padEnd(6)} ${reason}`)
-    for (const detail of item.details ?? []) {
-      if (detail.result === 'PASS') continue
-      lines.push(`        - ${detail.item}: ${detail.result} ${String(detail.reason).slice(0, 140)}`)
-    }
-  }
+  renderBucket(lines, 'Blocking (FAIL)', report.buckets?.blocking ?? [], byId)
+  lines.push('')
+  renderBucket(lines, 'Hygiene (WARN)', report.buckets?.hygiene ?? [], byId)
+  lines.push('')
+  renderBucket(lines, 'Partly checked (static subset)', report.buckets?.partial ?? [], byId)
   lines.push('')
-  lines.push(`coverage: mandatory=${coverage.mandatory} pass=${coverage.pass} warn=${coverage.warn} fail=${coverage.fail} na=${coverage.na} notRun=${coverage.notRun}`)
+  renderBucket(lines, 'Not checked (NA / not-run / ERROR)', report.buckets?.notChecked ?? [], byId)
+  lines.push('')
+  const passed = (report.checks ?? []).filter(item => item.result === 'PASS')
+  lines.push(`passed (${passed.length}): ${passed.map(item => item.id).join(', ') || 'none'}`)
+  lines.push(`coverage: total=${coverage.total ?? report.checks.length} checked=${coverage.checked ?? coverage.pass + coverage.warn + coverage.fail} pass=${coverage.pass} warn=${coverage.warn} fail=${coverage.fail} na=${coverage.na} notRun=${coverage.notRun} partial=${coverage.partial ?? 0} error=${coverage.error} advisory=${coverage.advisory}`)
+  if (coverage.entryBlocking) {
+    const blocking = coverage.entryBlocking
+    lines.push(`entryBlocking: checked=${blocking.checked?.length ?? '?'}/${blocking.required} failed=[${(blocking.failed ?? []).join(', ')}] notChecked=[${(blocking.notChecked ?? []).join(', ')}] pass=${blocking.pass}`)
+  }
+  lines.push(`metrics: checked=${report.metrics?.checked ?? '?'}/${report.metrics?.total ?? '?'} declaredFields=${report.metrics?.declaredFields ?? 0}/5`)
   if (conclusion.reason) lines.push(`reason: ${conclusion.reason}`)
   if (conclusion.status === 'incomplete') lines.push('NOT A DS-C PASS: at least one mandatory check did not run (see notRun).')
   if (Array.isArray(report.advice) && report.advice.length > 0) {