@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/test-kit/corpus-recipe.ts

@@ -3,30 +3,30 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Shared harness for the slice-recipe tests. Each of them was carrying its own copy of the same three
- *   pieces — a row type, a scratch-directory writer, and a runner that differed only in which recipe and
- *   which seed it passed.
+ *   Shared harness for the corpus-recipe tests.
  *
- *   Lives under `test-kit/` (the convention `mailwoman/test-kit/` set) and is excluded from corpus's
- *   build project, so it is never emitted into `out/` and never reaches the published tarball.
+ *   It lives under `test-kit/` and is excluded from corpus's build project, so it is never emitted into
+ *   `out/` and never reaches the published tarball.
  */
 
 import { temporaryDirectory, type TemporaryDirectory } from "@mailwoman/core/fs/temporary"
-import { writeLocalTextFile } from "@mailwoman/core/fs/writers"
+import { writeLocalTextFile, writeLocalJSONLFile } from "@mailwoman/core/fs/writers"
 import { parseJSONStrict } from "@mailwoman/core/json"
+import type { PathBuilder } from "path-ts"
 
-import type { SliceRecipeOpts } from "#recipes/scaffold"
+import type { RecipeOptions } from "#recipes/scaffold"
 
 /**
- * The fields a slice-recipe assertion reads off an emitted row.
+ * The fields a recipe assertion reads off an emitted row.
  *
- * `parseJSONStrict` without a type argument hands back `unknown`; naming the shape is what lets the assertions be
- * checked at all. The previous `Record<string, never>` typed every property as `never`, so nothing could be read
- * without a cast and nothing was ever verified.
+ * A declared shape lets the code check `parseJSONStrict`'s `unknown` value.
  */
