dsh-data-quality 0.1.3 → 0.3.0

package/src/config.ts

@@ -7,6 +7,29 @@
 
 import z from '@deepseek-ai/schemastery'
 
+/** Per-dimension scorecard weights (all optional; defaults fill to `1` = equal). */
+export interface ScorecardWeights {
+  completeness?: number
+  uniqueness?: number
+  validity?: number
+  consistency?: number
+  timeliness?: number
+  accuracy?: number
+}
+
+/** The six scorecard dimension ids, in report order (kept in sync with `scorecard.ts`). */
+const SCORECARD_DIMENSIONS = ['completeness', 'uniqueness', 'validity', 'consistency', 'timeliness', 'accuracy'] as const
+
+/** Equal-weight defaults for {@link ScorecardWeights}. */
+const EQUAL_WEIGHTS: Required<ScorecardWeights> = {
+  completeness: 1,
+  uniqueness: 1,
+  validity: 1,
+  consistency: 1,
+  timeliness: 1,
+  accuracy: 1,
+}
+
 /** Raw plugin config — every field optional; {@link resolveConfig} supplies the defaults. */
 export interface Config {
   /** Master switch; `false` mounts nothing. */
@@ -25,6 +48,8 @@ export interface Config {
   workspaceRoot?: string
   /** Persist reports to the `data_quality` storage domain. */
   storeReports?: boolean
+  /** Per-dimension weights for the scorecard's weighted overall total (non-negative). */
+  scorecardWeights?: ScorecardWeights
 }
 
 /** Fully resolved config handed to the runtime. */
@@ -37,6 +62,7 @@ export interface ResolvedConfig {
   readonly allowedExtensions: readonly string[]
   readonly workspaceRoot: string
   readonly storeReports: boolean
+  readonly scorecardWeights: Required<ScorecardWeights>
 }
 
 /** Schemastery schema: the loader validates and fills defaults before `apply`. */
@@ -49,6 +75,16 @@ export const Config: z<Config> = z.object({
   allowedExtensions: z.array(z.string()).default(['.csv', '.tsv', '.json', '.jsonl']),
   workspaceRoot: z.string().default(''),
   storeReports: z.boolean().default(true),
+  scorecardWeights: z
+    .object({
+      completeness: z.number().default(1),
+      uniqueness: z.number().default(1),
+      validity: z.number().default(1),
+      consistency: z.number().default(1),
+      timeliness: z.number().default(1),
+      accuracy: z.number().default(1),
+    })
+    .default(EQUAL_WEIGHTS),
 })
 
 /** Throw unless `value` is a positive safe integer. */
@@ -91,6 +127,8 @@ export function resolveConfig(config: Config = {}): ResolvedConfig {
     throw new TypeError('allowedExtensions must not be empty')
   }
 
+  const scorecardWeights = resolveScorecardWeights(config.scorecardWeights)
+
   return {
     enabled: config.enabled ?? true,
     maxRows,
@@ -100,5 +138,19 @@ export function resolveConfig(config: Config = {}): ResolvedConfig {
     allowedExtensions,
     workspaceRoot: config.workspaceRoot ?? '',
     storeReports: config.storeReports ?? true,
+    scorecardWeights,
+  }
+}
+
+/** Resolve scorecard weights, filling defaults and rejecting non-negative violations loudly. */
+function resolveScorecardWeights(weights: ScorecardWeights = {}): Required<ScorecardWeights> {
+  const out = {} as Required<ScorecardWeights>
+  for (const dimension of SCORECARD_DIMENSIONS) {
+    const value = weights[dimension] ?? 1
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+      throw new TypeError(`scorecardWeights.${dimension} must be a non-negative finite number, got ${String(value)}`)
+    }
+    out[dimension] = value
   }
+  return out
 }

package/src/contract.ts

