dsh-standards 1.4.1 → 1.5.0

package/40-checker/src/report.mjs

@@ -108,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, declarations = null }) {
+export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true, declarations = null, runtimeChecks = 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'])
@@ -123,7 +123,12 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   const missing = mandatory.filter(id => !byId.has(id))
   const failed = selected.filter(item => item.result === 'FAIL')
   const errored = selected.filter(item => item.result === 'ERROR')
-  const notRun = selected.filter(item => !allowedNa(item, scope, profile, kind) && (item.coverage === 'not-run' || item.coverage === 'partial'))
+  // A static `partial` PASS is still a PASS for the mandatory set: it is
+  // recorded in buckets.partial / coverage.partial, and "what was not run" is
+  // its own signal. Only a check that did not run at all makes the report
+  // incomplete. Otherwise every bundle would be exit 2 forever, because the
+  // static subset can never be full without executing the package.
+  const notRun = selected.filter(item => !allowedNa(item, scope, profile, kind) && item.coverage === 'not-run')
   const notRunIds = [...new Set([...missing, ...errored.map(item => item.id), ...notRun.map(item => item.id)])]
   const warnings = selected.filter(item => item.result === 'WARN')
   const pass = selected.filter(item => item.result === 'PASS')
@@ -134,7 +139,7 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   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 notRunAll = effectiveChecks.filter(item => item.result !== 'NA' && item.coverage === 'not-run')
   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
@@ -251,6 +256,11 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
       reason: reasonParts.join('; '),
     },
   }
+  // Additive only: describes what actually executed (runtime/host), the
+  // elapsed time, and the isolation it used. It is a sibling of `checks` and
+  // never changes the verdict. Kept out of the 1.0.0 schema shape and only
+  // emitted when a runtime/host run was requested.
+  if (runtimeChecks) report.runtimeChecks = runtimeChecks
   // 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) {
@@ -302,6 +312,41 @@ function renderBucket(lines, title, rows, byId) {
   }
 }
 
