dsh-tower 2.1.0-beta.1 → 2.3.0

package/domain/state.js

@@ -1,17 +1,123 @@
-// Pure state-file validation (#56 P4).
+// Pure state-file validation and migration decisions (#56 P4, #72).
 //
-// The structural contract lives in `state/schema.js` (TypeBox) and the policy
-// checks in `state/semantics.js`. This module stays the public entry point so
-// every app/tool import of `domain/state.js` is unchanged.
+// The structural contract lives in `state/schema.js` (TypeBox), the policy
+// checks in `state/semantics.js`, and the version registry in
+// `state/migrations.js`. This module stays the public entry point so every
+// app/tool import of `domain/state.js` is unchanged.
+//
+// `validateState` proves a document matches the *current* schema.
+// `prepareState` is the load-path decision: it inspects the version, applies the
+// ordered migration registry, then validates the target schema. Both are pure;
+// the side effects (backup, write, activity) live in `adapters/stateFile.js`.
 // @ts-check
 import { TowerToolError } from './errors.js'
+import { SCHEMA_VERSION } from './mission.js'
+import { migrationChain, migrateState } from './state/migrations.js'
 import { stateShapeError } from './state/schema.js'
 import { assertStateSemantics } from './state/semantics.js'
 
 /** @typedef {import('../types/index.js').TowerState} TowerState */
+/** @typedef {{ from: number, to: number }} MigrationStep */
+/** @typedef {import('./state/migrations.js').StateMigration} StateMigration */
 
 export { StateSchema, stateShapeError } from './state/schema.js'
 
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Classify a document's `schemaVersion` without throwing. This is the read path
+ * doctor uses, so it must stay usable on a repository that cannot load.
+ * @param {unknown} state
+ * @param {string} [statePath]
+ * @param {readonly StateMigration[]} [migrations] registry to classify against
+ * @returns {{
+ *   status: 'current'|'migratable'|'newer'|'unmigratable'|'invalid',
+ *   currentVersion: number|null,
+ *   supportedVersion: number,
+ *   migrations: MigrationStep[],
+ *   message?: string,
+ * }}
+ */
+export function inspectStateVersion(state, statePath, migrations) {
+  const where = statePath ? ` at ${statePath}` : ''
+  if (!isPlainObject(state)) {
+    return {
+      status: 'invalid',
+      currentVersion: null,
+      supportedVersion: SCHEMA_VERSION,
+      migrations: [],
+      message: `tower state is not an object${where}`,
+    }
+  }
+  const version = /** @type {Record<string, any>} */ (state).schemaVersion
+  if (!Number.isInteger(version) || version < 1) {
+    return {
+      status: 'invalid',
+      currentVersion: null,
+      supportedVersion: SCHEMA_VERSION,
+      migrations: [],
+      message: `tower state has no usable schemaVersion (${JSON.stringify(version)})${where}`,
+    }
+  }
+  if (version === SCHEMA_VERSION) {
+    return { status: 'current', currentVersion: version, supportedVersion: SCHEMA_VERSION, migrations: [] }
+  }
+  if (version > SCHEMA_VERSION) {
+    return { status: 'newer', currentVersion: version, supportedVersion: SCHEMA_VERSION, migrations: [] }
+  }
+  const chain = migrationChain(version, SCHEMA_VERSION, migrations)
+  if (!chain) {
+    return { status: 'unmigratable', currentVersion: version, supportedVersion: SCHEMA_VERSION, migrations: [] }
+  }
+  return {
+    status: 'migratable',
+    currentVersion: version,
+    supportedVersion: SCHEMA_VERSION,
+    migrations: chain.map((step) => ({ from: step.from, to: step.to })),
+  }
+}
+
+/**
+ * @param {{ status: string, currentVersion: number|null, supportedVersion: number, message?: string }} info
+ * @param {string} [statePath]
+ * @returns {TowerToolError}
+ */
+function versionError(info, statePath) {
+  const where = statePath ? ` at ${statePath}` : ''
+  if (info.status === 'newer') {
+    return new TowerToolError(
+      'state-version-unsupported',
+      `tower state${where} has schemaVersion ${info.currentVersion}, but this build supports ${info.supportedVersion}: it was written by a newer dsh-tower and will not be downgraded`,
+      {
+        nextAction: `upgrade dsh-tower to a release that supports state schemaVersion ${info.currentVersion}; the file was left untouched`,
+      },
+    )
+  }
+  if (info.status === 'migratable') {
+    return new TowerToolError(
+      'state-version-unsupported',
+      `tower state${where} has schemaVersion ${info.currentVersion}; load it through the state loader to migrate it to ${info.supportedVersion}`,
+      { nextAction: 'call any tower tool; mutations apply the migration under the state lock' },
+    )
+  }
+  if (info.status === 'unmigratable') {
+    return new TowerToolError(
+      'state-version-unsupported',
+      `tower state${where} has schemaVersion ${info.currentVersion}, which has no migration to ${info.supportedVersion}`,
+      {
+        nextAction: `restore a state.json written by dsh-tower ${info.supportedVersion}; this build will not guess at an unknown schema`,
+      },
+    )
+  }
+  return new TowerToolError('state-corrupt', info.message ?? `tower state is not usable${where}`)
+}
+
 /**
  * @param {string} message
  * @returns {never}
@@ -21,13 +127,57 @@ function fail(message) {
 }
 
 /**
+ * Prove a document matches the current schema. Any other version is rejected
+ * with a version error rather than corruption; the load path migrates first.
  * @param {unknown} state
  * @param {string} [statePath]
  * @returns {TowerState}
  */
 export function validateState(state, statePath) {
+  const info = inspectStateVersion(state, statePath)
+  if (info.status !== 'current') throw versionError(info, statePath)
   const where = statePath ? ` at ${statePath}` : ''
   const shapeError = stateShapeError(state, where)
   if (shapeError) fail(shapeError)
   return assertStateSemantics(state, where)
 }