@@ -0,0 +1,190 @@
+/**
+ * Delivery contract for `data_clean`: a deterministic pre-delivery validation
+ * summary (primary-key/type/dedupe row-count comparison plus uniqueness and
+ * non-null regression) and the clean before/after profile diff report. Pure —
+ * no I/O, no clock, no RNG; timestamps are injected.
+ * @module dsh-data-quality/contract
+ */
+
+import { isMissing, parseBoolean, parseDate, parseNumeric, throwIfAborted, type Row, type Table } from './dataset.ts'
+import type { CleanResult, CleanRule } from './clean.ts'
+import { profileTable, type ProfileReport } from './profile.ts'
+import type { ScorecardDimensionName } from './scorecard.ts'
+
+/** The pre-delivery contract summary attached to a clean run. */
+export interface CleanContractSummary {
+  /** Row count before cleaning. */
+  readonly inputRows: number
+  /** Row count after cleaning. */
+  readonly outputRows: number
+  /** Rows removed across all rules. */
+  readonly removedRows: number
+  /** Key columns of the first `dedupe` rule; `null` when no dedupe rule ran (uniqueness then covers full rows). */
+  readonly dedupeColumns: string[] | null
+  /** Whether the uniqueness key is free of duplicates in the cleaned output. */
+  readonly uniqueKeys: boolean
+  /** Remaining duplicate rows over the uniqueness key in the cleaned output. */
+  readonly remainingDuplicateRows: number
+  /** Non-null regression: remaining missing cells in columns a `fill-missing` rule targeted. */
+  readonly remainingMissing: Array<{ readonly column: string; readonly count: number }>
+  /** Type regression: remaining non-conforming cells in columns a `coerce-type` rule targeted. */
+  readonly typeConformance: Array<{ readonly column: string; readonly to: 'number' | 'date' | 'boolean'; readonly invalidCount: number }>
+  /** Per-column decision trace: which strategies touched each column and how many rows they affected. */
+  readonly columnDecisions: Array<{
+    readonly column: string
+    readonly decisions: Array<{ readonly strategy: string; readonly affectedRows: number }>
+  }>
+}
+
+/** The clean before/after profile diff report (persisted under the `clean-diff` report kind). */
+export interface CleanProfileDiff {
+  readonly dataset: string
+  /** Full profile of the input dataset. */
+  readonly before: ProfileReport
+  /** Full profile of the cleaned output (including its scorecard). */
+  readonly after: ProfileReport
+  readonly generatedAt: number
+}
+
+/** Count missing cells in one column of the cleaned output. */
+function countMissing(rows: readonly Row[], column: string, signal?: AbortSignal): number {
+  let count = 0
+  for (const [index, row] of rows.entries()) {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    if (isMissing(row[column])) count += 1
+  }
+  return count
+}
+
+/** Count present cells in one column that still fail to parse as the requested type. */
+function countNonConforming(rows: readonly Row[], column: string, to: 'number' | 'date' | 'boolean', signal?: AbortSignal): number {
+  let count = 0
+  for (const [index, row] of rows.entries()) {
+    if (index % 1024 === 0) throwIfAborted(signal)
+    const cell = row[column]
+    if (isMissing(cell)) continue
+    const conforms = to === 'number' ? parseNumeric(cell) !== undefined : to === 'date' ? parseDate(cell) !== undefined : parseBoolean(cell) !== undefined
+    if (!conforms) count += 1
+  }
+  return count
+}
+
+/**
+ * Compute the pre-delivery contract summary from a cleaning run: dedupe
+ * before/after row counts, the dedupe key's uniqueness regression, and the
+ * non-null/type regressions over the columns the rules targeted.
+ * @param result - the cleaning outcome (input/output rows plus cleaned rows).
+ * @param rules - the ordered rules that produced `result`.
+ * @param options - optional abort signal.
+ * @returns the contract summary.
+ */
+export function computeCleanContract(
+  result: CleanResult,
+  rules: readonly CleanRule[],
+  options: { signal?: AbortSignal | undefined } = {},
+): CleanContractSummary {
+  const dedupeRule = rules.find((rule) => rule.rule === 'dedupe') as Extract<CleanRule, { rule: 'dedupe' }> | undefined
+  const dedupeColumns = dedupeRule === undefined ? null : [...(dedupeRule.columns ?? result.columns)]
+  const keyColumns = dedupeColumns ?? result.columns
+  const seen = new Set<string>()
+  let remainingDuplicateRows = 0
+  for (const [index, row] of result.rows.entries()) {
+    if (index % 1024 === 0) throwIfAborted(options.signal)
+    const key = JSON.stringify(keyColumns.map((column) => row[column] ?? null))
+    if (seen.has(key)) {
+      remainingDuplicateRows += 1
+    } else {
+      seen.add(key)
+    }
+  }
+  const remainingMissing = rules
+    .filter((rule) => rule.rule === 'fill-missing')
+    .map((rule) => {
+      const fill = rule as Extract<CleanRule, { rule: 'fill-missing' }>
+      return { column: fill.column, count: countMissing(result.rows, fill.column, options.signal) }
+    })
+  const typeConformance = rules
+    .filter((rule) => rule.rule === 'coerce-type')
+    .map((rule) => {
+      const coerce = rule as Extract<CleanRule, { rule: 'coerce-type' }>
+      return { column: coerce.column, to: coerce.to, invalidCount: countNonConforming(result.rows, coerce.column, coerce.to, options.signal) }
+    })
+  const columnDecisions = traceColumnDecisions(result, rules)
+  return {
+    inputRows: result.inputRows,
+    outputRows: result.outputRows,
+    removedRows: result.inputRows - result.outputRows,
+    dedupeColumns,
+    uniqueKeys: remainingDuplicateRows === 0,
+    remainingDuplicateRows,
+    remainingMissing,
+    typeConformance,
+    columnDecisions,
+  }
+}
+
+/** The columns a single rule targets (single-column rules target one column; trim/dedupe may target many). */
+function ruleColumns(rule: CleanRule, allColumns: readonly string[]): string[] {
+  switch (rule.rule) {
+    case 'fill-missing':
+    case 'coerce-type':
+    case 'normalize-unit':
+    case 'map-values':
+      return [rule.column]
+    case 'trim':
+    case 'dedupe':
+      return [...(rule.columns ?? allColumns)]
+    default:
+      return []
+  }
+}
+
+/** Build the per-column decision trace: strategies + affected rows, in dataset column order. */
+function traceColumnDecisions(
+  result: CleanResult,
+  rules: readonly CleanRule[],
+): CleanContractSummary['columnDecisions'] {
+  const byColumn = new Map<string, Array<{ strategy: string; affectedRows: number }>>()
+  for (const [index, rule] of rules.entries()) {
+    const log = result.logs[index]
+    if (log === undefined) continue
+    for (const column of ruleColumns(rule, result.columns)) {
+      const list = byColumn.get(column) ?? []
+      list.push({ strategy: rule.rule, affectedRows: log.affectedRows })
+      byColumn.set(column, list)
+    }
+  }
+  return result.columns
+    .filter((column) => byColumn.has(column))
+    .map((column) => ({ column, decisions: byColumn.get(column) as Array<{ strategy: string; affectedRows: number }> }))
+}
+
+/**
+ * Build the clean before/after profile diff: two full {@link ProfileReport}
+ * snapshots (input and cleaned output) under one envelope. Reuses the profile
+ * engine so the scorecard and duplicate detection stay consistent across the
+ * whole plugin.
+ * @param input - the input dataset.
+ * @param output - the cleaned dataset.
+ * @param options - dataset label, injected timestamp, optional weights, optional abort signal.
+ * @returns the diff report.
+ */
+export function computeCleanProfileDiff(
+  input: Table,
+  output: Table,
+  options: { dataset: string; generatedAt: number; scorecardWeights?: Readonly<Record<ScorecardDimensionName, number>> | undefined; signal?: AbortSignal | undefined },
+): CleanProfileDiff {
+  const before = profileTable(input, {
+    dataset: options.dataset,
+    generatedAt: options.generatedAt,
+    scorecardWeights: options.scorecardWeights,
+    signal: options.signal,
+  })
+  const after = profileTable(output, {
+    dataset: options.dataset,
+    generatedAt: options.generatedAt,
+    scorecardWeights: options.scorecardWeights,
+    signal: options.signal,
+  })
+  return { dataset: options.dataset, before, after, generatedAt: options.generatedAt }
+}