+/**
+ * Runtime provenance: what actually ran, for how long, and where. A failed
+ * run must say why instead of silently falling back to static rows.
+ */
+function renderRuntime(lines, runtime) {
+  if (!runtime) return
+  if (!runtime.executed) {
+    // Do not repeat six not-run rows that the partial/not-checked buckets
+    // already explain; one line is enough to say nothing executed.
+    lines.push(`Runtime checks (not executed): ${runtime.reason ?? runtime.failure ?? 'no runtime requested'}`)
+    lines.push('')
+    return
+  }
+  const modes = Array.isArray(runtime.modes) && runtime.modes.length > 0 ? runtime.modes.join('+') : 'none'
+  const elapsed = Number.isFinite(runtime.durationMs) ? `${runtime.durationMs} ms` : 'n/a'
+  const isolation = runtime.isolation?.isolatedHome ? 'temporary DSH_HOME' : 'un-isolated'
+  lines.push(`Runtime checks (${modes}, ${elapsed}, ${isolation}):`)
+  if (runtime.failure) lines.push(`  failure: ${String(runtime.failure).replace(/\s+/g, ' ').slice(0, 200)}`)
+  const rows = Array.isArray(runtime.checks) ? runtime.checks : []
+  if (rows.length === 0) {
+    lines.push('  none')
+  } else {
+    for (const row of rows) {
+      const reason = String(row.reason ?? '').replace(/\s+/g, ' ').slice(0, 140)
+      lines.push(`  ${(ICON[row.result] ?? row.result).padEnd(4)} ${String(row.id).padEnd(7)} ${String(row.coverage ?? '-').padEnd(8)} ${reason}`)
+    }
+  }
+  const entry = runtime.entry
+  if (entry) {
+    const reason = String(entry.reason ?? '').replace(/\s+/g, ' ').slice(0, 140)
+    lines.push(`  ${(ICON[entry.result] ?? entry.result).padEnd(4)} ${String(entry.id).padEnd(7)} ${String(entry.coverage ?? '-').padEnd(8)} ${reason}`)
+  }
+  lines.push('')
+}
+
 export function formatText(report) {
   const lines = []
   const { subject, anchor = {}, conclusion, coverage } = report
@@ -318,6 +363,7 @@ export function formatText(report) {
   lines.push('')
   renderBucket(lines, 'Partly checked (static subset)', report.buckets?.partial ?? [], byId)
   lines.push('')
+  renderRuntime(lines, report.runtimeChecks)
   renderBucket(lines, 'Not checked (NA / not-run / ERROR)', report.buckets?.notChecked ?? [], byId)
   lines.push('')
   const passed = (report.checks ?? []).filter(item => item.result === 'PASS')

package/40-checker/src/runtime-child.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Runs L1-L3 in a disposable child process so a plugin cannot block or take over
+// the checker. Input: JSON on stdin. Output: one marker line + JSON on fd 3.
+//
+// The child is *expected to be hostile*: a plugin may leave timers, sockets or
+// workers referenced after `dispose()`. Waiting for the process to exit then
+// looks like a hang even though every check finished, so the result is written
+// first and the process is terminated in the write callback. The parent also
+// resolves on the marker line, so a plugin that keeps the event loop alive
+// cannot turn a completed run into "killed after timeout".
+import fs from 'node:fs'
+import { runRuntimeChecks } from './runtime.mjs'
+import { readSources } from './util.mjs'
+import { scrubProcessEnv } from './sandbox-env.mjs'
+
+export const MARKER = '__DSH_RUNTIME_CHECKS__'
+
+const chunks = []
+for await (const chunk of process.stdin) chunks.push(chunk)
+const input = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+
+// This process imports the inspected package; keep only allowlisted env keys,
+// then apply the caller-supplied disposable HOME/DSH_HOME/TMPDIR. DSH_HOME is
+// deliberately not allowlisted: an inherited real profile must never reach a
+// plugin, while an explicit temp directory from the checker is trusted.
+scrubProcessEnv()
+const overrides = {
+  DSH_HOME: input.home,
+  HOME: input.home,
+  USERPROFILE: input.home,
+  TMPDIR: input.tmp,
+  TEMP: input.tmp,
+  TMP: input.tmp,
+  XDG_CONFIG_HOME: input.home ? `${input.home}/.config` : undefined,
+  XDG_DATA_HOME: input.home ? `${input.home}/.local/share` : undefined,
+  XDG_CACHE_HOME: input.home ? `${input.home}/.cache` : undefined,
+}
+for (const [key, value] of Object.entries(overrides)) {
+  if (typeof value === 'string' && value !== '') process.env[key] = value
+}
+
+const started = process.hrtime.bigint()
+let payload
+try {
+  let sources = []
+  try { sources = readSources(input.dir) } catch { sources = [] }
+  const checks = await runRuntimeChecks({ ...input, sources })
+  payload = { checks, durationMs: Number((process.hrtime.bigint() - started) / 1_000_000n), error: null }
+} catch (error) {
+  payload = {
+    checks: [],
+    durationMs: Number((process.hrtime.bigint() - started) / 1_000_000n),
+    error: String(error?.stack ?? error?.message ?? error).slice(0, 2000),
+  }
+}
+
+const line = `${MARKER}${JSON.stringify(payload)}\n`
+// The plugin shares stdout, so results go to a dedicated pipe (fd 3) that a
+// plugin printing logs cannot interleave with or truncate.
+const writeResult = (callback) => {
+  try { fs.writeSync(3, line) } catch {
+    // A direct `node src/runtime-child.mjs` has no fd 3: fall back to stdout.
+    process.stdout.write(line, callback)
+    return
+  }
+  callback()
+}
+writeResult(() => process.exit(0))

package/40-checker/src/runtime.mjs

@@ -193,7 +193,9 @@ export async function runRuntimeChecks(input) {
   const provideResult = declared.length === 0 ? 'NA' : worst(provideDetails.map(item => item.result))
   const provideCheck = check({
     id: 'DSC-05', clause: 'C-5', layer: 'L1', result: provideResult,
-    reason: provideDetails.filter(item => item.result !== 'PASS' && item.result !== 'NA').map(item => `${item.item}: ${item.reason}`).join(' | '),
+    // NA is a real finding too ("nothing declared"), so keep its reason; an
+    // empty reason here used to make DSC-05 look unexplained in the report.
+    reason: provideDetails.filter(item => item.result !== 'PASS').map(item => `${item.item}: ${item.reason}`).join(' | '),
     details: provideDetails,
   })