+
+/**
+ * The pure load-path decision: migrate an older document through the registry,
+ * validate the result against the target schema, then report what happened. The
+ * returned state is the validated migrated document; the caller decides whether
+ * to persist it (only while holding the state lock).
+ *
+ * @param {unknown} state
+ * @param {string} [statePath]
+ * @param {{ migrations?: readonly StateMigration[] }} [options]
+ * @returns {{ state: TowerState, from: number, to: number, migrated: MigrationStep[], changed: boolean }}
+ */
+export function prepareState(state, statePath, options = {}) {
+  const info = inspectStateVersion(state, statePath, options.migrations)
+  if (info.status === 'current') {
+    return {
+      state: validateState(state, statePath),
+      from: SCHEMA_VERSION,
+      to: SCHEMA_VERSION,
+      migrated: [],
+      changed: false,
+    }
+  }
+  if (info.status !== 'migratable') throw versionError(info, statePath)
+  const outcome = migrateState(/** @type {Record<string, any>} */ (state), {
+    statePath,
+    to: info.supportedVersion,
+    migrations: options.migrations,
+  })
+  // Validation runs on the *target* document: a shape that was invalid under
+  // the old schema (a missing `tasks` array, say) may be valid after a backfill,
+  // and validating the target is what proves the migration did its job.
+  return {
+    state: validateState(outcome.state, statePath),
+    from: outcome.from,
+    to: outcome.to,
+    migrated: outcome.steps,
+    changed: true,
+  }
+}

package/domain/summary.js

@@ -1,6 +1,7 @@
 // Pure mission/finding summaries.
 // @ts-check
 import { FINDING_STATUSES } from './mission.js'
+import { completionReportBytes } from './missions/completion.js'
 
 /** @typedef {import('../types/index.js').Finding} Finding */
 /** @typedef {import('../types/index.js').FindingSummary} FindingSummary */
@@ -53,6 +54,7 @@ export function missionSummary(mission) {
     reviewPolicy: mission.reviewPolicy ?? 'required-clean',
     mergedCommit: mission.mergedCommit ?? null,
     mergedAt: mission.mergedAt ?? null,
+    reportBytes: completionReportBytes(mission.completionReport),
     updatedAt: mission.updatedAt,
   }
 }