package/src/dataset.ts

@@ -9,6 +9,7 @@
 import { open, stat } from 'node:fs/promises'
 import path from 'node:path'
 import { createHash } from 'node:crypto'
+import { TextDecoder } from 'node:util'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import type { ResolvedConfig } from './config.ts'
 
@@ -18,12 +19,22 @@ export type Cell = JsonValue
 /** One dataset row keyed by column name. */
 export type Row = Record<string, Cell>
 
+/** Detected file encoding metadata (BOM presence + UTF-8 validity). */
+export interface EncodingInfo {
+  /** `'utf-8'` when a UTF-8 byte-order mark was present, else `null`. */
+  readonly bom: 'utf-8' | null
+  /** Whether the bytes decode as valid UTF-8 (no replacement characters forced). */
+  readonly validUtf8: boolean
+}
+
 /** A tabular dataset: ordered columns plus rows. */
 export interface Table {
   /** Column names in file order. */
   readonly columns: string[]
   /** Rows, each carrying every declared column (missing cells are `null`). */
   readonly rows: Row[]
+  /** Detected file encoding; present only for tables loaded from a file. */
+  readonly encoding?: EncodingInfo
 }
 
 /** The root form a document load returns (citation checking walks this). */
@@ -101,13 +112,39 @@ export function throwIfAborted(signal: AbortSignal | undefined): void {
 }
 
 /**
- * Read a dataset file under the size cap.
+ * Detect a UTF-8 byte-order mark and validate the byte sequence. Invalid
+ * UTF-8 is a data-quality finding the profile reports (`validUtf8: false`)
+ * rather than a structural error that blocks the read — the decoded text
+ * keeps U+FFFD replacement characters so the profile can still run.
+ * @param buffer - raw file bytes.
+ * @returns the encoding metadata.
+ */
+export function detectEncoding(buffer: Uint8Array): EncodingInfo {
+  const bom = buffer.length >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf ? 'utf-8' : null
+  const body = bom === 'utf-8' ? buffer.subarray(3) : buffer
+  let validUtf8 = true
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(body)
+  } catch {
+    validUtf8 = false
+  }
+  return { bom, validUtf8 }
+}
+
+/** Decode file bytes, stripping a UTF-8 BOM and preserving replacement characters for invalid bytes. */
+function decodeUtf8Text(buffer: Uint8Array, encoding: EncodingInfo): string {
+  const body = encoding.bom === 'utf-8' ? buffer.subarray(3) : buffer
+  return new TextDecoder('utf-8').decode(body)
+}
+
+/**
+ * Read a dataset file under the size cap, detecting its encoding.
  * @param absolutePath - normalized absolute path (from {@link resolveWorkspacePath}).
  * @param config - resolved config (size cap).
  * @param signal - optional abort signal honored around the read.
- * @returns the UTF-8 text.
+ * @returns the decoded UTF-8 text plus its encoding metadata.
  */