-export interface SliceRow {
+export interface RecipeRow {
 	raw: string
-	synth_method?: string
+	recipe?: string
+	register?: string | null
+	surface?: string
+	base_source_id?: string | null
 	source?: string
 	source_id?: string
 	components?: Partial<Record<string, string>>
@@ -38,49 +38,66 @@ export interface SliceRow {
  * A recipe's `run` surface, as the tests drive it.
  */
 export interface CorpusRecipe<TStats> {
-	run(options: SliceRecipeOpts, emit: (line: string) => void): Promise<TStats>
+	run(options: RecipeOptions, emit: (line: string) => void): Promise<TStats>
 }
 
 /**
  * The two input paths a recipe reads, plus the directory holding them.
  *
- * The CALLER owns it: a recipe opens both files by path well after this function returns, so the directory has to
- * outlive the call. Bind it with `using` and it goes when the test does.
+ * The caller owns it, because a recipe opens both files by path well after this function returns.
  */
-export type SliceRecipeInputs = TemporaryDirectory & { input: string; exclude: string }
+export type RecipeInputs = TemporaryDirectory & { input: PathBuilder; exclude: PathBuilder }
 
 /**
  * Write the tuple + reserved-surface inputs a recipe reads, into a fresh temporary directory.
  */
-export async function scratch(prefix: string, tuples: object[], surfaces: string[]): Promise<SliceRecipeInputs> {
+export async function scratch(prefix: string, tuples: object[], surfaces: string[]): Promise<RecipeInputs> {
 	const dir = await temporaryDirectory(`${prefix}-`)
-	const input = dir.resolve("tuples.jsonl")
-	const exclude = dir.resolve("surfaces.txt")
+	const input = dir.path("tuples.jsonl")
+	const exclude = dir.path("surfaces.txt")
 
-	await writeLocalTextFile(tuples.map((t) => JSON.stringify(t)).join("\n") + "\n", input)
+	await writeLocalJSONLFile(tuples, input)
 	await writeLocalTextFile("# reserved\n" + surfaces.join("\n") + "\n", exclude)
 
 	return dir.moveWith({ input, exclude })
 }
 
 /**
- * Bind a recipe and its seed to a runner the tests call with just the tuples and reserved surfaces. The seed is
- * per-recipe and required — these suites assert on generated distributions.
+ * The register id included in a harness-built tuple set.
+ *
+ * It names no publisher, so a row written under it cannot be mistaken for a real register's record.
+ */
+export const TEST_REGISTER = "test-harness"
+
+/**
+ * Bind a recipe and its seed to a runner the tests call with just the tuples and reserved surfaces.
+ *
+ * The seed is required because these suites assert on generated distributions.
  */
-export function sliceRunner<TStats>(prefix: string, recipe: CorpusRecipe<TStats>, seed: number) {
+export function recipeRunner<TStats>(prefix: string, recipe: CorpusRecipe<TStats>, seed: number) {
 	return async function run(
 		tuples: object[],
 		surfaces: string[],
-		opts: Partial<SliceRecipeOpts> = {}
-	): Promise<{ stats: TStats; rows: SliceRow[] }> {
+		opts: Partial<RecipeOptions> = {}
+	): Promise<{ stats: TStats; rows: RecipeRow[] }> {
 		await using inputs = await scratch(prefix, tuples, surfaces)
 		const lines: string[] = []
 
 		const stats = await recipe.run(
-			{ output: "", seed, variants: 1, input: inputs.input, excludeSurfaces: inputs.exclude, ...opts },
+			{
+				output: "",
+				seed,
+				variants: 1,
+				input: inputs.input,
+				excludeSurfaces: inputs.exclude,
+				// The tuples come from this harness rather than a publisher.
+				// A recipe that reads them refuses to run without a register.
+				register: TEST_REGISTER,
+				...opts,
+			},
 			(line) => lines.push(line)
 		)
 
-		return { stats, rows: lines.map((line) => parseJSONStrict<SliceRow>(line)) }
+		return { stats, rows: lines.map((line) => parseJSONStrict<RecipeRow>(line)) }
 	}
 }

package/lib/test-kit.ts

@@ -0,0 +1,116 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The corpus adapter-test harness — the sibling of `mailwoman/test-kit/`.
+ *
+ *   `corpus/package.json` excludes this directory from the published tarball.
+ *   That entry predates this file. The test harness can therefore import `vitest`.
+ *   `mailwoman/test-kit/index.ts` uses the same packaging boundary.
+ */
+
+import { temporaryDirectory, type TemporaryDirectory } from "@mailwoman/core/fs/temporary"
+import { PathBuilder, type PathBuilderLike } from "path-ts"
+import { createNewlineWriter, JSONSpliterator } from "spliterator"
+import { afterEach, beforeEach } from "vitest"
+
+import type { CanonicalRow } from "#types"
+
+/**
+ * A per-test scratch directory.
+ *
+ * `path` exists only inside a test body.
+ * A read before `beforeEach` or after `afterEach` throws.
+ */
+export interface ScratchDir {
+	readonly path: PathBuilder
+}
+
+/**
+ * Register a fresh scratch directory for each test in the current suite, removed afterwards.
+ *
+ * `slug` names the directory (`mailwoman-<slug>-xxxxxx` under the OS temp dir)
+ * so a stray leftover is traceable to its suite.
+ * Teardown swallows its own errors, because a test that already removed the directory
+ * or a platform holding a handle open must not turn a passing assertion into a failing suite.
+ */
+export function useScratchDir(slug: string): ScratchDir {
+	let owned: TemporaryDirectory | undefined
+
+	beforeEach(async () => {
+		owned = await temporaryDirectory(`mailwoman-${slug}-`)
+	})
+
+	// The directory is owned by the test, never by a module-scoped stack: under `isolate: false`
+	// this module is shared across every corpus adapter suite in a fork.
+	afterEach(async () => {
+		try {
+			await owned?.[Symbol.asyncDispose]()
+		} catch {}
+
+		owned = undefined
+	})
+
+	return {
+		get path(): PathBuilder {
+			if (!owned) throw new Error(`useScratchDir("${slug}"): the scratch directory exists only inside a test body`)
+
+			return owned.path
+		},
+	}
+}
+
+/**
+ * Read back the canonical rows a `runAdapter` call wrote at `<outputDir>/<adapterID>/canonical.jsonl`.
+ */
+export function readCanonicalRows(outputDir: PathBuilderLike, adapterID: string): Promise<CanonicalRow[]> {
+	return Array.fromAsync(
+		JSONSpliterator.fromAsync<CanonicalRow>(PathBuilder.from(outputDir)(adapterID, "canonical.jsonl"))
+	)
+}
+
+/**
+ * Write a delimited fixture (a header line plus the given rows) and answer its path;
+ * `createNewlineWriter` terminates every line, so a caller passes content without a delimiter.
+ */
+export async function writeDelimitedFixture<P extends PathBuilderLike>(
+	filePath: P,
+	header: string,
+	rows: readonly string[]
+): Promise<P> {
+	await using out = createNewlineWriter(filePath)
+
+	await out.write(header)
+
+	for (const row of rows) {
+		await out.write(row)
+	}
+
+	return filePath
+}
+
+/**
+ * Whether a test that calls a publisher's live service should run.
+ *
+ * CI's `unit-slow` leg runs every `*.integration.test.ts`, and the required
+ * `test` context fails when that leg does.
+ * A test calling a foreign government host therefore makes a merge depend on that host's
+ * availability: Poland's address service answered `ECONNRESET` mid-run on 2026-10-02
+ * and reddened a local preflight that had passed an hour earlier.
+ *
+ * So a live-service test is opt-in, and the suite reports it as skipped
+ * rather than passing on a check it did not make.
+ * Run one with `MAILWOMAN_LIVE_PUBLISHER_TESTS=1 yarn vitest --run --config vitest.slow.config.ts <file>`.
+ *
+ * A test reading a committed fixture needs this switch unset, and most of
+ * each harvester's coverage is there.
+ * The switch is for the assertions only the publisher can answer: that a URL still serves,
+ * that a feed still states what the register recorded, that a harvest the adapter can read comes back.
+ *
+ * It reads `process.env` directly, because it is a per-run test switch rather than
+ * project configuration and so has no entry in `@mailwoman/core/env`.
+ */
+export const LIVE_PUBLISHER_TESTS =
+	// oxlint-disable-next-line sister-software/no-process-globals -- stated in the block above.
+	process.env.MAILWOMAN_LIVE_PUBLISHER_TESTS === "1"

package/lib/tools/align-canonical.ts

@@ -0,0 +1,64 @@
+import { stringifyJSON } from "@mailwoman/core/json"
+import { createNewlineWriter, JSONSpliterator } from "spliterator"
+
+/**
+ * Re-emit a canonical jsonl ({raw, components, country, source, ...}) as a labeled jsonl in
+ * the current align format, by running every row through `alignRow` (corpus/src/align.ts).
+ *
+ * Most synthetic recipe outputs are generated on demand by a recipe (parametrized by --count),
+ * so re-emitting them in a new label format is a re-run.
+ * A few are fixed corpora with a hand/DeepSeek-authored canonical source that is never regenerated,
+ * notably `deepseek-kryptonite` (the adversarial hard-case set) and the `deepseek-translit-*` variants.
+ *
+ * Their committed parquets use the label format that was current when they were first built.
+ *
+ * When the corpus label format changes (the char-offset span triple), those fixed
+ * corpora are aligned again from their canonical source.
+ * Feed the canonical source back through the same `alignRow` the from-source build uses,
+ * so the spans land in the new format with zero drift.
+ *
+ * That is what this does.
+ * Canonical jsonl in → labeled jsonl out, one `alignRow` per row, quarantine on miss.
+ *
+ * It is the uniform counterpart to `tools/overlay/kryptonite.ts`
+ * (which couples to a base manifest and writes parquet directly).
+ * Output goes to jsonl so it joins the same jsonl-to-parquet path every other overlay uses.
+ *
+ * Usage: mailwoman corpus align-slice\ --input /path/canonical-kryptonite.jsonl\
+ * --out /tmp/kryptonite-labeled.jsonl\ --corpus-version 0.5.0
+ */
+import { alignRow } from "#utils"
+
+export interface AlignCanonicalOptions {
+	input: string
+	output: string
+	corpusVersion: string
+}
+
+export async function alignCanonicalRows(args: AlignCanonicalOptions): Promise<void> {
+	await using outStream = createNewlineWriter(args.output)
+	let labeled = 0
+	let quarantined = 0
+	const quarantineReasons: Record<string, number> = {}
+
+	for await (const canonical of JSONSpliterator.fromAsync<Parameters<typeof alignRow>[0]>(args.input)) {
+		// Stamp the target corpus version so the emitted row's provenance matches the run it joins.
+		canonical.corpus_version = args.corpusVersion
+		const result = alignRow(canonical)
+
+		if (result.kind === "labeled") {
+			await outStream.write(stringifyJSON(result.row))
+
+			labeled++
+		} else {
+			quarantined++
+			const r = result.row.reason ?? "unknown"
+			quarantineReasons[r] = (quarantineReasons[r] ?? 0) + 1
+		}
+	}
+
+	console.error(
+		`align-canonical: ${labeled} labeled, ${quarantined} quarantined → ${args.output}\n` +
+			`  quarantine reasons: ${stringifyJSON(quarantineReasons)}`
+	)
+}