package/domain/surface.js

@@ -0,0 +1,248 @@
+// Concept budget: surface metrics, the committed baseline and its classifications (#84).
+//
+// The repository does not measure "how many concepts a user has to hold" by
+// counting lines. It measures the surface — config leaf keys, config sections and
+// registered tools — and keeps a committed baseline. Growth is refused by
+// default: a baseline decision that raises a count must name either an ADR (why
+// the surface has to grow) or deletions that are provably gone from the live
+// surface (the added concept replaced a removed one).
+//
+// This module is pure: no fs, no git. `scripts/surface-baseline.mjs` supplies
+// the live counts and the file reads; `scripts/lib/surface.mjs` wraps them.
+export const SURFACE_BASELINE_FILE = 'scripts/surface-baseline.json'
+export const SURFACE_CLASSIFICATION_FILE = 'docs/reference/surface-budget.md'
+export const SURFACE_KEYS = ['configKeys', 'sections', 'tools']
+export const CONFIG_CLASSES = ['core', 'tuning', 'niche']
+export const TOOL_CLASSES = ['core', 'optional']
+export const SURFACE_SCHEMA_VERSION = 1
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * The human-readable count line shared by `tower_doctor` and the generated
+ * references: `config keys: N · sections: N · tools: N`.
+ * @param {{ configKeys?: number, sections?: number, tools?: number }} counts
+ */
+export function surfaceLine(counts = {}) {
+  const value = (key) => (Number.isInteger(counts[key]) ? String(counts[key]) : '?')
+  return `config keys: ${value('configKeys')} · sections: ${value('sections')} · tools: ${value('tools')}`
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function surfaceError(message) {
+  return new Error(message)
+}
+
+/**
+ * Parse and validate `scripts/surface-baseline.json`. Throws with an actionable
+ * message when the file is malformed; returns a normalized copy otherwise.
+ * @param {string | object} source
+ */
+export function parseBaseline(source) {
+  let value
+  if (typeof source === 'string') {
+    try {
+      value = JSON.parse(source)
+    } catch (error) {
+      throw surfaceError(`surface baseline is not valid JSON: ${error?.message ?? error}`)
+    }
+  } else {
+    value = source
+  }
+  if (!isPlainObject(value)) throw surfaceError('surface baseline must be a JSON object')
+  if (value.schema !== undefined && value.schema !== SURFACE_SCHEMA_VERSION) {
+    throw surfaceError(`surface baseline schema ${value.schema} is not supported (expected ${SURFACE_SCHEMA_VERSION})`)
+  }
+  if (typeof value.date !== 'string' || !ISO_DATE.test(value.date)) {
+    throw surfaceError(`surface baseline needs a date (YYYY-MM-DD), got ${JSON.stringify(value.date)}`)
+  }
+  if (!isPlainObject(value.surfaces)) throw surfaceError('surface baseline needs a "surfaces" object')
+  const surfaces = {}
+  for (const key of SURFACE_KEYS) {
+    const entry = value.surfaces[key]
+    if (!isPlainObject(entry)) throw surfaceError(`surface baseline misses the "${key}" entry`)
+    if (!Number.isInteger(entry.seed) || entry.seed < 0) {
+      throw surfaceError(`surface baseline ${key}.seed must be a non-negative integer`)
+    }
+    if (!Number.isInteger(entry.value) || entry.value < 0) {
+      throw surfaceError(`surface baseline ${key}.value must be a non-negative integer`)
+    }
+    if (!Array.isArray(entry.decisions)) throw surfaceError(`surface baseline ${key}.decisions must be an array`)
+    surfaces[key] = {
+      seed: entry.seed,
+      value: entry.value,
+      decisions: entry.decisions.map((decision, index) => {
+        if (!isPlainObject(decision)) {
+          throw surfaceError(`surface baseline ${key}.decisions[${index}] must be an object`)
+        }
+        if (!Number.isInteger(decision.from) || decision.from < 0) {
+          throw surfaceError(`surface baseline ${key}.decisions[${index}].from must be a non-negative integer`)
+        }
+        if (!Number.isInteger(decision.to) || decision.to < 0) {
+          throw surfaceError(`surface baseline ${key}.decisions[${index}].to must be a non-negative integer`)
+        }
+        return { ...decision }
+      }),
+    }
+  }
+  return { schema: SURFACE_SCHEMA_VERSION, date: value.date, surfaces }
+}
+
+/**
+ * The rows of the classification table, already parsed. `kind` is `config` or
+ * `tools`, `name` is the key/tool name, `className` is the declared class.
+ * @param {string} markdown
+ */
+export function parseClassification(markdown) {
+  const text = String(markdown ?? '')
+  const dateMatch = /^\s*(?:[-*]\s*)?Decision date:\s*(\d{4}-\d{2}-\d{2})\s*$/im.exec(text)
+  const entries = []
+  let kind = null
+  for (const rawLine of text.split(/\r?\n/)) {
+    const heading = /^#{1,6}\s+(.+?)\s*$/.exec(rawLine)
+    if (heading) {
+      const title = heading[1].toLowerCase()
+      kind = title.includes('config') ? 'config' : title.includes('tool') ? 'tools' : null
+      continue
+    }
+    if (!kind) continue
+    const match = /^\|\s*`([^`]+)`\s*\|\s*([a-z-]+)\s*\|\s*(.*?)\s*\|\s*$/.exec(rawLine)
+    if (!match) continue
+    entries.push({ kind, name: match[1].trim(), className: match[2].trim().toLowerCase(), note: match[3].trim() })
+  }
+  return { date: dateMatch ? dateMatch[1] : null, entries }
+}
+
+/**
+ * Validate the classification table against the live surface. Every live key and
+ * tool must appear exactly once with a legal class; every `niche` row must carry
+ * a removal note, so "we will remove it later" is a written promise rather than
+ * an implication.
+ * @param {string} markdown
+ * @param {{ configKeys: string[], sections: string[], tools: string[] }} liveNames
+ * @param {{ baselineDate?: string }} [options]
+ * @returns {{ date: string | null, entries: Array<{ kind: string, name: string, className: string, note: string }>, findings: Array<{ code: string, level: string, message: string }> }}
+ */
+export function validateClassification(markdown, liveNames, options = {}) {
+  const parsed = parseClassification(markdown)
+  const findings = []
+  const text = String(markdown ?? '')
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+  if (!parsed.date) {
+    record('classification-date', 'classification table needs a "Decision date: YYYY-MM-DD" line')
+  } else if (options.baselineDate && parsed.date !== options.baselineDate) {
+    record(
+      'classification-date',
+      `classification date ${parsed.date} does not match the baseline date ${options.baselineDate}`,
+    )
+  }
+
+  const checkRows = (kind, expected, legal) => {
+    const rows = parsed.entries.filter((entry) => entry.kind === kind)
+    const seen = new Map()
+    for (const row of rows) {
+      if (seen.has(row.name)) record('classification-duplicate', `${kind === 'config' ? 'config key' : 'tool'} ${row.name} is classified twice`)
+      seen.set(row.name, row)
+      if (!legal.includes(row.className)) {
+        record(
+          'classification-class',
+          `${kind === 'config' ? 'config key' : 'tool'} ${row.name} has class "${row.className}" (expected ${legal.join('/')})`,
+        )
+      }
+    }
+    for (const name of expected) {
+      if (!seen.has(name)) record('classification-missing', `${kind === 'config' ? 'config key' : 'tool'} ${name} is not classified`)
+    }
+    const expectedSet = new Set(expected)
+    for (const name of seen.keys()) {
+      if (!expectedSet.has(name)) record('classification-unknown', `${kind === 'config' ? 'config key' : 'tool'} ${name} is not in the live surface`)
+    }
+    return rows
+  }
+
+  const configRows = checkRows('config', liveNames.configKeys, CONFIG_CLASSES)
+  checkRows('tools', liveNames.tools, TOOL_CLASSES)
+  const nicheRows = configRows.filter((row) => row.className === 'niche')
+  for (const row of nicheRows) {
+    if (!/removal note:/i.test(row.note)) {
+      record('niche-removal-note', `niche config key ${row.name} needs a "Removal note:" in its table row`)
+    }
+  }
+  if (nicheRows.length === 0 && !/no key qualifies as niche/i.test(text)) {
+    record('niche-removal-note', 'no niche config key has a removal note and the table does not say "no key qualifies as niche"')
+  }
+  return { date: parsed.date, entries: parsed.entries, findings }
+}
+
+/**
+ * Validate a committed baseline against the live counts and its own decision
+ * chain. This is the brake: `current[surface] !== entry.value` fails, and every
+ * decision that grows a count must name an existing ADR or deletions that are
+ * provably absent from the live surface.
+ *
+ * @param {ReturnType<typeof parseBaseline>} baseline
+ * @param {{ configKeys: number, sections: number, tools: number, liveNames: { configKeys: string[], sections: string[], tools: string[] } }} current
+ * @param {{ exists?: (relativePath: string) => boolean }} [options]
+ * @returns {Array<{ code: string, level: string, message: string }>}
+ */
+export function validateBaseline(baseline, current, options = {}) {
+  const exists = options.exists ?? (() => false)
+  const findings = []
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+
+  for (const key of SURFACE_KEYS) {
+    const entry = baseline.surfaces[key]
+    const live = current[key]
+    if (!Number.isInteger(live)) {
+      record('surface-missing', `live ${key} count is unavailable`)
+      continue
+    }
+    if (live !== entry.value) {
+      const direction = live > entry.value ? 'grew' : 'shrank'
+      record(
+        'stale-baseline',
+        `${key} ${direction} from the committed baseline ${entry.value} to ${live}; update ${SURFACE_BASELINE_FILE} with an ADR or a deletion record before landing`,
+      )
+    }
+    let running = entry.seed
+    entry.decisions.forEach((decision, index) => {
+      const where = `${key}.decisions[${index}]`
+      if (decision.from !== running) {
+        record('broken-chain', `${where}.from ${decision.from} does not continue from ${running}`)
+      }
+      if (decision.date !== undefined && !ISO_DATE.test(String(decision.date))) {
+        record('broken-chain', `${where}.date is not YYYY-MM-DD`)
+      }
+      const growth = decision.to - decision.from
+      if (growth > 0) {
+        const deletions = Array.isArray(decision.deletions)
+          ? decision.deletions.filter((name) => typeof name === 'string' && name.trim()).map((name) => name.trim())
+          : []
+        const adr = typeof decision.adr === 'string' && decision.adr.trim() ? decision.adr.trim().replace(/\\/g, '/') : null
+        const adrExists = Boolean(adr) && adr.startsWith('docs/adr/') && adr.endsWith('.md') && exists(adr)
+        const liveNames = new Set(current.liveNames?.[key] ?? [])
+        const stillLive = deletions.filter((name) => liveNames.has(name))
+        const deletionEvidence = deletions.length >= growth && stillLive.length === 0
+        if (!adrExists && !deletionEvidence) {
+          const reasons = []
+          if (adr && !adrExists) reasons.push(`ADR ${adr} does not exist under docs/adr/`)
+          if (deletions.length === 0) reasons.push('no deletions recorded')
+          else if (stillLive.length > 0) reasons.push(`deleted name(s) are still in the live surface: ${stillLive.join(', ')}`)
+          else if (deletions.length < growth) reasons.push(`only ${deletions.length} deletion(s) for a growth of ${growth}`)
+          record('growth-without-evidence', `${where} grows ${key} by ${growth} without an ADR or a matching deletion (${reasons.join('; ')})`)
+        }
+      }
+      running = decision.to
+    })
+    if (running !== entry.value && !(entry.decisions.length === 0 && entry.value < running)) {
+      record(
+        'broken-chain',
+        `${key} value ${entry.value} does not match the last decision (${running}); every count change needs a decision record`,
+      )
+    }
+  }
+  return findings
+}