-export async function readDatasetText(absolutePath: string, config: ResolvedConfig, signal?: AbortSignal): Promise<string> {
+export async function readDatasetFile(absolutePath: string, config: ResolvedConfig, signal?: AbortSignal): Promise<{ text: string; encoding: EncodingInfo }> {
   throwIfAborted(signal)
   let info
   try {
@@ -128,7 +165,9 @@ export async function readDatasetText(absolutePath: string, config: ResolvedConf
   const handle = await open(absolutePath, 'r')
   try {
     throwIfAborted(signal)
-    return await handle.readFile('utf8')
+    const buffer = await handle.readFile()
+    const encoding = detectEncoding(buffer)
+    return { text: decodeUtf8Text(buffer, encoding), encoding }
   } finally {
     await handle.close()
   }
@@ -325,12 +364,12 @@ function parseJsonLines(text: string): unknown[] {
  * @returns the parsed table.
  */
 export async function loadTable(absolutePath: string, config: ResolvedConfig, signal?: AbortSignal): Promise<Table> {
-  const text = await readDatasetText(absolutePath, config, signal)
+  const { text, encoding } = await readDatasetFile(absolutePath, config, signal)
   const ext = path.extname(absolutePath).toLowerCase()
   throwIfAborted(signal)
-  if (ext === '.csv') return parseDelimited(text, ',', config, signal)
-  if (ext === '.tsv') return parseDelimited(text, '\t', config, signal)
-  return parseJsonTable(text, ext, config, signal)
+  if (ext === '.csv') return { ...parseDelimited(text, ',', config, signal), encoding }
+  if (ext === '.tsv') return { ...parseDelimited(text, '\t', config, signal), encoding }
+  return { ...parseJsonTable(text, ext, config, signal), encoding }
 }
 
 /**
@@ -345,11 +384,11 @@ export async function loadTable(absolutePath: string, config: ResolvedConfig, si
 export async function loadDocument(absolutePath: string, config: ResolvedConfig, signal?: AbortSignal): Promise<DocumentRoot> {
   const ext = path.extname(absolutePath).toLowerCase()
   if (ext === '.json') {
-    const text = await readDatasetText(absolutePath, config, signal)
+    const { text } = await readDatasetFile(absolutePath, config, signal)
     return { kind: 'json', value: parseJsonDocument(text) }
   }
   if (ext === '.jsonl') {
-    const text = await readDatasetText(absolutePath, config, signal)
+    const { text } = await readDatasetFile(absolutePath, config, signal)
     return { kind: 'json', value: parseJsonLines(text) }
   }
   const table = await loadTable(absolutePath, config, signal)
@@ -405,18 +444,25 @@ const DATE_PATTERNS: readonly RegExp[] = [
   /^(\d{4})-(\d{1,2})-(\d{1,2})[ T](\d{1,2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?$/u,
 ]
 
-/**
- * Deterministic date parse to epoch milliseconds. Accepts `YYYY-MM-DD`,
- * `YYYY/MM/DD`, and ISO-like datetimes (date-only forms read as UTC midnight).
- * Calendar-invalid dates (e.g. 2025-13-40) reject. Returns `undefined` when
- * the cell is not a recognized date.
- * @param cell - the cell to parse (`undefined` when the column is absent).
- * @returns epoch milliseconds, or `undefined`.
- */
-export function parseDate(cell: Cell | undefined): number | undefined {
+/** Deterministic date-format labels in {@link DATE_PATTERNS} order. */
+const DATE_FORMATS = ['iso-date', 'slash-date', 'datetime'] as const
+
+/** The format label of a recognized date cell (source pattern, not the epoch). */
+export type DateFormat = (typeof DATE_FORMATS)[number]
+
+/** A recognized date cell: its parsed epoch plus the source format label. */
+export interface DateParse {
+  /** Epoch milliseconds (UTC). */
+  readonly epoch: number
+  /** Which {@link DATE_PATTERNS} entry matched. */
+  readonly format: DateFormat
+}
+
+/** Parse one date cell to its epoch plus format; `undefined` when unrecognized. */
+function parseDateCellInternal(cell: Cell | undefined): DateParse | undefined {
   if (typeof cell !== 'string') return undefined
   const text = cell.trim()
-  for (const pattern of DATE_PATTERNS) {
+  for (const [index, pattern] of DATE_PATTERNS.entries()) {
     const match = pattern.exec(text)
     if (match === null) continue
     const year = Number(match[1])
@@ -429,11 +475,45 @@ export function parseDate(cell: Cell | undefined): number | undefined {
     const epoch = Date.UTC(year, month - 1, day, hour, minute, second)
     const check = new Date(epoch)
     if (check.getUTCMonth() !== month - 1 || check.getUTCDate() !== day) return undefined
-    return epoch
+    const format = DATE_FORMATS[index]
+    if (format === undefined) return undefined
+    return { epoch, format }
   }
   return undefined
 }
 
+/**
+ * Deterministic date parse to epoch milliseconds. Accepts `YYYY-MM-DD`,
+ * `YYYY/MM/DD`, and ISO-like datetimes (date-only forms read as UTC midnight).
+ * Calendar-invalid dates (e.g. 2025-13-40) reject. Returns `undefined` when
+ * the cell is not a recognized date.
+ * @param cell - the cell to parse (`undefined` when the column is absent).
+ * @returns epoch milliseconds, or `undefined`.
+ */
+export function parseDate(cell: Cell | undefined): number | undefined {
+  return parseDateCellInternal(cell)?.epoch
+}
+
+/**
+ * Parse one date cell to its epoch plus source format label.
+ * @param cell - the cell to parse (`undefined` when the column is absent).
+ * @returns the parsed date, or `undefined` when the cell is not a recognized date.
+ */
+export function parseDateCell(cell: Cell | undefined): DateParse | undefined {
+  return parseDateCellInternal(cell)
+}
+
+/**
+ * The format label of a recognized date cell (`iso-date` / `slash-date` /
+ * `datetime`); `undefined` when the cell is not a recognized date. Used to
+ * measure a date column's format consistency.
+ * @param cell - the cell to inspect (`undefined` when the column is absent).
+ * @returns the source format label, or `undefined`.
+ */
+export function dateFormatOf(cell: Cell | undefined): DateFormat | undefined {
+  return parseDateCellInternal(cell)?.format
+}
+
 /** Boolean parse: true/false/yes/no/1/0, case-insensitive. */
 export function parseBoolean(cell: Cell | undefined): boolean | undefined {
   if (typeof cell === 'boolean') return cell

package/src/events.ts

@@ -33,6 +33,8 @@ export interface DataQualityEventData {
     readonly rules?: number
     readonly failedRules?: number
     readonly passed?: boolean
+    readonly expectations?: number
+    readonly failedExpectations?: number
   }
 }
 

package/src/index.ts

@@ -23,14 +23,15 @@ import { LocalDataQualityService } from './provider-local.ts'
 import { defineProfileTool } from './tools/profile.ts'
 import { defineCleanTool } from './tools/clean.ts'
 import { defineVerifyTool } from './tools/verify.ts'
+import { defineReportTool } from './tools/report.ts'
 import { VERSION } from './version.ts'
 
 export const name = 'data-quality'
-/** The three model tools and the durable report domain. */
+/** The four model tools and the durable report domain. */
 export const inject = ['tools', 'storageDomain']
 
 export { Config, resolveConfig } from './config.ts'
-export type { Config as DataQualityConfig, ResolvedConfig } from './config.ts'
+export type { Config as DataQualityConfig, ResolvedConfig, ScorecardWeights } from './config.ts'
 export { VERSION } from './version.ts'
 export {
   DataQualityService,
@@ -43,16 +44,21 @@ export {
 } from './service.ts'
 export { LocalDataQualityService, type ProviderDeps } from './provider-local.ts'
 export type { CleanRule, CleanRuleLog, CleanResult } from './clean.ts'
-export type { ProfileReport, ColumnProfile, NumericProfile } from './profile.ts'
-export type { VerifyRule, VerifyReport, VerifyRuleResult, VerifyEvidenceRow } from './verify.ts'
-export { parseLocator, checkCitations } from './verify.ts'
-export { profileTable, renderProfileText } from './profile.ts'
+export { computeCleanContract, computeCleanProfileDiff, type CleanContractSummary, type CleanProfileDiff } from './contract.ts'
+export type { ProfileReport, ColumnProfile, NumericProfile, DuplicateDetection, InferredType } from './profile.ts'
+export type { VerifyRule, VerifyReport, VerifyRuleResult, VerifyEvidenceRow, VerifyExpectation, VerifyExpectationResult, VerifyMetric } from './verify.ts'
+export { parseLocator, checkCitations, verifyExpectations, VerifyExpectationError } from './verify.ts'
+export { profileTable, renderProfileText, detectDuplicateRows, countDuplicateRows, numericProfile } from './profile.ts'
+export { computeScorecard, type DataQualityScorecard, type ScorecardDimension, type ScorecardDimensionName } from './scorecard.ts'
+export { INDUSTRY_PRESETS, INDUSTRY_PRESET_IDS, resolveIndustryPreset, type IndustryPreset } from './presets.ts'
 export { applyCleanRules, serializeDelimited } from './clean.ts'
 export { verifyTable, renderVerifyText } from './verify.ts'
 export {
   DatasetError,
   loadTable,
   loadDocument,
+  readDatasetFile,
+  detectEncoding,
   parseDelimited,
   parseJsonTable,
   resolveWorkspacePath,
@@ -60,15 +66,22 @@ export {
   isMissing,
   parseNumeric,
   parseDate,
+  parseDateCell,
+  dateFormatOf,
   parseBoolean,
   type Table,
   type Row,
   type Cell,
   type DocumentRoot,
+  type DateParse,
+  type DateFormat,
+  type EncodingInfo,
 } from './dataset.ts'
-export { dataQualityDomainSpec, reportKeyOf, reportRecordSchema, type ReportRecord, type ReportStore } from './store.ts'
+export { dataQualityDomainSpec, reportKeyOf, reportRecordSchema, isValidReportKey, type ReportRecord, type ReportStore, type StoredReport } from './store.ts'
 export { DATA_QUALITY_EVENT_TYPES, appendDataQualityEvent, type DataQualityEventData, type DataQualityEventType } from './events.ts'
 export { MAX_CELL_TEXT, truncateCell, truncateRow } from './present.ts'
+export { renderProfileHtml, renderCleanHtml, type CleanReportHtml } from './report-html.ts'
+export { REPORT_SCHEMA_VERSION } from './version.ts'
 
 /**
  * Mount the seam: resolve config (fail loud), open the report domain, publish
@@ -97,6 +110,11 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
         return key
       },
       get: (key) => reports.get(key),
+      list: (kind) =>
+        [...reports.entries()]
+          .filter(([, record]) => record.kind === kind)
+          .sort(([keyA], [keyB]) => (keyA < keyB ? -1 : keyA > keyB ? 1 : 0))
+          .map(([key, record]) => ({ key, ...record })),
     }
   }
 
@@ -104,7 +122,8 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
   ctx.tools.register(defineProfileTool(service))
   ctx.tools.register(defineCleanTool(service))
   ctx.tools.register(defineVerifyTool(service))
-  logger.info(`dsh-data-quality ${VERSION} mounted: ctx.dataQuality + data_profile/data_clean/data_verify`)
+  ctx.tools.register(defineReportTool(service))
+  logger.info(`dsh-data-quality ${VERSION} mounted: ctx.dataQuality + data_profile/data_clean/data_verify/data_report`)
 
   if (domain !== undefined) {
     const handle = domain